Overview

Relevant source files

• .gemini/settings.json
• .github/pull_request_template.md
• .gitignore
• AGENTS.md
• CONTRIBUTING.md
• README.md
• assets/adk-web-dev-ui-function-call.png
• scripts/unittests.sh

Purpose and Scope

This page introduces the Agent Development Kit (ADK) Python framework, explaining its purpose, architecture, and how major components interact. It provides the conceptual foundation needed to understand the detailed documentation in subsequent sections.

ADK is a code-first Python framework for building, evaluating, and deploying AI agents. This overview covers the framework's layered architecture, execution flow, and deployment patterns.

For installation instructions, see Installation. For creating your first agent, see Quick Start Guide.

Sources: README.md1-180 pyproject.toml1-225 AGENTS.md1-256

What is ADK?

ADK (Agent Development Kit) is an open-source Python framework for building AI agents with code. The framework provides:

Core Capabilities:

• Multi-provider LLM support - Unified interface for Gemini, Claude, OpenAI, and 100+ models via LiteLLM
• Tool ecosystem - Python functions, OpenAPI specs, MCP protocol, BigQuery, search, code execution
• Multi-agent orchestration - Compose agents with SequentialAgent, ParallelAgent, LoopAgent
• Stateless execution - Runner class fetches state from BaseSessionService, enables horizontal scaling
• Pluggable persistence - InMemorySessionService, DatabaseSessionService, VertexAiSessionService, GcsArtifactService
• CLI and web UI - adk run, adk web, adk eval for development and testing
• Deployment targets - Cloud Run, Vertex AI Agent Engine, GKE via adk deploy

Design Philosophy:

• Code-first (Python functions and classes, not YAML/JSON config as primary interface)
• Model-agnostic (works with any LLM provider through BaseLlm interface)
• Deployment-agnostic (same code runs locally, Cloud Run, GKE, Agent Engine)
• Service abstraction (swap backends via URI configuration)

Sources: README.md26-31 README.md42-61 pyproject.toml5-6 AGENTS.md8-15

What is ADK?

ADK (Agent Development Kit) is an open-source, code-first Python framework for building, evaluating, and deploying AI agents. It provides:

• Model-agnostic LLM integration - Works with Gemini, Anthropic, OpenAI, and 100+ models via LiteLLM
• Rich tool ecosystem - Python functions, OpenAPI specs, MCP tools, and Google Cloud integrations
• Multi-agent orchestration - Compose specialized agents into hierarchies
• Complete lifecycle support - Local development, evaluation framework, and deployment to Cloud Run, Vertex AI Agent Engine, or GKE
• Production-ready state management - Sessions, artifacts, memory, and credentials with pluggable backends

The framework is optimized for Gemini and Google Cloud but remains deployment-agnostic and compatible with other frameworks.

Sources: README.md26-31 pyproject.toml5-6 AGENTS.md8-15

Core Architecture

The ADK framework follows a layered architecture where each layer has well-defined responsibilities. This design enables flexibility, testability, and deployment portability.

Architecture Layers

Figure 1: ADK Layered Architecture - Code Entity View

Architecture Layers:

Layer	Key Classes	Responsibility	Source Files
User Interfaces	cli_tools_click, AdkWebServer, get_fast_api_app()	CLI commands, dev UI, API endpoints	cli/cli_tools_click.py cli/adk_web_server.py cli/fast_api.py
Orchestration	Runner, InvocationContext, PluginManager	Stateless execution, session lifecycle, plugin hooks	runners.py agents/invocation_context.py plugins/plugin_manager.py
Agent	BaseAgent, LlmAgent, SequentialAgent, ParallelAgent, LoopAgent	Agent hierarchy, multi-agent composition	agents/base_agent.py agents/llm_agent.py agents/sequential_agent.py
LLM Flow	BaseLlmFlow, SingleFlow, LiveRequestQueue	Request/response processing, streaming, compaction	flows/llm_flows/base_llm_flow.py flows/llm_flows/single_flow.py
LLM Provider	BaseLlm, Gemini, LiteLlm, AnthropicLlm, Claude	Model integration, type conversion	models/base_llm.py models/gemini.py models/lite_llm.py
Tool	BaseTool, McpToolset, BigQueryToolset, FunctionTool	Tool execution, authentication, MCP protocol	tools/base_tool.py tools/mcp_tool/mcp_toolset.py
Service	BaseSessionService, DatabaseSessionService, GcsArtifactService	Session persistence, artifact storage, state management	sessions/base_session_service.py artifacts/gcs_artifact_service.py

