问题：在构建AI智能体时淹没在文档中
你决定使用Google的智能体开发工具包（ADK）构建一个AI智能体。你清楚地知道智能体需要做什么——也许它需要从API获取数据、处理用户请求，或者协调多个子智能体。你打开文档，突然发现自己盯着数百页的内容，涵盖智能体类型、工具定义、编排模式、回调、状态管理等等。
挫败感很快产生。你花了几个小时阅读关于SequentialAgent的内容，而你只需要一个带有工具的简单Agent。你搜索如何定义回调函数，结果发现自己迷失在抽象基类和插件架构的海洋中。文档很全面，但并没有针对当前任务进行优化：现在就写出可工作的代码。
这是使用复杂AI框架的开发者常见体验。从“我知道我想构建什么”到“我知道如何编写代码”之间的差距成为生产力杀手。你最终打开多个浏览器标签页，不断在IDE和文档之间切换，试图拼凑出正确的导入、类名和方法签名。
为什么会发生这种情况
现代AI智能体框架功能强大但复杂。它们支持多种用例——从简单的单智能体系统到具有状态管理和人在回路模式的复杂多智能体工作流。这种灵活性意味着文档必须涵盖许多场景，使得找到你需要的特定模式变得困难。
此外，AI智能体开发仍在发展中。API会变化，新功能被添加，最佳实践也在改变。六个月前有效的方法可能不再是今天推荐的做法。开发者需要一种方式来快速访问当前的、实用的示例，而无需深入理论解释。
好的解决方案应该改变什么
一个有效的解决方案应该提供：
- 快速访问常见模式，无需深入文档挖掘
- 实际可工作的代码示例，复制和调整后即可使用
- 清晰的边界，显示何时使用哪种模式
- 与现有工作流的集成，而不是强迫你学习另一个工具
- 反映最新API变化的当前信息
介绍ADK代码参考技能
google-agents-cli-adk-code技能正是为了解决这个问题而设计的。它是Google智能体开发工具包技能套件的一部分，专门专注于为使用Python编写智能体代码提供快速参考模式。
这个技能不是全面文档的替代品。相反，它充当最常见ADK模式的精选速查表。当你需要定义智能体、添加工具、实现回调或管理状态时，这个技能为你提供基本的代码模式，而无需周围的理论背景。
这个技能提供什么
该技能包括以下参考材料：
- 核心智能体定义，使用
Agent类 - 工具集成模式，用于添加自定义函数
- 回调实现，用于处理智能体生命周期事件
- 状态管理方法，用于在交互间维护上下文
- 多智能体编排，使用
SequentialAgent、ParallelAgent和LoopAgent - 基于图的工作流，用于复杂的智能体拓扑
参考材料按用例组织，因此你可以快速找到匹配当前任务的模式。例如，如果你正在构建一个带有一个工具的简单智能体，你会在核心参考中找到一个完整、可工作的示例。如果你需要协调多个智能体，工作流参考会向你展示如何设置基于图的编排。
这个技能何时适合你的工作流
这个技能在以下情况下最有用：
- 你正在积极编写ADK智能体代码，需要快速参考模式
- 你知道想构建什么，但不确定确切的API语法
- 你正在开发基于Python的智能体（其他语言支持即将推出）
- 你想避免在IDE和文档之间切换上下文
- 你需要反映最新ADK版本的当前模式
何时寻找其他方案
如果以下情况，这个技能可能不是最佳选择：
- 你从头开始一个新项目 — 考虑使用
/google-agents-cli-scaffold技能 - 你需要部署现有智能体 —
/google-agents-cli-deploy技能涵盖部署工作流 - 你正在评估智能体性能 —
/google-agents-cli-eval技能专注于评估方法 - 你使用Python以外的语言 — 这个技能目前只涵盖Python ADK模式
实际用法：如何开始
在使用这个技能之前，有一个重要的前提条件：你需要安装agents-cli工具并搭建好项目。技能文档建议首先激活/google-agents-cli-workflow技能，其中包含所需的开发阶段和搭建步骤。
以下是实际工作流程：
- 检查是否有项目：在终端中运行
agents-cli info。如果显示项目配置，你可以直接使用代码参考。 - 如果需要，创建新项目：如果不存在项目，运行
agents-cli scaffold create <name>来设置基本结构。 - 增强现有代码：如果你有现有代码，运行
agents-cli scaffold enhance .将其与ADK结构集成。
项目设置好后，你可以使用技能的参考来编写智能体代码。该技能提供两个主要参考文件：
references/adk-python.md— 大多数智能体的核心ADK API模式references/adk-workflows.md— 用于复杂拓扑的基于图的工作流API
示例：构建带工具的简单智能体
假设你想构建一个可以获取天气信息的智能体。使用技能的核心参考，你会找到类似这样的模式：
from google.adk.agents import Agent
def get_weather(city: str) -> dict:
"""获取城市的当前天气。"""
# 在实际实现中，这会调用天气API
return {"city": city, "temp": "22°C", "condition": "sunny"}
root_agent = Agent(
name="my_agent",
model="gemini-flash-latest",
instruction="你是一个可以查询天气信息的有用助手。",
tools=[get_weather],
)
这个示例展示了一个带有一个工具的智能体的最小设置。技能的参考会解释每个参数，并展示不同用例的变体。
评估这个技能是否满足你的需求
在决定使用这个技能之前，请考虑以下因素：
能力边界
- 语言限制：目前仅支持Python。如果你使用其他语言，需要等待未来更新或直接使用官方文档。
- 范围限制：专注于代码模式，而不是项目设置或部署。你需要互补技能来完成这些任务。
- 深度与广度：提供快速参考模式，而不是详尽的API文档。对于边缘情况或高级功能，你可能仍然需要查阅完整文档。
最佳用例
- 快速原型开发：当你需要快速让基本智能体工作时
- 模式识别：当你不确定该使用哪个ADK类或方法时
- 代码一致性：当你想在团队中遵循推荐模式时
- 学习ADK：当你刚接触框架并想查看可工作的示例时
何时不使用它
- 生产环境调试：对于生产智能体中的复杂问题，你需要更深入的调查
- 性能优化：该技能专注于正确性，而不是性能调优
- 自定义扩展：如果你需要扩展ADK超出其标准模式
设置上下文和安全考虑
安装要求
该技能需要agents-cli工具，可以通过以下方式安装：
uv tool install google-agents-cli
这会安装命令行界面，提供对技能参考和其他ADK开发工具的访问。
安全信号
- 仓库所有权：该技能由Google维护，与开发ADK的是同一组织
- 许可证：Apache-2.0，对商业友好且许可宽松
- 安全级别：在技能元数据中标记为“低”风险
- 活跃开发：该仓库有超过3000个星标，表明社区关注度
仓库信号
- GitHub仓库：google/agents-cli
- 主题标签：包括相关标签如
google-cloud、gemini、agents、adk - 版本：0.5.1，表明它仍在发展中但功能正常
- 依赖项：只需要
agents-cli二进制文件
与你的开发工作流集成
这个技能作为更大工作流的一部分效果最佳。技能文档提到了几个相关技能：
/google-agents-cli-workflow— 用于开发工作流和编码指南/google-agents-cli-scaffold— 用于项目创建和增强/google-agents-cli-eval— 用于评估方法和测试/google-agents-cli-deploy— 用于部署和生产工作流
典型的工作流可能如下：
- 使用
/google-agents-cli-workflow了解开发过程 - 使用
/google-agents-cli-scaffold设置项目 - 使用
/google-agents-cli-adk-code（此技能）编写智能体代码 - 使用
/google-agents-cli-eval测试和评估智能体 - 使用
/google-agents-cli-deploy部署到生产环境
最终考虑
google-agents-cli-adk-code技能解决了AI智能体开发中的一个真实痛点：知道想构建什么与知道如何编写代码之间的差距。它不是消除理解ADK需求的魔法解决方案，但为常见模式提供了实用的捷径。
如果你正在使用Google的ADK，并发现自己不断搜索代码示例，这个技能可以为你节省大量时间。然而，了解它的局限性很重要：它仅支持Python，专注于代码模式而不是全面文档，并且作为包含互补技能的更大工作流的一部分效果最佳。
在使用之前，确保你已安装agents-cli工具并搭建好项目。然后，在编写智能体代码时使用技能的参考作为快速指南，仅在遇到边缘情况或需要更深入理解时才查阅完整文档。