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

Google 发布 google/adk-recipes 仓库，三层结构服务 Agent Platform

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

AI 导读

Google 将原 google/adk-samples 重构为 google/adk-recipes，用 core/、plugins/、contrib/ 三层分别承载参考模式、可安装垂直技能和端到端可部署服务，并作为 Agents CLI、Agent Garden 与 Gemini Enterprise app 的统一内容来源。

推荐理由

Google 把 ADK 示例库重构为面向编码智能体的三层仓库，读者可据此了解 Agent 技能打包与安装的现行做法。

正文 · AI 翻译

2026年10月15日

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

引言

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

ADK 配方对智能体友好：我们让智能体可以轻松地 1) 发现适用于各种智能体用例的相关配方，以及 2) 从你喜爱的 harness 中自动安装并使用它们。

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

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

仓库里有什么

2 (1)

三个顶层根目录，每个都锚定一种读者操作：

Gemini_Generated_Image_6297en6297en6297

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

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

每个 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/ 配方。该 CLI 于今年早些时候在 Google Cloud Next 上推出，公开了完整的搭建 → 部署 → 评估 → 发布生命周期；它所提供的基础内容来自我们的配方。Horizon 是我们下面要研究的参考 harness，它是 Agents CLI 视为生产模板的一个示例模式。

Agent Garden 展示精选内容。开发者进入该仓库的路径是向 contrib/ 提交拉取请求：一个配方进入 GitHub，成为公共 ADK 生态系统的一部分，从那一刻起就可被其他开发者和阅读该仓库的编码助手发现。出现在 Agent Garden 图库中则是 Agent Garden 团队做出的另一项编辑决定，该团队会精选一部分配方，并按自己的节奏将它们提升到公共目录中。一旦某个智能体进入图库，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

纯文本

已复制

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

针对运行中后端的第一轮聊天确认记忆层已正确连接：

5

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

零售 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/
        └── ...

纯文本

已复制

这个插件目前提供两项技能。第一项，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 的参考到视频模式，以图像流程生成的静态图作为生成动作的条件。该技能附带一个预检产品抠图分类器和可配置的安全级别，这些操作细节在第三次真实生产部署后变得显而易见。

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

# 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 参考到视频管道，可将该静态图变成合成图动态的八秒演播室走秀动画。

该流水线与类别无关。把产品图片换成一副太阳镜，配合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 是无人能复现的原型。将三者放在一个仓库中，在共享的清单模式和治理管道下发布，让开发者或编码助手可以沿任一方向遍历整个技术栈，每个 Agent Platform 界面都从同一事实来源读取。

实际结果是，从“我需要一个能做 X 的 agent”到运行中的生产服务的门槛更低：编码助手可以搭建一个 Horizon 形态的 agent，安装垂直 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 官方支持的产品。Recipes 仅用于演示和作为起点，不用于生产环境。

上一篇

下一篇

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

Google / GeminiAgent 智能体开源生态部署工程产品更新#产品更新#Agent#开源/仓库#Google#部署/工程