跳到正文
Google Developers Blog·· 19 小时前精选AI 评分66

Google 发布 google/adk-recipes：三层结构统一 ADK 智能体配方库

Three layers, one repo: a tour of google/adk-recipes

AI 导读

Google 推出 google/adk-recipes，作为 google/adk-samples 的重构后继版本，用 core/、plugins/、contrib/ 三层结构为 Agents CLI、Agent Garden 和 Gemini Enterprise app 提供统一内容源。

推荐理由

原文完整拆解了 adk-recipes 三层结构和安装流程，读者可以据此判断它如何降低从脚手架到部署的门槛。

正文 · AI 翻译

2026年10月15日

为 Google Cloud 的 Agents CLI、Agent Garden 和 Gemini Enterprise 应用提供支持的精选 ADK recipes 库。

简介

如今，在 Google Cloud 上构建应用的开发者可以从终端搭建一个长时程记忆代理，用一行命令将零售垂直技能安装到编码助手中，并将一个完整接线的生产服务部署到 Cloud Run、Agent Runtime、Agent Garden 或 Gemini Enterprise 应用——所有这些都来自同一个精选源码树。这棵树就是 google/adk-recipes，它是 google/adk-samples 重构后的继任者，如今作为唯一事实来源为 Agent Platform 提供服务。

ADK recipes 对代理友好：我们让您的代理可以轻松地 1) 发现适用于各种代理用例的相关 recipes，2) 从您喜爱的 harness 中自动安装并使用它们。

google/adk-recipes 将其内容分为三个顶层文件夹：core/ 用于由 Agents CLI 和 DevRel 团队精选的参考模式，plugins/ 用于打包为符合 Agent Plugins v1.0.0 规范的 Plugin Recipes 的可安装垂直技能，contrib/ 用于跨五种语言的端到端可部署服务。每一个部分都以机器可读性为首要考虑进行设计。

接下来是对该仓库结构的介绍、三个实操示例（每层一个），以及对新结构所赋能之处的思考。

仓库内容

2 (1)

三个顶层根目录，各自锚定一个读者动作：

Gemini_Generated_Image_6297en6297en6297

每个 recipe 都附带一个经过验证的 manifest.yaml、一个 AGENTS.md（用于告知打开它的编码助手该 recipe 是什么以及如何使用），以及（对于 contrib/ 和 plugins/）一个 Dockerfile 加一个可运行性测试。CI 会对每个 PR 强制执行这些标准，仓库中的一组编码助手技能（prepare-python-recipe、generate-manifest、github-pr-review 等）会完成大部分准备工作，因此您的代理可以端到端地搭建、验证并提交一个 recipe。

为编码助手而构建，而不仅仅是为开发者

每一个 AGENTS.md、每一个 manifest.yaml、每一个 SKILL.md 都主要是为将代表您打开该仓库的 AI 编码助手编写的；README.md 文件仍是人类阅读的内容。手册词汇表捕捉了这种双重表述：“Recipe——位于 core/、 contrib/ 或 plugins/ 下的可运行代理示例（或可导入的代理模块），供 ADK 开发者和编码代理共同使用。”

它在 Agent Platform 各处的支持范围

adk-recipes 作为 ADK 内容的唯一事实来源，服务于消费它的三个 Agent Platform 界面。每个界面通过各自的协议读取该仓库。

Agents CLI 读取 core/。当开发者运行 uvx --from google-agents-cli agents-cli create my-agent 时，Agents CLI 可以按需搭建一个 core/ recipe。该 CLI 于今年早些时候在 Google Cloud Next 上推出，公开了完整的搭建 → 部署 → 评估 → 发布生命周期；它所提供的基础内容来自我们的 recipes。Horizon 是我们将在下文探讨的参考 harness，是 Agents CLI 视为生产模板的一个示例模式。

