Index your code with Devin
DeepWiki

google/adk-python

Menu

Overview

Relevant source files

Purpose and Scope

The Agent Development Kit (ADK) is an open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents. ADK enables developers to define agent logic, tools, and orchestration directly in Python code for maximum flexibility, testability, and version control.

This documentation covers the entire ADK Python system, from core execution abstractions through deployment. While ADK is optimized for Google's Gemini models and ecosystem (Vertex AI, BigQuery, Cloud Run), it is model-agnostic and deployment-agnostic, supporting multiple LLM providers and target platforms.

Installation: The framework is distributed as google-adk on PyPI and requires Python 3.10 or higher.

For details on specific subsystems, see: Getting Started, Agent System, Execution and Orchestration, LLM Integration, Tools and Extensions, Deployment.

Sources: README.md1-180 pyproject.toml1-218

Core Architecture

ADK's architecture is organized into distinct layers that separate concerns between execution, integration, persistence, and user interfaces.

Key Architectural Principles:

  1. Stateless Orchestration: The Runner class does not hold conversation state. It retrieves sessions from BaseSessionService, executes agent logic, and persists events back to the service.

  2. Agent Composition: Complex behaviors emerge from composing simple agents. The BaseAgent hierarchy supports multi-agent systems through sub_agents.

  3. Service Abstractions: Core capabilities (sessions, artifacts, memory) are defined as abstract base classes with multiple implementations (in-memory, cloud-backed).

  4. Tool Extensibility: The BaseTool interface enables integration with any external capability, from Python functions to REST APIs to Model Context Protocol servers.

Sources: src/google/adk/runners.py src/google/adk/agents/base_agent.py src/google/adk/agents/invocation_context.py High-Level Architecture Diagram 1

Core Abstractions

Execution Engine

The execution engine consists of three primary abstractions:

AbstractionCode EntityResponsibility
Runnergoogle.adk.runners.RunnerStateless orchestration of agent execution. Manages invocation lifecycle, plugin callbacks, event compaction.
Agentgoogle.adk.agents.base_agent.BaseAgentBlueprint defining identity, instructions, tools, and sub-agents. Implements run_async() for execution logic.
InvocationContextgoogle.adk.agents.invocation_context.InvocationContextContainer for execution state: session, services, agent states, configuration. Passed to agents during execution.

Execution Flow:

  1. Runner.run_async(session_id, message) is called
  2. Runner retrieves Session from BaseSessionService
  3. Runner creates InvocationContext with session, services, and configuration
  4. Runner calls agent.run_async(context)
  5. Agent enters Reason-Act loop: call LLM → execute tools → generate response
  6. Each step produces Event objects streamed to caller
  7. Events are appended to session via SessionService
  8. Optional event compaction reduces session size

Sources: src/google/adk/runners.py src/google/adk/agents/base_agent.py src/google/adk/agents/invocation_context.py AGENTS.md37-72

Agent Types

ADK provides multiple agent types for different orchestration patterns:

  • LlmAgent: Standard agent that calls an LLM with tools and instructions. Supports multi-agent composition via sub_agents list.
  • SequentialAgent: Executes sub-agents in sequence, passing state between them.
  • ParallelAgent: Executes sub-agents concurrently, merging their results.
  • LoopAgent: Repeatedly executes sub-agents until a termination condition is met.

All agents inherit from BaseAgent and implement run_async(context: InvocationContext).

Sources: src/google/adk/agents/llm_agent.py src/google/adk/agents/sequential_agent.py src/google/adk/agents/parallel_agent.py src/google/adk/agents/loop_agent.py

Tool System

The tool system provides extensible capabilities through a unified interface:

Tools are defined by implementing BaseTool or by decorating Python functions. The framework provides:

  • Built-in tools: transfer_to_agent, code execution, Google Search
  • OpenAPI integration: OpenAPIToolset auto-generates tools from OpenAPI specs
  • MCP integration: McpToolset connects to Model Context Protocol servers
  • BigQuery integration: BigQueryToolset provides SQL execution and ML functions

Sources: src/google/adk/tools/base_tool.py src/google/adk/tools/openapi_tool/ src/google/adk/tools/mcp_tool/ src/google/adk/tools/bigquery_tool/ Tool Integration Architecture Diagram 3

Persistence Layer

The persistence layer defines abstract service interfaces with multiple implementations:

ServiceInterfaceImplementationsPurpose
SessionBaseSessionServiceIn-Memory, Database, Vertex AIConversation history and state
ArtifactBaseArtifactServiceIn-Memory, GCSBinary data (images, audio, files)
MemoryBaseMemoryServiceIn-Memory, Vertex RAGLong-term recall across sessions

