agents-cli 参考配方Reference Recipes全解用 ADK 样例驱动 Agent 开发【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli导读本文围绕 agents-cli 技能体系中的核心参考文档——google-agents-cli-adk-code技能下的references/samples.md仓库路径skills/google-agents-cli-adk-code/references/samples.md展开系统讲解参考配方Reference Recipes这一开发方法它是什么、如何获取与研读、如何按需求 → 配方的映射找到现成的 ADK 实现、以及九个core/核心配方的定位与关键文件。读完本文你将掌握一套先克隆配方、再读AGENTS.md、最后动手实现的可复用工作流避免从零手写沙箱、技能加载器、记忆存储等复杂能力。一、参考配方是什么不只是样例而是被精选的实现在 agents-cli 的技能体系中SKILL.md 将 ADK 开发分为「研究配方Study Recipes→ 脚手架Scaffold→ 编写代码」三个阶段。samples.md承担的就是第一阶段的核心职责它是一个按能力需求索引的配方目录topic-indexed catalog把你在构建 Agent 时可能遇到的每一种复杂能力映射到一段经过 agents-cli 团队精选和维护的现成实现上。这些配方存放在独立的开源仓库google/adk-samples中其中core/python/是精选层curated tier——由 agents-cli 团队维护、代表规范的 ADK 模式而contrib/则是社区与合作伙伴贡献的扩展层范围更广但不保证带有AGENTS.md导学文件。文档开篇用一句近乎严格的话定义了使用纪律Reading this page is not studying a recipe.阅读本页并不等于研究了配方。每个core/配方都随附一份AGENTS.md其中包含配方的设计意图intent、按优先级排序的按此顺序研读文件导览ranked study in this order file tour、哪些内容可原样复制、哪些是配方特有的what to copy as-is versus what is recipe-specific以及常见坑gotchas。在打开配方的AGENTS.md之前任何回答都只是凭记忆作答。这从机制上保证了索引只给你一个名字真正的实现细节必须从代码本身获取。同时文档明确划出一条边界研究并适配Study and adapt——不要从配方脚手架化dont scaffold from a recipe。参考配方的目的是理解模式、抽取模式而不是把整个配方目录当作项目骨架来复制。二、获取配方sparse-checkout 克隆工作流文档给出了标准的配方获取命令通过git sparse-checkout只拉取你需要的配方子目录避免完整克隆整个样本仓库[ -d /tmp/adk-samples ] || git clone --filterblob:none --depth 1 --sparse \ https://github.com/google/adk-samples /tmp/adk-samples cd /tmp/adk-samples git sparse-checkout add core/python/recipe cat core/python/recipe/AGENTS.md逐条拆解这段命令的意图参数作用--filterblob:none懒加载文件内容blob只在需要时才从远端获取大幅减少克隆体积--depth 1浅克隆只取最新一次提交适合研究当前状态而非查看历史--sparse启用稀疏检出初始仅检出根目录文件git sparse-checkout add core/python/recipe只将目标配方目录纳入工作树cat core/python/recipe/AGENTS.md配方获取后的第一动作阅读其导学文件这是一个幂等命令目录已存在则跳过克隆直接进入后续步骤适合反复执行。为什么不用adk脚手架快捷方式文档特别提醒agents-cli scaffold create的--agent adkname快捷方式只能触达python/agents/这一旧版legacy目录树无法触达core/。这一点在仓库源码中得到直接印证在 src/google/agents/cli/scaffold/utils/remote_template.py 中adk前缀被解析为if agent_spec.startswith(adk): sample_name agent_spec[4:] # Remove adk prefix return RemoteTemplateSpec( repo_urlhttps://github.com/google/adk-samples, template_pathfpython/agents/{sample_name}, # 旧版树而非 core/ git_refmain, is_adk_samplesTrue, )可见脚手架路径被硬编码指向python/agents/{sample_name}。因此想要研究core/精选配方必须走上文的手工 sparse-checkout 流程而不是脚手架命令。脚手架命令的完整参数参考见 skills/google-agents-cli-scaffold/references/flags.md。何时克隆与开发工作流Workflow的配合samples.md还规定了克隆时机的两条规则Phase 1工作流阶段在写任何代码之前先克隆上述配方并阅读其AGENTS.mdPhase 0规格阶段在规格spec中写出配方名字即可实际克隆等待批准裸的 how 问题没有规格可等待在回答之前就先克隆。这种克隆等待审批的设计避免在规格尚未确定时过早拉取大量无关代码。三、需求 → 配方映射表先查表再动手文档提供了一张核心映射表将你需要的能力与应研究的配方一一对应。这张表是samples.md的灵魂完整继承如下。请注意这些能力都不是脚手架标志scaffold flags而是通过研读配方、自行适配获得的。你需要应研究对你自己的文档做检索/搜索RAGrag-agent-search托管式摄入·rag-vector-search自定义分块 向量化代表用户运行 Shell 命令或 Python沙箱化、隔离的或按用户隔离的环境/工作区long-horizon-harness可被 Agent 加载的技能——运行时发现的SKILL.md文件夹、会话中途重新绑定、从记忆中提升/降级long-horizon-harness长期自主运行——跨天工作、断点续跑、无人值守、上下文压缩long-horizon-harness在高风险、高价值或不可逆操作前的审批门禁/升级/人工签字human-in-the-looplong-harness持久、回合中途·ambient-expense-agent工作流暂停·deep-search计划审批跨会话记忆cross-session-memory原语·long-horizon-harness在其上构建的自改进循环拦截有害内容或高风险调用——在单一位置做内容审核覆盖协调者与每个子 Agent 而无需改动它们safety-pluginsrunner 级插件·long-horizon-harness按工具守卫链 数据外泄检测模型永远不可见的按用户凭据long-horizon-harness代表用户操作其数据的 OAuth 用户授权oauth-user-consent-flow带隔离上下文窗口的子 Agent 委派long-horizon-harness无聊天界面——记录/消息落队列后自动处理事件驱动、定时、批处理或无人值守 workerambient-expense-agentPub/Sub 队列消费者·long-horizon-harness例程 调度器带引用来源的迭代式研究deep-search生成图片或视频——商品摄影、模特穿戴虚拟试穿、360° 旋转、背景替换——以及 MCP 工具集genmedia-for-commerceA2A 互操作包括 Gemini Enterprise 客户端怪癖long-horizon-harness注原表中long-horizon-harness持久、回合中途一处原文档写作long-horizon-harness按上下文应为同一配方原表对它的功能描述为 durable, mid-turn持久、回合中暂停等待审批与配方定位一致。使用这张表的正确姿势是先用它确定配方名字然后回到第二节的克隆流程去读配方的AGENTS.md与代码而不是停留在名字层面。四、九个核心配方全景文档明确以下九个是core/Python 配方的完整集合complete set。如果某个能力不在表中就意味着没有对应的 core 配方——不要臆造一个看似合理的名字例如core/python/code-execution和core/python/human-in-the-loop并不存在。此时应去contrib/查找或自行实现。1.long-horizon-harness— 完整的 Agent操控台一个完整 agent harness按用户沙箱、运行时发现的SKILL.md技能、带自改进循环的跨会话记忆、分层工具护栏、带持久 HITL 的子 Agent 委派、按用户密钥。其AGENTS.md把每个接口映射到实现它的真实函数因此你可以只抽取其中一个模式而不必采纳整个 harness。关键文件AGENTS.md、horizon/agent.py、horizon/fast_api_app.py、docs/architecture.md、docs/quickstart.md关键词harness、sandbox、shell execution、code execution、isolated environment、long-horizon、long-running、multi-day、autonomous、resumable、compaction、guardrails、exfil、egress、approval gate、human-in-the-loop、HITL、per-user secrets、credentials、sub-agents、delegation、self-improving、memory bank、routines、scheduler、a2a、skills、model routing2.rag-agent-search— 托管式文档搜索通过 Agent Platform SearchDiscovery Engine实现托管式文档搜索配完全托管的 GCS Data Connector把文件丢进 bucket 即可无需维护摄入代码。关键文件AGENTS.md、app/agent.py、infra/terraform/agent_platform_search.tf、infra/terraform/scripts/setup_data_connector.py关键词RAG、document search、Discovery Engine、Agent Platform Search、managed ingestion、GCS data connector、PDF、HTML、grounding3.rag-vector-search— 向量检索 RAG基于 Vertex AI Vector Search 2.0 的 RAG配 KFP 摄入流水线分块 BigQuery 暂存嵌入向量由服务端自动生成。关键文件AGENTS.md、app/agent.py、data_ingestion/data_ingestion_pipeline/pipeline.py、infra/terraform/scripts/setup_vector_search_collection.py关键词RAG、retrieval、vector search、embeddings、similarity search、ScaNN、semantic search、document QA、ingestion pipeline、chunking4.cross-session-memory— 跨会话记忆原语通过 Vertex AI Memory Bank 记住用户的偏好与事实每回合结束后写入在后续回合开始时召回。关键文件AGENTS.md、app/app_utils/memory_config.py、app/agent.py、app/fast_api_app.py关键词memory、cross-session、recall、remember、preferences、Memory Bank、PreloadMemoryTool5.oauth-user-consent-flow— OAuth 用户授权流在 OAuth 2.0 同意流consent flow之后代表用户读取其 Google Drive同一套代码路径在本地 ADK Web 与生产环境 Gemini Enterprise 中都能工作。关键文件AGENTS.md、app/auths.py、app/tools.py、tools/register_oauth.py关键词OAuth、user consent、authentication、Google Drive、Workspace、Agent Runtime、Gemini Enterprise6.ambient-expense-agent— 无聊天循环的事件驱动 Agent没有聊天循环Pub/Sub 事件驱动一个基于图graph的Workflow业务规则留在代码中只有高价值 case 才进入 LLM并在那里暂停等待人工审批。关键文件AGENTS.md、expense_agent/agent.py、expense_agent/fast_api_app.py、terraform/pubsub.tf关键词ambient、event-driven、scheduled、cron、Pub/Sub、workflow、human-in-the-loop、approval、alerts、no UI这与 adk-python.md 中「事件驱动/环境 Agent」一节的描述呼应ADK 提供内建触发器端点trigger_sources[pubsub, eventarc]Pub/Sub 与 Eventarc 有 10 分钟处理时限而定时执行可借助 Cloud Scheduler 发布到 Pub/Sub 主题来实现每天 20:00 运行。在实现这类无界面 Agent 之前文档明确要求先克隆并研究该生产样例。7.deep-search— 带引用的迭代式研究研究型 Agent先做计划含审批步骤然后循环搜索 → 批判 → 精炼直到达到质量门槛最后写出带内联引用inline citations的报告。关键文件AGENTS.md、app/agent.py、app/config.py、frontend/src/App.tsx关键词research、citations、iterative、critique、grounding、multi-agent、human-in-the-loop、web search、report8.safety-plugins— runner 级安全护栏将安全护栏做成 ADKBasePlugin挂载在Runner上后会包裹其下每一个 Agent 与子 Agent阻止有害内容进入会话状态。关键文件AGENTS.md、safety_plugins/plugins/model_armor.py、safety_plugins/plugins/agent_as_a_judge.py、safety_plugins/main.py关键词safety、guardrails、harmful content、moderation、content filtering、Model Armor、LLM-as-a-judge、session poisoning、plugins、runner-wide、applies to all sub-agents这与 ADK 的插件机制一致插件是跨所有 Agent/工具/LLM 的全局回调钩子适合日志、护栏等横切关注点App(plugins[...])注册的插件会先于 Agent 级回调执行见 adk-python.md 第 10 节。9.genmedia-for-commerce— 全栈零售媒体多 Agent全栈多 Agent 零售媒体方案虚拟试穿virtual try-on、360° 商品旋转、背景替换通过MCP 工具服务器与 Veo 流水线编排。关键文件AGENTS.md、genmedia4commerce/mcp_server/server.py、genmedia4commerce/workflows/shared/vector_search.py、genmedia4commerce/agent.py关键词MCP、media、image generation、video generation、product photography、on-model imagery、virtual try-on、360° spin、background replacement、Veo、retail、e-commerce、catalogue、full-stack、React、Gemini Enterprise配方之外的兜底contrib/如果上面九项都无法命中你的需求contrib/目录存放社区与合作伙伴贡献的配方——范围更广完整解决方案而非孤立模式但未经 agents-cli 团队精选因此不保证有AGENTS.md指导。当core/覆盖不了某个特定需求时去那里找或自行构建。五、从配方到代码与 ADK 参考速查的配合配方是完整实现而 adk-python.md 是语法速查。两者的配合方式在 SKILL.md 的参考索引中有明确说明参考何时阅读references/samples.md本文对应文档主题索引式配方目录。在 Workflow Phase 1、脚手架与写代码之前阅读把能力映射到实现它的配方references/adk-python.md核心 ADK API 速查Agent、工具、回调、插件、状态、artifacts、多 Agent 系统、SequentialAgent/ParallelAgent/LoopAgent、自定义BaseAgent、ManagedAgent、A2A、A2UIreferences/adk-workflows.md基于图的 Workflow APIADK 2.0节点、边、扇出/扇入、HITL、并行处理例如你从samples.md得知跨会话记忆应研究cross-session-memory配方那么在研读配方的memory_config.py时可以用adk-python.md中的PreloadMemoryTool与generate_memories_callback模式来对照理解 Memory Bank 的写入与召回时机。又比如 子 Agent 委派对应long-horizon-harness其底层委托机制共享状态、LLM 委派、AgentTool、ADK 2.0 Task 委派都可以在速查中查到语法细节。对于深度知识速查与配方都指向两个权威来源curl https://adk.dev/llms.txt拉取文档索引后按需WebFetch具体页面或直接 inspect 已安装的 ADK 包python -c import google.adk; print(google.adk.__path__[0])获取精确的函数签名与实现。六、实践要点与纪律总结先查表后克隆再读AGENTS.md。顺序不可颠倒映射表给名字克隆给代码AGENTS.md给研读顺序、复制边界与坑。配方是研读对象不是脚手架输入。脚手架--agent adkname只能到达旧版python/agents/树见 remote_template.py 的硬编码路径core/精选配方必须走 sparse-checkout。列表之外的能力 没有 core 配方。不要猜测不存在的名字去contrib/或自行实现。只抽取需要的模式。long-horizon-harness的AGENTS.md刻意把每个接口映射到实现函数正是为了让你抬走一个模式而不背上整个 harness。能力 ≠ 脚手架标志。映射表中的所有能力都来自研读 适配没有任何一个对应agents-cli scaffold create的选项——脚手架只负责项目骨架scaffold create name/scaffold enhance .见 cmd_scaffold_group.py。这套主题索引 精选实现 强制导学的配方体系是 agents-cli 将复杂 Agent 能力从从零手写降级为先抄后改的关键机制它把 Docker 沙箱、技能加载器、内容审核回调、记忆存储这些易错工程变成了有据可依、有AGENTS.md导航、有 gotchas 预警的研读对象。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考