Agent Garden 展示精选内容。面向开发者进入该仓库的路径是向 contrib/ 提交一个 pull request：一个 recipe 进入 GitHub，成为公共 ADK 生态系统的一部分，从那一刻起便可被其他开发者以及阅读该仓库的编码助手发现。出现在 Agent Garden 画廊中则是 Agent Garden 团队另行做出的编辑决定，该团队会精选一部分 recipes，并按自己的节奏将其推广到公共目录。一旦某个代理进入画廊，Google Cloud 项目中的任何开发者都可以一键安装。

3

除了这些主要界面之外，Google Cloud 自身的基础设施组件也作为构建模块出现在这些 recipe 之中。Horizon 使用 Agent Platform Sandboxes 实现按用户隔离的沙箱、Memory Bank 实现持久记忆、Agent Platform Sessions 管理会话状态。零售产品搜索 Plugin Recipe 使用 Gemini Enterprise Agent Platform 上的 Vector Search 2.0，并与 BigQuery 配合。零售虚拟试穿 Plugin Recipe 使用 Gemini 图像模型生成静态合成图，使用 Veo 3.1 Reference-to-Video 生成动画输出。这些 recipe 不只是与 Agent Platform 并存，它们还记录了 Agent Platform 的实际使用方式。

对于在 Google Cloud 工具链之外使用编码助手的开发者（Claude Code、Antigravity、Cursor、Windsurf、Zed 等），Plugin Recipes 还可以通过 vercel-labs 维护的开源 npx skills CLI 进行安装。

Horizon：core/ 的参考模式

4

构建一个能处理单次对话的 agent 是一个已被充分理解的问题。而构建一个能在多日交互中保持连贯、记住用户昨天做了什么、并为明天规划任务的 agent，则是一项本质上不同的工程。无论这个 agent 被构建用来做什么，这种长时程系统的难点都是相同的：跨会话记忆、按用户隔离的工具执行沙箱、密钥管理、防止失控行为的护栏，以及让多步骤任务可恢复的编排原语。Horizon 位于 core/python/long-horizon-harness，是我们构建的参考 harness，用来把这些原语汇集到一处。

从全新克隆到运行中的 Horizon 实例的最短路径：

uvx google-agents-cli setup
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
gcloud services enable aiplatform.googleapis.com

git clone --depth 1 --filter=blob:none --sparse https://github.com/google/adk-recipes.git
cd adk-recipes
git sparse-checkout set core/python/long-horizon-harness
cd core/python/long-horizon-harness

# Default: LHA_ENVIRONMENT_BACKEND=local, in-memory sessions, no cloud deploys needed
make dev-local

Plain text

已复制

make deploy 通过 Terraform 将后端部署到 Cloud Run；make destroy 则将其拆除。Horizon 的评估套件位于 tests/eval/evalsets/，包含十八项具名行为准则，涵盖记忆召回、基于注入的数据外泄尝试、对抗性输入下的护栏中止、工具选择纪律，以及旅程级的剧情产物评估。这些准则通过 uv run pytest tests/eval 执行。

对运行中的后端进行第一轮聊天即可确认记忆层接线正确：

5

Horizon 是我们提供给编码助手、供其在构建更困难的东西之前研究的 harness。当开发者要求自己的助手构建一个必须跨多日交互运行的 agent 时，正确的下一步是 uvx google-agents-cli create，以 Horizon 作为脚手架，其余 harness 部分便会各就各位。

零售 Plugin Recipe

Horizon 编码的是一种参考模式，而不是一个垂直领域。为此，仓库的第二层包含 Plugin Recipes，每一个都针对特定的行业领域。本次发布中完整覆盖的第一个垂直领域是零售，位于 plugins/retail/。

Plugin Recipe 格式建立在发布在 agent-plugins.org 的 Agent Plugins v1.0.0 规范之上，这是一个用于跨编码助手打包可安装 AI 技能的开源标准。该规范将插件定义为一个或多个技能的捆绑包，并带有一个顶层 plugin.json 清单，声明名称、版本、许可证和所有权。每个技能都是一个自包含的文件夹，包含一个 SKILL.md 对话式安装器、一个 README.md、一个由质量门禁组成的 EVAL.yaml，以及该技能完成工作所需的脚本和资源。零售插件的目录结构为：

