Agent Runtime
Layer 4 of 12·Slice: Orchestration core·Platform: LangGraph
Scope of this page. Reference material for the Agent Runtime layer: what it owns, what it must not own, and how Synedrix OS implements it today. It is descriptive, not normative — where this page and the Layer Taxonomy Table disagree, the taxonomy table wins.
What this layer is
The Agent Runtime Layer executes agents with bounded scope and lifecycle management. It owns agent lifecycle, invocation context, execution state, and communication patterns — the mechanics of how a single agent-driven step actually runs, holds state across turns, and returns a result, as distinct from the Orchestration Layer’s concern of what happens next across a whole workflow.
flowchart LR
n1([Agent Runtime]):::term
subgraph What it owns
n2[Agent lifecycle]:::agent
n3[Invocation context]:::agent
n4[Execution state]:::agent
n5[Communication patterns]:::agent
end
n1 --> n2
subgraph What it must not own
n6[UI concerns]:::warn
n7[Human Interface Layer]:::term
n6 --> n7
n8[Business-specific workflow routing]:::warn
n9[Orchestration Layer]:::term
n8 --> n9
n10[Workflow triggers and business sequencing]:::warn
n11[Orchestration Layer]:::term
n10 --> n11
n12[Policy decisions]:::warn
n13[Policy Guard Agent]:::term
n12 --> n13
n14[Tool authorization resolution]:::warn
n15[Orchestration Layer]:::term
n14 --> n15
n16[LLM tracing prompts evaluations]:::warn
n17[Langfuse]:::term
n16 --> n17
n18[Canonical business state]:::warn
n19[Supabase PG17]:::term
n18 --> n19
end
n1 --> n6
subgraph Interfaces with
n20[Orchestration]:::check
n21[Memory]:::check
n22[Tools]:::check
n23[Observability]:::check
end
n1 --> n20
What it owns
Per the Layer Taxonomy Table, Agent Runtime owns the following:
- Agent lifecycle — how an agent-driven step is instantiated, executed, and terminated for a given invocation.
- Invocation context — the inputs, resolved tool set, and deployment mode an agent runs with.
- Execution state — graph state, checkpoints, and any working memory accumulated during a run.
- Communication patterns — how nodes/agents within a run pass state to one another (fan-out, supervisor delegation, generator/critic loops, and so on).
What it must not own
The layer executes agents; it does not decide what they’re allowed to do or what happened outside its own run.
| Concern | Correct owner |
|---|---|
| UI concerns | Human Interface Layer |
| Business-specific workflow routing | Orchestration Layer (n8n) |
| Workflow triggers and business sequencing | Orchestration Layer (n8n) |
| Policy decisions | Policy Guard Agent (os-agt-002), per the Agent Registry |
| Tool authorization resolution | Orchestration Layer — it resolves the active tool set and passes it in; the runtime only enforces it |
| LLM tracing, prompts, evaluations | Langfuse (Layer 10) |
| Canonical business state | Supabase PG17 (Layer 7) |
Interfaces with
The Agent Runtime is invoked by, and reports back to, the layers around it rather than acting as an independent entrypoint.
- Orchestration — n8n invokes this layer as a governed step whenever a workflow’s
execution_patternis stateful or cyclic, carryingcorrelation_id,causation_id,agent_id,deployment_mode, and the resolvedactive_tool_set, and receiving the canonical Outcome Envelope back. - Memory — graph state and a checkpointer provide in-session working memory; canonical, semantic, graph, and temporal recall are all modeled as explicit tool calls rather than ambient context, keeping memory access a governed, auditable action.
- Tools — LangChain-bound tools are the runtime’s only path to external systems, and the executor rejects any tool call outside the passed-in active tool set.
- Observability — every invocation emits Langfuse traces and returns an Outcome Envelope so a run inside the runtime is exactly as observable as a run entirely inside n8n.
How Synedrix OS implements it
The LangGraph Runtime Implementation Guide fixes the mapping from OS concepts to concrete LangGraph constructs: an agent-driven step becomes a compiled StateGraph, graph State carries correlation_id, causation_id, and task input, and the four cyclic/multi-agent execution patterns become specific topologies — iterative is a conditional edge looping back to the agent node until a convergence predicate holds, reflect-and-revise is a generator node feeding a critic node with a conditional exit, consensus is a fan-out to voter nodes reduced by a quorum function, and hierarchical is a supervisor node delegating to sub-graphs whose Outcome Envelopes nest into the parent’s execution_context. HITL approval is modeled as a LangGraph interrupt at a checkpoint, resumed by the same callback mechanism n8n’s Wait node uses.
The invocation contract is fixed in both directions. n8n calls LangGraph with a request carrying correlation_id, causation_id, agent_id, execution_pattern, deployment_mode, active_tool_set, and the task input; LangGraph must return the canonical Outcome Envelope with source.type: "agent" and the inherited correlation and causation IDs unchanged. Three rules make this a governed bridge rather than a second, ungoverned runtime: the graph never mints a new correlation_id; the executor is initialized only with the passed-in active_tool_set and rejects and logs (agent.tool.unauthorized) anything outside it; and deployment_mode: air-gapped forces local model bindings (Ollama/vLLM) only.
The Agent Spec governs what an agent is independent of which engine runs it — identity, purpose, authority, prompt policy, contracts, tool permissions, memory profile, task surface, workflow roles, interoperability, runtime policy, policy bindings, and observability. Its optional runtime_policy.runtime_engine field (n8n-aiagent | langgraph) is what actually selects this layer for a given agent: cyclic or multi-agent execution_pattern values require langgraph, while simple acyclic agents may declare n8n-aiagent or omit the field and default to it. The agent’s canonical agent_id and name are stable across either engine — moving an agent from n8n to LangGraph is a deployment decision, not a re-registration.
Platform mapping
LangGraph is the sole platform mapped to this layer, with LangChain as a library inside it rather than a separate platform row.
| Platform | Notes |
|---|---|
| LangGraph | Stateful/cyclic/multi-agent reasoning runtime; built with the LangChain library; invoked by n8n as a governed step. See ADR-OS-001. |
OS agents at this layer
One OS-owned agent is registered at this layer.
| Agent ID | Name | Decision scope | What it does |
|---|---|---|---|
os-agt-009 | General Chat Agent | recommend | Answers natural-language questions about Synedrix OS by retrieving grounded context from a semantic knowledge base (Qdrant, read-only) and composing a cited response, for standalone chat surfaces such as a public website that sit outside any domain pack. It is invoked directly as a standalone LangGraph service with no owning n8n workflow — a bounded exception to the usual n8n-fronted invocation path, compliant only while its decision_scope stays recommend and no write-class tool is bound. |
Layer principles that apply
- Layer Principle 2 — Controls before execution. The governance bridge — Policy Guard reachability, HITL interrupts, tool-authorization enforcement, and mandatory Outcome Envelope returns — is what keeps this layer from becoming an execution path that bypasses governance for convenience.
- Layer Principle 4 — Memory is shared, access is scoped. Working memory lives in graph state and a checkpointer; canonical, semantic, and graph recall are explicit, scoped tool calls rather than context an agent is handed ambiently.
Related Synedrix OS documents
- Layer Taxonomy Table — the authoritative row for this layer.
- LangGraph Runtime Implementation Guide — OS concept to LangGraph construct, invocation contract, pattern topologies, compliance checklist.
- ADR-OS-001 — the decision that created this layer’s dedicated platform.
- Agent Spec — full agent anatomy, including the
runtime_enginefield that selects this layer. - LangGraph platform reference — what LangGraph is, what it is normally used for, and its licence position.
Synedrix OS · Layer reference · Agent Runtime