# google/adk-python architecture

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

- Interactive diagram: https://gitdiagram.com/google/adk-python
- Repository: https://github.com/google/adk-python
- Video tour (about a minute): https://gitdiagram.com/google/adk-python/video

## Overview

ADK is a code-first Python framework for defining agents, composing workflow execution, and connecting tools and models. Its principal path is developer-defined agents and workflows, followed by runtime execution and event/session state; the README also documents evaluation, deployment, and multi-agent delegation. The map preserves those capabilities and key runtime layers. Some major subsystems are represented by their exact tree directories because their implementation files were not sampled; edges are limited to README statements and visible source-index or excerpt evidence.

Main entry points: [`src/google/adk/agents/invocation_context.py`](https://github.com/google/adk-python/blob/main/src/google/adk/agents/invocation_context.py) (Invocation context), [`src/google/adk/agents/base_agent.py`](https://github.com/google/adk-python/blob/main/src/google/adk/agents/base_agent.py) (Agent definitions), [`src/google/adk/tools/base_tool.py`](https://github.com/google/adk-python/blob/main/src/google/adk/tools/base_tool.py) (Tool execution), [`src/google/adk/flows/llm_flows`](https://github.com/google/adk-python/tree/main/src/google/adk/flows/llm_flows) (LLM flows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Agent authoring"]
  node_agent["Agent definitions<br/>[base_agent.py]"]
  node_agent_config["Agent config<br/>[agent_config.py]"]
  node_workflow["Workflow composition"]
  node_task_api["Task delegation"]
end

subgraph group_runtime["Execution runtime"]
  node_runtime_context["Invocation context"]
  node_llm_flow["LLM flows"]
  node_model["Model requests<br/>[llm_request.py]"]
  node_tool_runtime["Tool execution<br/>[base_tool.py]"]
  node_events["Event stream<br/>[event.py]"]
  node_plugins["Plugin callbacks<br/>[plugin_manager.py]"]
end

subgraph group_state["State and services"]
  node_session["Session state<br/>[session.py]"]
  node_session_service["Session services"]
  node_database_sessions[("Database sessions")]
  node_artifacts[("Artifact services")]
  node_memory[("RAG memory")]
end

subgraph group_capabilities["Tools and integrations"]
  node_auth["Authentication<br/>[auth_handler.py]"]
  node_tool_integrations["Tool ecosystem"]
  node_code_execution["Code execution"]
end

subgraph group_operations["Evaluation and operations"]
  node_evaluation["Agent evaluation"]
  node_cli["CLI and web UI<br/>[cli.py]"]
  node_deployment["Deployment"]
end

node_developer(("Developer"))
node_end_user(("Agent user"))

node_developer -->|"defines"| node_agent
node_developer -->|"composes"| node_workflow
node_agent -->|"orchestrated by"| node_workflow
node_workflow -.->|"runs with"| node_runtime_context
node_agent -.->|"runs with"| node_runtime_context
node_runtime_context -.->|"drives"| node_llm_flow
node_llm_flow -.->|"requests"| node_model
node_llm_flow -.->|"dispatches"| node_tool_runtime
node_tool_runtime -->|"uses"| node_tool_integrations
node_tool_runtime -->|"can execute"| node_code_execution
node_runtime_context -.->|"records"| node_events
node_plugins -->|"callbacks receive"| node_events
node_session -->|"contains"| node_events
node_session_service -->|"manages"| node_session
node_database_sessions -->|"persists"| node_session
node_runtime_context -.->|"uses"| node_session_service
node_runtime_context -.->|"can access"| node_artifacts
node_runtime_context -.->|"can access"| node_memory
node_tool_runtime -.->|"may require"| node_auth
node_developer -->|"configures"| node_agent_config
node_agent -->|"delegates tasks"| node_task_api
node_end_user -->|"runs locally"| node_cli
node_cli -.->|"loads"| node_agent
node_developer -->|"evaluates"| node_evaluation
node_developer -->|"deploys"| node_deployment
node_deployment -.->|"packages"| node_agent

click node_agent "https://github.com/google/adk-python/blob/main/src/google/adk/agents/base_agent.py"
click node_agent_config "https://github.com/google/adk-python/blob/main/src/google/adk/agents/agent_config.py"
click node_workflow "https://github.com/google/adk-python/tree/main/src/google/adk/workflow"
click node_task_api "https://github.com/google/adk-python/tree/main/src/google/adk/a2a"
click node_runtime_context "https://github.com/google/adk-python/blob/main/src/google/adk/agents/invocation_context.py"
click node_llm_flow "https://github.com/google/adk-python/tree/main/src/google/adk/flows/llm_flows"
click node_model "https://github.com/google/adk-python/blob/main/src/google/adk/models/llm_request.py"
click node_tool_runtime "https://github.com/google/adk-python/blob/main/src/google/adk/tools/base_tool.py"
click node_events "https://github.com/google/adk-python/blob/main/src/google/adk/events/event.py"
click node_plugins "https://github.com/google/adk-python/blob/main/src/google/adk/plugins/plugin_manager.py"
click node_session "https://github.com/google/adk-python/blob/main/src/google/adk/sessions/session.py"
click node_session_service "https://github.com/google/adk-python/blob/main/src/google/adk/sessions/base_session_service.py"
click node_database_sessions "https://github.com/google/adk-python/blob/main/src/google/adk/sessions/database_session_service.py"
click node_artifacts "https://github.com/google/adk-python/tree/main/src/google/adk/artifacts"
click node_memory "https://github.com/google/adk-python/blob/main/src/google/adk/memory/vertex_ai_rag_memory_service.py"
click node_auth "https://github.com/google/adk-python/blob/main/src/google/adk/auth/auth_handler.py"
click node_tool_integrations "https://github.com/google/adk-python/tree/main/src/google/adk/tools"
click node_code_execution "https://github.com/google/adk-python/tree/main/src/google/adk/code_executors"
click node_evaluation "https://github.com/google/adk-python/tree/main/src/google/adk/evaluation"
click node_cli "https://github.com/google/adk-python/blob/main/src/google/adk/cli/cli.py"
click node_deployment "https://github.com/google/adk-python/tree/main/src/google/adk/cli/deployers"

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,node_agent_config,node_workflow,node_task_api,node_end_user toneBlue
class node_runtime_context,node_llm_flow,node_model,node_tool_runtime,node_events,node_plugins toneAmber
class node_session,node_session_service,node_database_sessions,node_artifacts,node_memory toneMint
class node_auth,node_tool_integrations,node_code_execution toneRose
class node_evaluation,node_cli,node_deployment,node_developer toneIndigo
```

## Components

### Agent authoring

- [Agent definitions](https://github.com/google/adk-python/blob/main/src/google/adk/agents/base_agent.py): `src/google/adk/agents/base_agent.py`
- [Agent config](https://github.com/google/adk-python/blob/main/src/google/adk/agents/agent_config.py): `src/google/adk/agents/agent_config.py`
- [Workflow composition](https://github.com/google/adk-python/tree/main/src/google/adk/workflow): `src/google/adk/workflow`
- [Task delegation](https://github.com/google/adk-python/tree/main/src/google/adk/a2a): `src/google/adk/a2a`

### Execution runtime

- [Invocation context](https://github.com/google/adk-python/blob/main/src/google/adk/agents/invocation_context.py): `src/google/adk/agents/invocation_context.py`
- [LLM flows](https://github.com/google/adk-python/tree/main/src/google/adk/flows/llm_flows): `src/google/adk/flows/llm_flows`
- [Model requests](https://github.com/google/adk-python/blob/main/src/google/adk/models/llm_request.py): `src/google/adk/models/llm_request.py`
- [Tool execution](https://github.com/google/adk-python/blob/main/src/google/adk/tools/base_tool.py): `src/google/adk/tools/base_tool.py`
- [Event stream](https://github.com/google/adk-python/blob/main/src/google/adk/events/event.py): `src/google/adk/events/event.py`
- [Plugin callbacks](https://github.com/google/adk-python/blob/main/src/google/adk/plugins/plugin_manager.py): `src/google/adk/plugins/plugin_manager.py`

### State and services

- [Session state](https://github.com/google/adk-python/blob/main/src/google/adk/sessions/session.py): `src/google/adk/sessions/session.py`
- [Session services](https://github.com/google/adk-python/blob/main/src/google/adk/sessions/base_session_service.py): `src/google/adk/sessions/base_session_service.py`
- [Database sessions](https://github.com/google/adk-python/blob/main/src/google/adk/sessions/database_session_service.py): `src/google/adk/sessions/database_session_service.py`
- [Artifact services](https://github.com/google/adk-python/tree/main/src/google/adk/artifacts): `src/google/adk/artifacts`
- [RAG memory](https://github.com/google/adk-python/blob/main/src/google/adk/memory/vertex_ai_rag_memory_service.py): `src/google/adk/memory/vertex_ai_rag_memory_service.py`

### Tools and integrations

- [Authentication](https://github.com/google/adk-python/blob/main/src/google/adk/auth/auth_handler.py): `src/google/adk/auth/auth_handler.py`
- [Tool ecosystem](https://github.com/google/adk-python/tree/main/src/google/adk/tools): `src/google/adk/tools`
- [Code execution](https://github.com/google/adk-python/tree/main/src/google/adk/code_executors): `src/google/adk/code_executors`

### Evaluation and operations

- [Agent evaluation](https://github.com/google/adk-python/tree/main/src/google/adk/evaluation): `src/google/adk/evaluation`
- [CLI and web UI](https://github.com/google/adk-python/blob/main/src/google/adk/cli/cli.py): `src/google/adk/cli/cli.py`
- [Deployment](https://github.com/google/adk-python/tree/main/src/google/adk/cli/deployers): `src/google/adk/cli/deployers`

### Other components

- **Developer**
- **Agent user**

## Connections

- Developer → Agent definitions: defines
- Developer → Workflow composition: composes
- Agent definitions → Workflow composition: orchestrated by
- Workflow composition → Invocation context: runs with (evidence: `src/google/adk/agents/invocation_context.py`)
- Agent definitions → Invocation context: runs with (evidence: `src/google/adk/agents/invocation_context.py`)
- Invocation context → LLM flows: drives
- LLM flows → Model requests: requests
- LLM flows → Tool execution: dispatches
- Tool execution → Tool ecosystem: uses (evidence: `src/google/adk/tools/base_tool.py`)
- Tool execution → Code execution: can execute
- Invocation context → Event stream: records (evidence: `src/google/adk/agents/invocation_context.py`)
- Plugin callbacks → Event stream: callbacks receive (evidence: `src/google/adk/plugins/plugin_manager.py`)
- Session state → Event stream: contains (evidence: `src/google/adk/sessions/session.py`)
- Session services → Session state: manages (evidence: `src/google/adk/sessions/base_session_service.py`)
- Database sessions → Session state: persists (evidence: `src/google/adk/sessions/database_session_service.py`)
- Invocation context → Session services: uses (evidence: `src/google/adk/agents/invocation_context.py`)
- Invocation context → Artifact services: can access (evidence: `src/google/adk/agents/invocation_context.py`)
- Invocation context → RAG memory: can access
- Tool execution → Authentication: may require
- Developer → Agent config: configures
- Agent definitions → Task delegation: delegates tasks
- Agent user → CLI and web UI: runs locally
- CLI and web UI → Agent definitions: loads
- Developer → Agent evaluation: evaluates
- Developer → Deployment: deploys
- Deployment → Agent definitions: packages