plugins/retail/
├── plugin.json
└── skills/
    ├── product-search/
    │   ├── SKILL.md       # Q-MODE conversational installer
    │   ├── README.md
    │   ├── EVAL.yaml      # LLM-as-judge rubrics + deterministic assertions
    │   ├── scripts/
    │   ├── references/
    │   └── assets/
    └── virtual-tryon/
        └── ...

Plain text

已复制

这个插件目前包含两项技能。第一项，retail-product-search，用于构建一个 ADK 智能体，它带有一个由 Gemini Enterprise Agent Platform 上的 Vector Search 2.0 以及 BigQuery 目录支持的向量检索工具。该技能处理整个流水线：将 CSV 或 JSON 目录导入 BigQuery，使用 Vertex AI Embeddings 生成多模态和文本嵌入，构建 Vector Search 集合，用 retrieve_docs 工具搭建 ADK 智能体脚手架，并部署到 Cloud Run。该智能体有意设计为单智能体：一个 root_agent 配一个检索工具，没有协调层。语义复杂性存在于检索流水线和评估器评分标准中，而不是智能体之间的通信；添加编排层会掩盖这一模式，而不是阐明它。

第二项技能，retail-virtual-tryon，生成模特穿着或手持产品的照片级合成图，并可选叠加一段八秒的工作室走秀视频。它默认使用 gemini-2.5-flash-image，当编辑质量比延迟更重要时回退到 gemini-2.5-pro-image。对于视频，它使用 veo-3.1-generate-001 的 Reference-to-Video 模式，将生成的动态效果以图像流水线产生的静态图为条件。该技能附带一个预检产品抠图分类器和可配置的安全级别，这些操作细节在第三次真实生产部署后就会变得显而易见。

两项技能都可以通过一条命令安装到任何能读取技能的编程助手中：

# From Antigravity, Claude Code, Codex, Cursor …
npx skills add google/adk-recipes --skill retail-product-search --full-depth
npx skills add google/adk-recipes --skill retail-virtual-tryon --full-depth

纯文本

已复制

--full-depth 标志指示 CLI 跳过其默认的顶层查找，发现嵌套的 plugins/retail/skills/ 结构。安装会落到 ~/.agents/skills/<skill-name>/ 中，并以符号链接方式接入本地机器上检测到的每个编程助手：

$ npx skills add google/adk-recipes --skill retail-product-search --full-depth -g

●  claude-code_2-1-288_agent  Agent detected — installing non-interactively
◇  Source: https://github.com/google/adk-recipes.git
◇  Repository cloned
◇  Found 11 skills

●  Installing to: Antigravity CLI, Augment, IBM Bob, Claude Code, OpenClaw,
   CodeBuddy, Continue, Crush, Droid, Goose, Junie, iFlow CLI,
   Kilo Code, Kiro CLI, Kode, MCPJam, Mux, OpenHands, Qoder, Qwen Code,
   Roo Code, Trae, Windsurf, Zencoder, …

◇  Installation Summary ──────────────────────────────────────────────────╮
│  ~/.agents/skills/retail-product-search                                │
│    universal: Antigravity CLI, Droid, Kilo Code, Amp +15   │
│    symlink → Augment, IBM Bob, Claude Code, OpenClaw, CodeBuddy +25    │
├────────────────────────────────────────────────────────────────────────╯

◇  Installed 1 skill
└  Done!  Review skills before use; they run with full agent permissions.

纯文本

已复制

技能生态系统被设计为可组合的。retail-product-search SKILL.md 指示宿主编程助手从 google/skills 拉取两个配套技能（如果它们尚未安装），将 BigQuery 基础知识和 Gemini API 用法等横切关注点集中在一处，并可供多个垂直插件复用。

