# Google 代理开发套件 (ADK) 技能 ## 目的为使用 Google 代理开发套件 (ADK) 开发代理应用程序和多代理系统提供专门指导。使 AI 助手能够设计代理、构建工具、编排多代理工作流程、实施内存/状态管理以及遵循代码优先开发模式部署基于代理的应用程序。 ## 何时使用此技能在以下情况下调用该技能： * 通过工具集成构建对话式人工智能代理 * 创建多代理编排系统 * 开发工作流代理（顺序、并行、迭代） * 为代理实施自定义工具 * 为复杂任务设计代理架构 * 将代理应用程序部署到生产环境 * 评估座席绩效和行为 * 实施人机交互模式请勿将此技能用于： * 通用Python开发（使用Python特定技能） * 简单的REST API开发（ADK用于代理系统） * 前端开发（ADK是后端代理框架） * 直接使用 LLM API，无需代理编排（使用 LLM 提供商 SDK） * 非 Python 代理框架（LangChain、CrewAI、AutoGPT - 不同模式） ## ADK 核心概念 ### 平台架构 **框架理念：** * **代码优先方法** \- 在 Python 代码中定义代理（不是 YAML/JSON 配置） * **与模型无关** \- 针对 Gemini 进行了优化，但支持其他 LLM * **可组合** \- 从简单的代理基元构建复杂的系统 * **Observable** \- 与跟踪和监控工具的内置集成 **支持的语言：** * **Python**（主要的、最成熟的）- `google-adk` 包 * **Go** （可用）- `adk-go` 存储库 * **Java**（可用）- `adk-java` 存储库 **运行环境：** * 需要 Python 3.9+ * 用于部署的代理引擎（容器化执行） * 用于开发/测试的 Web UI（Angular + FastAPI） * 用于评估和部署操作的 CLI ### 代理类型和层次结构 **1\. LlmAgent**（动态、模型驱动） _用途：_ * 对话式界面 * 具有不确定性的决策 * 自然语言理解 * 创意任务（内容生成） * 情境推理 _特点：_ * 使用LLM进行决策 * 非确定性执行 * 由模型驱动的工具选择 * 处理不明确的输入 **2\.工作流程代理**（确定性、编程性） _顺序代理：_ * 按固定顺序执行工具 * 用于：具有依赖性的多步骤流程 * 示例：数据管道（获取→转换→加载） _并行代理：_ * 同时执行多个工具 * 用于：需要聚合的独立操作 * 示例：多源数据收集 _循环代理：_ * 重复执行直到条件满足 * 用于：迭代细化、收敛任务 * 示例：生成器-批评者模式 **3\.自定义代理**（用户定义的逻辑） _用途：_ * 特定领域的编排 * 复杂的状态机 * 与现有系统集成 * 专门的执行模式 **药剂成分：** * 代理可以包含子代理（分层） * 父代理协调子代理 * 支持多级嵌套 ### 工具生态系统 **工具类别：** 1. **内置工具**： * **搜索** \- 通过 Google 搜索 API 进行网络搜索 * **代码执行** \- Python 代码解释器（沙盒） * **Google Cloud 工具** \- Vertex AI、BigQuery、云存储 2. **自定义功能工具** : * Python 函数包装为工具 * 根据类型提示自动生成模式 * 支持异步函数 3. **OpenAPI工具**： * 根据 OpenAPI/Swagger 规范自动生成 * 基于HTTP的服务集成 4. **MCP（模型上下文协议）工具**： * 与MCP服务器集成 * 跨框架工具共享 **工具属性：** * **名称** \- 唯一标识符 * **描述** \- LLM 的自然语言解释 * **参数** \- JSON 模式定义输入 * **函数** \- 执行逻辑 * **确认** \- 可选的人机交互批准 ### 内存和状态管理 **会话管理：** * 代理维护对话历史记录 * 自动上下文窗口管理 * 可配置的历史记录保留 **状态持久性：** * 每个代理的自定义状态对象 * 序列化支持（JSON、pickle） * 数据库集成以实现长期存储 **上下文缓存：** * 减少重复上下文的标记使用 * 自动缓存失效 * 可配置缓存TTL ## 代理开发方法论 ### 规划阶段 **第 1 步：定义代理目的** * 主要目标（单一职责） * 输入/输出格式 * 成功标准 * 失效模式 **第 2 步：确定所需工具** 决策标准： * 使用可用的**内置工具**（搜索、代码执行） * 为简单操作创建**自定义函数**（<100行） * 对现有 REST API 使用 **OpenAPI 工具** * 使用**MCP工具**实现跨框架兼容性 **第3步：选择代理类型** 开始：代理人的决策模式是什么？ │ ├─> 需要自然语言推理？ ─是─> LlmAgent ★ │ ├─> 固定的步骤顺序？ │ └─> 顺序工作流代理★ │ ├─> 独立并行运行？ │ └─> 并行工作流代理★ │ ├─> 需要迭代细化？ │ └─> 循环工作流代理★ │ └─> 自定义编排逻辑？ └─> 定制代理 ★ **第 4 步：设计多代理架构**（如果需要）图案： * **协调员/调度员** \- 中央代理通往专家的路线 * **顺序管道** \- 代理 A 的输出 → 代理 B 的输入 * **并行扇出/收集** \- 分配工作，聚合结果 * **分层分解** \- 将复杂任务分解为子任务 ### 实施阶段 **代理实施示例：** [请参阅代码示例：examples/google_adk_agent_implementation.py] 展示的关键代理模式： * **LlmAgent** \- `create_weather_assistant()` \- 具有自定义工具的对话代理 * **SequentialAgent** \- `create_data_pipeline()` \- 有序执行（获取 → 转换 → 保存） * **ParallelAgent** \- `create_market_researcher()` \- 并发工具执行 * **LoopAgent** \- `create_content_generator()` \- 带中断条件的迭代细化 * **会话管理** \- `create_stateful_session()` \- 具有历史记录的多轮对话 ### 测试阶段 **网页用户界面测试：** # 启动API服务器 adk api_server --端口 8000 # 启动 Web UI（单独的终端） cd adk-网络 npm 安装 npm 启动 # 访问：http://localhost:4200 **程序化测试：** # 代理的单元测试 def test_weather_agent(): 代理 = create_weather_agent() response = agent.run("纽约天气如何？") 在response.content.lower()中断言“天气” 断言response.success为True # 使用模拟工具进行集成测试 def test_pipeline_agent(): 代理 = create_pipeline_agent(mock_tools=True) 结果 = agent.run({"input": "test_data"}) 断言结果[“状态”] ==“已完成” **评估框架：** 从google.adk.evaluation导入evaluate_agent # 基于标准的评估结果=评估代理（代理=我的代理，测试用例=[ {"input": "2+2 是多少？", "expected_output": "4"}, {“input”：“解释量子计算”，“criteria”：“mentions_qubits”} ], evaluator_model =“gemini-2.0-flash” ） print(f"通过率：{results.pass_rate}") print(f"平均分：{results.avg_score}") ## 工具开发 [请参阅代码示例：examples/google_adk_tools_example.py] ### 自定义功能工具实例证明： * **基本功能工具** \- `calculate_tax()` \- 带类型提示的简单工具 * **异步工具** \- `fetch_user_data()` \- 异步 API 调用 * **HITL 确认** \- `send_email()`、`delete_user_account()` \- 需要人工批准 * **输入验证** \- `send_email_tool()` \- 电子邮件格式验证和清理 * **重试逻辑** \- `fetch_external_data()` \- 使用指数退避自动重试 * **速率限制** \- `call_external_api()` \- 基于装饰器的速率限制 * **错误处理** \- `fetch_stock_price()` \- 失败时优雅降级 ### OpenAPI 工具 **整合模式：** * 从 OpenAPI 规范 URL 加载工具 * 针对特定操作的可选工具过滤 * 根据规范自动生成架构 [请参阅：examples/google_adk_tools_example.py 中的`create_api_agent()`] ### MCP 工具集成 **整合模式：** * 连接到MCP服务器端点 * 导入工具以实现跨框架兼容性 [请参阅：examples/google_adk_tools_example.py 中的`create_mcp_agent()`] ## 多代理编排 [请参阅代码示例：examples/google_adk_multi_agent.py] ### 多代理模式 **模式 1：协调员/调度员**（复杂度：4） * **用例：** 将用户请求路由到专门代理 * **函数：** `create_coordinator_system()` \- 天气+金融专家 **模式 2：顺序管道**（复杂度：3） * **用例：** 具有依赖关系的多阶段处理 * **函数：** `create_content_pipeline()` \- 研究→写入→编辑 **模式 3：并行扇出/聚集**（复杂度：4） * **用例：** 聚合多个来源的结果 * **函数：** `create_market_analysis_system()` \- 技术+基本面+情绪分析 **模式4：层次分解**（复杂度：5） * **用例：** 将复杂的任务分解为可管理的子任务 * **函数：** `create_project_management_system()` \- 多级代理层次结构 **模式 5：生成器-临界循环**（复杂度：4） * **用例：** 带反馈的迭代细化 * **函数：** `create_quality_content_system()` \- 生成 → 批评 → 精炼 **模式 6：人在环 (HITL)**（复杂度：3） * **用例：** 关键决策需要人工批准 * **函数:** `create_account_management_agent()` \- 删除前确认 **模式7：状态管理** * **用例：** 跨会话的持久用户上下文 * **Class:** `StatefulAgent` \- 具有历史记录的内存状态存储 **模式8：数据库持久化** * **用例：** 长期状态存储 * **函数：** `save_state()`、`load_state()` \- PostgreSQL 支持的持久性 ## 内存和状态管理 [请参阅代码示例：examples/google_adk_multi_agent.py - 状态管理部分] ### 会话管理 **基本会话模式：** * 多轮对话并保留历史记录 * 自动上下文窗口管理 * 可配置的历史限制 [请参阅：examples/google_adk_agent_implementation.py 中的“create_stateful_session()”] ### 状态持久化 **自定义状态对象：** * 每个用户的内存状态存储 * 基于数据类的状态建模 * 对话历史记录跟踪 [请参阅：examples/google_adk_multi_agent.py 中的 `StatefulAgent` 类] **数据库持久性：** * 使用 SQLAlchemy 进行长期状态存储 * JSON序列化状态数据 * PostgreSQL/MySQL 支持 [参见：examples/google_adk_multi_agent.py 中的 `save_state()`、`load_state()` 函数] ## 部署选项 [请参阅代码示例：examples/google_adk_deployment.py] ### 代理引擎（托管服务） **部署命令：** pip 安装 google-adk[cli] adk授权登录 adk 部署 --agent-file agent.py --agent-name my_agent --project-id my-gcp-project --region us-central1 [请参阅：`create_development_agent()` 以获取配置示例] ### 云运行部署 **组件：** *带有代理端点的FastAPI服务器 * 用于容器化的 Dockerfile * 健康检查和错误处理 * 环境配置 [请参阅：FastAPI 应用程序实现、Dockerfile 参考、examples/google_adk_deployment.py 中的部署命令] ### Docker 容器化 **自托管选项：** * Docker 与 Redis 组合 * 单容器部署 * 环境变量配置 [请参阅：docker-compose.yml 参考，examples/google_adk_deployment.py 中的部署命令] ### 资源要求代理复杂性 |中央处理器|内存 |并发请求 ---|---|---|--- 简单的 LlmAgent | 1 核 | 512MB | 10 工作流代理| 2 核 | 1GB | 20 多代理（3-5 个代理）| 4 核 | 2GB | 10 复杂多代理 (>5) | 8 核 | 4GB | 5 ## 评估与测试 [请参阅代码示例：examples/google_adk_deployment.py - 评估端点] ### 基于标准的评估 **图案：** * 定义自定义评估标准（准确性、有用性等） * 针对代理运行测试用例 * 分析通过率和分数 [请参阅：examples/google_adk_deployment.py 中的“evaluate_agent_endpoint()”] ### 用户模拟评估 **图案：** * 模拟用户与既定目标的交互 * 跟踪目标完成率 * 测量平均完成周转数 [有关 UserSimulator 示例，请参阅文档] ## 最佳实践 [请参阅代码示例：examples/google_adk_tools_example.py - 工具设计最佳实践部分] ### 代理指令编写 **有效模式：** * 明确的角色和职责 * 具有约束的结构化格式 * 具体工具使用指导 * 交互示例 [参见：examples/google_adk_tools_example.py 末尾的好与坏示例] ### 工具设计原则 **关键原则：** 1. **单一职责** \- 每个工具都有一个明确的目的 2. **描述性命名** \- 清晰的动作和对象命名 3. **类型提示** \- 所有参数的完整类型注释 [请参阅：examples/google_adk_tools_example.py 末尾的工具设计示例] ### 错误处理 **策略：** * **优雅降级** \- 返回错误消息而不是引发异常 * **重试逻辑** \- 带指数退避的自动重试 * **输入验证** \- 验证并清理所有输入 [请参阅示例/google_adk_tools_example.py 中的“fetch_stock_price()”、“fetch_external_data()”、“send_email_tool()”] ### 安保与安全 **实施：** * **输入验证** \- 电子邮件格式验证、长度限制 * **Rate Limiting** \- 基于装饰器的请求限制 * **清理** \- 删除危险的 HTML/脚本内容 [参见：examples/google_adk_tools_example.py 中的 `send_email_tool()`、`rate_limit()` 装饰器] ### 性能优化 **异步工具：** * 异步函数自动并行执行 * 提高了 I/O 密集型操作的吞吐量 [请参阅：examples/google_adk_tools_example.py 中的 `fetch_price()`、`create_portfolio_analyzer()`] ## 质量门 ### 完成的定义：代理在以下情况下，代理已做好生产准备： 1. **功能：** * ✓ 代理完成测试用例的主要目标 * ✓ 通过有效输入工具执行成功 * ✓ 错误处理涵盖预期的故障模式 * ✓ 多轮对话保持上下文 2. **性能：** * ✓ 简单查询响应时间<5秒 * ✓ 复杂工作流程的响应时间 <30 秒 * ✓ 评估通过率≥80% * ✓ 部署限制内的资源使用 3. **安全：** * ✓ 所有工具的输入验证 * ✓ 高风险行为需要确认（HITL） * ✓ 无硬编码凭证或 API 密钥 * ✓ 外部API调用速率限制 4. **可观察性：** * ✓ 配置用于调试的日志记录 * ✓ 为多代理工作流程启用跟踪 * ✓ 跟踪评估指标 * ✓ 配置错误警报 5. **文件：** * ✓ 记录代理的目的和能力 * ✓ 工具描述清晰准确 * ✓ 提供示例用法 * ✓ 记录已知限制 ### 完成的定义：工具在以下情况下，工具即可投入生产： 1. **接口：** * ✓ 函数具有所有参数的类型提示 * ✓ 文档字符串解释目的、参数、返回 * ✓ 参数说明指导LLM选型 * ✓ 返回值可 JSON 序列化 2. **可靠性：** * ✓ 带有信息性消息的错误处理 * ✓ 输入验证防止无效操作 * ✓ 为长时间运行的操作配置超时 * ✓ 短暂故障的重试逻辑 3. **测试：** * ✓ 单元测试涵盖成功案例 * ✓ 单元测试涵盖错误情况 * ✓ 与代理执行的集成测试 * ✓ 昂贵操作的性能基准 ## 错误处理指南 ### 常见问题和解决方案 **问题：代理未调用正确的工具** * **原因：** 工具描述不清楚或不明确 * **分辨率：** # 不好：描述模糊 def 过程（数据）： """处理数据。""" # 太通用 # 好：具体描述 def validate_email_format(email: str) -> bool: """检查电子邮件地址是否符合有效格式 (user@domain.com)。仅使用此工具来验证电子邮件语法，而不是验证电子邮件是否存在或可送达。""" **问题：代理无限循环** * **原因：** Loop Agent 中没有终止条件 * **分辨率：** # 添加 max_iterations 和显式中断条件代理 = 循环代理( 工具=[...], max_iterations=10, # 硬限制 break_condition=lambda 结果： result.get("已完成", False) ） **问题：“工具执行失败”错误** * **原因：** 工具引发未处理的异常 * **分辨率：** defRobust_tool（参数：str）->str：尝试：结果=有风险的操作（参数） return f"成功：{结果}" 除了 SpecificError 为 e： return f“操作失败：{e.message}” 除了异常 e： logger.error(f"robust_tool 中出现意外错误：{e}") 返回“服务临时错误，请重试” **问题：代理响应太慢** * **原因：** 可以并行化时顺序调用工具 * **分辨率：** # 使用并行代理或异步工具代理 = 并行代理( tools=[tool1, tool2, tool3] # 并发执行） **问题：超出上下文限制** * **原因：** 对话历史记录太长 * **分辨率：** 会话=会话（代理=我的代理， max_history_turns=10, # 限制历史记录 context_window_tokens=30000 # 设置显式限制） **问题：在 Cloud Run 上部署失败** * **原因：** 缺少依赖项或环境变量 * **分辨率：** # 确保requirements.txt完整 pip freeze > 要求.txt # 设置所需的环境变量 gcloud 运行部署 my-agent \ --set-env-vars GOOGLE_API_KEY=your_key,AGENT_CONFIG=prod ### 调试策略 **1\.启用详细日志记录：** 导入日志记录日志记录.basicConfig（级别=日志记录.DEBUG） logger =logging.getLogger(“google.adk”) logger.setLevel(日志记录.DEBUG) **2\.独立测试工具：** # 无需代理的测试工具工具 = Tool.from_function(my_function) 结果 = my_function("test_input") print(f"工具输出：{结果}") **3\.使用 Web UI 进行交互式调试：** adk api_server --调试 # 访问用户界面 http://localhost:4200 # 查看工具调用、代理推理、响应生成 **4\.检查代理执行跟踪：** 响应 = agent.run("测试查询", return_trace=True) print(response.trace) # 显示所有工具调用和决策 ## 复杂度评级任务|评级 |描述 ---|---|--- 简单的 LlmAgent 工具 | 2 |基本对话代理顺序工作流代理 | 2 |固定顺序工具执行并行工作流代理 | 3 |并发操作循环工作流代理| 3 |迭代细化定制代理| 3 |用户自定义编排协调员/调度员（2-3 名代理）| 4 |多代理路由顺序管道（3+ 代理）| 4 |链式代理执行分层多代理（>5 个代理）| 5 |复杂的嵌套架构定制工具开发| 2 | Python 函数包装器 OpenAPI工具集成| 2 |根据规格自动生成 MCP 工具集成 | 3 |跨框架工具部署到代理引擎 | 2 |托管部署自托管 Docker 部署 | 3 |容器编排先进的评估框架| 4 |定制标准和模拟 ## 参考文献 ### 官方文档 * **主要文档：** * **Python SDK：** * **示例：** * **网络用户界面：** ### Python SDK 资源 * **安装：** `pip install google-adk` * **API 参考：** * **快速入门指南：** ### 其他语言 * **Go SDK：** * **Java SDK：** ### 社区资源 * **GitHub 讨论：** * **问题跟踪器：** ### 相关技能 * 对于工作流程自动化：使用`n8n`技能 * 对于 API 设计：使用 `api-design-architect` 技能 * 对于云部署：使用 `cloud-devops-expert` 技能 * 对于Python开发：使用Python特定的技能 * 对于 LLM 集成：使用模型提供商 SDK（OpenAI、Anthropic 等） ** ** **版本：** 1.0.0 **最后更新时间：** 2025-11-13 **复杂度评级：** 3（中等 - 需要代理架构知识） **预计学习时间：** 10-15 小时即可熟练掌握

谷歌广告

包含技能