This document provides a high-level introduction to the Agent Development Kit (ADK) Python framework. It covers the framework's core philosophy, architectural design, main components, and how they interact. For installation instructions, see Installation. For detailed component documentation, see the relevant sections: Agent System, Execution and Orchestration, LLM Integration, Tools and Extensions, Persistence and State, User Interfaces, Evaluation and Testing, and Deployment.
The Agent Development Kit (ADK) is an open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents. While optimized for Google's Gemini models and the Google Cloud ecosystem, ADK is fundamentally model-agnostic and deployment-agnostic, supporting multiple LLM providers and deployment targets.
ADK applies software engineering principles to AI agent development, treating agents as versioned, testable, and deployable software artifacts. The framework provides abstractions for defining agent behavior, orchestrating multi-agent workflows, managing conversation state, integrating tools, and deploying to production environments.
Current Version: 1.22.1
Sources: README.md1-31 src/google/adk/version.py16 AGENTS.md1-16
ADK is built on three foundational principles:
Agent logic, tools, and orchestration are defined directly in Python code. This approach enables:
Configuration files (YAML) are supported as an optional convenience, but the framework prioritizes programmatic definition. See Agent Configuration for details.
The same agent definition (agent.py) runs unchanged across multiple environments:
adk web or adk runThis separation of agent logic from deployment infrastructure eliminates environment-specific code paths.
The Runner class orchestrates agent execution without maintaining conversation history in memory. All state is delegated to pluggable service implementations (BaseSessionService, BaseArtifactService, BaseMemoryService), enabling horizontal scaling and flexible persistence strategies.
Sources: AGENTS.md5-14 contributing/adk_project_overview_and_architecture.md5-12 README.md26-30
Architecture Layers Explained
The framework is organized into six distinct layers, each with clear responsibilities:
Layer 1 - Developer Interface: Entry points for interacting with agents. The CLI provides commands like adk web, adk run, and adk eval. The WebUI offers interactive debugging. Direct API usage imports classes from google.adk.
Layer 2 - Agent Definition: Blueprints that define agent behavior. LlmAgent is the primary agent type. Multi-agent systems use the sub_agents parameter. AgentConfig enables YAML-based definitions.
Layer 3 - Execution Engine: Stateless orchestration of agent execution. Runner provides run_async() for production and run_live() for bidirectional streaming. InvocationContext carries state across a single turn. LlmFlow manages LLM request/response cycles.
Layer 4 - LLM Integration: Abstracts differences between LLM providers. BaseLlm defines the interface. Gemini integrates Google's models via google.genai. LiteLlm supports 100+ providers through the litellm library. AnthropicLlm integrates Claude.
Layer 5 - Services: Pluggable abstractions for state management. BaseSessionService manages conversation history. BaseArtifactService handles file storage. BaseMemoryService provides long-term knowledge. CredentialService manages authentication.
Layer 6 - Persistence: Concrete implementations of service abstractions. Multiple backends support different deployment scenarios: in-memory for testing, SQLite for local development, PostgreSQL/MySQL for production, Spanner for scale, Vertex AI for managed deployments.
Sources: Architecture diagrams provided, src/google/adk/agents/llm_agent.py src/google/adk/runners.py src/google/adk/sessions/base_session_service.py src/google/adk/models/base_llm.py
Execution Flow Explained
Invocation Starts: User calls Runner.run_async() with app name, user ID, session ID, and a new message.
Session Retrieval: Runner fetches the session from BaseSessionService, which includes all prior conversation events.
Context Creation: Runner creates an InvocationContext containing the session, new message, and service references.
Agent Execution: Agent.run_async() is called with the context, entering the Reason-Act loop.
LLM Interaction: LlmFlow sends requests to BaseLlm, which returns responses potentially containing tool calls or agent transfers.
Tool Execution: If tool calls are present, BaseTool.execute() is invoked with arguments and context.
Event Streaming: Each step generates Event objects that are streamed to the user via Server-Sent Events (SSE) and persisted to BaseSessionService.
Loop Continuation: The Reason-Act loop continues until the agent produces a final response.
Invocation Complete: Runner updates final state and returns.
Sources: AGENTS.md37-71 src/google/adk/runners.py src/google/adk/flows/llm_flows/base_llm_flow.py
| Class | Purpose | File Path |
|---|---|---|
LlmAgent | Primary agent powered by LLM with tools | src/google/adk/agents/llm_agent.py |
LoopAgent | Executes child agents in a loop until condition met | src/google/adk/agents/loop_agent.py |
SequentialAgent | Executes child agents in sequence | src/google/adk/agents/sequential_agent.py |
ParallelAgent | Executes child agents concurrently | src/google/adk/agents/parallel_agent.py |
WorkflowAgent | Directed acyclic graph (DAG) based execution | src/google/adk/agents/workflow_agent.py |
The Runner class is the stateless orchestrator defined in src/google/adk/runners.py It provides three execution modes:
run_async(): Asynchronous execution for production, returns an async generator of eventsrun(): Synchronous wrapper for testing and debuggingrun_live(): Bidirectional streaming for real-time audio/video interactionsThe Runner never stores conversation state internally. It fetches state from BaseSessionService at the start of each invocation and persists events as they are generated.
Tools extend agent capabilities. The framework supports multiple tool types:
| Tool Type | Base Class | Example |
|---|---|---|
| Python Functions | FunctionTool | Decorated with @function |
| OpenAPI Specs | OpenAPIToolset | REST API integration |
| MCP Protocol | MCPToolset | Model Context Protocol servers |
| Google Cloud | BigQueryToolset, BigtableToolset, SpannerToolset | First-party GCP tools |
| Built-in | google_search, BuiltInCodeExecutor | Framework-provided tools |
See Tools and Extensions for complete documentation.
Sessions store conversation history and state. The BaseSessionService interface defines the contract, implemented by:
InMemorySessionService: Development and testingSqliteSessionService: Local persistenceDatabaseSessionService: PostgreSQL/MySQL for productionSpannerSessionService: Google Cloud Spanner for scaleVertexAiSessionService: Vertex AI Agent Engine integrationSessions maintain three state scopes:
app: prefix): Shared across all usersuser: prefix): Shared across user's sessionstemp: prefix): Never persistedSee Session Management and State Hierarchy for details.
Sources: src/google/adk/agents/ src/google/adk/runners.py src/google/adk/tools/ src/google/adk/sessions/
ADK projects follow a canonical structure for tool compatibility:
my_project/
├── agent.py # Must define root_agent or app
├── __init__.py # Must contain: from . import agent
├── requirements.txt # Optional dependencies
└── .env # Optional environment variables
The agent.py file must define either:
root_agent = Agent(...) for simple agentsapp = App(root_agent=..., plugins=[...]) for advanced configurationThis structure enables automatic discovery by CLI tools.
Sources: AGENTS.md138-165 contributing/adk_project_overview_and_architecture.md27-46
| Command | Purpose | Output |
|---|---|---|
adk run <path> | Execute agent via CLI | Prints events to stdout |
adk web <path> | Launch development UI | Opens web interface at localhost:8000 |
adk eval <agent> <evalset> | Run evaluation suite | Generates metrics and reports |
pytest | Run unit tests | Test results and coverage |
adk api_server <path> | Start production server | FastAPI server with REST endpoints |
Sources: src/google/adk/cli/cli_tools_click.py README.md99-151
Production deployments expose agents via FastAPI. The get_fast_api_app() helper function creates a configured FastAPI application:
Standard endpoints include:
POST /run_sse: Execute agent with Server-Sent Events streamingGET /list-apps: List available agentsPOST /live: Bidirectional streaming for audio/videoSee FastAPI Server and API Endpoints Reference for complete documentation.
Sources: src/google/adk/cli/fast_api.py contributing/adk_project_overview_and_architecture.md62-80
ADK supports multiple deployment targets with minimal configuration changes:
| Target | Command | Session Backend | Artifact Backend |
|---|---|---|---|
| Local | adk web | SQLite or in-memory | Local files |
| Cloud Run | adk deploy cloud_run | Cloud SQL | GCS |
| Vertex AI | adk deploy agent_engine | Vertex AI Sessions | Vertex AI |
| GKE | adk deploy gke | Cloud SQL or Spanner | GCS |
The framework automatically detects the deployment environment and configures appropriate service backends. Developers can override defaults using service URIs:
See Deployment for detailed instructions on each target.
Sources: src/google/adk/cli/cli_tools_click.py CHANGELOG.md1-90
Current Version: 1.22.1 (Released January 9, 2026)
ADK follows Semantic Versioning 2.0.0. The framework is under active development with approximately bi-weekly releases. Recent major features include:
DatabaseSessionService with migration toolingFor complete release history, see CHANGELOG.md1-90
Installation:
Sources: CHANGELOG.md1-90 README.md62-83 src/google/adk/version.py16 AGENTS.md411-487
For additional resources, visit:
Sources: README.md92-180 contributing/adk_project_overview_and_architecture.md1-114
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.