LangGraph — Agent Runtime

Platform 2 of 12·OS Layer 4 (Agent Runtime)·Required in all deployment modes

Scope of this page. Reference material for the LangGraph platform: what it is, what it is normally used for, and how and why Synedrix OS uses it. It is descriptive, not normative — where this page and a canonical spec in docs/os/ disagree, the canonical spec wins. Platform responsibilities are set by Tech Stack §13; the build-level mapping is the LangGraph Runtime Implementation Guide.

What LangGraph is link

LangGraph describes itself as “a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents.”

Its own documentation is emphatic about the level it operates at: “LangGraph is very low-level, and focused entirely on agent orchestration.” It does not abstract prompts or architecture. It provides the supporting infrastructure — “durable execution, streaming, human-in-the-loop, and more” — for any long-running, stateful workflow or agent. One of its stated core strengths is “the ability to mix deterministic steps with LLM-driven agentic steps in a single graph.”

The model is small and composable:

Durable execution is the property that follows from checkpointing rather than a separate feature. Persistence lets applications “resume after an interruption, recover from a failure, or remember information across interactions”. If a node fails mid-super-step, LangGraph “stores pending checkpoint writes from any other nodes that completed successfully at that super-step”, so resuming does not re-run the successful ones. The strength of the guarantee is configurable through three durability modes:

• "exit" — “LangGraph persists changes only when graph execution exits — successfully, with an error, or due to a human-in-the-loop interrupt.” Best performance, no mid-execution recovery.
• "async" — “LangGraph persists changes asynchronously while the next step executes.” Good performance and durability, with a small risk of a lost checkpoint on a crash.
• "sync" — “LangGraph persists changes synchronously before the next step starts.” Highest durability, some performance overhead.

Checkpointing also gives time travel: replaying from a prior checkpoint, or forking from one “with modified state to explore an alternative path”.

LangChain is a separate library from the same authors and is used inside LangGraph graphs, not alongside them as a peer platform. LangChain “provides create_agent: a minimal, highly configurable agent harness” and supplies the model, tool and integration abstractions. LangGraph’s own guidance is that LangChain components are commonly used to integrate models and tools, “but you don’t need to use LangChain to use LangGraph”. LangGraph “is built by LangChain Inc, the creators of LangChain, but can be used without LangChain.”

What LangGraph is normally used for link

The patterns LangGraph’s own documentation leads with, in its guide to workflows and agents:

• Prompt chaining — a fixed sequence of model calls where each step operates on the previous output, optionally with a programmatic gate between steps.
• Parallelization — fanning work out to several nodes in the same super-step and combining the results.
• Routing — classifying an input and directing it to a specialised downstream path.
• Orchestrator-worker — an orchestrator node that plans and delegates to dynamically created workers.
• Evaluator-optimizer — a generator node paired with an evaluator node that loops until the output passes.
• Agents — a dynamic tool-calling loop where the model “defines its own processes and tool usage” rather than following a predetermined code path.

The documentation draws the line as: “Workflows have predetermined code paths and are designed to operate in a certain order. Agents are dynamic and define their own processes and tool usage.” LangGraph covers both, and its central claim is that both can live in the same graph.

The general benefits it leads with are persistence (“build agents that persist through failures and can run for extended periods, resuming from where they left off”), human-in-the-loop (“incorporate human oversight by inspecting and modifying agent state at any point”), comprehensive memory across short and long term, and streaming.

The common thread is that LangGraph owns reasoning shape and execution state: how many turns, what loops back, what state accumulates, where a human is asked, and what survives a crash — not what business event started the work.

How Synedrix OS uses it link

LangGraph is the Agent Runtime of Synedrix OS and sits at Layer 4 of the twelve-layer taxonomy, whose brief is to “execute agents with bounded scope and lifecycle management”. It is required in all three deployment modes. It was introduced by ADR-OS-001, which split Layer 4 out of Orchestration (Layer 3) and left n8n as pure orchestration.

flowchart LR
  n1([LangGraph]):::term
  subgraph What it owns
    n2[Stateful agent graphs with checkpointing and durable execution]:::agent
    n3[The cyclic and multi-agent execution patterns]:::agent
    n4[Human-in-the-loop interrupts that suspend and resume a graph at a checkpoint wired to the OS HITL Gateway]:::agent
    n5[Tool-calling reasoning loops built with the LangChain library]:::agent
  end
  n1 --> n2
  subgraph What it does not own
    n6[Workflow triggers and business sequencing]:::warn
    n7[n8n]:::term
    n6 --> n7
    n8[Policy decisions]:::warn
    n9[Policy Guard]:::term
    n8 --> n9
    n10[Tool authorization resolution]:::warn
    n11[Orchestration]:::term
    n10 --> n11
    n12[LLM tracing prompts evaluations]:::warn
    n13[Langfuse]:::term
    n12 --> n13
    n14[Canonical business state]:::warn
    n15[Supabase PG17]:::term
    n14 --> n15
  end
  n1 --> n6
  subgraph Why LangGraph
    n16[Checkpointing gives auditable execution state]:::term
    n17[Explicit graphs beat implicit agent loops]:::term
    n18[Open source and self-hostable in full]:::term
  end
  n1 --> n16

