Status: Canonical (adopted via ADR-OS-001) Implements: Core Principles — Principle 2 (Orchestration is the center of gravity), Principle 4 (Governance before execution), Principle 11 (Open by default, sovereign by design) Authority for: the division of responsibility between the Orchestration Layer (Layer 3) and the Agent Runtime Layer (Layer 4), the n8n↔LangGraph boundary contract, and the governance bridge that keeps a second execution engine inside OS governance.

Overview

This document defines the target architecture in which n8n owns orchestration (Layer 3) and LangGraph owns the agent runtime (Layer 4), with LangChain as the runtime’s agent/tool library and Langfuse retained as the LLM-engineering layer (Layer 10). It is the architecture decided in ADR-OS-001. The load-bearing content is §5 (Governance Integration): a second execution engine is only admissible if it cannot become an ungoverned shadow runtime.

1. Current state

n8n is named for Layer 3 (Orchestration) in the platform mapping, but Layer 4 (Agent Runtime) has no dedicated platform — n8n fills it implicitly. Every agent-driven step is an n8n AI Agent node, which is a low-code wrapper over LangChain (@n8n/n8n-nodes-langchain.agent). Consequences observed today:

  • The cyclic/stateful execution patterns (iterative, consensus, reflect-and-revise, hierarchical) are simulated with Code nodes that hand-manage iteration counters and convergence in $execution.customData.
  • High-stakes control is already pushed outside n8n where the visual graph is insufficient (e.g. the Trading watchdog).
  • Orchestration concerns (sequencing, gates, glue) and agent-reasoning concerns (stateful multi-step cognition) are entangled in one tool, contrary to the Layer 3/Layer 4 separation in the taxonomy.

2. Target architecture

Two platforms, one per layer, with a single well-defined boundary.

LayerPlatformOwns
3 — Orchestrationn8nTriggers, input validation, business-workflow sequencing, deterministic steps, approval/HITL routing, sub-workflow composition, outcome persistence, event emission.
4 — Agent RuntimeLangGraphStateful/cyclic/multi-agent reasoning: graph state, checkpoints, HITL interrupts, consensus/reflection loops. Built with LangChain (models, tools, RAG, MCP adapters).
10 — LLM EngineeringLangfuse (retained)Prompt versioning, traces, token/cost, evaluations — for both n8n agents and LangGraph agents.

2.1 The n8n ↔ LangGraph boundary

LangGraph is invoked as a governed step inside an n8n workflow — never as an independent entrypoint that bypasses orchestration. The boundary is a contract, not a shared runtime:

flowchart TD
  T[n8n: trigger]:::agent --> IV[input validation]:::agent --> CI[correlation-id init]:::agent
  CI --> G[n8n: deterministic glue, policy pre-gate]:::agent
  G --> INV[n8n → LangGraph: invoke runtime via HTTP / MCP / A2A]:::agent
  INV -.-> RQ[request carries: correlation_id, causation_id, task input, resolved active_tool_set, deployment_mode]:::term
  INV --> LG[LangGraph: stateful agent graph executes, with in-graph policy/HITL calls]:::agent
  LG --> RT[LangGraph → n8n: returns the canonical Outcome Envelope]:::agent
  RT --> OP[n8n: outcome persist, append-only → emit os.outcome.* → continue / gate / escalate]:::agent
  • Transport: HTTP for internal calls; MCP when the runtime is consumed as a tool/context server; A2A when delegating to or from another agent system at the platform edge. All three are already governed by the Interoperability Strategy.
  • Return contract: LangGraph MUST return the canonical Outcome Envelope so the boundary produces no lineage or observability gap.

3. New role of n8n

n8n stops being the agent reasoning runtime and becomes the orchestration kernel only.

Stays in n8n (Layer 3)Moves to LangGraph (Layer 4)
Event triggers (Hookdeck ingress, webhooks, schedule, human-command)Multi-step agent cognition with evolving state
Input validation and schema normalization (deterministic steps)Cyclic reasoning: iterate, reflect-and-revise, converge
Business-workflow sequencing and sub-workflow compositionMulti-agent consensus / quorum voting
Policy Guard and HITL routing (the gates and waits)Hierarchical agent delegation with shared graph state
Outcome persistence (agent_invocations, workflow_outcomes) and event emissionTool-calling reasoning loops with checkpointed recovery
Deterministic glue: Set, Merge, Filter, HTTP, DB read/write—

Simple acyclic agents MAY remain as n8n AI Agent nodes (see §4). n8n always owns the trigger, the surrounding sequence, the gates, and outcome persistence — even when a reasoning step runs in LangGraph.

4. Decision-boundary rule

