Agent Runtime Policy Spec

Status link

Canonical spec. Companion to Synedrix OS - Agent Spec. Supersedes: v0.3. Related artifacts: Synedrix OS - Agent Spec, Synedrix OS - Agent Registry Spec, Synedrix OS Workflow Contract Spec, Synedrix OS Core Principles, Synedrix OS Observability Metrics Spec, Synedrix OS Interoperability Protocol Strategy, Synedrix OS Orchestration & Runtime Strategy.

Purpose link

The Agent Runtime Policy defines how an agent executes — model selection, latency and cost budgets, tool authorization, retry behaviour, fallback degradation, concurrency limits, and circuit-breaker conditions.

Separating runtime policy from agent definition allows execution parameters to be tuned, versioned, and overridden per environment or business instance without touching the agent’s identity, contracts, or governance profile.

Scope link

Runtime policy applies to a single agent invocation lifecycle: from the moment orchestration hands a task to an agent, through model inference and tool calls, to the moment a structured outcome is returned or escalation is triggered.

It does not cover:

• Workflow-level retries or compensation (Workflow Contract Spec).
• Approval or policy gate logic (agent authority and policy bindings).
• Prompt content or prompt versioning (prompt_policy in Agent Spec).
• Observability and tracing configuration (Agent Evaluation Spec and tech stack).

Runtime policy schema link

runtime_policy:

  # Deployment mode (governs model routing options available to this agent)
  deployment_mode:             # cloud-connected | self-hosted-hybrid | air-gapped
                               # Must match the declaring business instance's deployment_mode.
                               # If unset, inherits from the business instance declaration.

  # Runtime engine (which execution engine runs this agent — see ADR-OS-001)
  runtime_engine:              # n8n-aiagent | langgraph
                               # n8n-aiagent: agent runs as an n8n AI Agent node (Layer 3 host).
                               #   Acceptable only for acyclic patterns (sequential, conditional,
                               #   parallel, fan-out-fan-in, pipeline).
                               # langgraph: agent runs in the LangGraph Agent Runtime (Layer 4).
                               #   Required for stateful/cyclic/multi-agent patterns
                               #   (iterative, consensus, reflect-and-revise, hierarchical).
                               # If unset, defaults to n8n-aiagent. The orchestrator MUST route
                               # cyclic/multi-agent execution_patterns to langgraph regardless of
                               # this default. See Orchestration & Runtime Strategy v0.1 §4.

  # Model selection
  primary_model:               # Cloud: e.g. gpt-4o, claude-sonnet-4-6
                               # Local: e.g. ollama/llama3.1, vllm/mistral-7b
                               # Format for local: <provider>/<model-name>:<tag>
  model_type:                  # cloud | local | hybrid
                               # cloud: primary_model is a cloud API endpoint
                               # local: primary_model is a local inference endpoint
                               # hybrid: primary_model is local, fallback_model may be cloud
                               # Note: deployment_mode: air-gapped enforces model_type: local only.
  local_model_provider:        # ollama | vllm | lm_studio | llamacpp
                               # Required when model_type: local or hybrid.
  local_model_endpoint:        # e.g. http://localhost:11434 (Ollama default)
                               # e.g. http://localhost:8000 (vLLM default)
                               # Required when model_type: local or hybrid.
  model_routing_strategy:      # fixed | cost-optimised | latency-optimised | local-first | custom-router-ref
  fallback_model:              # Can be a local model URI or a cloud model URI.
                               # In deployment_mode: air-gapped, must be a local URI or null.
  model_router_ref:

  # Budget controls
  token_budget:
    input_max:
    output_max:
    total_hard_limit:
  latency_budget_ms:
  latency_slo_ms:
  cost_budget_usd:             # Set to null for local-only deployments where token cost is not applicable.
                               # Use compute_cost_tracking: true instead for air-gapped mode.
  compute_cost_tracking:       # true | false — enables compute resource tracking for local inference.
                               # Replaces cost_budget_usd in air-gapped deployments.

  # Tool execution limits (operational controls — not authorization)
  max_tool_hops:
  tool_call_timeout_ms:
  parallel_tool_calls:

  # Tool authorization (see dedicated section below for full model)
  tool_authorization_policy:
    active_tool_set:           # all | declared | restricted
    tool_grants:               # List of explicitly activated tools (required when active_tool_set: declared)
    tool_suspensions:          # Tools removed from the active set (required when active_tool_set: restricted)
    mcp_tool_policy:           # Policy governing MCP-backed tools
    a2a_tool_policy:           # Policy governing A2A-backed tool invocations

  # Streaming
  streaming_enabled:
  streaming_chunk_timeout_ms:

  # Retry behaviour (agent-level, within a single task)
  retry_policy:
    max_attempts:
    backoff_strategy:          # immediate | linear | exponential
    backoff_base_ms:
    retryable_conditions:      # tool-timeout | model-unavailable | schema-validation-error
    non_retryable_conditions:  # policy-veto | auth-failure | hard-limit-exceeded

  # Fallback and degradation
  fallback_policy:
    on_model_failure:          # abort | use-fallback-model | rules-only-degradation
                               # In air-gapped mode: use-fallback-model requires fallback_model
                               # to be a local URI. Cloud fallback is not permitted.
    on_tool_failure:           # abort | skip-tool-and-continue | escalate
    on_budget_exceeded:        # abort | truncate-output | escalate
    degraded_mode_ref:

  # Concurrency
  concurrency_limit:
  queue_overflow_behaviour:    # reject | queue | escalate

  # Circuit breaker
  circuit_breaker:
    enabled:
    failure_threshold:
    recovery_timeout_ms:
    probe_on_recovery:

  # Session and context window
  context_window_strategy:     # full | sliding | summarised
  working_memory_ttl_ms:

  # Environment overrides
  environment_overrides:
    production:
    staging:

