Overview
Relevant source files
- .agents/skills/adk-setup/SKILL.md
- .github/.release-please-manifest.json
- .github/pull_request_template.md
- .github/release-please-config.json
- .github/workflows/check-file-contents.yml
- .github/workflows/copybara-pr-handler.yml
- .github/workflows/issue-monitor.yml
- .github/workflows/release-cherry-pick.yml
- .github/workflows/release-cut.yml
- .github/workflows/release-finalize.yml
- .github/workflows/release-please.yml
- .github/workflows/release-publish.yml
- .gitignore
- AGENTS.md
- CHANGELOG.md
- CONTRIBUTING.md
- README.md
- assets/adk-web-dev-ui-function-call.png
- contributing/samples/integrations/files_retrieval_agent/README.md
- contributing/samples/mcp/mcp_server_side_sampling/README.md
- src/google/adk/agents/agent_config.py
- src/google/adk/agents/base_agent.py
- src/google/adk/agents/base_agent_config.py
- src/google/adk/agents/common_configs.py
- src/google/adk/agents/config_agent_utils.py
- src/google/adk/agents/config_schemas/AgentConfig.json
- src/google/adk/agents/llm_agent.py
- src/google/adk/agents/llm_agent_config.py
- src/google/adk/agents/loop_agent.py
- src/google/adk/agents/loop_agent_config.py
- src/google/adk/agents/parallel_agent.py
- src/google/adk/agents/parallel_agent_config.py
- src/google/adk/agents/sequential_agent.py
- src/google/adk/agents/sequential_agent_config.py
- src/google/adk/version.py
- tests/unittests/agents/test_agent_config.py
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.
What is ADK?
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:
- Code-first: Everything is defined in Python code for versioning, testing, and IDE support. This avoids GUI-based logic and ensures compatibility with standard development workflows README.md64-72 AGENTS.md33-34
- Modularity & Composition: Complex systems are built by composing multiple, specialized agents or workflows README.md89-93
- Deployment-Agnostic: The agent's core logic is separate from its deployment environment. The same code can run locally via CLI, as a FastAPI server, or on cloud platforms like Cloud Run and Vertex AI README.md98-103 CHANGELOG.md8
- Workflow-driven: ADK 2.0 introduces a graph-based execution engine for composing deterministic execution flows, supporting routing, loops, and human-in-the-loop patterns README.md35-38
Sources: README.md1-50 AGENTS.md31-45
Repository Structure
The following diagram illustrates the high-level organization of the ADK codebase.
Key Directories and Files:
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
System Architecture
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:
- Declarative Agents: Agents are blueprints defining identity, instructions, and tools AGENTS.md37
- Stateless Orchestration: The
Runner(andNodeRunnerfor workflows) manages execution flow without holding long-term state, relying on external session services AGENTS.md38 AGENTS.md46 - Event-Driven State: All interactions are captured as
Eventobjects, which are stored in aSessionto provide a full history and enable resumability AGENTS.md40 README.md27-29 - Unified Tool Interface: All capabilities, from local functions to remote MCP servers, inherit from
BaseTool, providing a consistent interface for the LLM viaFunctionDeclarationsrc/google/adk/tools/base_tool.py51 src/google/adk/tools/base_tool.py107
Sources: AGENTS.md31-55 src/google/adk/tools/base_tool.py51-120 src/google/adk/models/llm_request.py50-101
Core Components
Runner and Engine
The Runner is the central orchestration engine. It coordinates the execution of agents and workflows, handling the communication between LLMs and tools AGENTS.md38
Agents and Workflows
- Agent: A configuration object (often
LlmAgent) defining the model, instructions, and available tools README.md64-72 - Workflow: A graph-based engine that allows for complex, non-linear execution patterns like loops and conditional branching README.md35-38 README.md89-93
- Task API: A structured way for agents to delegate tasks to other agents, supporting both single-turn and multi-turn interactions README.md40-42
Tools and Capabilities
- BaseTool: The abstract base class for all tools src/google/adk/tools/base_tool.py51
- FunctionTool: A wrapper that turns standard Python functions into tools the LLM can call src/google/adk/agents/llm_agent.py182
- Long Running Tools: Tools that can return a resource ID and finish later, supporting asynchronous and human-in-the-loop workflows src/google/adk/tools/base_tool.py59-62
Sources: README.md33-43 AGENTS.md31-48 src/google/adk/tools/base_tool.py51-82 src/google/adk/agents/llm_agent.py182
Key Capabilities
Multi-Provider LLM Support
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
Session Resumability and Persistence
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
Event Compaction
To handle long histories, ADK includes logic to summarize previous interactions, including thoughts and tool calls, to fit within model context windows CHANGELOG.md17
Telemetry and Metrics
ADK integrates with OpenTelemetry via the AutoTracingPlugin and emits native gen_ai.client.* metrics for monitoring performance and usage CHANGELOG.md9 CHANGELOG.md15
Next Steps
- Getting Started: Follow the Installation and Quick Start Guide to set up your environment and run your first agent.
- Core Concepts: Deep dive into Agent System, the Runner, and Tool Framework.
- Advanced Orchestration: Explore the Workflow Engine for building complex, graph-based agentic applications.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.