安装后，编程助手会读取 SKILL.md 并启动 Q-MODE 访谈。对于 retail-product-search，Quick Start 是两个问题（GCP 项目 ID 和产品数据路径，两者都有合理的默认值）；Full Setup 再增加两个问题，涵盖产品字段级别和 GCP 区域。访谈结束时，该技能已经写好了一个反映项目实际形态的 ./design-spec.md，并执行了 scripts/setup.py，将目录落入 BigQuery、生成嵌入、构建 Vector Search 集合，并针对结果运行 EVAL.yaml。如果评分标准和断言检查低于 80% 的通过目标，该技能会停止并呈现具体的失败项。

在捆绑的五产品演示目录上运行端到端设置会产生：

$ .venv/bin/python scripts/setup.py --config ./design-spec.md

INFO:__main__: SETUP PIPELINE (driven by design-spec.md)
INFO:__main__:   Project:      testproject-425813
INFO:__main__:   Region:       us-central1
INFO:__main__:   Validating sample data... Validated 5 records.
INFO:__main__:   Ingesting into BigQuery...
INFO:ingest_bigquery: Creating dataset testproject-425813.retail_skill_products
INFO:ingest_bigquery: Loaded 5 valid products
INFO:__main__:   Creating Vector Search collection...
INFO:ingest_vertex_search: Collection created successfully
INFO:ingest_vertex_search: Ingestion complete: 5 created, 0 skipped, 0 errors
INFO:__main__: SETUP COMPLETE

纯文本

已复制

针对该技能刚刚配置好的集合进行实时检索会返回：

>>> from app.agent import retrieve_docs
>>> retrieve_docs("wireless headphones under 200")

纯文本

已复制 

Product 1: Wireless Headphones  $199.99  by Sony      (Audio)       rated 4.5/5
          Premium noise-cancelling over-ear headphones with 30-hour battery
Product 2: Laptop Stand         $49.99   by Generic   (Accessories) rated 4.2/5
Product 3: Mechanical Keyboard  $129.99  by Keychron  (Peripherals) rated 4.6/5
Product 4: USB-C Cable          $19.99   by Anker     (Cables)      rated 4.7/5
Product 5: Monitor Light Bar    $59.99   by BenQ      (Lighting)    rated 4.4/5

纯文本

已复制

虚拟试穿技能在交互式演示中更快。直接调用 generate_tryon_image，传入用户肖像和产品图像，大约十秒即可生成本节顶部所示的照片级合成图。将相同的输入通过 generate_tryon_video 和 Veo Reference-to-Video 处理，可将该静态图变为合成图运动中的八秒工作室走秀动画。

该流水线是类别无关的。将产品图片替换为一副太阳镜，配合 product_category='eyewear'，会调用同样的 generate_tryon_image 调用，并在无需任何进一步配置的情况下生成正确类别的合成图：

6

零售是首个以这种格式完全覆盖的垂直领域。其他垂直领域将作为 plugins/ 下各自的文件夹落地，遵循相同的结构和相同的 Agent Plugins 规范，因此开发者可以期待跨行业一致的安装体验。

在 contrib/: 中，一个基于该插件构建的零售 agent

contrib/ 层是 ADK recipes 成为端到端可部署服务的地方。目前那里有十二个 Python agents，涵盖了 ADK 在实践中通常用于构建的各种应用类型：金融（financial advisor、small-business loan processor）、评估（LLM auditor）、文档与知识流水线（high-volume document analyzer、multiformat hybrid RAG）、内容与品牌（brand-aligned presentations、brand-search optimization、on-brand genmedia）、零售（product search、virtual try-on），以及框架示例（agent-skills tutorial、staged UI widgets）。Java、Go、TypeScript 和 Kotlin 各自携带更小的集合。contrib/ 中的每一项都是一个 core/ 模式或 plugins/ 技能如何成为运行服务的完整示例。

