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 | src/google/adk/agents/base_agent.py93-176 src/google/adk/agents/llm_agent.py198-205 |
src/google/adk/workflow/ | Graph-based execution infrastructure | AGENTS.md42-43 |
src/google/adk/tools/ | Tool framework and built-in capabilities | src/google/adk/agents/llm_agent.py137-145 |
src/google/adk/models/ | LLM abstraction and request/response models | src/google/adk/agents/llm_agent.py50-53 |
src/google/adk/integrations/ | First-party integrations (GCS, BigQuery, E2B) | CHANGELOG.md10-18 |
src/google/adk/optimization/ | Agent prompt and behavior optimization | CHANGELOG.md15 |
Sources: AGENTS.md31-55 src/google/adk/agents/base_agent.py93-176 src/google/adk/agents/llm_agent.py198-205 CHANGELOG.md10-18
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:
LlmAgent class is a core implementation of this src/google/adk/agents/llm_agent.py198-205Runner (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-29GCSToolset, follow a consistent interface src/google/adk/agents/llm_agent.py140-194 CHANGELOG.md10Sources: AGENTS.md31-55 src/google/adk/agents/llm_agent.py140-205 src/google/adk/agents/base_agent.py93-176 CHANGELOG.md10
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-72 The LlmAgent class src/google/adk/agents/llm_agent.py198-205 is a primary example. BaseAgent src/google/adk/agents/base_agent.py93-94 provides the abstract base.SequentialAgent src/google/adk/agents/sequential_agent.py53 and ParallelAgent src/google/adk/agents/parallel_agent.py165 for basic orchestration, though Workflow is now preferred.AntigravityAgent allows wrapping Google Antigravity SDK agents as native ADK nodes CHANGELOG.md19McpToolset for Model Context Protocol CHANGELOG.md23 or the GCSToolset for Google Cloud Storage CHANGELOG.md10E2BEnvironment CHANGELOG.md18Sources: README.md33-43 AGENTS.md31-48 src/google/adk/agents/llm_agent.py181-205 src/google/adk/agents/base_agent.py93-94 CHANGELOG.md10-23
ADK provides a unified interface for multiple LLM providers, including Gemini (supporting Gemma 4), Anthropic, and OpenAI CHANGELOG.md17 CHANGELOG.md25 src/google/adk/agents/llm_agent.py201-205
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 The BaseAgentState src/google/adk/agents/base_agent.py80-85 and SequentialAgentState src/google/adk/agents/sequential_agent.py42-47 classes are used for managing agent-specific state.
The framework supports the Gemini Live API, including features like input transcription and translation configuration in RunConfig CHANGELOG.md21-22
The GEPARootAgentOptimizer allows for automated improvement of agent prompts CHANGELOG.md15 Evaluation tools support user simulator configurations for testing CHANGELOG.md16
ADK integrates with OpenTelemetry and supports per-request configuration for fine-grained tracing and metrics CHANGELOG.md26
Sources: README.md27-29 AGENTS.md40 CHANGELOG.md15-26 src/google/adk/agents/llm_agent.py201-205 src/google/adk/agents/base_agent.py80-85 src/google/adk/agents/sequential_agent.py42-47
Refresh this wiki