# langchain-ai/langgraph-swarm-py architecture

> Architecture diagram of the GitHub repository langchain-ai/langgraph-swarm-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/langgraph-swarm-py
- Repository: https://github.com/langchain-ai/langgraph-swarm-py

## Overview

LangGraph Swarm is a Python library for assembling specialized agents into a shared-state graph that can transfer control between agents and resume with the last active agent. The principal workflow is to create handoff tools, supply agents to create_swarm, compile the resulting graph, and invoke it across turns. The graph distinguishes handoff construction and destination discovery from swarm assembly and entry routing. README-documented memory, streaming, and human-in-the-loop capabilities are provided through LangGraph; source excerpts do not show their internal wiring.

Main entry points: [`langgraph_swarm/swarm.py`](https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/swarm.py) (Swarm builder), [`langgraph_swarm/handoff.py`](https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/handoff.py) (Handoff tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assembly["Swarm assembly"]
  node_swarm_builder["Swarm builder<br/>[swarm.py]"]
  node_state_router["Active-agent router<br/>[swarm.py]"]
end

subgraph group_transfer["Agent handoffs"]
  node_handoff_tool["Handoff tool<br/>[handoff.py]"]
  node_destination_discovery["Destination discovery<br/>[handoff.py]"]
end

subgraph group_runtime["Graph runtime"]
  node_compiled_graph["Compiled swarm"]
  node_conversation_state[("Conversation state")]
  node_langgraph_runtime["LangGraph runtime"]
  node_memory_services[("Memory services")]
  node_human_review(("Human review"))
  node_streaming["Streaming output"]
end

node_developer(("Application developer"))
node_agent_defs["Configured agents"]
node_caller(("Application caller"))

node_developer -->|"creates"| node_handoff_tool
node_developer -->|"assembles"| node_swarm_builder
node_agent_defs -->|"supplies agents"| node_swarm_builder
node_swarm_builder -->|"discovers destinations"| node_destination_discovery
node_swarm_builder -->|"adds router"| node_state_router
node_swarm_builder -->|"returns graph"| node_compiled_graph
node_state_router -->|"routes entry"| node_compiled_graph
node_handoff_tool -->|"updates messages"| node_conversation_state
node_handoff_tool -->|"transfers control"| node_compiled_graph
node_destination_discovery -->|"provides destinations"| node_swarm_builder
node_caller -->|"invokes"| node_compiled_graph
node_compiled_graph -.->|"executes on"| node_langgraph_runtime
node_compiled_graph -.->|"shares messages"| node_conversation_state
node_langgraph_runtime -.->|"supports persistence"| node_memory_services
node_langgraph_runtime -.->|"supports review"| node_human_review
node_langgraph_runtime -.->|"supports streaming"| node_streaming

click node_handoff_tool "https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/handoff.py"
click node_destination_discovery "https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/handoff.py"
click node_swarm_builder "https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/swarm.py"
click node_state_router "https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/swarm.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_swarm_builder,node_state_router toneBlue
class node_handoff_tool,node_destination_discovery toneAmber
class node_compiled_graph,node_conversation_state,node_langgraph_runtime,node_memory_services,node_human_review,node_streaming toneMint
class node_developer,node_agent_defs,node_caller toneIndigo
```

## Components

### Swarm assembly

- [Swarm builder](https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/swarm.py): `langgraph_swarm/swarm.py`
- [Active-agent router](https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/swarm.py): `langgraph_swarm/swarm.py`

### Agent handoffs

- [Handoff tool](https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/handoff.py): `langgraph_swarm/handoff.py`
- [Destination discovery](https://github.com/langchain-ai/langgraph-swarm-py/blob/main/langgraph_swarm/handoff.py): `langgraph_swarm/handoff.py`

### Graph runtime

- **Compiled swarm**
- **Conversation state**
- **LangGraph runtime**
- **Memory services**
- **Human review**
- **Streaming output**

### Other components

- **Application developer**
- **Configured agents**
- **Application caller**

## Connections

- Application developer → Handoff tool: creates (evidence: `README.md`)
- Application developer → Swarm builder: assembles (evidence: `README.md`)
- Configured agents → Swarm builder: supplies agents (evidence: `langgraph_swarm/swarm.py`)
- Swarm builder → Destination discovery: discovers destinations (evidence: `langgraph_swarm/swarm.py`)
- Swarm builder → Active-agent router: adds router (evidence: `langgraph_swarm/swarm.py`)
- Swarm builder → Compiled swarm: returns graph (evidence: `langgraph_swarm/swarm.py`)
- Active-agent router → Compiled swarm: routes entry (evidence: `langgraph_swarm/swarm.py`)
- Handoff tool → Conversation state: updates messages (evidence: `langgraph_swarm/handoff.py`)
- Handoff tool → Compiled swarm: transfers control (evidence: `langgraph_swarm/handoff.py`)
- Destination discovery → Swarm builder: provides destinations (evidence: `langgraph_swarm/swarm.py`)
- Application caller → Compiled swarm: invokes (evidence: `README.md`)
- Compiled swarm → LangGraph runtime: executes on
- Compiled swarm → Conversation state: shares messages (evidence: `README.md`)
- LangGraph runtime → Memory services: supports persistence (evidence: `README.md`)
- LangGraph runtime → Human review: supports review (evidence: `README.md`)
- LangGraph runtime → Streaming output: supports streaming (evidence: `README.md`)