为了使插件与其可部署对应物之间的关系具体化，以 contrib/python/retail-product-search 为例。上一节中的零售插件引导开发者完成了一次对话式安装，预置了 Vector Search 集合、BigQuery 目录和嵌入。contrib agent 是可部署的对应物：一个长期运行的服务，从该集合中读取数据，并基于它回答自然语言购物查询。插件负责一次性设置；contrib agent 负责服务形态。两者由同一团队维护以保持同步，而该 agent 的 README 引导新用户先运行插件的设置：

make -C plugins/retail/skills/product-search setup PROJECT_ID=your-project

纯文本

已复制

一旦集合（retail-skill-products-collection）填充完毕，该 agent 就从 contrib/python/retail-product-search 克隆出来，指向一个 GCP 项目，并通过 .env 中的布尔标志在五种部署角色之一上呈现。

部署上线后，该 agent 会暴露一个托管的购物助手端点。我们之前直接从 Python 调用的同一个 retrieve_docs 工具现在位于聊天界面之后，可通过部署的 Reasoning Engine 访问，或在开发期间通过 ADK Web UI 访问。完全相同的 agent 代码回答完全相同的购物查询，在本地运行以供检查：

7

UI 左侧的 agent 图确认了单 agent 架构（product_search_agent → retrieve_docs）。右侧面板追踪每次工具调用。响应基于 Vector Search 中的真实目录行：“Sony Wireless Headphones · Price: $199.99 · Brand: Sony · Rating: 4.5/5 (50 in stock) · Premium noise-cancelling over-ear headphones featuring an impressive 30-hour battery life.” 没有产品被幻觉出来；基于 BigQuery 的 Vector Search 集合是事实来源。

这就是零售插件为团队带来的东西。该插件通过任何编码助手都能执行的对话式安装，一次性编码好数据管道的配置。contrib 代理是运行中的服务，可以以五种形态部署，任何组织都可以将其作为起点并替换成自己的目录。contrib/python/retail-virtual-tryon 中的虚拟试穿对应部分遵循同样的模式：一个更小的根代理，编排 try_on_product_image 和 try_on_product_video 工具，以相同的五种形态部署，基于虚拟试穿插件的一次性设置构建。

为什么这很重要

一个没有垂直领域的参考框架只是个玩具；一个没有可部署产物的垂直领域技能只是一张幻灯片；一个没有参考模式的可部署代理只是一个没人能复现的原型。将三者放在同一个仓库中交付，使用共享的清单模式和治理管道，让开发者或编码助手可以双向地走通整个技术栈，每个 Agent Platform 界面都从同一个真实来源读取数据。

实际结果是，从“我需要一个能做 X 的代理”到运行中的生产服务的门槛更低了：编码助手可以搭建一个 Horizon 形态的代理，安装一个垂直领域 Plugin Recipe，并查阅 contrib/ 中的部署记录，无需在仓库之间进行转换或协调清单格式。对于构建垂直领域解决方案的团队，Plugin Recipes 将领域专业知识一次性打包，并以相同的安装流程和质量关卡分发给市场上的每一个编码助手。

开始使用

# Install Agents CLI
uvx --from google-agents-cli agents-cli setup

# Scaffold a Horizon-shaped agent
uvx --from google-agents-cli agents-cli create my-agent

# Install a retail skill into your coding assistant
npx skills add google/adk-recipes --skill retail-product-search --full-depth

# Launch the deployable retail agent as a managed artifact
uvx --from google-agents-cli agents-cli create retail-product-search

纯文本

已复制

并非 Google 官方支持的产品。Recipe 仅用于演示和作为起点，不适用于生产环境。

上一页

下一页

来源：Google Developers Blog · developers.googleblog.com

Google / GeminiAgent 智能体开源生态MCP 与工具调用教程实践#教程/实践#Agent#MCP/工具调用#开源/仓库#Google