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

Google 介绍 google/adk-recipes 仓库的三层结构与 Agent Platform 集成

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

AI 导读

Google Developers Blog 介绍 google/adk-recipes 仓库，它是 google/adk-samples 的重构后继版本，以 core/、plugins/、contrib/ 三层作为 Agent Platform 各入口的单一内容来源。

推荐理由

官方详解 google/adk-recipes 三层结构，读者可以据此了解同一仓库如何同时服务 Agents CLI、Agent Garden 和 Gemini Enterprise。

正文 · 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/ 用于以 Plugin Recipes 形式打包、符合 Agent Plugins v1.0.0 规范的可安装垂直技能，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/ 提交拉取请求：一个 recipe 进入 GitHub，成为公共 ADK 生态系统的一部分，从那一刻起就可被其他开发者和读取该仓库的编码助手发现。出现在 Agent Garden 图库中则是 Agent Garden 团队做出的另一项编辑决定，该团队会精选一部分 recipes，并按自己的节奏将其推广到公共目录。一旦某个智能体进入图库，Google Cloud 项目中的任何开发者都可以一键安装。

3

除了这些主要界面之外，Google Cloud 自身的基础设施组件也作为构建模块出现在这些配方之中。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 生成动画输出。这些配方并非只是与 Agent Platform 并存；它们记录了 Agent Platform 的实际使用方式。

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

Horizon：一个参考模式，用于 core/

4

构建一个能够处理单次对话的智能体是一个已被充分理解的问题。构建一个能够在多天的交互中保持自身状态、记住用户昨天做了什么并规划明天任务的智能体，则是一项本质上不同的工作。这类长时程系统的难点，无论智能体被构建来做什么，都是相同的：跨会话记忆、工具执行的按用户沙箱隔离、密钥管理、防止失控行为的护栏，以及使多步骤任务可恢复的编排原语。Horizon 位于 core/python/long-horizon-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 是我们提供给编码助手的测试框架，供其在构建更困难的东西之前进行研究。当开发者要求其助手构建一个必须在多天交互中运行的智能体时，正确的下一步是以 Horizon 作为脚手架使用 uvx google-agents-cli create，其余测试框架便会各就各位。

零售 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，快速开始是两个问题（GCP 项目 ID 和产品数据路径，两者都有合理的默认值）；完整设置再增加两个问题，涵盖产品字段级别和 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/:中，一个基于该插件构建的零售智能体

contrib/层是 ADK 配方变为可端到端部署的服务的地方。目前那里有十二个 Python 智能体，涵盖了 ADK 在实践中通常用于构建的各类应用：金融（财务顾问、小微企业贷款处理）、评估（LLM 审计器）、文档与知识流水线（高吞吐文档分析器、多格式混合 RAG）、内容与品牌（品牌一致的演示文稿、品牌搜索优化、符合品牌调性的生成媒体）、零售（产品搜索、虚拟试穿），以及框架示例（智能体技能教程、分阶段 UI 组件）。Java、Go、TypeScript 和 Kotlin 各自带有较小的集合。contrib/中的每个条目都是一个实例，展示core/模式或plugins/技能如何变成可运行的服务。

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

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

纯文本

已复制

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

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

7

UI 左侧的智能体图确认了单智能体架构（product_search_agent → retrieve_docs）。右侧面板追踪每次工具调用。响应基于 Vector Search 中真实的目录行："Sony 无线耳机 · 价格：$199.99 · 品牌：Sony · 评分：4.5/5（库存 50 件）· 高端降噪头戴式耳机，拥有令人印象深刻的 30 小时电池续航。" 没有产品被幻觉出来；BigQuery 之上的 Vector Search 集合是事实来源。

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

为什么这很重要

没有垂直场景的参考框架只是玩具；没有可部署产物的垂直技能只是一张幻灯片；没有参考模式的可部署 agent 只是一个无人能复现的原型。将这三者放在同一个仓库中，使用共享的 manifest schema 和治理管道，让开发者或编码助手可以沿任一方向走通整个技术栈，每个 Agent Platform 界面都从同一个事实来源读取。

实际结果是，从“我需要一个能做 X 的 agent”到运行中的生产服务，门槛更低了：编码助手可以搭建一个 Horizon 形态的 agent，安装一个垂直 Plugin Recipe，并直接使用 contrib/ 中的部署记录，而无需在仓库之间转换或协调 manifest 格式。对于构建垂直解决方案的团队，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 官方支持的产品。Recipes 仅用于演示和作为起点，不适用于生产环境。

上一页

下一页

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

Google / GeminiAgent 智能体开源生态产品更新#产品更新#Agent#开源生态#Google