Doramagic.ai
English

Doramagic 项目包 · 项目说明书

adk-python 项目

一个开源、代码优先的 Python 工具包，用于灵活且可控地构建、评估和部署复杂的 AI agent。

ADK 概述与核心代理类型

Google Agent Development Kit（ADK）是一个用于构建代理式应用（agentic apps）的 Python 框架。仓库文档说明 "ADK applications are built using two main classes"（资料来源：README.md），其要求 Python 3.10+，可通过 pip install google-ad...

章节 相关页面

继续阅读本节完整说明和来源证据。

ADK 框架定位与 2.0 架构演进

Google Agent Development Kit（ADK）是一个用于构建代理式应用（agentic apps）的 Python 框架。仓库文档说明 "ADK applications are built using two main classes"（资料来源：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）。贡献者侧的整体架构与设计哲学总览可见仓库内的 contributing/README.md。

核心代理类型与角色

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

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

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

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

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

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

Workflow 运行时与 Task API

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与定位

Workflow 运行时（Workflow Runtime）与 Task API 是 Google ADK（Agent Development Kit）2.0 引入的两大核心能力，用以将"代理（agent）"与"确定性流程"解耦并协同工作。资料来源：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 展示了条件路由的写法：

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

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

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

关键能力

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

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

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

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

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

YAML 配置化：除 Python 外，节点与边可通过 YAML 描述。资料来源：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）：

  • 多轮任务模式（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 演示了"父代理 → 调用带 input_schema / output_schema 的子代理 → 接收结构化结果"这一典型 Task API 链路。当 output_schema 与 tools 同时出现时，ADK 会自动注入一个特殊 set_model_response 工具，使模型能够用工具收集信息、再以结构化形式交付最终响应——该限制在 issue #701 中被社区长期关注，并已在新版本中解除。资料来源：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 展示了 request_input 工具在 LLM Agent 中的使用方式，是 Task API "人机协作"模式在 LLM 节点上的对应实现。

See Also

资料来源：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。

工具、MCP 与集成生态

google-adk（Agent Development Kit）是一套面向生产级智能体应用的 Python 框架，工具（Tool）、工具集（Toolset）、MCP（Model Context Protocol）以及与外部系统的集成共同构成了 ADK 的扩展能力。工具是智能体与外部世界交互的最小单元；MCP 则提供了一种标准化的进程间协议，让本地或远程 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 工具集。典型的集成示例包括：

在模型层，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 的转译路径完整

参见

来源：https://github.com/google/adk-python / 项目说明书

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

ADK（Agent Development Kit）Python 版本是一套用于构建、运行与部署 AI 智能体（Agent）的开源框架。README.md 明确指出，ADK 2.0 引入了 Workflow Runtime（基于图结构的执行引擎，支持路由、扇出/扇入、循环、重试、状态管理、动态节点、人机协同和嵌套工作流），以及 Task API（结构化的智能体间委派协议），...

章节 相关页面

继续阅读本节完整说明和来源证据。

一、概览

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），该工作正与此适配器不断扩展的方向相关。

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。

三、会话、内存与结构化 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。

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
output_schema 与工具并用已通过 set_model_response 处理器支持issue #701
Claude Skills 暴露社区建议扩展，目前需自建提示issue #3611
多后端可移植性通过 LiteLLM 抽象层与适配器矩阵扩展issue #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

来源：https://github.com/google/adk-python / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Decision ledger: persist the authority, refusal, and approval behind each tool call

可能阻塞安装或首次运行。

high 来源证据：PROGRESSIVE_SSE_STREAMING is not honored by the LiteLlm adapter — function-call argument deltas are buffered until fini…

可能影响授权、密钥配置或安全边界。

high 来源证据：[FR]: Emit canonical gen_ai.* OTEL metrics from ADK's telemetry layer — RFC feedback request

可能影响升级、迁移或版本选择。

high 来源证据：[LiteLLM] _is_thinking_blocks_format drops Gemini thinking_blocks (only matches Anthropic 'signature' key)

可能影响授权、密钥配置或安全边界。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录