What it owns link

Per Tech Stack §13, LangGraph owns:

• Stateful agent graphs with checkpointing and durable execution
• The cyclic and multi-agent execution patterns: iterative, consensus, reflect-and-revise, hierarchical
• Human-in-the-loop interrupts that suspend and resume a graph at a checkpoint, wired to the OS HITL Gateway
• Tool-calling reasoning loops built with the LangChain library: model abstraction, tool calling, structured output, RAG over Qdrant, and MCP adapters

LangChain is a library inside this platform, not a separate platform row in the canonical stack.

The LangGraph Runtime Implementation Guide fixes the mapping from OS concepts to LangGraph constructs. An agent becomes a compiled StateGraph; graph State carries correlation_id, causation_id and task input; the four declared execution patterns become specific topologies — iterative is a conditional edge looping back until a convergence predicate holds, reflect-and-revise is a generator node feeding a critic node, consensus is a fan-out to voter nodes with a reducer node computing quorum, and hierarchical is a supervisor node delegating to subgraphs. HITL approval is a LangGraph interrupt at a checkpoint, resumed by the HITL callback.

What it does not own link

This list is the whole point of the Layer 3 / Layer 4 split. LangGraph reasons; it does not decide what it is allowed to do.

How it is invoked link

LangGraph is invoked by n8n as a governed step over HTTP, MCP or A2A. The boundary contract is specified in Orchestration & Runtime Strategy §5, with a worked reference implementation in POC: n8n → LangGraph Governance Bridge (WF-OS-POC-001).

The invocation carries invocation_id, correlation_id, causation_id, agent_id, execution_pattern, deployment_mode, the resolved active_tool_set, and the task input. The orchestration layer has already persisted the immutable start row before calling the runtime. LangGraph returns the canonical Outcome Envelope with source.type: "agent" and the inherited correlation and causation IDs; n8n persists the terminal outcome and emits os.outcome.* events.

• The graph reads correlation_id and causation_id from the request into State and never mints new ones, so lineage does not break at the layer boundary.
• The executor is initialised with the resolved active_tool_set; any tool call outside it is rejected and emits agent.tool.unauthorized. LangGraph resolves nothing about authorization itself.
• deployment_mode: air-gapped forces local model bindings only, via Ollama or vLLM.

Agent-driven steps in a workflow declared under the Workflow Contract Spec reach LangGraph through this path; the agent_roles and approval_requirements fields of that contract are what determine which graph runs and where it must interrupt. Agent definitions themselves live in the Agent Registry, which is where decision_scope, execution_pattern and escalation_path are declared before any graph is built.

Observability, and why LangSmith is not in the stack link

LangGraph and LangChain emit traces to Langfuse at Layer 10, over OpenTelemetry or a native exporter, which is the same platform n8n’s agents trace to.

LangGraph’s own documentation routes observability, evaluation and deployment through LangSmith, and recommends it throughout. Synedrix OS deliberately does not take that recommendation. Per Tech Stack §13 and ADR-OS-001 §3.3 and §5.3, LangSmith is not part of the canonical stack on three grounds:

1. It is proprietary SaaS, which violates Principle 11 — open by default, sovereign by design.
2. It breaks Mode 3 (air-gapped), where no external API call of any kind is permitted.
3. It duplicates Langfuse, which already holds Layer 10, and the stack’s platforms must have non-overlapping responsibilities.

The ADR states the deciding axis explicitly: it is “Principle 11 + non-overlapping responsibilities, not capability”. LangGraph and LangChain are adopted because they are open source, self-hostable and fill a genuinely empty layer; LangSmith is rejected because it is none of the first two and overlaps the third. Crucially, “adopting LangGraph does not require adopting LangSmith — LangChain/LangGraph trace cleanly to Langfuse via OTel.”

LangSmith may be used as an optional developer-time convenience in cloud-connected Mode 1. It may not appear in a Mode 2 or Mode 3 deployment, and nothing in the OS may depend on it.

How it is operated link

The Synedrix OS self-hosted stack ships a reference LangGraph agent service, langgraph-agent, defined in langgraph-compose.yml in the synedrix-os-stack-self-hosted repository. It exposes the governed HTTP invocation endpoint on port 8765 on the synedrix_core Docker network, and connects to SearXNG as a read-only search tool, Langfuse for trace emission, and the LiteLLM proxy for model routing.