Sources: src/google/adk/runners.py src/google/adk/agents/base_agent.py src/google/adk/agents/llm_agent.py src/google/adk/flows/llm_flows/base_llm_flow.py src/google/adk/models/base_llm.py src/google/adk/tools/base_tool.py src/google/adk/sessions/base_session_service.py src/google/adk/cli/cli_tools_click.py

System Components

Component Overview Table

Component	Key Classes/Modules	Purpose	Key Files
Runner	Runner	Stateless orchestration engine that manages agent execution, event streaming, and service coordination	runners.py1-1000
Agents	BaseAgent, LlmAgent, LoopAgent, ParallelAgent, SequentialAgent	Define agent behavior, instructions, tools, and orchestration patterns	agents/base_agent.py agents/llm_agent.py agents/loop_agent.py
LLM Flows	BaseLlmFlow, SingleFlow	Handle LLM request/response processing, tool calls, and reason-act cycles	flows/llm_flows/base_llm_flow.py flows/llm_flows/single_flow.py
Models	BaseLlm, Gemini, LiteLlm, AnthropicLlm, Claude	Integrate with LLM providers with unified interface	models/base_llm.py models/gemini.py models/lite_llm.py models/anthropic_llm.py
Tools	BaseTool, FunctionTool, BaseToolset, McpToolset, BigQueryToolset	Extend agent capabilities with functions, APIs, and integrations	tools/base_tool.py tools/mcp_tool/mcp_toolset.py tools/bigquery/bigquery_toolset.py
Sessions	BaseSessionService, DatabaseSessionService, VertexAiSessionService	Persist conversation state and event history with state scoping	sessions/base_session_service.py sessions/database_session_service.py
Artifacts	BaseArtifactService, LocalArtifactService, GcsArtifactService	Store and retrieve files, images, audio, and other binary data	artifacts/base_artifact_service.py artifacts/gcs_artifact_service.py
Memory	BaseMemoryService, VertexAiMemoryBankService	Provide long-term memory, RAG, and memory consolidation	memory/base_memory_service.py memory/vertexai_memory_bank_service.py
Evaluation	LocalEvalService, AgentEvaluator, LlmBackedUserSimulator	Test and evaluate agent performance with metrics, personas, and test cases	evaluation/local_eval_service.py evaluation/agent_evaluator.py
CLI/Web	cli_tools_click, AdkWebServer, get_fast_api_app()	Provide command-line tools and browser-based development UI	cli/cli_tools_click.py cli/adk_web_server.py cli/fast_api.py
Deployment	to_cloud_run(), to_agent_engine(), to_gke()	Deploy agents to Cloud Run, Vertex AI Agent Engine, or GKE	cli/cli_deploy.py1-1500
A2A	RemoteA2aAgent, A2aAgentExecutor	Enable inter-agent communication via Agent-to-Agent protocol	a2a/remote_a2a_agent.py a2a/a2a_agent_executor.py

Sources: src/google/adk/runners.py src/google/adk/agents/ src/google/adk/tools/ src/google/adk/sessions/ src/google/adk/evaluation/ src/google/adk/cli/ src/google/adk/a2a/

Request Flow: User Message to Agent Response

Figure 2: Single Invocation Flow - Method-Level View

Invocation Lifecycle:

