# https://github.com/google/adk-python Project Manual

Generated at: 2026-06-21 13:26:52 UTC

## Table of Contents

- [Overview and System Architecture](#page-1)
- [LLM Agents, Tools, and Skills](#page-2)
- [Workflow Runtime and Task API](#page-3)
- [Integrations, Deployment, and Operations](#page-4)

<a id='page-1'></a>

## Overview and System Architecture

### Related Pages

Related topics: [LLM Agents, Tools, and Skills](#page-2), [Workflow Runtime and Task API](#page-3), [Integrations, Deployment, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/google/adk-python/blob/main/README.md)
- [contributing/README.md](https://github.com/google/adk-python/blob/main/contributing/README.md)
- [contributing/samples/core/input_output_schema/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/input_output_schema/README.md)
- [contributing/samples/tools/output_schema_with_tools/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/tools/output_schema_with_tools/README.md)
- [contributing/samples/core/artifacts/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/artifacts/README.md)
- [contributing/samples/hitl/request_input_tool/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/hitl/request_input_tool/README.md)
- [contributing/samples/workflows/loop/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/loop/README.md)
- [contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md)
- [contributing/samples/multimodal/static_non_text_content/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/multimodal/static_non_text_content/README.md)
- [src/google/adk/cli/built_in_agents/README.md](https://github.com/google/adk-python/blob/main/src/google/adk/cli/built_in_agents/README.md)
- [contributing/samples/integrations/spanner_rag_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/spanner_rag_agent/README.md)
- [contributing/samples/adk_team/adk_triaging_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_triaging_agent/README.md)
- [contributing/samples/adk_team/adk_answering_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_answering_agent/README.md)
- [contributing/samples/adk_team/adk_pr_triaging_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_pr_triaging_agent/README.md)
- [contributing/samples/adk_team/adk_issue_monitoring_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_issue_monitoring_agent/README.md)
- [contributing/samples/adk_team/adk_documentation/adk_release_analyzer/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_documentation/adk_release_analyzer/README.md)
- [contributing/samples/config/core_basic_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/config/core_basic_config/README.md)
</details>

# 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:

| Feature | Description |
| :--- | :--- |
| **Workflow Runtime** | A graph-based execution engine for deterministic flows with routing, fan-out/fan-in, loops, retry, state, dynamic nodes, human-in-the-loop, and nested workflows. |
| **Task API** | Structured agent-to-agent delegation with multi-turn task mode, single-turn controlled output, mixed delegation patterns, HITL, and task agents as workflow nodes. |

> **⚠️ 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

```bash
pip install google-adk
```

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

---

## Core Architecture

ADK is organized around a layered architecture that separates agent definition, execution, tooling, and state management. The framework supports multiple agent construction patterns ranging from minimal Python classes to fully declarative YAML configurations.

```mermaid
graph TD
    User[User Input] --> Runner[ADK Runner]
    Runner --> RootAgent[Root Agent]
    RootAgent --> LLM[LLM Agent]
    RootAgent --> Workflow[Workflow Agent]
    LLM --> Tools[Tools / Toolset]
    LLM --> Schema[Input/Output Schema]
    Workflow --> Loop[Loop Node]
    Workflow --> Route[Route Node]
    Tools --> MCP[MCP Tools]
    Tools --> Spanner[Spanner RAG]
    Tools --> Artifacts[Artifacts]
    Runner --> Session[Session Service]
    Runner --> Events[Event Stream]
```

### Agent Construction Patterns

ADK supports two primary patterns for constructing agents:

1. **Code-based (Python classes):** The beginner-friendly approach using the `Agent` class directly. This is the path most samples demonstrate for LLM agents, custom tools, and request-input HITL flows. Source: [contributing/samples/hitl/request_input_tool/README.md:30-44]()
2. **Config-based (YAML):** The declarative approach where an agent is described by `root_agent.yaml`. The basic configuration covers name, description, and model. Source: [contributing/samples/config/core_basic_config/README.md:1-8]()

### Input/Output Schema

Agents can be constrained with Pydantic models passed via `input_schema` and `output_schema`. When combined with `mode='single_turn'`, an agent can be invoked as a structured tool by a parent agent. Source: [contributing/samples/core/input_output_schema/README.md:1-22]()

### Structured Output with Tools

A long-standing community constraint stated that `output_schema` disabled tool usage. This was addressed by a special processor: when both `output_schema` and `tools` are specified, ADK automatically adds a `set_model_response` tool. The model uses regular tools for information gathering, then emits structured data via `set_model_response`, which ADK extracts and validates. Source: [contributing/samples/tools/output_schema_with_tools/README.md:1-23](). Community discussion of this constraint is tracked in issue #701.

### Workflow Runtime

The workflow runtime uses a graph-based model. Nodes yield `Event` objects that carry a `route`, and edges are defined with a routing map. Conditional edges connect a routing node back to a previous node to form loops. For example, a `route_headline` function can return `Event(route=node_input.grade)` to route an "unrelated" grade back to a generator. Source: [contributing/samples/workflows/loop/README.md:1-32]()

---

## Built-in Tools and Extensions

ADK ships with a rich ecosystem of tools, toolsets, and built-in agents that extend agent capabilities without requiring external integration code.

### Artifacts

Artifacts allow agents to persist binary or text content across turns. The artifacts sample demonstrates:

- **Text artifacts** with MIME type (`text/plain` or `text/html`) and file extension (`.txt` or `.html`)
- **Media artifacts** generated via `types.Part.from_bytes` and `ctx.save_artifact` for image, audio, and video (with OpenCV)
- **Versioning**, where the `generate_report` tool increments a version on each call
- **Loading** via the built-in `LoadArtifactsTool` (exposed to the model as `load_artifacts`)

Source: [contributing/samples/core/artifacts/README.md:1-15]()

### MCP Toolset

The Model Context Protocol (MCP) is supported via `MCPToolset`, which exposes async methods for connecting to MCP servers. A typical config-based MCP integration (e.g., Notion) requires an `OPENAPI_MCP_HEADERS` environment variable carrying an authorization bearer token. Source: [contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md:20-30](). Note that the async-only nature of `MCPToolset` is the subject of community issue #28, which requests support for asynchronous initialization of `root_model` in ADK agents.

### Multimodal Static Content

ADK supports static instructions containing mixed content types — text, `inline_data` (base64-encoded images), and `file_data` (Gemini Files API or GCS URIs). Non-text parts receive automatic reference IDs like `inline_data_0` and `file_data_1`. The Vertex AI backend supports both GCS URI and HTTPS URL access methods. Source: [contributing/samples/multimodal/static_non_text_content/README.md:1-30]()

### Spanner RAG Integration

The `google.adk.tools.spanner` module provides built-in tools for Spanner-backed RAG using native Spanner vector search (KNN or ANN). Real-time data is returned as soon as transactions are committed. Custom tools can be created by extending the existing ones. Source: [contributing/samples/integrations/spanner_rag_agent/README.md:1-18]()

### Built-in CLI Agents

The CLI ships with built-in agents including an `AgentBuilderAssistant` that supports schema discovery, project structure analysis, and dynamic path resolution bound to a session's working directory. Two schema modes are offered:

| Mode | Behavior | Best For |
| :--- | :--- | :--- |
| **Embedded** | Full `AgentConfig` schema embedded in context | Faster execution, higher token usage |
| **Query** | Dynamic schema queries via tools | Lower initial token usage, targeted operations |

Source: [src/google/adk/cli/built_in_agents/README.md:1-30]()

### Human-in-the-Loop: Request Input

The built-in `request_input` tool allows an LLM agent to proactively request clarification from the user without losing context. The agent dynamically constructs a JSON schema to ask only for missing details. Source: [contributing/samples/hitl/request_input_tool/README.md:1-22]()

---

## Community Agents and Roadmap

The ADK project maintains a set of community reference agents in `contributing/samples/adk_team/` that demonstrate governance and operational patterns. These agents are dual-mode (interactive via `adk web`, or fully automated via GitHub Actions).

### Community Reference Agents

| Agent | Purpose | Source |
| :--- | :--- | :--- |
| **Issue Triaging Assistant** | Adds component labels, sets Bug/Feature type, assigns owners based on label rules | [contributing/samples/adk_team/adk_triaging_agent/README.md:1-18]() |
| **PR Triaging Assistant** | Recommends labels, assigns reviewers, checks contribution guides for new PRs | [contributing/samples/adk_team/adk_pr_triaging_agent/README.md:1-14]() |
| **Issue Monitoring Agent** | Audits GitHub issues for SEO spam, applies `spam` label, pre-filters maintainer comments | [contributing/samples/adk_team/adk_issue_monitoring_agent/README.md:1-12]() |
| **Answering Agent** | Answers GitHub Discussions, batch-processes recent discussions, runs as GitHub Action | [contributing/samples/adk_team/adk_answering_agent/README.md:1-30]() |
| **Release Analyzer** | Diff-compares releases, identifies required docs updates, files GitHub issues | [contributing/samples/adk_team/adk_documentation/adk_release_analyzer/README.md:1-16]() |

### Community-Driven Roadmap

The ADK Roadmap 2025 Q3 (issue #2133) is a publicly tracked discussion where the team shares ongoing work and invites community contribution. Top community feature requests tracked in discussions include:

- **#3611** — Support for the Claude skill feature across GCP foundational models
- **#2133** — Roadmap 2025 Q3
- **#701** — Structured output (`output_schema`) alongside tool calls (now addressed)
- **#28** — Asynchronous initialization for `root_model`
- **#1096** — Native Open-WebUI support as a backend

Source: Community context surfaced in [contributing/samples/adk_team/adk_pr_triaging_agent/README.md:1-10]()

---

## See Also

- [Output Schema with Tools](output-schema-with-tools.md)
- [MCP Toolset and Notion Integration](mcp-toolset-notion.md)
- [Workflow Loops and Conditional Routing](workflow-loops.md)
- [Artifacts and Media Handling](artifacts.md)
- [Human-in-the-Loop: Request Input](hitl-request-input.md)
- [Community Reference Agents](adk-team-agents.md)
- [Contributing Guide](contributing.md)

---

<a id='page-2'></a>

## LLM Agents, Tools, and Skills

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [Workflow Runtime and Task API](#page-3), [Integrations, Deployment, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/google/adk-python/blob/main/README.md)
- [src/google/adk/models/llm_response.py](https://github.com/google/adk-python/blob/main/src/google/adk/models/llm_response.py)
- [contributing/samples/config/core_basic_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/config/core_basic_config/README.md)
- [contributing/samples/multi_agent/multi_agent_basic_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/multi_agent/multi_agent_basic_config/README.md)
- [contributing/samples/core/input_output_schema/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/input_output_schema/README.md)
- [contributing/samples/tools/output_schema_with_tools/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/tools/output_schema_with_tools/README.md)
- [contributing/samples/hitl/request_input_tool/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/hitl/request_input_tool/README.md)
- [contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md)
- [contributing/samples/integrations/spanner_rag_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/spanner_rag_agent/README.md)
- [contributing/samples/multimodal/static_non_text_content/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/multimodal/static_non_text_content/README.md)
- [contributing/samples/models/litellm_with_fallback_models/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/models/litellm_with_fallback_models/README.md)
- [contributing/samples/models/hello_world_apigeellm/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/models/hello_world_apigeellm/README.md)
</details>

# 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](https://github.com/google/adk-python/issues/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]()).

```mermaid
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:

| Tool family | Purpose | Sample reference |
|-------------|---------|------------------|
| Function tools (e.g. `create_support_ticket`) | Domain-specific Python callables | `contributing/samples/hitl/request_input_tool/README.md` |
| `request_input` | Human-in-the-loop clarification with a dynamic JSON schema | `contributing/samples/hitl/request_input_tool/README.md` |
| MCP toolsets | Connect to external MCP servers (e.g. Notion) over stdio | `contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md` |
| Built-in Spanner tools | RAG and KNN/ANN vector search against Cloud Spanner | `contributing/samples/integrations/spanner_rag_agent/README.md` |
| First-party GCS toolset | Cloud Storage integration added in v2.3.0 | `README.md` release notes |

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](https://github.com/google/adk-python/issues/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](https://github.com/google/adk-python/issues/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](https://github.com/google/adk-python/issues/3611), 42 comments). The ADK roadmap thread ([issue #2133](https://github.com/google/adk-python/issues/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)](https://github.com/google/adk-python/issues/2133), [Claude skills (#3611)](https://github.com/google/adk-python/issues/3611), [Output schema + tools (#701)](https://github.com/google/adk-python/issues/701), [Async root_model (#28)](https://github.com/google/adk-python/issues/28)

---

<a id='page-3'></a>

## Workflow Runtime and Task API

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [LLM Agents, Tools, and Skills](#page-2), [Integrations, Deployment, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/google/adk/workflow/_workflow.py](https://github.com/google/adk-python/blob/main/src/google/adk/workflow/_workflow.py)
- [src/google/adk/workflow/_graph.py](https://github.com/google/adk-python/blob/main/src/google/adk/workflow/_graph.py)
- [src/google/adk/workflow/_node.py](https://github.com/google/adk-python/blob/main/src/google/adk/workflow/_node.py)
- [src/google/adk/workflow/_function_node.py](https://github.com/google/adk-python/blob/main/src/google/adk/workflow/_function_node.py)
- [src/google/adk/workflow/_llm_agent_wrapper.py](https://github.com/google/adk-python/blob/main/src/google/adk/workflow/_llm_agent_wrapper.py)
- [src/google/adk/workflow/_parallel_worker.py](https://github.com/google/adk-python/blob/main/src/google/adk/workflow/_parallel_worker.py)
- [src/google/adk/events/event.py](https://github.com/google/adk-python/blob/main/src/google/adk/events/event.py)
- [contributing/samples/workflows/route/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/route/README.md)
- [contributing/samples/workflows/state/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/state/README.md)
- [contributing/samples/workflows/loop/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/loop/README.md)
- [contributing/samples/workflows/loop_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/loop_config/README.md)
- [contributing/samples/workflows/request_input/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/request_input/README.md)
- [contributing/samples/workflows/request_input_advanced/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/request_input_advanced/README.md)
- [contributing/samples/workflows/parallel_worker/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/parallel_worker/README.md)
- [contributing/samples/core/input_output_schema/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/input_output_schema/README.md)
- [contributing/samples/patterns/workflow_triage/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/patterns/workflow_triage/README.md)
</details>

# 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.

| Pattern | Mechanism | Sample |
| --- | --- | --- |
| Routing | Conditional edge keyed on `Event.route`; LLM classifies input, dispatcher routes to specialised agent | [contributing/samples/workflows/route/README.md]() |
| Loop (Python) | A grader node yields the previous node's name as a route to cycle back; terminates when a different route has no outgoing edge | [contributing/samples/workflows/loop/README.md]() |
| Loop (YAML) | Same as above, with `output_schema_code` resolving a Pydantic model by dotted path (`.agent.Feedback`) | [contributing/samples/workflows/loop_config/README.md]() |
| Parallel workers | `parallel_worker=True` on a node whose input is an iterable; runtime fans out then joins | [contributing/samples/workflows/parallel_worker/README.md]() |
| HITL (simple) | Node yields `RequestInput(message=...)`; next node receives the user's reply as `node_input` | [contributing/samples/workflows/request_input/README.md]() |
| HITL (structured) | Same as above plus `payload` (UI data) and `response_schema` (constrained JSON) | [contributing/samples/workflows/request_input_advanced/README.md]() |
| Structured I/O | `Agent(input_schema=..., output_schema=..., mode='single_turn')` used as a typed tool by a parent agent | [contributing/samples/core/input_output_schema/README.md]() |
| Manager + workers | Manager LLM updates an execution plan, `SequentialAgent`/`ParallelAgent` run the chosen workers, summary agent closes out | [contributing/samples/patterns/workflow_triage/README.md]() |

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](https://github.com/google/adk-python/issues/2133)

---

<a id='page-4'></a>

## Integrations, Deployment, and Operations

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [LLM Agents, Tools, and Skills](#page-2), [Workflow Runtime and Task API](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/google/adk-python/blob/main/README.md)
- [contributing/README.md](https://github.com/google/adk-python/blob/main/contributing/README.md)
- [src/google/adk/cli/built_in_agents/README.md](https://github.com/google/adk-python/blob/main/src/google/adk/cli/built_in_agents/README.md)
- [contributing/samples/integrations/pubsub/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/pubsub/README.md)
- [contributing/samples/integrations/spanner_rag_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/spanner_rag_agent/README.md)
- [contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md)
- [contributing/samples/adk_team/adk_triaging_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_triaging_agent/README.md)
- [contributing/samples/adk_team/adk_answering_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_answering_agent/README.md)
- [contributing/samples/adk_team/adk_issue_monitoring_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_issue_monitoring_agent/README.md)
- [contributing/samples/adk_team/adk_pr_triaging_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_pr_triaging_agent/README.md)
- [contributing/samples/adk_team/adk_documentation/adk_release_analyzer/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/adk_documentation/adk_release_analyzer/README.md)
- [contributing/samples/code_execution/custom_code_execution/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/code_execution/custom_code_execution/README.md)
- [contributing/samples/core/artifacts/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/artifacts/README.md)
</details>

# 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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/issues/3611)) and **Open-WebUI as a backend** ([#1096](https://github.com/google/adk-python/issues/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.

| Integration | Sample Path | Capabilities | Notes |
| --- | --- | --- | --- |
| Pub/Sub | `contributing/samples/integrations/pubsub/` | `publish_message`, `pull_messages`, `acknowledge_messages` | Supports ADC or service account keys via `CREDENTIALS_TYPE` ([contributing/samples/integrations/pubsub/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/pubsub/README.md)). |
| Spanner (RAG) | `contributing/samples/integrations/spanner_rag_agent/` | Vector search (KNN/ANN), product retrieval | Demonstrates extending built-in Spanner tools with custom variants ([contributing/samples/integrations/spanner_rag_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/spanner_rag_agent/README.md)). |
| Notion (MCP) | `contributing/samples/mcp/tool_mcp_stdio_notion_config/` | Page/database search, create pages | Uses `OPENAPI_MCP_HEADERS` and `Notion-Version: 2022-06-28` ([contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md)). |
| Artifacts | `contributing/samples/core/artifacts/` | Text, image, audio, video versioning | Requires `opencv-python` and `numpy` for video generation ([contributing/samples/core/artifacts/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/artifacts/README.md)). |
| Custom Code Execution | `contributing/samples/code_execution/custom_code_execution/` | Sandboxed interpreter for plotting, scripts | Invoked via `adk run` or `adk web` ([contributing/samples/code_execution/custom_code_execution/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/code_execution/custom_code_execution/README.md)). |

The GCS toolset, listed in the 2.3.0 changelog ([README.md](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/contributing/samples/adk_team/adk_triaging_agent/README.md), [contributing/samples/adk_team/adk_answering_agent/README.md](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md)). For tools that require async setup, a long-standing limitation tracked in [#28](https://github.com/google/adk-python/issues/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](https://github.com/google/adk-python/blob/main/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.

```mermaid
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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/contributing/samples/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](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/pubsub/README.md), [contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/issues/28), [src/google/adk/cli/built_in_agents/README.md](https://github.com/google/adk-python/blob/main/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](https://github.com/google/adk-python/blob/main/contributing/samples/tools/output_schema_with_tools/README.md), [#701](https://github.com/google/adk-python/issues/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](https://github.com/google/adk-python/blob/main/README.md)).

## See Also

- [Structured Output and Tools](structured-output-and-tools.md)
- [MCP and External Tooling](mcp-and-external-tooling.md)
- [Sessions, Events, and State](sessions-events-and-state.md)
- [Workflow Runtime and Task API](workflow-runtime-and-task-api.md)
- [Contributing Samples Index](contributing-samples-index.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: google/adk-python

Summary: 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
- Evidence strength: source_linked
- 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.
- 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
- Evidence strength: source_linked
- 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.
- 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
- Evidence strength: source_linked
- 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.
- 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/google/adk-python/issues/5712

## 5. Identity risk - Identity risk requires verification

- Severity: medium
- Evidence strength: runtime_trace
- 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.
- Repro command: `pip install google-adk`
- Evidence: identity.distribution | https://github.com/google/adk-python

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/google/adk-python/issues/6174

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/google/adk-python/issues/5590

## 8. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/google/adk-python

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/google/adk-python

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/google/adk-python

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/google/adk-python

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/adk-python

## 13. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/adk-python

<!-- canonical_name: google/adk-python; human_manual_source: deepwiki_human_wiki -->