Tool authorization model link

For a conceptual explanation of what a tool is, what the active tool set means, and how end-to-end enforcement works across n8n and LangGraph, see Tool Authorization Model. This section is the authoritative schema reference.

The three-layer model link

Tool authorization in Synedrix OS follows a three-layer model. Each layer can only restrict, never expand, the permissions granted by the layer above it.

The ceiling rule: A tool not declared in the agent spec’s tool_permissions can never be activated by a runtime policy or instance override. Authorization can only restrict downward from the declared ceiling — it cannot grant new capabilities.

flowchart TB
    L1["Capability ceiling: agent definition, tool_permissions"]
    L2["Runtime authorization: runtime policy, tool_authorization_policy"]
    L3["Instance restriction: business instance, environment_overrides"]
    L1 -->|"restricts down to"| L2
    L2 -->|"restricts down to"| L3

Tool authorization schema link

tool_authorization_policy:

  active_tool_set: all | declared | restricted
  # all      — activates every tool in the agent's tool_permissions (default when field is absent)
  # declared — activates only the tools listed in tool_grants; all others are inactive
  # restricted — activates all tools in tool_permissions MINUS those listed in tool_suspensions

  tool_grants:
    # Required when active_tool_set: declared.
    # Each entry activates one tool from the tool_permissions ceiling.
    # A tool_id not present in tool_permissions is a configuration error.
    - tool_id: string             # Must match a tool_id in agent spec tool_permissions
      condition:                  # Optional — activate tool only when condition is met
        trigger: always | risk_score_below | workflow_class | deployment_mode
        threshold: number         # Used with risk_score_below; range 0.0–1.0
        value: string             # Used with workflow_class or deployment_mode

  tool_suspensions:
    # Required when active_tool_set: restricted.
    # Each entry removes one tool from the active set.
    - tool_id: string             # Must match a tool_id in agent spec tool_permissions
      reason: string              # Human-readable reason for suspension
      suspension_scope: permanent | conditional
      condition:                  # Required when suspension_scope: conditional
        trigger: risk_score_above | workflow_class | deployment_mode
        threshold: number         # Used with risk_score_above; range 0.0–1.0
        value: string             # Used with workflow_class or deployment_mode

  mcp_tool_policy:
    # Governs MCP-backed tools specifically (see Interoperability Strategy v0.2).
    # Applies on top of tool_grants/tool_suspensions — MCP tools must also pass those filters.
    require_mcp_approval: boolean   # When true, every MCP tool call is submitted to the Policy Guard Agent
                                    # before execution. Default: true for agents with risk_tier: high or critical.
    mcp_server_allowlist:           # Optional array of MCP server IDs. When set, only these MCP servers
      - server_id: string           # may be invoked. Tools from other servers are silently suppressed.
    mcp_server_denylist:            # Optional array of MCP server IDs. When set, these servers are blocked
      - server_id: string           # regardless of tool_permissions declaration.
    mcp_write_approval_required: boolean  # When true, all write-capable MCP tool calls
                                          # (side_effect_class: write or higher) require Policy Guard approval.
                                          # Default: true. Must be explicitly set to false to disable.

  a2a_tool_policy:
    # Governs A2A-backed tool invocations (cross-system agent delegation).
    # See Interoperability Strategy v0.2 for A2A adoption phases and trust model.
    require_a2a_approval: boolean   # When true, all A2A tool invocations are submitted to Policy Guard.
                                    # Default: true for all agents.
    a2a_trust_tier: trusted | provisional | untrusted
    # trusted     — A2A partner is a verified Synedrix OS instance; read-only calls auto-approved
    # provisional — A2A partner is known but unverified; all calls require Policy Guard approval
    # untrusted   — A2A partner is external; all calls require Policy Guard approval and are logged
    a2a_partner_allowlist:          # Optional. When set, only these A2A partner agent IDs are permitted.
      - partner_agent_id: string