1. Session Fetch: Runner.run_async() calls BaseSessionService.get_session() to load all events and state
2. Context Creation: InvocationContext bundles session, services, and config
3. Agent Execution: LlmAgent.run_async() delegates to BaseLlmFlow._run_one_step_async()
4. Reason-Act Loop:
   • _preprocess_async() resolves tools and builds LlmRequest
   • BaseLlm.generate_content_async() calls the model
   • _postprocess_async() creates Event from LlmResponse
   • If function_calls exist, execute tools in parallel via BaseTool.run_async()
   • Yield events to Runner which persists via append_event() and streams to client
5. Compaction: Optional CompactionRequestProcessor summarizes old events
6. Completion: Return control to caller

Sources: src/google/adk/runners.py src/google/adk/flows/llm_flows/base_llm_flow.py src/google/adk/agents/llm_agent.py src/google/adk/sessions/base_session_service.py src/google/adk/tools/base_tool.py

CLI Commands and Entry Points

Figure 3: CLI Command Structure - Code Flow

CLI Command Table:

Command	Function	Purpose	Implementation
adk run	cli_run()	Interactive CLI testing	cli/cli.py calls Runner.run()
adk web	cli_web()	Development web UI	cli/adk_web_server.py wraps get_fast_api_app()
adk api_server	cli_api_server()	Production API server	cli/fast_api.py
adk eval	cli_eval()	Run evaluation sets	evaluation/local_eval_service.py
adk create	cli_create()	Scaffold new agent	Template generation
adk deploy cloud_run	cli_deploy_cloud_run()	Deploy to Cloud Run	cli/cli_deploy.py
adk deploy agent_engine	cli_deploy_agent_engine()	Deploy to Vertex AI	cli/cli_deploy.py
adk deploy gke	cli_deploy_gke()	Deploy to GKE	cli/cli_deploy.py

Key Classes:

• AgentLoader - Dynamically loads agents from filesystem cli/utils/agent_loader.py
• AdkWebServer - Wraps FastAPI app with service initialization cli/adk_web_server.py
• get_fast_api_app() - Factory function returning configured FastAPI() instance cli/fast_api.py

Sources: src/google/adk/cli/cli_tools_click.py src/google/adk/cli/fast_api.py src/google/adk/cli/adk_web_server.py src/google/adk/cli/cli_deploy.py src/google/adk/cli/utils/agent_loader.py

Development to Production Workflow

Agent Structure Convention

Agents follow a mandatory directory structure:

my_agent/
├── __init__.py       # Must contain: from . import agent
└── agent.py          # Must define: root_agent OR app

Two patterns:

Pattern 1: Simple Agent (for basic agents without plugins)

Pattern 2: App Pattern (for plugins, event compaction, custom config)

AgentLoader.load() discovers agents by importing the module and looking for root_agent or app.

Sources: AGENTS.md138-164 src/google/adk/cli/utils/agent_loader.py

Local Development Flow

Figure 4: Local Development Commands and Service Backends

Service URI Configuration:

Service	Default	SQLite Example	GCP Example
Session	InMemorySessionService	--session_service_uri sqlite:///sessions.db	--session_service_uri vertexai://project-id/region
Artifact	InMemoryArtifactService	--artifact_service_uri file:///tmp/artifacts	--artifact_service_uri gs://bucket-name/prefix
Memory	None (optional)	N/A	--memory_service_uri vertexai://project-id/region/corpus

Service factory functions in cli/utils/service_factory.py:

• create_session_service_from_options(uri) → BaseSessionService
• create_artifact_service_from_options(uri) → BaseArtifactService
• create_memory_service_from_options(uri) → BaseMemoryService

Sources: src/google/adk/cli/cli_tools_click.py src/google/adk/cli/adk_web_server.py src/google/adk/cli/utils/agent_loader.py src/google/adk/cli/utils/service_factory.py src/google/adk/sessions/base_session_service.py src/google/adk/artifacts/base_artifact_service.py