Checkpointer choice is the operational decision that matters most. LangGraph ships checkpointer implementations as separate installable libraries: langgraph-checkpoint with an in-memory saver “for experimentation”, langgraph-checkpoint-sqlite which is “ideal for experimentation and local workflows”, and langgraph-checkpoint-postgres which is “ideal for using in production”. The Postgres saver is the one that matters for Synedrix OS, because interrupts require a durable checkpointer to survive an approval wait: LangGraph’s documentation is explicit that in production this “should be a persistent checkpointer (e.g. backed by a database)”. A graph that interrupts for a human approval and holds that state only in memory is not a governed approval.

Note that a checkpointer is agent working state, not canonical business truth. memory_profile.working_memory maps to graph state plus a checkpointer; canonical memory access is a tool node performing a Supabase read. The two must not be collapsed.

Why LangGraph link

• It is a runtime, not a workflow engine. Layer 4 needs to hold reasoning state across turns and survive failures. n8n sequences and retries; LangGraph loops, accumulates state and resumes. That is exactly the separation ADR-OS-001 formalises.
• Interrupts are the native form of a governed approval. An interrupt suspends a graph at a checkpoint and waits indefinitely for external input, which is precisely the shape of an OS approval gate. The OS does not have to simulate human-in-the-loop with polling or timeouts.
• Checkpointing gives auditable execution state. Every super-step produces a snapshot, and time travel allows replaying or forking a prior checkpoint. A governed system must be able to answer what an agent knew at the moment it acted.
• Explicit graphs beat implicit agent loops. The four canonical execution patterns are declared in the agent registry and realised as named nodes and edges. Authority boundaries are readable from the topology rather than buried in a prompt.
• Open source and self-hostable in full. MIT licensed, runs as a Python service against local inference, which is what Modes 2 and 3 require and what keeps Principle 11 intact.
• LangChain underneath is shared vocabulary with Layer 3. n8n’s AI nodes are an implementation of LangChain’s JavaScript framework, so promoting a simple acyclic n8n agent to a stateful LangGraph agent is a deployment decision rather than a conceptual rewrite.

Deployment and licensing link

Self-hosting. LangGraph is a library installed with pip install -U langgraph (Python >= 3.11 for the CLI) and runs as an ordinary Python service under Docker or Kubernetes. A local server can be run with langgraph-cli. LangGraph’s own documentation routes production deployment through LangSmith Cloud and its self-hosted variants; Synedrix OS does not use that path, and instead runs the graph inside its own service behind the governed HTTP endpoint described above. That is a supported use — LangGraph “can be used standalone”.

Licence. Verified directly against the official repositories:

• github.com/langchain-ai/langgraph — MIT License, “Copyright (c) 2024 LangChain, Inc.”
• github.com/langchain-ai/langchain — MIT License, “Copyright (c) LangChain, Inc.”

Both match what Tech Stack §13 records (“MIT (LangGraph), MIT (LangChain)”). MIT places no restriction on commercial use, redistribution or delivery of the software to a customer as part of a product, so unlike n8n’s Sustainable Use License there is no open item here.

One boundary is worth stating plainly, because it is easy to lose: the MIT licence covers LangGraph and LangChain, not LangSmith. LangSmith is a proprietary hosted product from the same vendor and the surrounding documentation treats it as the default. Keeping it out of the canonical stack is an active decision that has to be re-made in every implementation, not a property inherited from the licence.

Official documentation link

• LangGraph overview
• Graph API overview — state, nodes, edges, reducers, super-steps
• Persistence — checkpointers against stores
• Checkpointers — threads, durability modes, checkpointer libraries
• Interrupts — pausing and resuming for human input
• Subgraphs
• Time travel — replay and fork
• Fault tolerance — retries, timeouts, error handlers
• Workflows and agents — the canonical pattern catalogue
• LangChain overview — the agent harness library used inside graphs
• LangGraph LICENSE — MIT
• LangChain LICENSE — MIT

Related Synedrix OS documents link

• Synedrix OS Tech Stack — normative platform responsibilities; §13 covers LangGraph.
• ADR-OS-001 — Agent Runtime Split — the decision that created Layer 4, adopted LangGraph and LangChain, and rejected LangSmith.
• Orchestration & Runtime Strategy — the n8n↔LangGraph boundary, routing rule and governance bridge.
• LangGraph Runtime Implementation Guide — OS concept to LangGraph construct, invocation contract, pattern topologies, compliance checklist.
• Layer Taxonomy Table — Layer 4 definition and platform mapping.
• Workflow Contract Spec — the contract whose agent_roles and approval_requirements drive graph invocation.
• Outcome Spec — the envelope every graph must return.
• Agent Registry — where decision_scope, execution_pattern and escalation_path are declared.
• Core Principles — Principle 11 and the three deployment modes that exclude LangSmith.
• POC: n8n → LangGraph Governance Bridge — WF-OS-POC-001, the first end-to-end Layer 3 → Layer 4 invocation.

Synedrix OS · Platform reference · LangGraph