Related Pages

Related topics: LLM Agents, Tools, and Skills, Workflow Runtime and Task API, Integrations, Deployment, and Operations

Overview and System Architecture

Purpose and Scope

The Agent Development Kit (ADK) for Python is a framework maintained by Google for building, orchestrating, and deploying AI agents. It provides two main building classes: LLM Agents (driven by large language models) and Workflow Agents (deterministic graph-based flows). ADK is designed to be flexible, modular, and extensible, supporting both code-based and config-based agent definitions. Source: README.md:1-15

ADK targets Python 3.10+ and ships as the google-adk package on PyPI. The release cadence is roughly bi-weekly, and the most recent release is v2.3.0 (June 2026), which introduces a create_http_options parameter on ContextCacheConfig and a GCS first-party toolset for ADK integrations. Source: README.md:50-60

What's New in 2.0

Version 2.0 introduced two major capabilities:

⚠️ Breaking Changes from 1.x: Sessions generated by ADK 2.0 are readable by ADK 1.28+ but are incompatible with older 1.x versions due to changes in the agent API, event model, and session schema. Source: README.md:17-30

Installation

pip install google-adk

Optional integrations are installed with extras: pip install "google-adk[extensions]". Source: README.md:42-48

Related Pages

Related topics: Overview and System Architecture, Workflow Runtime and Task API, Integrations, Deployment, and Operations

LLM Agents, Tools, and Skills

Overview

