# bhancockio/adk-python architecture

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

- Interactive diagram: https://gitdiagram.com/bhancockio/adk-python
- Repository: https://github.com/bhancockio/adk-python

## Overview

ADK is a code-first Python framework for building, running, evaluating, and deploying AI agents. The main runtime path is a user request entering the runner, which executes an agent or composed multi-agent workflow; LLM flows call models and tools, and the resulting events and state are managed through session services. The graph also preserves memory, artifacts, authentication, evaluation, and developer UI/deployment capabilities documented in the README. Wiring not established by the sampled excerpts is omitted; some subsystem paths are exact enclosing directories from the tree.

Main entry points: [`src/google/adk/tools`](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/tools) (Tool framework), [`src/google/adk/runners.py`](https://github.com/bhancockio/adk-python/blob/main/src/google/adk/runners.py) (Runner), [`src/google/adk/cli`](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/cli) (CLI commands), [`src/google/adk/agents`](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/agents) (Agent hierarchy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_runner["Runner<br/>[runners.py]"]
  node_agent["Agent hierarchy"]
  node_events["Events and actions"]
end

subgraph group_intelligence["Agent intelligence"]
  node_llmflow["LLM flows"]
  node_models["Model adapters"]
  node_planner["Planning"]
end

subgraph group_capabilities["Tools and integrations"]
  node_toolkit["Tool framework"]
  node_api_tools["API integrations"]
  node_mcp["MCP integration"]
  node_auth["Authentication"]
  node_codeexec["Code execution"]
end

subgraph group_state["Runtime state"]
  node_sessions[("Session services")]
  node_memory[("Memory services")]
  node_artifacts[("Artifact services")]
end

subgraph group_operations["Developer operations"]
  node_eval["Agent evaluation"]
  node_cli["CLI commands"]
  node_devui["Development UI<br/>[fast_api.py]"]
end

node_user(("Agent user"))
node_model_service{{"LLM providers"}}
node_tool_services{{"External tool APIs"}}
node_cloud_services{{"Google Cloud services"}}
node_developer(("Agent developer"))

node_user -->|"sends request"| node_runner
node_runner -->|"runs agent"| node_agent
node_agent -->|"executes flow"| node_llmflow
node_llmflow -->|"requests generation"| node_models
node_models -->|"calls provider"| node_model_service
node_llmflow -->|"dispatches tools"| node_toolkit
node_toolkit -->|"uses API tools"| node_api_tools
node_toolkit -->|"uses MCP tools"| node_mcp
node_toolkit -->|"prepares credentials"| node_auth
node_toolkit -->|"executes code"| node_codeexec
node_api_tools -->|"calls APIs"| node_tool_services
node_mcp -->|"connects to servers"| node_tool_services
node_runner -->|"loads and saves"| node_sessions
node_runner -->|"handles events"| node_events
node_agent -.->|"plans actions"| node_planner
node_toolkit -.->|"retrieves memory"| node_memory
node_toolkit -.->|"loads artifacts"| node_artifacts
node_sessions -.->|"uses cloud storage"| node_cloud_services
node_artifacts -.->|"stores artifacts"| node_cloud_services
node_memory -.->|"retrieves context"| node_cloud_services
node_developer -->|"runs commands"| node_cli
node_cli -->|"starts evaluation"| node_eval
node_cli -->|"starts UI"| node_devui
node_devui -->|"serves agent runs"| node_runner
node_eval -->|"evaluates runs"| node_runner
node_cli -.->|"deploys agents"| node_cloud_services

click node_runner "https://github.com/bhancockio/adk-python/blob/main/src/google/adk/runners.py"
click node_agent "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/agents"
click node_events "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/events"
click node_llmflow "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/flows/llm_flows"
click node_models "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/models"
click node_planner "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/planners"
click node_toolkit "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/tools"
click node_api_tools "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/tools/openapi_tool"
click node_mcp "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/tools/mcp_tool"
click node_auth "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/auth"
click node_codeexec "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/code_executors"
click node_sessions "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/sessions"
click node_memory "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/memory"
click node_artifacts "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/artifacts"
click node_eval "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/evaluation"
click node_cli "https://github.com/bhancockio/adk-python/tree/main/src/google/adk/cli"
click node_devui "https://github.com/bhancockio/adk-python/blob/main/src/google/adk/cli/fast_api.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_runner,node_agent,node_events,node_user toneBlue
class node_llmflow,node_models,node_planner toneAmber
class node_toolkit,node_api_tools,node_mcp,node_auth,node_codeexec,node_tool_services toneMint
class node_sessions,node_memory,node_artifacts toneRose
class node_eval,node_cli,node_devui,node_model_service,node_cloud_services,node_developer toneIndigo
```

## Components

### Runtime orchestration

- [Runner](https://github.com/bhancockio/adk-python/blob/main/src/google/adk/runners.py): `src/google/adk/runners.py`
- [Agent hierarchy](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/agents): `src/google/adk/agents`
- [Events and actions](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/events): `src/google/adk/events`

### Agent intelligence

- [LLM flows](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/flows/llm_flows): `src/google/adk/flows/llm_flows`
- [Model adapters](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/models): `src/google/adk/models`
- [Planning](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/planners): `src/google/adk/planners`

### Tools and integrations

- [Tool framework](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/tools): `src/google/adk/tools`
- [API integrations](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/tools/openapi_tool): `src/google/adk/tools/openapi_tool`
- [MCP integration](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/tools/mcp_tool): `src/google/adk/tools/mcp_tool`
- [Authentication](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/auth): `src/google/adk/auth`
- [Code execution](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/code_executors): `src/google/adk/code_executors`

### Runtime state

- [Session services](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/sessions): `src/google/adk/sessions`
- [Memory services](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/memory): `src/google/adk/memory`
- [Artifact services](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/artifacts): `src/google/adk/artifacts`

### Developer operations

- [Agent evaluation](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/evaluation): `src/google/adk/evaluation`
- [CLI commands](https://github.com/bhancockio/adk-python/tree/main/src/google/adk/cli): `src/google/adk/cli`
- [Development UI](https://github.com/bhancockio/adk-python/blob/main/src/google/adk/cli/fast_api.py): `src/google/adk/cli/fast_api.py`

### Other components

- **Agent user**
- **LLM providers**
- **External tool APIs**
- **Google Cloud services**
- **Agent developer**

## Connections

- Agent user → Runner: sends request
- Runner → Agent hierarchy: runs agent
- Agent hierarchy → LLM flows: executes flow
- LLM flows → Model adapters: requests generation
- Model adapters → LLM providers: calls provider
- LLM flows → Tool framework: dispatches tools
- Tool framework → API integrations: uses API tools
- Tool framework → MCP integration: uses MCP tools
- Tool framework → Authentication: prepares credentials
- Tool framework → Code execution: executes code
- API integrations → External tool APIs: calls APIs
- MCP integration → External tool APIs: connects to servers
- Runner → Session services: loads and saves
- Runner → Events and actions: handles events
- Agent hierarchy → Planning: plans actions
- Tool framework → Memory services: retrieves memory
- Tool framework → Artifact services: loads artifacts
- Session services → Google Cloud services: uses cloud storage
- Artifact services → Google Cloud services: stores artifacts
- Memory services → Google Cloud services: retrieves context
- Agent developer → CLI commands: runs commands
- CLI commands → Agent evaluation: starts evaluation
- CLI commands → Development UI: starts UI
- Development UI → Runner: serves agent runs
- Agent evaluation → Runner: evaluates runs
- CLI commands → Google Cloud services: deploys agents