# langchain-ai/deepagents architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/deepagents
- Repository: https://github.com/langchain-ai/deepagents
- Video tour (about a minute): https://gitdiagram.com/langchain-ai/deepagents/video

## Overview

Deep Agents is a batteries-included, model-agnostic agent harness. A user submits a task through the core graph or the terminal coding client; the agent invokes an LLM, applies middleware, delegates work, uses tools and files, persists state, and streams a result. The repository also provides ACP and MCP-facing interfaces. The graph reflects README capabilities and sampled orchestration code; some internal call paths are inferred only from documented subsystem boundaries.

Main entry points: [`libs/deepagents/deepagents/graph.py`](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.py) (Agent Graph), [`libs/deepagents/deepagents/_tools.py`](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_tools.py) (Tool Catalog), [`libs/deepagents/deepagents/middleware/__init__.py`](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/__init__.py) (Middleware Stack), [`libs/code/deepagents_code/main.py`](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/main.py) (Code CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Agent Core"]
  node_agent_graph["Agent Graph<br/>[graph.py]"]
  node_model_profiles["Model Profiles"]
  node_middleware_stack["Middleware Stack<br/>[__init__.py]"]
  node_agent_result["Agent Result<br/>[graph.py]"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_tool_catalog["Tool Catalog<br/>[_tools.py]"]
  node_filesystem_tools["Filesystem Tools<br/>[filesystem.py]"]
  node_shell_backend["Shell Backend<br/>[local_shell.py]"]
  node_subagents["Sub-agents<br/>[subagents.py]"]
  node_skills["Skills<br/>[skills.py]"]
  node_permissions["Tool Permissions<br/>[permissions.py]"]
end

subgraph group_state["State Context"]
  node_context_manager["Context Manager<br/>[summarization.py]"]
  node_memory["Persistent Memory<br/>[memory.py]"]
  node_state_store[("State Store<br/>[store.py]")]
end

subgraph group_code["Coding Client"]
  node_code_cli["Code CLI<br/>[main.py]"]
  node_remote_client["Remote Agent Client<br/>[remote_client.py]"]
  node_server_manager["Server Manager<br/>[server_manager.py]"]
  node_hooks["Hooks Engine<br/>[engine.py]"]
end

subgraph group_interfaces["External Interfaces"]
  node_acp_server["ACP Server<br/>[server.py]"]
  node_mcp_tools["MCP Tools<br/>[mcp_tools.py]"]
end

node_user(("User"))
node_llm["Chat Model"]

node_user -->|"submits task"| node_agent_graph
node_agent_graph -->|"resolves model"| node_model_profiles
node_agent_graph -->|"calls model"| node_llm
node_agent_graph -->|"runs middleware"| node_middleware_stack
node_middleware_stack -->|"exposes tools"| node_tool_catalog
node_middleware_stack -->|"manages context"| node_context_manager
node_middleware_stack -->|"checks approval"| node_permissions
node_tool_catalog -->|"dispatches tools"| node_filesystem_tools
node_tool_catalog -->|"runs commands"| node_shell_backend
node_tool_catalog -->|"delegates tasks"| node_subagents
node_tool_catalog -->|"loads skills"| node_skills
node_filesystem_tools -->|"reads and writes"| node_state_store
node_memory -->|"stores recall"| node_state_store
node_context_manager -->|"offloads context"| node_state_store
node_agent_graph -->|"uses memory"| node_memory
node_agent_graph -->|"returns result"| node_agent_result
node_user -->|"starts coding"| node_code_cli
node_code_cli -->|"starts server"| node_server_manager
node_server_manager -->|"creates client"| node_remote_client
node_remote_client -->|"invokes graph"| node_agent_graph
node_code_cli -->|"coordinates hooks"| node_hooks
node_acp_server -.->|"serves agent"| node_agent_graph
node_mcp_tools -.->|"adds tools"| node_tool_catalog
node_agent_graph -.->|"traces via LangSmith"| node_llm

click node_agent_graph "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.py"
click node_model_profiles "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/profiles/provider/provider_profiles.py"
click node_middleware_stack "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/__init__.py"
click node_tool_catalog "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_tools.py"
click node_filesystem_tools "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/filesystem.py"
click node_shell_backend "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/local_shell.py"
click node_subagents "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/subagents.py"
click node_skills "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/skills.py"
click node_permissions "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/permissions.py"
click node_context_manager "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/summarization.py"
click node_memory "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/memory.py"
click node_state_store "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/store.py"
click node_code_cli "https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/main.py"
click node_remote_client "https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/client/remote_client.py"
click node_server_manager "https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/client/launch/server_manager.py"
click node_hooks "https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/hooks/engine.py"
click node_acp_server "https://github.com/langchain-ai/deepagents/blob/main/libs/acp/deepagents_acp/server.py"
click node_mcp_tools "https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_tools.py"
click node_agent_result "https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.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_agent_graph,node_model_profiles,node_middleware_stack,node_agent_result,node_user toneBlue
class node_tool_catalog,node_filesystem_tools,node_shell_backend,node_subagents,node_skills,node_permissions toneAmber
class node_context_manager,node_memory,node_state_store toneMint
class node_code_cli,node_remote_client,node_server_manager,node_hooks toneRose
class node_acp_server,node_mcp_tools,node_llm toneIndigo
```

## Components

### Agent Core

- [Agent Graph](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.py): `libs/deepagents/deepagents/graph.py`
- [Model Profiles](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/profiles/provider/provider_profiles.py): `libs/deepagents/deepagents/profiles/provider/provider_profiles.py`
- [Middleware Stack](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/__init__.py): `libs/deepagents/deepagents/middleware/__init__.py`
- [Agent Result](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.py): `libs/deepagents/deepagents/graph.py`

### Agent Capabilities

- [Tool Catalog](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_tools.py): `libs/deepagents/deepagents/_tools.py`
- [Filesystem Tools](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/filesystem.py): `libs/deepagents/deepagents/middleware/filesystem.py`
- [Shell Backend](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/local_shell.py): `libs/deepagents/deepagents/backends/local_shell.py`
- [Sub-agents](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/subagents.py): `libs/deepagents/deepagents/middleware/subagents.py`
- [Skills](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/skills.py): `libs/deepagents/deepagents/middleware/skills.py`
- [Tool Permissions](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/permissions.py): `libs/deepagents/deepagents/middleware/permissions.py`

### State Context

- [Context Manager](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/summarization.py): `libs/deepagents/deepagents/middleware/summarization.py`
- [Persistent Memory](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/memory.py): `libs/deepagents/deepagents/middleware/memory.py`
- [State Store](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/store.py): `libs/deepagents/deepagents/backends/store.py`

### Coding Client

- [Code CLI](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/main.py): `libs/code/deepagents_code/main.py`
- [Remote Agent Client](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/client/remote_client.py): `libs/code/deepagents_code/client/remote_client.py`
- [Server Manager](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/client/launch/server_manager.py): `libs/code/deepagents_code/client/launch/server_manager.py`
- [Hooks Engine](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/hooks/engine.py): `libs/code/deepagents_code/hooks/engine.py`

### External Interfaces

- [ACP Server](https://github.com/langchain-ai/deepagents/blob/main/libs/acp/deepagents_acp/server.py): `libs/acp/deepagents_acp/server.py`
- [MCP Tools](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/mcp_tools.py): `libs/code/deepagents_code/mcp_tools.py`

### Other components

- **User**
- **Chat Model**

## Connections

- User → Agent Graph: submits task
- Agent Graph → Model Profiles: resolves model
- Agent Graph → Chat Model: calls model
- Agent Graph → Middleware Stack: runs middleware
- Middleware Stack → Tool Catalog: exposes tools
- Middleware Stack → Context Manager: manages context
- Middleware Stack → Tool Permissions: checks approval
- Tool Catalog → Filesystem Tools: dispatches tools
- Tool Catalog → Shell Backend: runs commands
- Tool Catalog → Sub-agents: delegates tasks
- Tool Catalog → Skills: loads skills
- Filesystem Tools → State Store: reads and writes
- Persistent Memory → State Store: stores recall
- Context Manager → State Store: offloads context
- Agent Graph → Persistent Memory: uses memory
- Agent Graph → Agent Result: returns result
- User → Code CLI: starts coding
- Code CLI → Server Manager: starts server
- Server Manager → Remote Agent Client: creates client
- Remote Agent Client → Agent Graph: invokes graph
- Code CLI → Hooks Engine: coordinates hooks
- ACP Server → Agent Graph: serves agent
- MCP Tools → Tool Catalog: adds tools
- Agent Graph → Chat Model: traces via LangSmith