Services are configured via URI schemes (e.g., sqlite://, gs://bucket, rag://corpus_id) and registered in the service_registry.

Sources: src/google/adk/sessions/base_session_service.py src/google/adk/artifacts/base_artifact_service.py src/google/adk/memory/base_memory_service.py src/google/adk/cli/service_registry.py Session State Management Diagram 4

User Interfaces

ADK provides three primary interfaces for interacting with agents:

Command Line Interface

The CLI is implemented in src/google/adk/cli/cli_tools_click.py using Click and provides commands for:

  • Development: adk web, adk run for local testing
  • Evaluation: adk eval for quality assessment
  • Deployment: adk deploy with targets for Cloud Run, Vertex AI Agent Engine, and GKE

Sources: src/google/adk/cli/cli_tools_click.py1-1336 pyproject.toml79-80

Web Development UI

The development UI consists of:

  1. Frontend: Angular single-page application served from src/google/adk/cli/browser/
  2. Backend: FastAPI server created by get_fast_api_app() in src/google/adk/cli/fast_api.py
  3. Key Features:
    • Real-time event streaming via Server-Sent Events (/run_sse endpoint)
    • Event trace inspection (/debug/trace/ endpoints)
    • Multi-agent conversation visualization
    • Session management across users and apps

Sources: src/google/adk/cli/fast_api.py55-403 src/google/adk/cli/adk_web_server.py401-1502 Web UI and API Architecture Diagram 7

FastAPI Server Mode

For production deployments, ADK provides AdkWebServer.get_fast_api_app() which returns a configurable FastAPI instance. The server supports:

  • Service configuration: Via URI schemes for sessions, artifacts, and memory
  • CORS configuration: For cross-origin requests
  • Telemetry: OpenTelemetry integration for tracing
  • Hot reload: Optional file watching for agent changes
  • A2A protocol: Optional Agent-to-Agent communication endpoints

The same FastAPI instance can serve both the development UI and production API endpoints.

Sources: src/google/adk/cli/adk_web_server.py628-702 src/google/adk/cli/fast_api.py55-403

Development Lifecycle

The development lifecycle follows these stages:

1. Agent Definition

Agents must follow the required directory structure:

my_agent/
├── __init__.py      # Must contain: from . import agent
└── agent.py         # Must contain: root_agent = Agent(...)

Agents can be defined as simple Agent instances or wrapped in App for advanced configuration (plugins, event compaction).

Sources: AGENTS.md138-166 contributing/adk_project_overview_and_architecture.md27-47

2. Local Testing

  • adk run: Interactive REPL for quick functional testing
  • adk web: Full-featured development UI with event inspection
  • pytest: Automated unit and integration tests

3. Evaluation

The evaluation framework assesses agent quality using:

  • Evaluation sets: JSON files with test scenarios (*.evalset.json)
  • Metrics: ToolTrajectoryMetric, ResponseMatchMetric, SafetyMetric
  • Command: adk eval my_agent eval_set.json

Results are stored via EvalSetResultsManager (local or GCS-backed).

Sources: src/google/adk/evaluation/ Development to Deployment Lifecycle Diagram 5

4. Deployment

The adk deploy command supports three targets:

TargetCommandGenerated ArtifactsUse Case
Cloud Runadk deploy cloud_runDockerfileContainerized API server
Vertex AI Agent Engineadk deploy agent_engineReasoningEngine Python codeManaged agent hosting
GKEadk deploy gkeDockerfile, deployment.yamlKubernetes cluster deployment

All deployment targets automatically configure:

  • Service URIs (sessions, artifacts, memory)
  • Environment variables (project, region)
  • Tracing and observability
  • CORS and authentication

Sources: src/google/adk/cli/cli_deploy.py1-1336 src/google/adk/cli/cli_tools_click.py118-337

LLM Integration

ADK defines a BaseLlm interface with two primary methods:

  1. generate_content_async(): Standard request/response for text generation
  2. connect(): Bidirectional streaming for real-time interactions (Gemini Live API)

Supported Providers:

  • Gemini: Primary integration via google-genai SDK. Supports context caching, live streaming, multiple API versions.
  • LiteLLM: Wrapper for 100+ providers (OpenAI, Anthropic, Azure, AWS, etc.)
  • Anthropic: Direct Claude integration via official SDK

Agents specify their LLM via the model parameter, which accepts either a string identifier (e.g., "gemini-2.5-flash") or a BaseLlm instance.

Sources: src/google/adk/models/base_llm.py src/google/adk/models/gemini.py src/google/adk/models/litellm.py src/google/adk/models/anthropic_llm.py LLM Provider Integration Diagram 6

Project Structure

adk-python/
├── src/google/adk/
│   ├── agents/              # Agent implementations
│   ├── runners.py           # Runner orchestration
│   ├── tools/               # Tool ecosystem (50+ files)
│   │   ├── openapi_tool/
│   │   ├── mcp_tool/
│   │   └── bigquery_tool/
│   ├── models/              # LLM integrations
│   ├── flows/               # Execution flow management
│   ├── sessions/            # Session persistence
│   ├── memory/              # Long-term memory
│   ├── artifacts/           # Artifact storage
│   ├── evaluation/          # Evaluation framework
│   ├── cli/                 # CLI and web server
│   ├── a2a/                 # Agent-to-Agent protocol
│   └── telemetry/           # Observability
├── tests/
│   ├── unittests/           # 2600+ unit tests
│   └── integration/         # Integration tests
├── pyproject.toml           # Package configuration
└── README.md                # Project overview

Key Directories:

  • src/google/adk/agents/: All agent types and execution logic
  • src/google/adk/tools/: Built-in and integration tools
  • src/google/adk/cli/: CLI commands, FastAPI server, Angular UI
  • src/google/adk/evaluation/: Evaluation framework (47 files)
  • tests/unittests/: Comprehensive test coverage (236+ files)

Sources: AGENTS.md79-99 contributing/adk_project_overview_and_architecture.md1-108

Installation and Requirements

Minimum Requirements:

  • Python 3.10 or higher (Python 3.11+ strongly recommended)
  • pip or uv package manager

Installation:

Optional Dependencies:

The framework provides several optional dependency groups:

  • [eval]: Evaluation framework dependencies
  • [test]: Testing dependencies (pytest, etc.)
  • [a2a]: Agent-to-Agent protocol support
  • [extensions]: Extended integrations (LiteLLM, LangGraph, etc.)
  • [community]: Community-contributed tools

Example: pip install google-adk[eval,test]

Sources: README.md62-84 pyproject.toml26-161 CONTRIBUTING.md168-189