> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idun-group.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LangGraph

> Connect a LangGraph agent to Idun Engine with graph-based workflows, AG-UI streaming, and persistent checkpointing.

LangGraph is the primary framework integration in Idun Engine. It supports full AG-UI streaming, CopilotKit, and persistent checkpointing through in-memory, SQLite, or PostgreSQL backends.

<Tip>
  Want to start from working code? The [agent templates](/templates) include 7 LangGraph examples covering tool calling, structured I/O, and multi-step workflows.
</Tip>

## Code

```python agent.py theme={"theme":{"light":"github-light","dark":"github-dark"}}
from typing import Annotated, TypedDict

from langchain_google_genai import ChatGoogleGenerativeAI
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages


class State(TypedDict):
    messages: Annotated[list, add_messages]


llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash")


def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages"])]}


graph = StateGraph(State)
graph.add_node("chatbot", chatbot)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)
```

## Config

```yaml config.yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
server:
  api:
    port: 8000

agent:
  type: LANGGRAPH
  config:
    name: "my-langgraph-agent"
    graph_definition: "./agent.py:graph"
    checkpointer:
      type: sqlite
      db_url: "sqlite:///conversations.db"
```

## How it works

The LangGraph adapter wraps your `StateGraph` for production serving. Four stages, all driven by `agent.config` in `config.yaml`:

1. **Load.** `graph_definition` is parsed as `<file_path>:<variable_name>`. The adapter resolves it as a file path first (relative or absolute), then falls back to a Python module import path (`my_pkg.agent:graph`). Both work.
2. **Validate.** The exported variable must be a `StateGraph`. A `CompiledStateGraph` is accepted: the engine extracts `.builder` and recompiles with the engine-managed checkpointer and store, preserving any `interrupt_before` and `interrupt_after` you supplied to `.compile()`. A warning is logged when this path is taken.
3. **Compile.** The engine compiles the `StateGraph` with the checkpointer configured in `config.yaml` (`memory`, `sqlite`, or `postgres`) and wraps the result in `LangGraphAGUIAgent` from CopilotKit for AG-UI event streaming.
4. **Serve.** Chat requests POST to `/agent/run` with the AG-UI streaming protocol. The engine emits typed events (`RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `STEP_STARTED`, `STEP_FINISHED`, `RUN_FINISHED`) as SSE `data:` lines.

The capabilities endpoint introspects the compiled graph to detect chat vs structured input/output modes. A `StateGraph(state_schema)` with a `messages` field is treated as chat; an explicit `StateGraph(state, input_schema=..., output_schema=...)` declares a structured contract.

Source: [`libs/idun_agent_engine/src/idun_agent_engine/agent/langgraph/langgraph.py`](https://github.com/Idun-Group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/langgraph/langgraph.py).

## Notes

<Note>
  **Export the uncompiled `StateGraph`.** If you export a `CompiledStateGraph` (the result of `.compile()`), the engine extracts the original `StateGraph` via `.builder` and recompiles with the engine-managed checkpointer and store. Compile options like `interrupt_before` and `interrupt_after` are preserved. A warning is logged when this happens.
</Note>

<Note>
  **Import type annotations directly.** The engine introspects annotations when loading the graph. `from __future__ import annotations` produces deferred string annotations (PEP 563), and the resolver raises `NameError` on names like `Annotated` at graph-build time.
</Note>

<Note>
  **Always include a `checkpointer:` block.** LangGraph requires one at request time; requests fail with `No checkpointer set` when it is missing. Use `type: memory` for ephemeral state, `type: sqlite` or `type: postgres` for persistence. See [Memory and checkpointing for LangGraph](/memory/langgraph) for backend options.
</Note>

## Next steps

<Card title="Memory and checkpointing details" icon="database" horizontal href="/memory/langgraph">
  Backend options and configuration for persistent state.
</Card>

<Card title="Guardrails" icon="shield" horizontal href="/guardrails/overview">
  Add safety guards to your agent inputs and outputs.
</Card>

<Card title="Observability" icon="activity" horizontal href="/observability/overview">
  Trace runs, monitor latency, and inspect token usage.
</Card>

<Card title="MCP Servers" icon="plug" horizontal href="/mcp-servers/overview">
  Connect external tools through the Model Context Protocol.
</Card>