Deployment Pipeline

Figure 5: Deployment Targets and Build Process

Deployment Comparison:

Aspect	Cloud Run	Vertex AI Agent Engine	GKE
Build Function	to_cloud_run()	to_agent_engine()	to_gke()
Container	Auto-generated Dockerfile	No containerization	Auto-generated Dockerfile
Runtime	get_fast_api_app()	AdkApp wrapper	get_fast_api_app()
Scaling	Automatic (serverless)	Managed by Vertex AI	Manual (HPA)
Service Backend	User-configured URIs	Vertex AI managed	User-configured URIs
Entry Point	CMD adk api_server	vertexai.agent_engines API	CMD adk api_server
Access	HTTPS endpoint	Agent Engine API	HTTPS via LoadBalancer

Generated Dockerfile (Cloud Run/GKE):

Generated app.py (Agent Engine):

Sources: src/google/adk/cli/cli_deploy.py src/google/adk/cli/cli_tools_click.py src/google/adk/cli/fast_api.py

Key Design Patterns

Stateless Runner Pattern

The Runner class in src/google/adk/runners.py is intentionally stateless:

• Does not hold conversation history in memory
• Fetches session state from SessionService at the start of each invocation
• Delegates all persistence to service interfaces
• Enables horizontal scaling and resumability

Each call to Runner.run_async() processes a single user turn (invocation) by:

1. Loading session state
2. Creating an InvocationContext
3. Executing the agent's reason-act loop
4. Persisting events as they're generated
5. Optionally compacting old events

Sources: src/google/adk/runners.py1-1000 AGENTS.md38-71

Service Abstraction Pattern

All persistence concerns use base interfaces:

• BaseSessionService - Session CRUD and event history
• BaseArtifactService - File storage and retrieval
• BaseMemoryService - Long-term memory operations
• BaseCredentialService - Credential management

This enables:

• Local development with in-memory or SQLite backends
• Production deployment with Cloud SQL, Spanner, or GCS
• Testing with mock implementations
• Custom service implementations via service registry

Sources: src/google/adk/sessions/base_session_service.py1-200 src/google/adk/artifacts/base_artifact_service.py1-200 src/google/adk/memory/base_memory_service.py1-150 src/google/adk/cli/service_registry.py1-200

Plugin System Pattern

The framework uses plugins to extend functionality without modifying core code:

• BasePlugin interface with lifecycle hooks (before_agent_run, after_agent_run, etc.)
• PluginManager in runners.py orchestrates plugin execution
• Examples: ContextFilterPlugin (event compaction), telemetry plugins, custom middleware

Plugins are configured at the App level:

Sources: src/google/adk/plugins/base_plugin.py1-200 src/google/adk/runners.py1-100 src/google/adk/apps/app.py1-200

Agent Composition Pattern

Multi-agent systems are built through composition:

• BaseAgent defines the interface (run_async() method)
• Agents can have sub_agents that they delegate to
• Orchestration agents (ParallelAgent, SequentialAgent, LoopAgent) control how sub-agents execute
• The LLM decides when to invoke sub-agents based on descriptions and context

Sources: src/google/adk/agents/base_agent.py1-500 src/google/adk/agents/parallel_agent.py1-300 src/google/adk/agents/sequential_agent.py1-300 README.md116-137

Summary

ADK is structured as a layered framework where:

• User interfaces (CLI, Web UI, API) provide multiple entry points
• Runner orchestrates execution in a stateless manner
• Agents define behavior and can be composed hierarchically
• LLM Flows manage model interactions and tool execution
• Services provide pluggable backends for persistence
• Tools extend agent capabilities through a uniform interface

The same agent code runs in local development and production, with configuration controlling backend services and deployment targets. The framework prioritizes flexibility through abstraction while providing opinionated defaults for the Google Cloud ecosystem.

Sources: README.md1-180 AGENTS.md1-256 pyproject.toml1-225 src/google/adk/runners.py1-1000