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.md8-10
Design Philosophy:
Sources: README.md1-45 CHANGELOG.md3-17 contributing/adk_project_overview_and_architecture.md1-12
The following diagram illustrates the high-level organization of the ADK codebase.
Key Directories:
| Directory | Purpose | Key Files |
|---|---|---|
src/google/adk/agents/ | Agent implementations | base_agent.py, invocation_context.py |
src/google/adk/runners.py | Core orchestration engine | Runner class |
src/google/adk/apps/ | Application container | app.py |
src/google/adk/flows/ | Execution flow logic | llm_flows/single_flow.py |
src/google/adk/workflow/ | Graph orchestration | _workflow.py, _base_node.py |
Sources: src/google/adk/cli/utils/agent_loader.py33-38 src/google/adk/cli/utils/base_agent_loader.py24-25 contributing/adk_project_overview_and_architecture.md31-42
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 is the stateless orchestration engine. It manages the "Reason-Act" loop but delegates state storage to services like BaseSessionService contributing/adk_project_overview_and_architecture.md19-21InvocationContext encapsulates all data for a single turn, including history and active tools contributing/adk_project_overview_and_architecture.md15-26SingleFlow prepares LLM requests through a series of processors (e.g., compaction, instructions) README.md30-38App class serves as the top-level container, holding the root_agent and global configurations contributing/adk_project_overview_and_architecture.md75-80Sources: contributing/adk_project_overview_and_architecture.md13-26 src/google/adk/cli/utils/agent_loader.py113-125 README.md30-38
The Runner is the central engine. It orchestrates the "Reason-Act" loop, manages LLM calls, and executes tools contributing/adk_project_overview_and_architecture.md19 It is designed to be deployment-agnostic, allowing the same agent logic to run in different environments contributing/adk_project_overview_and_architecture.md11
Agents define identity, instructions, and tools. ADK 2.0 introduces Workflow for graph-based composition README.md30-33
| Entity | Purpose |
|---|---|
BaseAgent | Abstract base class for all agents src/google/adk/cli/utils/base_agent_loader.py24 |
Agent | Declarative configuration object defining identity, instructions, and tools contributing/adk_project_overview_and_architecture.md15 |
Workflow | A graph-based execution engine for composing deterministic flows README.md30-33 CHANGELOG.md11-13 |
App | Container for a root_agent or root_node src/google/adk/cli/utils/agent_loader.py35 |
Sources: README.md30-38 CHANGELOG.md11-13 contributing/adk_project_overview_and_architecture.md13-26
ADK provides an AgentLoader for centralized agent loading with isolation and caching src/google/adk/cli/utils/agent_loader.py58-70 It supports various structures:
agent_name.py).__init__.py.root_agent.yaml).Sources: src/google/adk/cli/utils/agent_loader.py60-70 tests/unittests/cli/utils/test_agent_loader.py56-126
ADK 2.0 supports structured agent-to-agent delegation via the Task API. This includes multi-turn task modes, single-turn controlled output, and mixed delegation patterns README.md35-37
ADK supports extensive tool integrations including:
Sources: README.md30-105 CHANGELOG.md3-17 contributing/adk_project_overview_and_architecture.md48-61
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.