This page provides a high-level introduction to the Agent Development Kit (ADK) Python repository, its architecture, and core concepts. ADK is designed to make AI agent development feel like software development, emphasizing flexibility, testability, and modularity.
Scope: This overview covers the foundational architecture, development workflow, and key capabilities of ADK. For detailed information on specific subsystems, refer to the linked sections throughout this document.
ADK is an open-source, code-first Python framework for building, evaluating, and deploying AI agents. It applies software development principles to agent creation, enabling developers to build sophisticated agentic systems ranging from simple single-agent applications to complex multi-agent orchestrations README.md13-15
Design Philosophy:
Sources: README.md1-50 AGENTS.md31-45
The following diagram illustrates the high-level organization of the ADK codebase.
Key Directories and Files:
| Directory/File | Purpose | Code Pointer |
|---|---|---|
src/google/adk/agents/ | Agent implementations and execution context | base_agent.py src/google/adk/agents/base_agent.py93 invocation_context.py src/google/adk/agents/llm_agent.py67 |
src/google/adk/workflow/ | Graph-based execution infrastructure | _workflow.py, _base_node.py AGENTS.md42-43 |
src/google/adk/tools/ | Tool framework and built-in capabilities | base_tool.py src/google/adk/tools/base_tool.py51 |
src/google/adk/models/ | LLM abstraction and request/response models | llm_request.py src/google/adk/models/llm_request.py50 |
src/google/adk/sessions/ | Conversation state persistence services | base_session_service.py CHANGELOG.md22 |
Sources: AGENTS.md31-55 src/google/adk/tools/base_tool.py51-100 src/google/adk/models/llm_request.py50-80 src/google/adk/agents/base_agent.py93 src/google/adk/agents/llm_agent.py67
The following diagram maps ADK's conceptual layers to concrete code entities, showing how natural language concepts correspond to actual classes and modules.
Key Architectural Principles:
Runner (and NodeRunner for workflows) manages execution flow without holding long-term state, relying on external session services AGENTS.md38 AGENTS.md46Event objects, which are stored in a Session to provide a full history and enable resumability AGENTS.md40 README.md27-29BaseTool, providing a consistent interface for the LLM via FunctionDeclaration src/google/adk/tools/base_tool.py51 src/google/adk/tools/base_tool.py107Sources: AGENTS.md31-55 src/google/adk/tools/base_tool.py51-120 src/google/adk/models/llm_request.py50-101
The Runner is the central orchestration engine. It coordinates the execution of agents and workflows, handling the communication between LLMs and tools AGENTS.md38
LlmAgent) defining the model, instructions, and available tools README.md64-72Sources: README.md33-43 AGENTS.md31-48 src/google/adk/tools/base_tool.py51-82 src/google/adk/agents/llm_agent.py182
ADK provides a unified interface for multiple LLM providers, including Gemini (via Google GenAI SDK v2.0.0), Anthropic, and OpenAI (via LiteLLM) CHANGELOG.md18-21 src/google/adk/models/llm_request.py67-75
Conversations are stored in sessions. ADK 2.0 supports resumable execution, allowing a run to pause for human input or long-running tool completion and resume later README.md27-29 AGENTS.md40
To handle long histories, ADK includes logic to summarize previous interactions, including thoughts and tool calls, to fit within model context windows CHANGELOG.md17
ADK integrates with OpenTelemetry via the AutoTracingPlugin and emits native gen_ai.client.* metrics for monitoring performance and usage CHANGELOG.md9 CHANGELOG.md15