Overview

Relevant source files

• .github/workflows/triage.yml
• README.md
• contributing/samples/adk_issue_formatting_agent/agent.py
• contributing/samples/adk_pr_triaging_agent/agent.py
• contributing/samples/adk_triaging_agent/README.md
• contributing/samples/adk_triaging_agent/__init__.py
• contributing/samples/adk_triaging_agent/agent.py
• contributing/samples/adk_triaging_agent/main.py
• contributing/samples/adk_triaging_agent/settings.py
• contributing/samples/adk_triaging_agent/utils.py
• llms-full.txt
• llms.txt
• pyproject.toml
• src/google/adk/cli/adk_web_server.py
• src/google/adk/cli/cli_deploy.py
• src/google/adk/cli/cli_tools_click.py
• src/google/adk/cli/conformance/__init__.py
• src/google/adk/cli/conformance/adk_web_server_client.py
• src/google/adk/cli/fast_api.py
• tests/unittests/cli/conformance/__init__.py
• tests/unittests/cli/conformance/test_adk_web_server_client.py
• tests/unittests/cli/test_cors_regex.py
• tests/unittests/cli/test_fast_api.py
• tests/unittests/cli/utils/test_cli_deploy.py
• tests/unittests/cli/utils/test_cli_deploy_to_cloud_run.py
• tests/unittests/cli/utils/test_cli_eval.py
• tests/unittests/cli/utils/test_cli_tools_click.py

Purpose and Scope

This document provides a high-level overview of the Agent Development Kit (ADK) Python framework, describing its architecture, core components, and how different subsystems interact. ADK is a code-first Python framework for building, evaluating, and deploying AI agents with support for multi-agent orchestration, tool integration, and flexible deployment options.

For installation and setup instructions, see Installation. For creating your first agent, see Quick Start Guide. For detailed information about specific subsystems, refer to the respective sections: Agent System, Tools and Extensions, Evaluation and Testing, and Deployment.

What is ADK

Agent Development Kit (ADK) is a flexible, modular framework that applies software development principles to AI agent creation. It is designed to simplify building, deploying, and orchestrating agent workflows from simple tasks to complex multi-agent systems. While optimized for Google's Gemini models and the Google ecosystem, ADK is model-agnostic and deployment-agnostic.

Sources: README.md1-30 pyproject.toml5-6

High-Level Architecture

The following diagram illustrates the overall system architecture, showing how different components interact:

Sources: src/google/adk/cli/cli_tools_click.py1-210 src/google/adk/cli/adk_web_server.py447-602 src/google/adk/cli/fast_api.py73-267

Core Components

Agent System

The agent system is built around a hierarchy of agent types, all inheriting from BaseAgent:

Agent Type	Description	Key File
BaseAgent	Abstract base class defining the agent interface	agents/base_agent.py
LlmAgent	Agents that interact with LLMs and use tools	agents/llm_agent.py
SequentialAgent	Orchestrates sub-agents in sequence	agents/sequential_agent.py
ParallelAgent	Runs sub-agents concurrently	agents/parallel_agent.py
LoopAgent	Repeats sub-agent execution	agents/loop_agent.py

Agents can be defined in Python code or using YAML configuration files (agent.yaml).

Sources: README.md101-137

Orchestration Layer

The orchestration layer manages agent execution and state:

The Runner class orchestrates agent execution within an InvocationContext, which provides access to services and manages execution state.

Sources: src/google/adk/cli/adk_web_server.py517-566

Services Architecture

ADK uses a service-oriented architecture with pluggable backends:

Service	Purpose	Implementations
BaseSessionService	Manages conversation sessions and state	InMemorySessionService, DatabaseSessionService, VertexAiSessionService
BaseArtifactService	Stores files and binary artifacts	InMemoryArtifactService, LocalArtifactService, GcsArtifactService
BaseMemoryService	Long-term memory storage and retrieval	InMemoryMemoryService, VertexAiMemoryService
BaseCredentialService	Authentication and credential management	InMemoryCredentialService

Sources: src/google/adk/cli/fast_api.py49-51 src/google/adk/cli/fast_api.py164-192

Tool Ecosystem

The tool system enables agents to interact with external systems:

