# https://github.com/google/adk-python 项目说明书

生成时间：2026-06-21 12:52:50 UTC

## 目录

- [ADK 概述与核心代理类型](#page-1)
- [Workflow 运行时与 Task API](#page-2)
- [工具、MCP 与集成生态](#page-3)
- [会话、内存、模型、评估与部署](#page-4)

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

## ADK 概述与核心代理类型

### 相关页面

相关主题：[Workflow 运行时与 Task API](#page-2), [工具、MCP 与集成生态](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [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/app/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/app/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/workflows/loop/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/loop/README.md)
- [contributing/samples/workflows/route/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/route/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)
- [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)
- [src/google/adk/labs/README.md](https://github.com/google/adk-python/blob/main/src/google/adk/labs/README.md)
</details>

# ADK 概述与核心代理类型

## ADK 框架定位与 2.0 架构演进

Google Agent Development Kit（ADK）是一个用于构建代理式应用（agentic apps）的 Python 框架。仓库文档说明 "ADK applications are built using two main classes"（资料来源：[README.md](https://github.com/google/adk-python/blob/main/README.md)），其要求 Python 3.10+，可通过 `pip install google-adk` 安装，并通过 `[extensions]` 安装可选集成。

2.0 版本引入了两项核心能力：

- **Workflow Runtime**：基于图的执行引擎，支持路由、扇出/扇入、循环、重试、状态管理、动态节点、人机协同与嵌套工作流。
- **Task API**：结构化的代理间委派机制，覆盖多轮任务模式、单轮受控输出、混合委派模式、人机协同，以及作为工作流节点的任务代理。

需要注意的是，2.0 与 1.x 之间存在重大不兼容：2.0 写入的会话（session）只能被 1.28+ 读取，更早的 1.x 版本无法解析（资料来源：[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)。

## 核心代理类型与角色

ADK 围绕"代理（agent）"概念组织代码，多种代理类型承担不同职责。下表归纳了仓库示例所展示的主要形态：

| 代理/容器 | 角色 | 关键特性 |
| --- | --- | --- |
| `Agent`（LLM 代理） | 由大模型驱动的对话单元 | 指令、工具、结构化输入/输出 |
| `App` | 顶层应用容器，包裹根代理或工作流 | 插件、事件压缩、上下文缓存 |
| `Workflow` 节点 | 确定性图执行单元 | 路由、循环、扇出/扇入 |
| 内建 CLI 代理 | 自举式代理开发助手 | 项目结构分析、动态路径解析 |
| 实验特性（Labs） | 尚不稳定的新能力 | 标注 WARNING，禁止生产依赖 |

`App` 容器位于系统最外层，承载 `root_agent` 并允许附加插件、事件压缩与上下文缓存等横切配置（资料来源：[contributing/samples/core/app/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/app/README.md)）。CLI 提供的 `AgentBuilderAssistant` 等内建代理用于脚手架搭建，提供 "embedded" 与 "query" 两种 schema 模式以权衡初始 token 用量与执行速度（资料来源：[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)）。`src/google/adk/labs/` 目录收纳实验特性，明确标注 "experimental" 并可能随时变更或删除（资料来源：[src/google/adk/labs/README.md](https://github.com/google/adk-python/blob/main/src/google/adk/labs/README.md)）。

## 代理执行模式与结构化输出

工作流图通过边（edge）连接节点。路由示例展示了如何基于分类结果将执行分发到不同分支（资料来源：[contributing/samples/workflows/route/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/route/README.md)）；循环示例则通过条件边把评估未通过的节点重新送回上游节点，直到产出合格结果（资料来源：[contributing/samples/workflows/loop/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/loop/README.md)）。

`Agent` 可通过 `input_schema` 与 `output_schema` 定义 Pydantic 契约，当与 `mode='single_turn'` 配合时即可作为结构化工具被父代理调用（资料来源：[contributing/samples/core/input_output_schema/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/input_output_schema/README.md)）。历史上 `output_schema` 与工具调用互斥（社区 Issue #701），新版本通过自动注入 `set_model_response` 内部工具解决了该约束，使模型可继续使用常规工具收集信息，最后再以结构化方式返回（资料来源：[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)）。

## 社区关注点与已知限制

根据社区讨论，开发者当前关注的主要议题包括：

- **结构化输出与工具协同**：Issue #701 报告了 `output_schema` 禁用工具的历史限制，现已通过专用处理器修复。
- **异步初始化**：Issue #28 指出 `MCPToolset` 仅暴露异步方法，而代理构造是同步的，文档示例需额外处理。
- **多模型后端**：Issue #3611 希望 ADK 暴露 Claude skills 能力；Issue #1096 提议将 Open WebUI 集成为一等后端。
- **路线图与计划**：Issue #2133 汇总了 2025 Q3 路线图，是社区了解演进方向的主要窗口。

## 参见

- [贡献者示例目录](https://github.com/google/adk-python/tree/main/contributing/samples)
- [官方 ADK 文档](https://google.github.io/adk-docs/)
- [示例仓库 adk-samples](https://github.com/google/adk-samples)

---

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

## Workflow 运行时与 Task API

### 相关页面

相关主题：[ADK 概述与核心代理类型](#page-1), [会话、内存、模型、评估与部署](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/google/adk-python/blob/main/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/route/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/route/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/state/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/state/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/multi_agent/multi_agent_seq_config/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/multi_agent/multi_agent_seq_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/hitl/request_input_tool/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/hitl/request_input_tool/README.md)
</details>

# Workflow 运行时与 Task API

## 概述与定位

`Workflow 运行时`（Workflow Runtime）与 `Task API` 是 Google ADK（Agent Development Kit）2.0 引入的两大核心能力，用以将"代理（agent）"与"确定性流程"解耦并协同工作。资料来源：[README.md](README.md) 指出：

> **Workflow Runtime**: A graph-based execution engine for composing deterministic execution flows for agentic apps, with support for routing, fan-out/fan-in, loops, retry, state management, 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, human-in-the-loop, and task agents as workflow nodes.

简而言之，Workflow Runtime 提供"图（graph）式"的可视化执行流；Task API 提供"结构化的代理间委托"接口。两者结合后，开发者既能用流程编排把控主干逻辑，又能在节点中嵌入 LLM 代理完成非确定性决策。

## 核心抽象：节点、事件、状态

Workflow 的最小执行单元是 **节点（Node）**。节点既可以是普通 Python 函数（`function node`），也可以是 LLM Agent。节点之间通过 **边（edges）** 串联，包括顺序边与条件边（带路由映射表）。资料来源：[contributing/samples/workflows/route/README.md](contributing/samples/workflows/route/README.md) 展示了条件路由的写法：

```python
yield Event(route="your_route_name")
# 在 edges 中通过 {"your_route_name": target_node} 建立映射
```

节点在执行过程中通过 **事件（Event）** 与运行时通信。常见的事件载荷包括 `route`（用于分支路由）、`state`（用于跨节点状态注入）、`RequestInput`（用于挂起并请求人工输入）。资料来源：[contributing/samples/workflows/state/README.md](contributing/samples/workflows/state/README.md) 列出 4 种状态读写方式：

| 方式 | 写 | 读 |
| --- | --- | --- |
| 直接字典操作 | `ctx.state["k"] = v` | `ctx.state["k"]` |
| 通过 Event | `yield Event(state={"k": v})` | 自动注入为函数参数 `def func(k): ...` |

## 关键能力

**路由（Routing）**：根据上一节点的输出，将执行流分发到不同分支。资料来源：[contributing/samples/workflows/route/README.md](contributing/samples/workflows/route/README.md) 中，分类节点将输入分为 `question`、`statement`、`other` 三类，分别路由至三个处理节点。

**循环（Loop）**：通过让路由节点指回上游节点实现迭代式精炼。资料来源：[contributing/samples/workflows/loop/README.md](contributing/samples/workflows/loop/README.md) 演示了"生成→评估→路由→若不通过则回到生成"的反馈循环。

**重试与回退**：与循环能力结合，可在节点级定义重试上限、回退目标节点，从而把"模型偶发失败"等非确定性纳入可控范围（参见 [README.md](README.md) 中关于 retry 的描述）。

**人机协作（Human-in-the-Loop）**：节点可 `yield` 一个 `RequestInput` 事件来挂起执行并等待人工反馈，下游节点以用户输入作为参数。资料来源：[contributing/samples/workflows/request_input/README.md](contributing/samples/workflows/request_input/README.md) 给出了"草稿邮件 → 人工审阅 → 批准 / 拒绝 / 修订"的完整模式。高级用法可附带 `payload` 与 `response_schema`，强制要求结构化响应。资料来源：[contributing/samples/workflows/request_input_advanced/README.md](contributing/samples/workflows/request_input_advanced/README.md) 演示了"请假天数 ≤ 1 自动批准，> 1 提交经理审批"的分支。

**嵌套工作流（Nested Workflows）**：一个 Workflow 节点可以是另一个 Workflow，从而把大型流程拆解为可复用、可独立测试的子图（参见 [README.md](README.md)）。

**YAML 配置化**：除 Python 外，节点与边可通过 YAML 描述。资料来源：[contributing/samples/workflows/loop_config/README.md](contributing/samples/workflows/loop_config/README.md) 介绍了两个 YAML 专用语法：`_code` 后缀字段（如 `output_schema_code: .agent.Feedback`）解析为 Python 代码引用；非 `.yaml`、非 `START` 的字符串解析为函数引用（如 `.agent.process_input`）。

## Task API：代理间结构化委托

Task API 把"代理调用代理"从"自然语言往返"提升为"强类型任务"。其支持的关键模式（参见 [README.md](README.md)）：

- **多轮任务模式（multi-turn task mode）**：父代理可开启多轮交互，与子代理持续交换上下文。
- **单轮受控输出（single-turn controlled output）**：通过 `output_schema` 约束子代理的返回结构。
- **混合委托（mixed delegation patterns）**：在同一工作流中混用"调用即返回"与"持续委托"。
- **人机协作**：委托过程中可随时插入人工审阅步骤。
- **任务代理作为工作流节点（task agents as workflow nodes）**：让 Task API 的执行单元直接出现在 Workflow 图中。

资料来源：[contributing/samples/core/input_output_schema/README.md](contributing/samples/core/input_output_schema/README.md) 演示了"父代理 → 调用带 `input_schema` / `output_schema` 的子代理 → 接收结构化结果"这一典型 Task API 链路。当 `output_schema` 与 `tools` 同时出现时，ADK 会自动注入一个特殊 `set_model_response` 工具，使模型能够用工具收集信息、再以结构化形式交付最终响应——该限制在 issue #701 中被社区长期关注，并已在新版本中解除。资料来源：[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)。

## 与社区反馈的呼应

社区 issue #28 长期请求对 `root_model` 的异步初始化支持。在 Workflow Runtime 中，函数节点天然以异步形式编排，LLM 节点可通过异步工具集（如 `MCPToolset`）接入，间接缓解了该痛点。资料来源：[contributing/samples/hitl/request_input_tool/README.md](contributing/samples/hitl/request_input_tool/README.md) 展示了 `request_input` 工具在 LLM Agent 中的使用方式，是 Task API "人机协作"模式在 LLM 节点上的对应实现。

## See Also

- 代理基础：[README.md](README.md)
- 多代理顺序流：[contributing/samples/multi_agent/multi_agent_seq_config/README.md](contributing/samples/multi_agent/multi_agent_seq_config/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)
- ADK Roadmap 2025 Q3：参见 issue #2133

---

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

## 工具、MCP 与集成生态

### 相关页面

相关主题：[ADK 概述与核心代理类型](#page-1), [会话、内存、模型、评估与部署](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/google/adk-python/blob/main/README.md)
- [src/google/adk/tools/function_tool.py](https://github.com/google/adk-python/blob/main/src/google/adk/tools/function_tool.py)
- [src/google/adk/tools/base_tool.py](https://github.com/google/adk-python/blob/main/src/google/adk/tools/base_tool.py)
- [src/google/adk/tools/base_toolset.py](https://github.com/google/adk-python/blob/main/src/google/adk/tools/base_toolset.py)
- [src/google/adk/tools/mcp_tool/mcp_toolset.py](https://github.com/google/adk-python/blob/main/src/google/adk/tools/mcp_tool/mcp_toolset.py)
- [src/google/adk/tools/mcp_tool/mcp_session_manager.py](https://github.com/google/adk-python/blob/main/src/google/adk/tools/mcp_tool/mcp_session_manager.py)
- [src/google/adk/models/anthropic_llm.py](https://github.com/google/adk-python/blob/main/src/google/adk/models/anthropic_llm.py)
- [src/google/adk/models/interactions_utils.py](https://github.com/google/adk-python/blob/main/src/google/adk/models/interactions_utils.py)
- [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/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/integrations/spanner_rag_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/spanner_rag_agent/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/antigravity_agent/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/antigravity_agent/README.md)
- [contributing/samples/core/artifacts/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/artifacts/README.md)
</details>

# 工具、MCP 与集成生态

## 概述

`google-adk`（Agent Development Kit）是一套面向生产级智能体应用的 Python 框架，工具（Tool）、工具集（Toolset）、MCP（Model Context Protocol）以及与外部系统的集成共同构成了 ADK 的扩展能力。工具是智能体与外部世界交互的最小单元；MCP 则提供了一种标准化的进程间协议，让本地或远程 MCP 服务器的能力以统一的形式被 ADK 智能体发现与调用；在此之上，ADK 还提供了多种 Google Cloud 一方工具集以及第三方模型（Anthropic Claude 等）适配，组成了一个开放的工具与集成生态。资料来源：[README.md:1-40]()

## 工具与工具集的核心抽象

ADK 中的工具分为两个层级。**单个工具**继承自 `BaseTool`，负责单次能力调用；**工具集**继承自 `BaseToolset`，负责以集合方式暴露并按需解析工具。`BaseToolset` 定义了 `async get_tools`、`async close` 等异步方法，使得工具集能够懒加载、按上下文构造工具实例。资料来源：[src/google/adk/tools/base_toolset.py]()

`FunctionTool` 是最常用的入口，它将普通 Python 函数包装为符合 LLM 工具调用约定的对象，从而让用户可以把任意同步函数注册到智能体上。结合 `output_schema`，ADK 还引入了名为 `set_model_response` 的内部工具，使得智能体能够在使用普通工具的同时输出结构化 JSON，社区问题 #701 "Structured Output (output schema) + Tool Call" 中描述的"output_schema 禁用工具"约束已经通过该特殊处理器被打破。资料来源：[contributing/samples/tools/output_schema_with_tools/README.md]()

## MCP 集成与社区需求

`McpToolset` 通过 `McpSessionManager` 维持与 MCP 服务器的会话，支持 stdio、SSE、HTTP 等多种传输形式。在配置式智能体中，开发者只需在 YAML 中声明 `OPENAPI_MCP_HEADERS` 等环境变量即可挂载外部 MCP 服务，例如 `tool_mcp_stdio_notion_config` 示例演示了如何让 ADK 智能体通过 Notion MCP 服务器操作页面与数据库。资料来源：[contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md]()

由于 `McpToolset` 仅暴露 `async` 初始化接口，而 LLM Agent 本身对外是同步的，社区问题 #28 反映了"root_model 异步初始化"的诉求——开发者希望在声明 `root_agent` 时可以直接以同步方式获取 MCP 工具。该问题提示在封装 MCP 工具集时需要使用 `asyncio.run` 或在 agent 工厂函数内做异步桥接。资料来源：[src/google/adk/tools/mcp_tool/mcp_toolset.py]()、[src/google/adk/tools/mcp_tool/mcp_session_manager.py]()

## 集成生态：一方工具集与第三方模型

除 MCP 外，ADK 在 `google.adk.tools.*` 命名空间下提供多个 Google Cloud 一方工具集，最新 v2.3.0 加入了 **GCS 工具集**。典型的集成示例包括：

- **Spanner RAG**：利用 Spanner 内置向量索引（KNN/ANN）实现操作型数据上的实时 RAG，工具位于 `google.adk.tools.spanner`，并支持基于现有工具派生自定义工具。资料来源：[contributing/samples/integrations/spanner_rag_agent/README.md]()
- **Pub/Sub**：通过 `publish_message`、`pull_messages`、`acknowledge_messages` 三个工具完成消息的发布、订阅与确认，支持 ADC 与服务账号两种凭证模式。资料来源：[contributing/samples/integrations/pubsub/README.md]()
- **Antigravity Agent**：将 ADK Runner 与 Antigravity SDK 智能体桥接，SDK 在本地模式下驱动 Go harness，再把轨迹步骤映射回 ADK 事件流。资料来源：[contributing/samples/integrations/antigravity_agent/README.md]()

在模型层，`AnthropicLlm` 将 Anthropic 的 `ContentBlock`（包括 `ThinkingBlock`、`RedactedThinkingBlock`、`ToolUseBlock`）转译为 `genai.Part`，并把 `cache_read_input_tokens` 视作 cached_content 的等价物，从而在多轮对话中保留 Claude 的推理签名。资料来源：[src/google/adk/models/anthropic_llm.py]()、[src/google/adk/models/interactions_utils.py]()

社区中呼声较高的话题包括 #3611 "Support Claude skill feature"——希望在 ADK 中正式暴露 Anthropic Skills 能力以替代手工拼装提示词；以及 #1096 "Add native Open-WebUI support as a backend for Google ADK"——把 ADK 作为后端嵌入 Open WebUI。这两项需求表明，围绕第三方模型与多端 UI 的集成正在成为生态扩展的重点方向。

## 工具调用与制品的协同

工具执行常会产出需要持久化或回传的二进制结果。`core/artifacts` 示例展示了文本（`text/plain`）、HTML（`text/html`）与媒体（image/audio/video）三种制品的保存方式：通过 `ctx.save_artifact` 与 `types.Part.from_bytes` 写入，再由内置的 `LoadArtifactsTool`（模型侧为 `load_artifacts`）按版本号加载最新结果。视频制品依赖 `opencv-python` 与 `numpy`，未安装时会回退到友好的错误提示。资料来源：[contributing/samples/core/artifacts/README.md]()

## 常见失败模式

| 现象 | 可能原因 | 处置建议 |
| :--- | :--- | :--- |
| `Unauthorized` (MCP Notion) | Token 错误或未授权页面 | 检查 `OPENAPI_MCP_HEADERS` 中的 Notion Token 与访问权限 |
| MCP 工具未出现 | 同步 Agent 中未等待 `get_tools` | 在工厂函数内 `asyncio.run` 异步获取工具列表 |
| 视频制品报错 | 缺少 `opencv-python`/`numpy` | 按 `artifacts/README.md` 提示安装依赖 |
| Claude 推理中断 | 未回传 `RedactedThinkingBlock.data` | 确保 `anthropic_llm.py` 的转译路径完整 |

## 参见

- 工作流运行时与任务 API：[README.md:24-39]()
- 配置式智能体与 MCP 挂载：[contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md]()
- Spanner RAG 与内置向量搜索：[contributing/samples/integrations/spanner_rag_agent/README.md]()
- Pub/Sub 一方工具集：[contributing/samples/integrations/pubsub/README.md]()
- 制品与版本化加载：[contributing/samples/core/artifacts/README.md]()

---

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

## 会话、内存、模型、评估与部署

### 相关页面

相关主题：[ADK 概述与核心代理类型](#page-1), [Workflow 运行时与 Task API](#page-2), [工具、MCP 与集成生态](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/google/adk-python/blob/main/README.md)
- [src/google/adk/models/anthropic_llm.py](https://github.com/google/adk-python/blob/main/src/google/adk/models/anthropic_llm.py)
- [contributing/samples/models/litellm_structured_output/agent.py](https://github.com/google/adk-python/blob/main/contributing/samples/models/litellm_structured_output/agent.py)
- [contributing/samples/models/hello_world_apigeellm/agent.py](https://github.com/google/adk-python/blob/main/contributing/samples/models/hello_world_apigeellm/agent.py)
- [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/pubsub/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/pubsub/README.md)
- [contributing/samples/workflows/loop/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/loop/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)
- [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/core/artifacts/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/artifacts/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)
</details>

# 会话、内存、模型、评估与部署

## 一、概览

ADK（Agent Development Kit）Python 版本是一套用于构建、运行与部署 AI 智能体（Agent）的开源框架。`README.md` 明确指出，ADK 2.0 引入了 **Workflow Runtime**（基于图结构的执行引擎，支持路由、扇出/扇入、循环、重试、状态管理、动态节点、人机协同和嵌套工作流），以及 **Task API**（结构化的智能体间委派协议），构成会话、内存、模型、评估与部署的运行时底座 资料来源：[README.md:10-18]()。

在 2.x 系列中，会话模型与事件模型经历了破坏性变更：`README.md` 强调 "Sessions generated by ADK 2.0 are readable by ADK 1.28+，但与更早的 1.x 不兼容"，这要求部署与评估管线在升级时同时考虑兼容窗口 资料来源：[README.md:5-9]()。

## 二、模型集成（Models）

ADK 通过统一抽象支持多类基础模型。`src/google/adk/models/anthropic_llm.py` 提供了对 Anthropic Claude 的适配，其中 `content_block_to_part` 负责将 Anthropic 特有的内容块（`ThinkingBlock`、`RedactedThinkingBlock`、`TextBlock`、`ToolUseBlock`）转换为生成式 Part，保留 `thought_signature` 以便在下一轮对话中回传到 Claude，从而维持推理链 资料来源：[src/google/adk/models/anthropic_llm.py:1-30]()。社区 Issue #3611 关注 Claude 技能（Skills）能力的暴露（[issue #3611](https://github.com/google/adk-python/issues/3611)），该工作正与此适配器不断扩展的方向相关。

LiteLLM 适配允许将任意兼容 OpenAI 协议的后端接入 ADK，示例 `contributing/samples/models/litellm_structured_output/agent.py` 通过 `LiteLlm(model="gemini-2.5-flash")` 复用 Gemini 2.5 Flash，但通过 Pydantic `output_schema=CitySummary` 强制结构化输出，展示了"模型无关"的结构化约束能力 资料来源：[contributing/samples/models/litellm_structured_output/agent.py:1-15]()。

社区 Issue #1096 提议增加 Open WebUI 作为后端，体现了多模型后端的扩展需求 资料来源：[issue #1096](https://github.com/google/adk-python/issues/1096)。

## 三、会话、内存与结构化 I/O

`contributing/samples/core/input_output_schema/README.md` 演示了如何为智能体配置 `input_schema` 与 `output_schema`，当与 `mode='single_turn'` 组合时，该子智能体可作为父智能体的结构化工具被调用，结构化输出会被自动反序列化为 Pydantic 模型 资料来源：[contributing/samples/core/input_output_schema/README.md:1-30]()。

历史限制在 Issue #701 中被讨论：`output_schema` 启用后曾禁用工具调用与控制权转移。`contributing/samples/tools/output_schema_with_tools/README.md` 现在展示了二者组合的方法——ADK 自动注入一个特殊工具 `set_model_response`，模型先使用普通工具收集信息，再以结构化数据提交最终响应 资料来源：[contributing/samples/tools/output_schema_with_tools/README.md:1-15]()。

`contributing/samples/core/artifacts/README.md` 进一步描述了会话范围内的工件（Artifact）版本化与媒体附件（图像/音频/视频），这些数据与会话状态一起参与评估 资料来源：[contributing/samples/core/artifacts/README.md:1-10]()。

## 四、工作流、部署与评估模式

`contributing/samples/workflows/loop/README.md` 给出循环工作流的典型模式：评估节点根据路由决定是否回流到生成节点，实现"条件回边"的有向图，Event 通过 `route` 字段决定下一节点 资料来源：[contributing/samples/workflows/loop/README.md:1-20]()。

```mermaid
graph TD
    START --> process_input
    process_input --> generate_headline
    generate_headline --> evaluate_headline
    evaluate_headline --> route_headline
    route_headline -->|unrelated| generate_headline
    route_headline -->|tech-related| END[Loop ends]
```

部署方面，ADK 通过 `adk web` 在本地启动 Web UI，也支持 MCP 工具集以子进程方式桥接外部服务（[contributing/samples/mcp/tool_mcp_stdio_notion_config/README.md:1-15]()）和 Pub/Sub 一方工具集（[contributing/samples/integrations/pubsub/README.md:1-10]()）。`src/google/adk/cli/built_in_agents/README.md` 描述了内置的 `AgentBuilderAssistant`，提供 `embedded` 与 `query` 两种 schema 模式，分别侧重完整 schema 内联与按需 schema 查询 资料来源：[src/google/adk/cli/built_in_agents/README.md:1-15]()。

评估通常通过 ADK 提供的 `adk_team` 示例参考实现：`adk_answering_agent` 在 GitHub Actions 中以批处理模式（`--recent N` 或 `--discussion '{...}'`）运行，直接消费事件载荷减少 API 调用 资料来源：[contributing/samples/adk_team/adk_answering_agent/README.md:1-15]()；`adk_pr_triaging_agent` 则在 PR 创建/编辑时自动打标签、分配审阅者并校验贡献指南 资料来源：[contributing/samples/adk_team/adk_pr_triaging_agent/README.md:1-15]()。

## 五、常见限制与排错

| 限制/问题 | 现状 | 参考 |
| --- | --- | --- |
| 异步根模型初始化 | 智能体导出同步构造器，但 MCP 工具集只提供 `async` 接口 | [issue #28](https://github.com/google/adk-python/issues/28) |
| `output_schema` 与工具并用 | 已通过 `set_model_response` 处理器支持 | [issue #701](https://github.com/google/adk-python/issues/701) |
| Claude Skills 暴露 | 社区建议扩展，目前需自建提示 | [issue #3611](https://github.com/google/adk-python/issues/3611) |
| 多后端可移植性 | 通过 LiteLLM 抽象层与适配器矩阵扩展 | [issue #1096](https://github.com/google/adk-python/issues/1096) |
| 2.0 会话兼容 | 2.0 会话可被 1.28+ 读取；与更早 1.x 不兼容 | [README.md:5-9]() |

排错时建议从 `adk web` 启动本地调试界面验证会话/事件序列，并复用 `AgentBuilderAssistant` 分析现有工程结构以发现配置偏差 资料来源：[src/google/adk/cli/built_in_agents/README.md:1-10]()。

## See Also

- [README.md](https://github.com/google/adk-python/blob/main/README.md) — 项目总体说明与 2.0 破坏性变更
- [src/google/adk/models/anthropic_llm.py](https://github.com/google/adk-python/blob/main/src/google/adk/models/anthropic_llm.py) — Claude 适配与思考链保留
- [contributing/samples/core/input_output_schema/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/core/input_output_schema/README.md) — 输入/输出 schema
- [contributing/samples/workflows/loop/README.md](https://github.com/google/adk-python/blob/main/contributing/samples/workflows/loop/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) — GitHub 讨论自动回复与评估流水线

---

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

---

## Doramagic 踩坑日志

项目：google/adk-python

摘要：发现 13 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Decision ledger: persist the authority, refusal, and approval behind each tool call。

## 1. 安全/权限坑 · 来源证据：Decision ledger: persist the authority, refusal, and approval behind each tool call

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Decision ledger: persist the authority, refusal, and approval behind each tool call
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/google/adk-python/issues/6099 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：PROGRESSIVE_SSE_STREAMING is not honored by the LiteLlm adapter — function-call argument deltas are buffered until fini…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：PROGRESSIVE_SSE_STREAMING is not honored by the LiteLlm adapter — function-call argument deltas are buffered until finish_reason
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/google/adk-python/issues/5342 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安全/权限坑 · 来源证据：[FR]: Emit canonical gen_ai.* OTEL metrics from ADK's telemetry layer — RFC feedback request

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FR]: Emit canonical gen_ai.* OTEL metrics from ADK's telemetry layer — RFC feedback request
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/google/adk-python/issues/5600 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安全/权限坑 · 来源证据：[LiteLLM] _is_thinking_blocks_format drops Gemini thinking_blocks (only matches Anthropic 'signature' key)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[LiteLLM] _is_thinking_blocks_format drops Gemini thinking_blocks (only matches Anthropic 'signature' key)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/google/adk-python/issues/5712 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `adk-python` 与安装入口 `google-adk` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`pip install google-adk`
- 证据：identity.distribution | https://github.com/google/adk-python | repo=adk-python; install=google-adk

## 6. 安装坑 · 来源证据：OpenAPI tool: generate_return_doc crashes on non-numeric response keys (default, NXX)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OpenAPI tool: generate_return_doc crashes on non-numeric response keys (default, NXX)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/google/adk-python/issues/6174 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：Text accumulation issue for output_key

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Text accumulation issue for output_key
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/google/adk-python/issues/5590 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/google/adk-python | README/documentation is current enough for a first validation pass.

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/google/adk-python | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/google/adk-python | no_demo; severity=medium

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/google/adk-python | no_demo; severity=medium

## 12. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/google/adk-python | issue_or_pr_quality=unknown

## 13. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/google/adk-python | release_recency=unknown

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