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:

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

---

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 (and NodeRunner for 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 Event objects, which are stored in a Session to 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 via FunctionDeclaration src/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.

Sources: README.md44-60 README.md105-109 CHANGELOG.md3-30