AgentGraph Compiler 🛠️🦜🔗

Compile structured YAML configurations into production‑grade LangGraph multi‑agent architectures.

AgentGraph Compiler eliminates LangGraph boilerplate by letting you declare your agent topology in YAML. Define nodes, chains, tools, edges, sub‑agents, and supervisors — the compiler scaffolds a complete, modular, runnable Python codebase ready for production.

📖 Full Developer Wiki → — complete reference for every YAML field, node type, edge type, and generated output.

---

🚀 Key Features

• Declarative Multi‑Agent Workflows — Define the full agent graph (nodes, edges, sub‑agents, supervisor routing) in simple YAML.
• TypedDict State (LangGraph‑native) — Generates TypedDict classes with Annotated[..., add_messages] reducers by default. Pydantic BaseModel is available via state_type: pydantic.
• Supervisor Orchestration — type: supervisor nodes generate an LLM-driven routing scaffold with configurable route_field and compile-time validation.
• Hierarchical Parent-Scoped Output — Sub-agent code is generated inside subdirectories under the parent source_dir (e.g. my_agent/adaptive_rag/).
• All LangGraph Edge Types — standard, conditional, supervisor_route, tool_loop, fan_out (Send API), and interrupt_before human‑in‑the‑loop.
• Parallel Fan-Out via Send API — type: fan_out dispatches one node to multiple inputs simultaneously using langgraph.types.Send.
• Async Node Scaffolding — async_fn: true generates async def node functions with notes on awaiting LLM/tool calls.
• Multi-Model LLM Support — provider: openai | anthropic | ollama | groq per chain or supervisor node with model-specific imports scaffolded.
• MCP Tool Client Stubs — source: mcp in the tools block scaffolds a Model Context Protocol client.
• Checkpointing — memory.type: sqlite | in_memory wires SqliteSaver / MemorySaver into workflow.compile().
• Real-time Streaming — Generated main.py uses app.stream() with thread config for node-by-node event output.
• Mermaid Flowcharts — Auto-generates flowchart.md with nested subgraph rendering and distinct supervisor styling.
• CLI — forge compile, forge validate, forge init, forge ingest, plus --dry-run preview.

---

🛠️ Quick Start

1. Install

Option A — PyPI (once published)

pip install agentgraph-compiler
# or
uv add agentgraph-compiler

Option B — Directly from GitHub (available now, no clone needed)

pip install agentgraph-compiler

Option C — Clone for local development

git clone https://github.com/cvaws/agentgraph-compiler.git
cd agentgraph-compiler
uv sync

After any install, the forge CLI is available in your environment:

forge --help

2. Initialize a Project

uv run forge init

Creates:

• configs/config.yaml — Global settings (models, vector store, embedding)
• configs/agents/agent.yaml — Starter agent workflow spec

3. Configure Environment

cp .env.example .env
# Fill in OPENAI_API_KEY (and optionally LANGCHAIN_API_KEY for tracing)

4. Validate Configuration

uv run forge validate configs/agents/agent.yaml

Runs Pydantic schema validation and checks all edge targets exist as declared nodes — without writing any files.

5. Compile Agent Topology

# Preview without writing files
uv run forge compile configs/agents/agent.yaml --dry-run

# Compile Python scaffold
uv run forge compile configs/agents/agent.yaml

6. Run the Agent

uv run python my_agent/main.py "How do I build multi-agent graphs with AgentGraph Compiler?"

---

💡 Try an Example

Six ready-to-compile examples cover every supported LangGraph pattern — all configs live in configs/agents/examples/:

Example	Pattern
simple_rag/	Single-agent RAG with conditional edges
multi_agent/	Supervisor + 2 sub-agents via graphRef
react_agent/	ReAct tool_loop + MCP tool client
parallel_fanout/	Parallel fan_out via Send API
human_in_loop/	interrupt_before + approve/revise cycle
async_agent/	async_fn: true async nodes

# Example: compile and run the ReAct agent
uv run forge compile configs/agents/examples/react_agent/agent.yaml
uv run python react_agent/main.py "What is the current price of Bitcoin?"

See configs/agents/examples/README.md for compile/run instructions for all examples.

---

📖 CLI Reference

Command	Usage	Description
compile	forge compile <path> [--dry-run]	Compiles YAML into Python scaffolds under source_dir.
validate	forge validate <path>	Schema validation + edge target reference checks.
init	forge init [directory]	Scaffolds starter configs/config.yaml and agent.yaml.
ingest	forge ingest [--config path]	Ingests URLs from config.yaml into Qdrant vector store.

---

⚙️ Global Configuration (configs/config.yaml)

Centralize model providers, vector store settings, and ingestion URLs:

models:
  chat:
    name: gpt-4o
    temperature: 0.5
  embedding:
    name: text-embedding-3-small
    provider: openai

vector_store:
  name: qdrant
  url: "http://localhost:6333"
  collection: "agent"

ingestion:
  urls:
    - "https://lilianweng.github.io/posts/2023-06-23-agent/"

---

📖 YAML Reference

Graph Config

version: "1.0"

graph:
  source_dir: "my_agent"               # Output directory for scaffolded Python code
  state_type: typeddict                 # "typeddict" (default, LangGraph-native) | "pydantic"
  state_schema: "graphs.state.AgentState"
  state_fields:
    messages: "List[BaseMessage]"       # → Annotated[List[BaseMessage], add_messages]
    next: "str"                         # Supervisor routing field
    context: "dict"
  shared_fields: [messages, context]    # Fields readable/writable by sub-agents
  memory:
    type: sqlite                        # "sqlite" | "in_memory" | omit for stateless
    db_path: ".checkpoints/agent.db"

