# arko555/deep_agent_experiement architecture

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

- Interactive diagram: https://gitdiagram.com/arko555/deep_agent_experiement
- Repository: https://github.com/arko555/deep_agent_experiement

## Overview

Deep Agent is a LangGraph-based assistant: a user request is routed once to skill-defined department agents, which run isolated tool loops; their results are checked and combined into the response. The graph also supports conversation memory, workspace file governance, dynamic tools, MCP tools, and remote A2A departments. Some subsystem links below are documented in the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`src/services/agent_orchestrator/graph.py`](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/graph.py) (Compiled graph), [`src/services/tools_integration/registry.py`](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/registry.py) (Tool registry), [`src/services/agent_orchestrator/orchestrator.py`](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/orchestrator.py) (Request router), [`src/services/agent_orchestrator/subagents.py`](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/subagents.py) (Department tool loops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI<br/>[main.py]"]
  node_ui["Chat UI<br/>[app.py]"]
end

subgraph group_flow["Orchestration"]
  node_graph["Compiled graph<br/>[graph.py]"]
  node_state_type["Agent state<br/>[state.py]"]
  node_router["Request router<br/>[orchestrator.py]"]
  node_fanout["Department fanout<br/>[subagent_engine.py]"]
  node_verify["Result verification<br/>[verification.py]"]
  node_aggregate["Result aggregation<br/>[aggregator.py]"]
end

subgraph group_departments["Departments"]
  node_skills["Skill discovery<br/>[memory.py]"]
  node_subagents["Department tool loops<br/>[subagents.py]"]
end

subgraph group_tools["Tools and integrations"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_builtin_tools["Built-in tools<br/>[tools.py]"]
  node_dynamic_tools["Dynamic tools<br/>[discovery.py]"]
  node_tool_metadata["Tool definitions<br/>[decorator.py]"]
  node_relevance["Tool shortlisting<br/>[relevance.py]"]
  node_validation["Tool validation<br/>[validation.py]"]
  node_mcp["MCP client<br/>[mcp_client.py]"]
  node_a2a["A2A client<br/>[a2a_client.py]"]
  node_bridge["Async bridge<br/>[async_bridge.py]"]
end

subgraph group_state["Memory and governance"]
  node_session["Conversation window<br/>[window.py]"]
  node_checkpoint[("Checkpoints<br/>[checkpoint.py]")]
  node_guardrails["Workspace safeguards<br/>[guardrails.py]"]
  node_workspace[("Workspace files")]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("User"))
node_model(("Configured LLM"))
node_mcp_servers{{"MCP servers"}}
node_remote_agents{{"Remote agents"}}

node_user -->|"submits request"| node_cli
node_user -->|"chats through"| node_ui
node_cli -->|"invokes agent"| node_graph
node_ui -->|"invokes agent"| node_graph
node_graph -->|"runs first"| node_router
node_graph -->|"dispatches departments"| node_fanout
node_graph -->|"checks fanout output"| node_verify
node_graph -->|"combines results"| node_aggregate
node_router -->|"routes with"| node_model
node_router -->|"reads message window"| node_session
node_graph -->|"configures checkpointing"| node_checkpoint
node_router -->|"builds department roster"| node_skills
node_skills -->|"defines roles"| node_subagents
node_fanout -->|"runs department loops"| node_subagents
node_subagents -->|"shortlists tools"| node_relevance
node_subagents -->|"dispatches tool calls"| node_registry
node_registry -->|"registers built-ins"| node_builtin_tools
node_registry -->|"loads dynamic tools"| node_dynamic_tools
node_dynamic_tools -->|"discovers decorated tools"| node_tool_metadata
node_registry -->|"validates payloads"| node_validation
node_registry -->|"dispatches MCP calls"| node_mcp
node_mcp -->|"calls configured servers"| node_mcp_servers
node_mcp -->|"runs async tools through"| node_bridge
node_fanout -->|"calls remote departments"| node_a2a
node_a2a -->|"sends agent request"| node_remote_agents
node_a2a -->|"runs async client through"| node_bridge
node_config -->|"configures servers"| node_mcp
node_config -->|"configures agents"| node_a2a
node_builtin_tools -->|"guards file access"| node_guardrails
node_guardrails -->|"limits file operations"| node_workspace
node_graph -->|"uses workflow state"| node_state_type

click node_cli "https://github.com/arko555/deep_agent_experiement/blob/main/main.py"
click node_ui "https://github.com/arko555/deep_agent_experiement/blob/main/app.py"
click node_graph "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/graph.py"
click node_state_type "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/state.py"
click node_router "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/orchestrator.py"
click node_fanout "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/subagent_engine.py"
click node_verify "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/verification.py"
click node_aggregate "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/aggregator.py"
click node_skills "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/memory.py"
click node_subagents "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/subagents.py"
click node_registry "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/registry.py"
click node_builtin_tools "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/tools.py"
click node_dynamic_tools "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/discovery.py"
click node_tool_metadata "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/decorator.py"
click node_relevance "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/relevance.py"
click node_validation "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/validation.py"
click node_mcp "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/mcp_client.py"
click node_a2a "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/a2a_client.py"
click node_bridge "https://github.com/arko555/deep_agent_experiement/blob/main/src/async_bridge.py"
click node_session "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/session_memory/window.py"
click node_checkpoint "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/session_memory/checkpoint.py"
click node_guardrails "https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/guardrails.py"
click node_workspace "https://github.com/arko555/deep_agent_experiement/tree/main/workspace"
click node_config "https://github.com/arko555/deep_agent_experiement/blob/main/src/config.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_cli,node_ui,node_user toneBlue
class node_graph,node_state_type,node_router,node_fanout,node_verify,node_aggregate toneAmber
class node_skills,node_subagents,node_mcp_servers toneMint
class node_registry,node_builtin_tools,node_dynamic_tools,node_tool_metadata,node_relevance,node_validation,node_mcp,node_a2a,node_bridge toneRose
class node_session,node_checkpoint,node_guardrails,node_workspace,node_config,node_model,node_remote_agents toneIndigo
```

## Components

### User entry

- [CLI](https://github.com/arko555/deep_agent_experiement/blob/main/main.py): `main.py`
- [Chat UI](https://github.com/arko555/deep_agent_experiement/blob/main/app.py): `app.py`

### Orchestration

- [Compiled graph](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/graph.py): `src/services/agent_orchestrator/graph.py`
- [Agent state](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/state.py): `src/services/agent_orchestrator/state.py`
- [Request router](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/orchestrator.py): `src/services/agent_orchestrator/orchestrator.py`
- [Department fanout](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/subagent_engine.py): `src/services/agent_orchestrator/subagent_engine.py`
- [Result verification](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/verification.py): `src/services/agent_orchestrator/verification.py`
- [Result aggregation](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/aggregator.py): `src/services/agent_orchestrator/aggregator.py`

### Departments

- [Skill discovery](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/memory.py): `src/services/agent_orchestrator/memory.py`
- [Department tool loops](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/agent_orchestrator/subagents.py): `src/services/agent_orchestrator/subagents.py`

### Tools and integrations

- [Tool registry](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/registry.py): `src/services/tools_integration/registry.py`
- [Built-in tools](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/tools.py): `src/services/tools_integration/tools.py`
- [Dynamic tools](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/discovery.py): `src/services/tools_integration/discovery.py`
- [Tool definitions](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/decorator.py): `src/services/tools_integration/decorator.py`
- [Tool shortlisting](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/relevance.py): `src/services/tools_integration/relevance.py`
- [Tool validation](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/validation.py): `src/services/tools_integration/validation.py`
- [MCP client](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/mcp_client.py): `src/services/tools_integration/mcp_client.py`
- [A2A client](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/a2a_client.py): `src/services/tools_integration/a2a_client.py`
- [Async bridge](https://github.com/arko555/deep_agent_experiement/blob/main/src/async_bridge.py): `src/async_bridge.py`

### Memory and governance

- [Conversation window](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/session_memory/window.py): `src/services/session_memory/window.py`
- [Checkpoints](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/session_memory/checkpoint.py): `src/services/session_memory/checkpoint.py`
- [Workspace safeguards](https://github.com/arko555/deep_agent_experiement/blob/main/src/services/tools_integration/guardrails.py): `src/services/tools_integration/guardrails.py`
- [Workspace files](https://github.com/arko555/deep_agent_experiement/tree/main/workspace): `workspace`
- [Runtime configuration](https://github.com/arko555/deep_agent_experiement/blob/main/src/config.py): `src/config.py`

### Other components

- **User**
- **Configured LLM**
- **MCP servers**
- **Remote agents**

## Connections

- User → CLI: submits request (evidence: `README.md`)
- User → Chat UI: chats through (evidence: `README.md`)
- CLI → Compiled graph: invokes agent
- Chat UI → Compiled graph: invokes agent (evidence: `app.py`)
- Compiled graph → Request router: runs first (evidence: `src/services/agent_orchestrator/graph.py`)
- Compiled graph → Department fanout: dispatches departments (evidence: `src/services/agent_orchestrator/graph.py`)
- Compiled graph → Result verification: checks fanout output (evidence: `README.md`)
- Compiled graph → Result aggregation: combines results (evidence: `README.md`)
- Request router → Configured LLM: routes with (evidence: `README.md`)
- Request router → Conversation window: reads message window (evidence: `src/services/agent_orchestrator/orchestrator.py`)
- Compiled graph → Checkpoints: configures checkpointing (evidence: `src/services/agent_orchestrator/graph.py`)
- Request router → Skill discovery: builds department roster (evidence: `README.md`)
- Skill discovery → Department tool loops: defines roles (evidence: `README.md`)
- Department fanout → Department tool loops: runs department loops (evidence: `src/services/agent_orchestrator/subagent_engine.py`)
- Department tool loops → Tool shortlisting: shortlists tools (evidence: `README.md`)
- Department tool loops → Tool registry: dispatches tool calls (evidence: `src/services/agent_orchestrator/subagents.py`)
- Tool registry → Built-in tools: registers built-ins (evidence: `src/services/tools_integration/tools.py`)
- Tool registry → Dynamic tools: loads dynamic tools (evidence: `README.md`)
- Dynamic tools → Tool definitions: discovers decorated tools
- Tool registry → Tool validation: validates payloads (evidence: `src/services/tools_integration/registry.py`)
- Tool registry → MCP client: dispatches MCP calls (evidence: `README.md`)
- MCP client → MCP servers: calls configured servers (evidence: `README.md`)
- MCP client → Async bridge: runs async tools through (evidence: `src/services/tools_integration/mcp_client.py`)
- Department fanout → A2A client: calls remote departments (evidence: `src/services/agent_orchestrator/subagent_engine.py`)
- A2A client → Remote agents: sends agent request (evidence: `src/services/tools_integration/a2a_client.py`)
- A2A client → Async bridge: runs async client through (evidence: `src/services/tools_integration/a2a_client.py`)
- Runtime configuration → MCP client: configures servers (evidence: `src/config.py`)
- Runtime configuration → A2A client: configures agents (evidence: `src/config.py`)
- Built-in tools → Workspace safeguards: guards file access (evidence: `src/services/tools_integration/tools.py`)
- Workspace safeguards → Workspace files: limits file operations (evidence: `README.md`)
- Compiled graph → Agent state: uses workflow state (evidence: `src/services/agent_orchestrator/graph.py`)