How authorization flows link

At agent invocation time, the orchestration layer computes the active tool set by applying layers in order:

1. Reads tool_permissions from the agent registry entry (capability ceiling).
2. Reads tool_authorization_policy from the active runtime policy (runtime restriction).
3. Applies any environment_overrides for the current deployment environment (instance restriction).
4. Passes the resolved active tool set to the agent executor.
5. The agent executor rejects any tool call that references a tool not in the resolved active tool set, emitting an agent.tool.unauthorized event.

The Policy Guard Agent is invoked at tool-call time (not at resolution time) when mcp_tool_policy.require_mcp_approval: true, a2a_tool_policy.require_a2a_approval: true, or when the tool’s approval_tier in the agent spec requires it.

flowchart TB
    A["Invocation: orchestration layer computes the active tool set"]
    B["1. Read tool_permissions from the registry entry: capability ceiling"]
    C["2. Read tool_authorization_policy from the active runtime policy"]
    D["3. Apply environment_overrides for the deployment environment"]
    E["4. Pass the resolved active tool set to the agent executor"]
    F{"Tool call in the active tool set?"}
    G["Tool call proceeds"]
    H["Rejected: agent.tool.unauthorized event"]
    I{"Approval required: MCP or A2A policy flag, or approval_tier?"}
    J{"Policy Guard Agent invoked at tool-call time: approved?"}
    K["Tool call does not proceed"]
    A --> B --> C --> D --> E --> F
    F -->|"yes"| I
    F -->|"no"| H
    I -->|"yes"| J
    I -->|"no"| G
    J -->|"approved"| G
    J -->|"not approved"| K

Observability events link

Runtime engine governance bridge link

When runtime_engine: langgraph, the agent executes in the LangGraph Agent Runtime (Layer 4) rather than as an n8n AI Agent node. A second execution engine is admissible only if it inherits the same governance the n8n host enforces. The orchestrator and the LangGraph executor MUST uphold the following bridge (full detail and topology in Orchestration & Runtime Strategy §5):

Engine selection rule: the workflow’s execution_pattern is authoritative. Cyclic/multi-agent patterns (iterative, consensus, reflect-and-revise, hierarchical) MUST set runtime_engine: langgraph. Acyclic patterns MAY use n8n-aiagent.

Model routing strategies link