Node Types

nodes:
  # Standard node — calls a Python function
  my_node:
    module: "graphs.nodes.my_node"
    function: "my_node"
    chains: ["my_chain"]              # Chains to import into the node
    description: "Does something useful."

  # Async node
  async_node:
    module: "graphs.nodes.async_node"
    async_fn: true                    # Scaffolds `async def async_node(state)`

  # Supervisor node — LLM-driven router
  supervisor:
    type: supervisor
    provider: openai                  # openai | anthropic | ollama | groq
    llm: gpt-4o
    route_field: next                 # State field the supervisor writes to (default: "next")
    system_prompt: "templates/supervisor.prompt"
    routes_to: [rag_agent, code_agent]

  # Sub-agent reference — compiles recursively, nested under parent source_dir
  rag_agent:
    graphRef: "sub-agents/adaptive-rag.yaml"
    description: "Adaptive RAG sub-agent."

Chain Config

chains:
  retrieval_grader:
    module: "graphs.chains.retrieval_grader"
    runnable: "retrieval_grader"
    provider: anthropic                         # Per-chain provider
    llm: claude-3-5-haiku-20241022
    temperature: 0.0
    prompt: "retrieval_grader"                  # Loads templates/retrieval_grader.prompt
    tools: [web_search]                         # Binds tool imports into chain scaffold
    description: "Binary relevance grader."

Edge Types

edges:
  # Standard directed edge
  - type: standard
    start: retrieve
    end: grade_documents

  # Conditional edge with a router function
  - type: conditional
    start: grade_documents
    router:
      module: "routers.router"
      function: "route_after_grading"
    mappings:
      web_search: web_search
      generate: generate

  # Supervisor routing — dispatches based on state[route_field]
  - type: supervisor_route
    start: supervisor
    routes_to: [rag_agent, code_agent]
    end: post_process

  # Tool loop — LLM node ↔ ToolNode
  - type: tool_loop
    start: llm_node
    tool_node: tools
    end: END

  # Fan-out — parallel dispatch via Send API
  - type: fan_out
    start: coordinator
    target: worker              # Node to fan out to (runs in parallel)
    field: tasks                # State field (iterable) to fan out over
    key: task                   # Key name in each Send payload
    end: aggregator

  # Human-in-the-loop — pause before this node
  - type: standard
    start: generate
    end: human_review
    interrupt_before: true

Tool Config

tools:
  web_search:
    module: "graphs.tools.web_search"
    function: "web_search"
    description: "Queries Tavily for web results."

  # MCP Tool Client stub
  my_mcp_tool:
    module: "graphs.tools.my_mcp_tool"
    function: "my_mcp_tool"
    source: mcp
    server_url: "http://localhost:8000/mcp"
    description: "Calls remote MCP server."

---

📊 Generated Flowchart

AgentGraph Compiler auto-generates flowchart.md for every compiled agent:

flowchart TD
    START([START]) --> supervisor{{"Supervisor: supervisor\n(Routes request to sub-agent)"}}
    supervisor -.->|rag_agent| rag_agent__START
    supervisor -.->|code_agent| code_agent__START

    subgraph rag_agent ["rag_agent (Adaptive RAG Sub-Agent)"]
        direction TB
        rag_agent__START --> retrieve["retrieve\n(Pulls document chunks from vector store)"]
        retrieve --> grade_documents["grade_documents"]
        grade_documents --> generate["generate"]
    end

    subgraph code_agent ["code_agent (Code Generator Sub-Agent)"]
        direction TB
        code_agent__START --> plan["plan\n(Breaks task into plan)"]
        plan --> write_code["write_code"]
    end

    rag_agent__END --> post_process["post_process\n(Formats final response)"]
    code_agent__END --> post_process
    post_process --> END([END])

    classDef supervisorStyle fill:#d35400,stroke:#fff,stroke-width:2px,color:#fff;
    class supervisor supervisorStyle;
    classDef nodeStyle fill:#2980b9,stroke:#fff,stroke-width:2px,color:#fff;
    class post_process nodeStyle;

---

📁 Generated Output Structure

forge compile configs/agents/agent.yaml scaffolds the full hierarchy under source_dir:

my_agent/                               ← Parent source_dir
├── flowchart.md                        ← Mermaid diagram of the multi-agent DAG
├── main.py                             ← Runnable entrypoint with app.stream()
├── graphs/
│   ├── __init__.py
│   ├── graph.py                        ← Compiled StateGraph + checkpointer
│   ├── state.py                        ← TypedDict AgentState with add_messages reducer
│   ├── chains/
│   │   └── post_process_chain.py
│   └── nodes/
│       ├── supervisor.py               ← LLM routing scaffold
│       └── post_process.py
│
├── adaptive_rag/                       ← Sub-agent nested under my_agent/
│   ├── graphs/
│   │   ├── graph.py
│   │   ├── state.py
│   │   └── nodes/
│   └── routers/
│
└── code_agent/                         ← Sub-agent nested under my_agent/
    ├── graphs/
    └── routers/

---

🔍 Observability (LangSmith)

Enable full step-by-step tracing in .env:

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langchain_api_key
LANGCHAIN_PROJECT=AgentGraph-Compiler-Agents

---

🧪 Tests

uv run pytest -v

CI runs on every push via .github/workflows/ci.yml.

---

🤝 Contributing

See CONTRIBUTING.md for dev setup, how to add new edge/node types, and the PR process.

---

📦 License

Released under the Apache 2.0 License. Version 0.2.5.