The workflow’s execution_pattern field is the router that selects the runtime engine.

execution_patternRuntime engineRationale
sequentialn8n AI Agent node (acceptable)Linear, acyclic
conditionaln8n AI Agent node (acceptable)Branch on a field
paralleln8n AI Agent node (acceptable)Independent branches → merge
fan-out-fan-inn8n AI Agent node (acceptable)Scatter/gather, no shared evolving state
pipelinen8n AI Agent node (acceptable)Linear deterministic + agent chain
iterativeLangGraphLoop with convergence + checkpointed state
reflect-and-reviseLangGraphGenerator/critic cycle with shared state
consensusLangGraphMulti-voter quorum with state aggregation
hierarchicalLangGraphSub-agent delegation with shared graph state

Guideline: if the pattern requires shared, evolving state across cycles or agents, it belongs in LangGraph. If it is acyclic plumbing, it stays in n8n.

5. Governance integration (load-bearing)

A second execution engine is admissible only if it cannot bypass OS governance or observability. The following bridge requirements make LangGraph a governed runtime, not a shadow runtime. Each maps to an OS invariant.

5.1 Lineage continuity

  • correlation_id and causation_id are passed into the LangGraph invocation and returned unchanged in the Outcome Envelope. The runtime never mints a new correlation_id when one is supplied.
  • Any Supabase write or event emission inside the runtime carries the inherited correlation_id.
  • Invariant satisfied: every workflow is observable end-to-end — no lineage gap at the boundary.

5.2 Policy-aware execution

  • Policy Guard (os-agt-002) is callable from inside LangGraph nodes. Any side-effecting (write) tool call is submitted to Policy Guard before execution, identically to the n8n tool-level gate.
  • HITL Gateway (os-agt-004) is reachable from inside the graph via a durable interrupt: the graph pauses (checkpoint), n8n’s Wait/callback mechanism collects the human decision, and execution resumes.
  • Invariant satisfied: no agent writes to production without policy-aware orchestration visibility.

5.3 Tool authorization

  • The three-layer model (capability ceiling → runtime restriction → instance override) from the Runtime Policy Spec is resolved by orchestration and the active tool set is passed into the LangGraph invocation.
  • The LangGraph executor rejects any tool call outside the resolved active set and emits agent.tool.unauthorized — the ceiling rule holds in the new runtime.
  • MCP/A2A tool policies (mcp_tool_policy, a2a_tool_policy) apply unchanged.
  • Invariant satisfied: every agent has explicit authority boundaries; no MCP/A2A interaction bypasses governance.

5.4 Outcomes and observability

  • Every LangGraph agent invocation returns the canonical Outcome Envelope and emits os.outcome.* events.
  • LLM traces flow to Langfuse (via OpenTelemetry / native exporter) — the same Layer 10 platform used by n8n agents. LangSmith is not used as a stack platform.
  • Invariant satisfied: every workflow is observable end-to-end.

5.5 Read-only and append-only guarantees

  • Audit & Lineage (os-agt-008) remains strictly read-only and never appears in any agent’s tools_allowed — including LangGraph agents.
  • The agent registry remains append-only at runtime; LangGraph agents are registered through the same registry schema and lifecycle.
  • Invariant satisfied: the Audit & Lineage read-only and registry append-only invariants.

6. Deployment-mode fit

Moden8nLangGraphLangfuseLangSmith
1 — Cloud-connectedSelf-hostedSelf-hostedSelf-hostedOptional dev-time convenience only
2 — Self-hosted hybridSelf-hostedSelf-hostedSelf-hostedNot permitted
3 — Air-gappedSelf-hostedSelf-hosted (local models only)Self-hostedNot permitted

LangGraph (MIT) and LangChain are self-hostable and run with local inference (Ollama/vLLM) in Modes 2 and 3, so the seam split preserves Principle 11 and all deployment modes. LangSmith is excluded from the canon because it is proprietary SaaS and breaks the Mode 3 air-gapped invariants; it duplicates Langfuse regardless.

7. Recommendation

Adopt the seam split: n8n → pure orchestration (Layer 3), LangGraph → agent runtime (Layer 4) built with LangChain, Langfuse retained for LLM engineering, LangSmith rejected from the canonical stack. Route by execution_pattern (§4). Build the §5 governance bridge as a precondition — the decision is non-compliant without it. The Trading domain’s 23-agent consensus/VETO engine is the recommended first validation case study.

Versioning

  • Version: 0.1
  • Supersedes: none — first version
  • Related: Synedrix OS ADR-OS-001 — Agent Runtime Split

Core Principles and Canonical Reference

Decision and architecture

Runtime, implementation, and interop

Synedrix OS · June 2026