Every model fallback emits an agent.runtime.model-fallback observability event regardless of routing strategy. In local mode, model-unavailable events indicate local inference server failure, not API quota exhaustion.

Local model URI format link

Local model URIs follow the pattern <provider>/<model-name>:<tag>.

Examples:

ollama/llama3.1:8b
ollama/mistral:7b-instruct
ollama/qwen2.5:14b
vllm/meta-llama/Llama-3.1-8B-Instruct
vllm/mistralai/Mistral-7B-Instruct-v0.3

The model tag (:8b, :7b-instruct) pins the specific quantisation or version. Untagged URIs resolve to the provider’s default. Business instances should always pin specific tags in production to prevent silent model changes on server update.

Retry vs workflow compensation link

Agent-level retry and workflow-level compensation are distinct concerns.

An agent must never attempt workflow-level compensation. On retry exhaustion it must emit a structured failure outcome and escalate via its escalation path.

Fallback degradation model link

Three ordered options when a model or tool is unavailable:

1. Use fallback model — switch to fallback_model and continue. Emit agent.runtime.model-fallback. In air-gapped deployments, fallback_model must be a local URI.
2. Rules-only degradation — bypass the LLM entirely and execute a deterministic rules engine. Emit agent.runtime.degraded-mode.
3. Escalate — halt and route to the escalation path in the agent’s authority profile. Emit agent.runtime.escalated.

High-risk agents (risk_tier: high or critical) must prefer escalation over silent degradation.

OS vs domain pack vs business instance split link

Recommended database tables link

agent_runtime_policies         — current active runtime policy per agent
agent_runtime_policy_versions  — full version history
agent_runtime_events           — append-only model-fallback, degraded-mode, retry, escalation, and circuit-breaker transition events
agent_model_routing_rules      — custom routing rule sets
agent_circuit_breaker_state    — mutable current open/closed/half-open projection per agent; transitions are recorded in agent_runtime_events
agent_tool_auth_events         — tool authorized, unauthorized, suspended, approval-requested events
agent_active_tool_sets         — resolved active tool set per agent per deployment environment (cache)

Invariants link

• An agent with runtime_engine: langgraph MUST satisfy the full runtime engine governance bridge — lineage continuity, Policy Guard reachability, HITL reachability, tool-authorization enforcement, and the Outcome Envelope return contract. A LangGraph agent that bypasses any of these is non-compliant (it would be a shadow runtime).
• The execution_pattern is authoritative for engine selection: iterative, consensus, reflect-and-revise, and hierarchical MUST run on runtime_engine: langgraph.
• The LangGraph executor MUST reject any tool call outside the resolved active_tool_set and emit agent.tool.unauthorized — the capability ceiling rule applies identically across runtime engines.
• Runtime policy and prompt policy are separate versioned artifacts — never merged.
• Every model fallback, degradation event, and circuit-breaker trigger must emit an observable event.
• Agents with risk_tier: high or critical must prefer escalation over silent degradation.
• Business instances cannot grant themselves higher budgets than the domain pack allows.
• Agent-level retry must never attempt workflow-level compensation.
• A business instance with deployment_mode: air-gapped must not contain any agent runtime policy with a cloud model URI in primary_model or fallback_model. This is a configuration error.
• In deployment_mode: air-gapped, model_type must be local for all agents. model_type: cloud or hybrid with a cloud fallback is not permitted.
• Local model URIs must pin a specific version tag in production deployments to prevent silent model changes on server update.
• The capability ceiling is inviolable: a tool not declared in the agent spec’s tool_permissions can never appear in tool_grants or be activated by any runtime policy or instance override.
• Authorization can only restrict: tool_authorization_policy can remove tools from the active set or add conditions; it cannot grant capabilities beyond the declared ceiling.
• Every tool call rejection (unauthorized or suspended) must emit an agent.tool.unauthorized or agent.tool.suspended event. Silent suppression is not permitted.
• mcp_tool_policy.mcp_write_approval_required defaults to true. Disabling it requires an explicit false declaration and must be justified in the agent’s authority profile.
• All A2A-originated tool invocations must pass Policy Guard approval regardless of trust tier when a2a_tool_policy.require_a2a_approval: true. Trust tier governs default approval posture — it does not bypass the Policy Guard.