Tools are converted to function declarations that LLMs can invoke. The canonical_tools resolution process handles tool discovery and registration.

Sources: README.md44-46 contributing/samples/adk_triaging_agent/agent.py249-301

Entry Points

ADK provides three primary entry points for interacting with agents:

CLI (Command-Line Interface)

The adk command provides access to all major functionality:

Sources: src/google/adk/cli/cli_tools_click.py206-210 pyproject.toml82-83

Web Development UI

The web UI provides a browser-based development interface:

The web UI is served at http://localhost:8000 when running adk web or adk run --web.

Sources: src/google/adk/cli/fast_api.py98-267 src/google/adk/cli/adk_web_server.py677-749

Direct Python API

ADK can be used directly as a Python library:

Sources: README.md88-114

Development Workflow

Creating Agents

Agents can be created using the CLI command or by writing Python/YAML directly:

This generates:

• my_agent/agent.py - Main agent definition
• my_agent/root_agent.yaml - Alternative YAML definition (optional)
• my_agent/requirements.txt - Dependencies
• my_agent/.env - Environment variables

Sources: src/google/adk/cli/cli_tools_click.py410-471

Running and Testing

Sources: src/google/adk/cli/cli_tools_click.py576-671 src/google/adk/cli/cli_tools_click.py702-967

Deployment

The deployment process generates appropriate configuration files (Dockerfile, Kubernetes manifests, etc.) and executes deployment commands.

Sources: src/google/adk/cli/cli_deploy.py65-102 README.md59-60

State Management and Session Lifecycle

State is hierarchical with three persistent scopes (app, user, session) plus ephemeral temp state. State changes are captured as deltas in events and atomically applied to storage.

Sources: src/google/adk/cli/adk_web_server.py650-676

Evaluation Framework

The evaluation framework operates in two phases: inference generation (using a UserSimulator to create conversations) and metric evaluation (scoring against defined rubrics).

Sources: src/google/adk/cli/cli_tools_click.py702-967

Deployment Targets

ADK supports multiple deployment targets, each with different characteristics:

Target	Use Case	Configuration	Scaling
Cloud Run	Fully managed containerized deployment	Dockerfile generated automatically	Auto-scaling, serverless
Vertex AI Agent Engine	Managed Vertex AI integration	ReasoningEngine with ADK wrapper	Managed by Google
GKE	Self-managed Kubernetes	Kubernetes manifests generated	Manual control
Local	Development and testing	Direct Python execution	Single instance

All deployment targets run the same AdkWebServer FastAPI application, ensuring consistency across environments.

Sources: src/google/adk/cli/cli_deploy.py410-469 README.md59-60

Key Design Principles

1. Code-First: Agents are defined primarily in Python code, enabling version control, testing, and IDE support
2. Modular: Core components (agents, tools, services) are loosely coupled and can be swapped
3. Model-Agnostic: While optimized for Gemini, ADK supports multiple LLM providers via LiteLlm and custom implementations
4. Service-Oriented: Pluggable service implementations allow switching between in-memory, database, and cloud backends
5. Event-Driven: Agent execution produces event streams that capture all interactions
6. Stateful: Built-in session management with hierarchical state scopes
7. Testable: Comprehensive evaluation framework with metric-based testing

Sources: README.md26-30 README.md42-61

Agent-to-Agent Communication (A2A)

ADK integrates with the A2A (Agent-to-Agent) protocol for remote agent communication:

A2A support is enabled via the --a2a flag when running the web server, which exposes A2A protocol endpoints for each agent with an agent.json file.

Sources: src/google/adk/cli/fast_api.py525-593 README.md85-90

Sample Applications

The repository includes several sample agents demonstrating ADK capabilities:

• GitHub Triaging Agent (contributing/samples/adk_triaging_agent/) - Automated issue triaging using GitHub API tools
• PR Triaging Agent (contributing/samples/adk_pr_triaging_agent/) - Pull request analysis and labeling
• Issue Formatting Agent (contributing/samples/adk_issue_formatting_agent/) - Issue template validation

These samples demonstrate real-world tool integration, multi-step workflows, and GitHub Actions integration.

Sources: contributing/samples/adk_triaging_agent/agent.py1-302 .github/workflows/triage.yml1-56