The Google Agent Development Kit (ADK) for Python is a framework for composing LLM-backed agents, deterministic workflows, and tool integrations. An LLM agent is a google.adk.agents.Agent instance whose decision-making is delegated to a language model. Around that core, the tools subsystem lets the agent take actions — call Python functions, query MCP servers, ask the user for clarification, or commit structured data — and the skills concept is a community-driven effort to expose Claude-style packaged capabilities (issue #3611) that is not yet a first-class module in the v2.3.0 release (Source: README.md:11-29).

LLM Agents

An LLM agent is constructed by instantiating Agent with a model, an instruction, and a list of tools. The runtime forwards the conversation history to the model, parses the response, and either returns a final message or dispatches a tool call. When the underlying model returns text with no candidates and no prompt feedback, the response is treated as a successful empty turn rather than an unknown error, which matters for tool-driven UI flows that legitimately complete a turn with no text (Source: src/google/adk/models/llm_response.py:96-110).

ADK 2.0 introduced two layers on top of the base LLM agent: a Workflow Runtime for graph-based deterministic execution (routing, fan-out, loops, retry, human-in-the-loop), and a Task API for structured agent-to-agent delegation with multi-turn and single-turn modes (Source: README.md:23-29). Sessions produced by 2.x are backward-compatible with ADK 1.28+ but are incompatible with older 1.x (Source: README.md:17-21). A minimal code-based agent is shown in contributing/samples/config/core_basic_config/README.md, and agents can also be defined declaratively in YAML and composed into multi-agent hierarchies (Source: contributing/samples/multi_agent/multi_agent_basic_config/README.md). For LLM-backed contracts, an agent can be wrapped with input_schema and output_schema Pydantic models and exposed as a structured tool to a parent agent when mode='single_turn' (Source: contributing/samples/core/input_output_schema/README.md).

graph TD
    User[User prompt] --> Agent[LLM Agent]
    Agent -->|prompt| Model[LLM Model]
    Model -->|tool call| Dispatcher{ADK runtime}
    Dispatcher -->|function tool| FT[Python callable]
    Dispatcher -->|request_input| HITL[User clarification]
    Dispatcher -->|MCP toolset| MCP[External MCP server]
    Dispatcher -->|set_model_response| Schema[Validate output_schema]
    FT --> Agent
    HITL --> Agent
    MCP --> Agent
    Schema --> Agent
    Agent -->|final answer| User

Tools

The tools parameter accepts a heterogeneous list. The patterns shipped in this repository include:

Historically output_schema and tools were mutually exclusive — structured output disabled tool use. That constraint was lifted through an internal set_model_response tool: the model gathers information with regular tools, then commits a final structured answer that ADK validates against the schema (Source: contributing/samples/tools/output_schema_with_tools/README.md). The original community discussion is tracked in issue #701.

MCP toolsets use the OPENAPI_MCP_HEADERS environment variable to inject authentication; the Notion sample configures a bearer token plus Notion-Version: 2022-06-28 (Source: contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md). For multimodal use, non-text parts in a static instruction (images, uploaded documents) are automatically assigned reference IDs such as inline_data_0 and file_data_1 and forwarded to the model (Source: contributing/samples/multimodal/static_non_text_content/README.md). Async initialization of root_model remains a friction point because MCPToolset only exposes async construction methods while Agent is synchronous (issue #28).

Skills and Community Requests

The community has repeatedly asked for first-class skills support, modeled on Claude's skill feature where each "skill" is a packaged bundle of instructions, tools, and resources that an agent can dynamically load (issue #3611, 42 comments). The ADK roadmap thread (issue #2133, 47 comments) lists this and other capabilities as open for community contribution.

No dedicated SkillToolset or SkillRegistry ships in the v2.3.0 source. Closely related primitives that the community uses to approximate skills include:

• Multi-agent delegation, where a "skill agent" is a focused sub-agent with its own instruction and toolset (Source: contributing/samples/multi_agent/multi_agent_basic_config/README.md).
• LiteLLM fallback chains, so an agent can switch between Gemini, OpenAI, and Anthropic models while preserving full conversational context (Source: contributing/samples/models/litellm_with_fallback_models/README.md).
• The ApigeeLlm class, whose model string encodes both the backend (Gemini or Vertex AI) and the API version (Source: contributing/samples/models/hello_world_apigeellm/README.md).
• Prompt-evolution optimizers such as the GEPA integration, which automatically improves an agent's instruction against benchmarks like Tau-bench (Source: contributing/samples/integrations/gepa/README.md).

See Also

• Agents (LLM, Workflow, Custom)
• Tools overview and built-in toolsets
• MCP Tools integration
• Multi-agent systems and the Task API
• Structured output and input/output schemas
• Community: Roadmap 2025 Q3 (#2133), Claude skills (#3611), Output schema + tools (#701), Async root_model (#28)

Related Pages

Related topics: Overview and System Architecture, LLM Agents, Tools, and Skills, Integrations, Deployment, and Operations

Workflow Runtime and Task API

Overview

The Workflow runtime is ADK Python's graph-based execution layer for orchestrating agents and Python functions. Unlike the pre-built SequentialAgent and ParallelAgent constructs, a Workflow expresses control flow as an arbitrary directed graph whose edges may be unconditional or depend on a "route" emitted by the upstream node. This enables conditional branching, iterative loops, fan-out parallelism, and human-in-the-loop (HITL) checkpoints that are difficult to express in the linear agent composition model. Source: contributing/samples/workflows/route/README.md, contributing/samples/workflows/loop/README.md

The Task API is the surface that nodes use to communicate with the runtime: yielding Event objects for routing and state, or RequestInput objects to suspend for human input. The runtime consumes this stream, advances the graph, and re-invokes the next node with its resolved input.

Core Architecture

A Workflow is built from three primary abstractions, all defined under src/google/adk/workflow/:

• Node — the base interface for any unit of work. Concrete subclasses include FunctionNode (wraps a Python callable) and LlmAgentWrapper (adapts a standard Agent to the node protocol). Source: src/google/adk/workflow/_node.py, src/google/adk/workflow/_function_node.py, src/google/adk/workflow/_llm_agent_wrapper.py
• Graph — owns the set of nodes and the edge definitions. Conditional edges are encoded as a tuple (source_node, {"route_name": target_node, ...}), where the dict maps emitted route strings to downstream nodes. Source: src/google/adk/workflow/_graph.py, contributing/samples/workflows/route/README.md
• Workflow — the driver. It starts from START, dispatches the current node, consumes the Event stream, applies state deltas, resolves the next edge, and repeats until a terminal node is reached. Source: src/google/adk/workflow/_workflow.py

The ParallelWorker decorator (parallel_worker=True) is the mechanism that turns a single node into a fan-out worker: when its input is an iterable, the runtime instantiates one worker per element concurrently and joins their outputs into a list before forwarding. Source: src/google/adk/workflow/_parallel_worker.py, contributing/samples/workflows/parallel_worker/README.md

Task API: Events, Routing, and State

The runtime's contract with nodes is intentionally narrow. A node function either returns a value or yields Event objects (and optionally RequestInput for suspension). The relevant fields are:

• route: str — a label that selects the next edge from the graph's routing map for the current node. Source: contributing/samples/workflows/route/README.md
• state: dict — a delta merged into the shared per-run state dictionary. Source: contributing/samples/workflows/state/README.md
• RequestInput(message, payload, response_schema) — a special event that halts the workflow and returns control to the caller. The user's reply is delivered as node_input to the next node. payload is opaque data for the client UI; response_schema is a Pydantic-generated JSON schema that constrains the reply shape. Source: contributing/samples/workflows/request_input/README.md, contributing/samples/workflows/request_input_advanced/README.md

State can be consumed in three equivalent ways: direct dictionary access (ctx.state["key"]), automatic parameter injection (declaring def func(key: str): causes the runtime to look up key from state), or simply by being passed through the Event stream of a prior node. Source: contributing/samples/workflows/state/README.md

Execution Patterns

The following table summarises the canonical topologies demonstrated by the bundled samples. All of them are expressed purely through the Task API primitives above, with no special-case runtime code.

A common community-requested pattern, combining output_schema with regular tools, is supported through a processor that injects a synthetic set_model_response tool — the model gathers information with the real tools, then commits the final structured payload via this synthetic tool. Source: contributing/samples/tools/output_schema_with_tools/README.md

Failure Modes and Gotchas

• Routing requires an explicit map: if a node yields a route that is not present in its outgoing edge map, the workflow will fail to advance. The runtime does not silently fall back to a default edge. Source: contributing/samples/workflows/route/README.md
• Loops are untyped: a routing node must guard termination itself (e.g. by yielding a different route for the "done" case); there is no built-in max-iteration counter. Source: contributing/samples/workflows/loop/README.md
• parallel_worker only fans out over iterables: passing a scalar input to a parallel-decorated node is a configuration error rather than a no-op. Source: contributing/samples/workflows/parallel_worker/README.md
• YAML resolution is path-relative: a _code reference starting with . resolves against the current agent directory's Python package, not an absolute import. Mismatched paths surface as import errors at workflow-construction time, not at run time. Source: contributing/samples/workflows/loop_config/README.md

See Also

• Output schema with tools: contributing/samples/tools/output_schema_with_tools/README.md
• HITL request_input tool (non-workflow): contributing/samples/hitl/request_input_tool/README.md
• Multi-agent sequential workflow (config-based): contributing/samples/multi_agent/multi_agent_seq_config/README.md
• ADK Roadmap 2025 Q3 (community context for upcoming workflow features): Issue #2133

Related Pages

Related topics: Overview and System Architecture, LLM Agents, Tools, and Skills, Workflow Runtime and Task API

Integrations, Deployment, and Operations

This page documents the integration surfaces, deployment workflows, and operational tooling that accompany the Agent Development Kit (ADK) for Python. ADK is shipped as the google-adk package and provides a runtime that can be exercised locally, deployed as a server, or composed with first-party and external services. The same source tree also doubles as the integration test bed: every sample under contributing/samples/ doubles as both documentation and a working reference for a specific integration or runtime scenario (README.md).

Overview and Scope

ADK version 2.3.0 introduces a GCS first-party toolset to the integrations catalog, alongside existing Pub/Sub and Spanner modules, and adds a create_http_options hook to ContextCacheConfig for cache creation timeouts (README.md). The CLI bundles a built-in AgentBuilderAssistant that bootstraps new agents from a chat session or a working directory (src/google/adk/cli/built_in_agents/README.md). At the same time, the community has repeatedly asked for additional runtimes — for example, Claude skill support (#3611) and Open-WebUI as a backend (#1096) — indicating that the integrations and operations story is still expanding.

First-Party Integrations

ADK exposes integrations as Python sub-packages under google.adk.tools.* plus a configuration-only path through MCP. The table below summarizes the integrations documented in the samples tree.

The GCS toolset, listed in the 2.3.0 changelog (README.md), joins these modules and is the recommended pattern for any new first-party integration: ship a tools/<service>/ Python package plus a runnable sample under contributing/samples/integrations/.

Deployment Patterns

ADK supports three primary deployment modes, all reachable from the CLI:

1. Interactive web — adk web boots a local FastAPI server and a browser UI bound to a single root directory. Built-in agents such as AgentBuilderAssistant rely on this mode for live creation and editing of agent files (src/google/adk/cli/built_in_agents/README.md).
2. Headless run — adk run <agent_dir> executes a single agent from the command line, suitable for scripted invocation. The custom code execution sample uses this to render charts from non-ASCII prompts (contributing/samples/code_execution/custom_code_execution/README.md).
3. Programmatic / server-mode — Application code imports Agent and friends directly. This is the path used by the automated triaging and answering samples (contributing/samples/adk_team/adk_triaging_agent/README.md, contributing/samples/adk_team/adk_answering_agent/README.md).

MCP tools are wired up through YAML configuration with environment-injected headers (see the Notion sample), so the same agent definition can target MCP servers without code changes (contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md). For tools that require async setup, a long-standing limitation tracked in #28 documents the gap between async MCP tool initialization and synchronous agent construction — the recommended mitigation is to wrap MCP toolset creation in an async helper before constructing the agent.

The release pipeline itself highlights the breaking changes from 1.x to 2.0: session schemas generated by ADK 2.0 remain readable by ADK 1.28+, but older 1.x versions cannot consume the new format. Production deployments should pin the runtime version explicitly and run a backfill migration if upgrading across this boundary (README.md).

Operations and Automation

ADK is increasingly used *as an operations tool* — the adk_team/ and adk_documentation/ sample folders contain full-featured automation agents that run both interactively and inside GitHub Actions.

flowchart LR
    A[GitHub Issue / PR / Discussion] --> B[Trigger Workflow]
    B --> C[ADK Agent<br/>triaging / answering / monitoring]
    C --> D{INTERACTIVE = 1?}
    D -- Yes --> E[adk web<br/>Human Approval]
    D -- No  --> F[Label / Comment / Lock<br/>via REST API]
    F --> G[Repository State]
    E --> G

Key operational samples:

• Issue Triaging Assistant assigns component labels (a2a, auth, core, mcp, tools, workflow, etc.), sets Bug/Feature types, and assigns owners when a planned label is present (contributing/samples/adk_team/adk_triaging_agent/README.md).
• PR Triaging Assistant runs on opened / reopened / edited events and applies labels non-interactively when INTERACTIVE=0 (contributing/samples/adk_team/adk_pr_triaging_agent/README.md).
• Issue Monitoring Agent is a cost-optimized moderation bot: it filters comments from maintainers and bots in Python *before* calling the LLM, truncates long bodies, and checks for its own signature to prevent double-flagging loops (contributing/samples/adk_team/adk_issue_monitoring_agent/README.md).
• Answering Agent supports --discussion_number, --recent N, and a --discussion '<json>' mode that consumes the GitHub event payload directly to save API calls (contributing/samples/adk_team/adk_answering_agent/README.md).
• Release Analyzer compares two releases of adk-python and opens documentation-update issues in adk-docs, again with an INTERACTIVE toggle (contributing/samples/adk_team/adk_documentation/adk_release_analyzer/README.md).

In all of these agents, the same INTERACTIVE environment variable switches the runtime between human-supervised and fully automated behavior, which is the canonical operational lever for production deployments.

Configuration and Common Failure Modes

Configuration flows through three channels: a .env file (e.g. GOOGLE_API_KEY, GOOGLE_GENAI_USE_ENTERPRISE), explicit environment variables (GITHUB_TOKEN, OWNER, CREDENTIALS_TYPE), and per-agent YAML for MCP toolsets (contributing/samples/integrations/pubsub/README.md, contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md).

Common failure modes documented across the samples:

• Notion MCP "Unauthorized" or "Object not found" — usually a missing or rotated integration token, or forgetting to grant the integration access to specific pages/databases via the Notion Access tab (contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md).
• Missing video artifacts — the artifacts sample returns an actionable error when opencv-python / numpy are not installed, while still allowing text and image artifacts to function (contributing/samples/core/artifacts/README.md).
• Async vs sync model wiring — agents exporting sync constructors cannot directly await an MCP toolset; defer toolset construction inside an async helper or use the agent-builder built-in to scaffold the wiring (#28, src/google/adk/cli/built_in_agents/README.md).
• Output schema vs tools conflict — combining output_schema with tools used to be disallowed but is now supported via an automatic set_model_response tool injected by ADK; deployers upgrading from older guides should re-test this combination (contributing/samples/tools/output_schema_with_tools/README.md, #701).
• Cache-creation timeouts — the new create_http_options field on ContextCacheConfig controls how long ADK waits when materializing a context cache; tuning this is the recommended remediation for long-running workflows hitting cache timeouts (README.md).

See Also

• Structured Output and Tools
• MCP and External Tooling
• Sessions, Events, and State
• Workflow Runtime and Task API
• Contributing Samples Index

Doramagic Pitfall Log

Found 13 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/google/adk-python/issues/6099

2. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/google/adk-python/issues/5342

3. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/google/adk-python/issues/5600

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/google/adk-python/issues/5712

5. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/google/adk-python

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/google/adk-python/issues/6174

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/google/adk-python/issues/5590

8. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/google/adk-python

9. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/google/adk-python

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/google/adk-python

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/google/adk-python

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/google/adk-python

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using adk-python with real data or production workflows.

• Decision ledger: persist the authority, refusal, and approval behind eac - github / github_issue
• [[FR]: Emit canonical gen_ai.* OTEL metrics from ADK's telemetry layer —](https://github.com/google/adk-python/issues/5600) - github / github_issue
• PROGRESSIVE_SSE_STREAMING is not honored by the LiteLlm adapter — functi - github / github_issue
• [[LiteLLM] _is_thinking_blocks_format drops Gemini thinking_blocks (only](https://github.com/google/adk-python/issues/5712) - github / github_issue
• OpenAPI tool: generate_return_doc crashes on non-numeric response keys ( - github / github_issue
• Text accumulation issue for output_key - github / github_issue
• v2.3.0 - github / github_release
• Release 1.35.2 - github / github_release
• Release 1.35.1 - github / github_release
• Release 1.35.0 - github / github_release
• v2.2.0 - github / github_release
• Release 1.34.2 - github / github_release