Metrics as Policy Inputs link

Runtime policies MAY consume canonical OS observability metrics as inputs to routing, fallback, and escalation decisions. The metric definitions below are owned by Synedrix OS Observability Metrics Spec and MUST NOT be redefined in runtime policy configuration.

Permitted metric inputs link

Default policy hooks link

Cost drift: When cost_drift_flag = true for a given (agent_id, model_id) slice, policies SHOULD trigger one of: model downgrade to a cheaper tier, temporary invocation throttle, or escalation to the HITL Gateway Agent for budget review. The default drift threshold for v0.1 is +30% relative to the rolling baseline (see §7.3 of the observability spec).

Hallucination and semantic validity: Interface agents and any agent surfacing outputs to end users SHOULD NOT pass responses where hallucination_probability exceeds the configured threshold (recommended default: 0.30) or where semantic_validity_flag = true. Suppressed responses must emit a structured failure outcome rather than silently dropping.

Risk alignment: Agents in risk_tier: medium, high, or critical MUST NOT be promoted from draft to active if any blocking evaluation suite reports a risk_alignment_score failure. This gate is enforced by the OS registry and is not bypassable by domain packs or business instances.

Tool reliability: When tool_success_rate for a named tool drops below the configured floor (recommended default: 0.90 over a 60-minute window), the runtime policy SHOULD escalate rather than continue retrying, and the Anomaly Detection Agent SHOULD be notified via the os.tool.reliability_aggregated event.

Tool authorization: The tool_success_rate metric, when persistently low for a specific tool, MAY trigger an automated tool_suspensions entry with suspension_scope: conditional to prevent cascading failures. This suspension must emit agent.tool.suspended events and must NOT be silent.

Versioning link

• Version: 0.4
• Supersedes: v0.3
• Related: Synedrix OS - Agent Spec, Synedrix OS Workflow Contract Spec, Synedrix OS Responsibility Matrix, Synedrix OS Core Principles, Synedrix OS Observability Metrics Spec, Synedrix OS Interoperability Protocol Strategy, Synedrix OS Orchestration & Runtime Strategy

Related Documents link

Tool Authorization link

• Synedrix OS - Agent Spec — tool_permissions array declares the capability ceiling; tool_authorization_policy in this spec can only restrict within that ceiling.
• Synedrix OS Interoperability Protocol Strategy — MCP and A2A governance principles; mcp_tool_policy and a2a_tool_policy in this spec implement those principles at the per-agent level.

Deployment link

• Synedrix OS Deployment Model Spec — Three canonical deployment modes; the deployment_mode field added in v0.2 implements that spec at the agent layer.
• Synedrix OS Core Principles — Principle 11 (Open by default, sovereign by design) is the governing constraint for the local model and air-gapped fields.

Agent Specifications link

• Synedrix OS - Agent Spec — Full agent anatomy; runtime policies govern the execution of agents defined there.
• Synedrix OS - Agent Registry Spec — Registry schema; active registry entries are required before a runtime policy can be applied.
• Synedrix OS - Agent Runtime Policy Spec v0.2 (deleted — superseded) — Previous version; superseded by this v0.3.

Architecture and Governance link

• Synedrix OS Workflow Contract Spec — Workflow standard; retry and compensation logic in this spec aligns with workflow error policies.
• Synedrix OS Responsibility Matrix — Ownership split; the OS/domain/instance columns apply to runtime policy field definitions.
• Synedrix OS Observability Metrics Spec — Defines cost_drift_flag, tool_success_rate, and other metrics that feed runtime policy decisions.

Teaching material link

• Synedrix OS Academy — Layer 4 teaching material. Chapter 02.3 covers policy enforcement, 02.4 the authority model and the capability ceiling, and 01.1 the model-role indirection behind primary_model and fallback_model. Teaching material, not normative: where a chapter disagrees with this spec, this spec wins.

Synedrix OS · May 2026