Google Developers Blog

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

6.9内容质量

TL;DR · AI 摘要

Three layers, one repo: a tour of google/adk-recipes - Google Developers Blog Google Tag Manager noscript End Google Tag...

核心要点

  • 主题聚焦：Three layers, one repo: a tour of google/adk-rec
  • 来源：Google Developers Blog，建议结合原文判断细节。
  • AI 分析暂不可用，本条为保底评分与摘要。
#AI#编程#前端#后端#云计算
打开原文

三层架构，一个仓库：google/adk-recipes 项目巡礼 - Google Developers Blog

Google Tag Manager (noscript)

结束 Google Tag Manager (noscript)

HTML

三层架构，一个仓库：google/adk-recipes 项目巡礼

2026年10月15日

Pier Paolo Ippolito

产品经理

Shahin Saadati

软件工程师

分享

  • Facebook
  • Twitter
  • LinkedIn
  • 邮件

为 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 平台的单一可信来源提供服务。

ADK 方案对代理友好：我们已简化了代理发现相关方案的流程，使您的代理能够 1）快速找到各种使用场景的相关方案，2）从您喜爱的框架中自动安装和使用这些方案。

google/adk-recipes 将内容划分为三个顶级文件夹：core/ 包含由 Agents CLI 和 DevRel 团队整理的参考模式，plugins/ 包含符合 Agent Plugins v1.0.0 规范的可安装垂直技能（以插件方案形式打包），contrib/ 包含跨五种语言的端到端可部署服务。每个部分都以机器可读性为主要设计考量。

以下将带您浏览仓库的结构，展示三个分层示例（每层一个），并探讨新架构带来的可能性。

仓库内容

三个顶级根目录，每个都对应一种读者操作：

每个方案都包含经过验证的 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 文件仍是人类阅读的内容。手册术语表体现了双重定位："方案——在 core/、contrib/ 或 plugins/ 下的可运行代理示例（或可导入代理模块），由 ADK 开发者和编码代理共同使用。"

在 Agent 平台上的应用

adk-recipes 是 ADK 内容在三个 Agent 平台界面上的单一可信来源。每个界面都通过自己的协议读取仓库。

Agents CLI 读取 core/。当开发者运行 uvx --from google-agents-cli agents-cli create my-agent 时，Agents CLI 可按需搭建 core/ 方案。今年早些时候在 Google Cloud Next 上发布的 CLI 暴露了完整的搭建 → 部署 → 评估 → 发布生命周期；其提供的基础内容均来自我们的方案。下文将探讨的 Horizon（参考框架）是 Agents CLI 视为生产模板的示例模式。

Agent Garden 提供精选内容。面向开发者的仓库接入路径是向 contrib/ 提交拉取请求：配方提交到 GitHub 后将成为公共 ADK 生态系统的一部分，并从此刻起被其他开发者和阅读仓库的代码助手发现。出现在 Agent Garden 画廊中是 Agent Garden 团队独立做出的编辑决策，该团队会精选部分配方并按照自己的节奏推广到公共目录。一旦代理出现在画廊中，任何 Google Cloud 项目中的开发人员都可以一键安装。

除了这些主要展示界面，Google Cloud 自身的基础设施组件会以构建模块的形式直接出现在配方中。Horizon 使用 Agent Platform Sandboxes 实现按用户沙箱化，使用 Memory Bank 实现持久化内存，使用 Agent Platform Sessions 管理会话状态。零售产品搜索插件配方使用 Gemini 企业代理平台上的 Vector Search 2.0 配合 BigQuery。零售虚拟试穿插件配方使用 Gemini 图像模型生成静态合成图，使用 Veo 3.1 Reference-to-Video 生成动画输出。这些配方不仅仅是与 Agent Platform 并行存在，它们还通过实际使用案例对 Agent Platform 进行了文档说明。

对于使用 Google Cloud 工具之外的代码助手（如 Claude Code、Antigravity、Cursor、Windsurf、Zed 等）的开发者，插件配方还会通过由 vercel-labs 维护的开源 npx skills CLI 进行安装。

Horizon：core/ 的参考模式

构建能够处理单次对话的代理是一个已被充分理解的问题。构建一个能够持续多日交互、记住用户昨日行为并规划明日任务的代理，是一项本质不同的工程挑战。这种长周期系统的难点无论代理的具体用途是什么都是一致的：跨会话记忆、按用户沙箱化的工具执行、密钥管理、防止失控行为的安全防护，以及使多步骤任务可恢复的编排原语。Horizon（位于 core/python/long-horizon-harness）是我们构建的参考框架，用于将这些原语集中在一个地方。

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

code
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

# 默认：LHA_ENVIRONMENT_BACKEND=local，内存会话，无需云部署
make dev-local

纯文本

已复制

make deploy 通过 Terraform 将后端部署到 Cloud Run；make destroy 会将其拆除。Horizon 的评估套件位于 tests/eval/evalsets/，包含 18 个命名行为准则，覆盖记忆召回、注入式数据泄露尝试、对抗性输入下的安全防护触发、工具选择纪律性以及剧情级画布制品评估。这些准则通过 uv run pytest tests/eval 执行。

对正在运行的后端进行首次聊天交互可验证内存层是否正确连接：

Horizon 是我们为编码助手提供的一个框架，用于在构建更复杂的系统之前进行学习。当开发者要求其助手构建一个需要跨多日交互运行的代理时，下一步正确的操作是使用 uvx google-agents-cli create 命令并以 Horizon 作为基础框架，其余的框架结构会自然就位。

零售插件配方

Horizon 编码了一个参考模式。它并不针对特定行业领域。为此，仓库的第二层包含插件配方（Plugin Recipes），每个配方都针对特定的行业领域。本次发布中第一个被完整覆盖的垂直领域是零售，相关资源位于 plugins/retail/ 路径下。

插件配方格式建立在 [agent-plugins.org](agent-plugins.org) 发布的 Agent Plugins v1.0.0 规范之上，这是一个用于在各类编码助手之间打包可安装 AI 技能的开放标准。该规范将插件定义为包含一个或多个技能的集合，顶层的 plugin.json 清单文件声明了名称、版本、许可证和所有权信息。每个技能都是一个自包含的文件夹，包含 SKILL.md 对话式安装器、README.md、EVAL.yaml 质量门限文件，以及技能执行所需脚本和资源。零售插件的目录结构如下：

code
plugins/retail/
├── plugin.json
└── skills/
    ├── product-search/
    │   ├── SKILL.md       # Q-MODE 对话式安装器
    │   ├── README.md
    │   ├── EVAL.yaml      # LLM-as-judge 评分标准 + 确定性断言
    │   ├── scripts/
    │   ├── references/
    │   └── assets/
    └── virtual-tryon/
        └── ...

当前该插件包含两个技能。第一个技能 retail-product-search 构建了一个 ADK 代理，其向量搜索检索工具基于 Gemini 企业代理平台的 Vector Search 2.0 和 BigQuery 目录。该技能处理整个流程：将 CSV 或 JSON 目录导入 BigQuery，使用 Vertex AI Embeddings 生成多模态和文本嵌入，构建向量搜索集合，使用 retrieve_docs 工具搭建 ADK 代理，并部署到 Cloud Run。该代理刻意设计为单代理结构：一个根代理、一个检索工具，没有协调层。语义复杂性体现在检索流程和评估标准中，而非代理间的通信；增加编排层反而会模糊这一模式。

第二个技能 retail-virtual-tryon 生成一个高度逼真的模特穿戴或手持产品的合成图像，可选地在图像上叠加一个八秒的时装走秀视频。默认使用 gemini-2.5-flash-image，当需要更高质量的编辑效果时会回退到 gemini-2.5-pro-image。视频生成使用 veo-3.1-generate-001 的 Reference-to-Video 模式，将生成的运动基于图像流程生成的静态图像进行条件控制。该技能包含预飞行产品抠图分类器和可配置的安全级别，这些操作细节在第三次实际生产部署后变得显而易见。

这两个技能可通过以下命令安装到任何支持技能读取的编码助手：

code
# 来自 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>/ 目录，并在本地机器检测到的所有编码助手之间创建符号链接：

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

●  claude-code_2-1-288_agent  检测到代理 — 正在非交互式安装
◇  来源: https://github.com/google/adk-recipes.git
◇  仓库已克隆
◇  发现 11 个技能

●  安装目标: 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, …

◇  安装摘要 ──────────────────────────────────────────────────╮
│  ~/.agents/skills/retail-product-search                                │
│    universal: Antigravity CLI, Droid, Kilo Code, Amp +15   │
│    符号链接 → Augment, IBM Bob, Claude Code, OpenClaw, CodeBuddy +25    │
├────────────────────────────────────────────────────────────────────────╯

◇  已安装 1 个技能
└  完成！使用前请查看技能；它们会以完整代理权限运行。

技能生态系统的设计目标是实现模块化组合。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、生成嵌入向量、构建向量搜索集合，并运行 EVAL.yaml 验证结果。如果评分标准和断言检查的通过率低于 80%，该技能会停止执行并显示具体失败信息。

对捆绑的五产品演示目录进行端到端设置运行会生成：

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

INFO:__main__: SETUP PIPELINE (由 design-spec.md 驱动)
INFO:__main__:   项目:      testproject-425813
INFO:__main__:   区域:       us-central1
INFO:__main__:   验证示例数据... 已验证 5 条记录。
INFO:__main__:   导入到 BigQuery...
INFO:ingest_bigquery: 创建数据集 testproject-425813.retail_skill_products
INFO:ingest_bigquery: 加载了 5 个有效产品
INFO:__main__:   创建向量搜索集合...
INFO:ingest_vertex_search: 集合创建成功
INFO:ingest_vertex_search: 导入完成: 5 个已创建，0 个跳过，0 个错误
INFO:__main__: SETUP 完成

对技能刚创建的集合进行实时检索会返回：

code
>>> from app.agent import retrieve_docs
>>> retrieve_docs("wireless headphones under 200")
code
产品 1：无线耳机  $199.99  Sony      （音频）       评分 4.5/5
          配备 30 小时电池的高端降噪头戴耳机
产品 2：笔记本支架         $49.99   Generic   （配件） 评分 4.2/5
产品 3：机械键盘           $129.99  Keychron  （外设） 评分 4.6/5
产品 4：USB-C 数据线        $19.99   Anker     （线缆） 评分 4.7/5
产品 5：显示器灯条         $59.99   BenQ      （照明） 评分 4.4/5

虚拟试穿功能更适合交互式演示。直接调用 generate_tryon_image 接口，传入用户人像和产品图片，可在约十秒内生成本节顶部展示的写实合成图像。相同输入通过 generate_tryon_video 和 Veo Reference-to-Video 处理后，可生成八秒的动态走秀动画。

该流程对品类无限制。将产品图片替换为太阳镜并设置 product_category='eyewear'，同样调用 generate_tryon_image 接口即可生成正确品类的合成图像，无需额外配置：

零售是首个完整覆盖的行业垂直领域。其他垂直领域将作为独立文件夹添加至 plugins/ 目录，遵循相同架构和 Agent Plugins 规范，开发者可期待跨行业一致的安装体验。

contrib/ 目录：基于插件构建的零售代理

contrib/ 层是 ADK 方案转化为端到端可部署服务的地方。目前该目录包含 12 个 Python 代理，覆盖 ADK 通常构建的应用类型：金融（理财顾问、小微企业贷款处理器）、评估（LLM 审计）、文档与知识流水线（高吞吐文档分析器、多格式混合 RAG）、内容与品牌（品牌对齐演示文稿、品牌搜索优化、品牌化内容生成）、零售（产品搜索、虚拟试穿）以及框架示例（代理技能教程、分步 UI 组件）。Java、Go、TypeScript 和 Kotlin 各有较小的实现集。contrib/ 中的每个条目都是核心模式或插件技能转化为运行服务的完整示例。

为具体说明插件与其可部署版本的关系，以 contrib/python/retail-product-search 为例。上一节的零售插件引导开发者完成了一次对话式安装，创建了向量搜索集合、BigQuery 目录和嵌入向量。contrib 代理是其可部署版本：一个持续运行的服务，从该集合读取数据并回答自然语言购物查询。插件负责一次性初始化，contrib 代理负责服务形态。两者由同一团队维护以保持同步，代理的 README 指导新用户首先运行插件的初始化：

code
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工具现在通过聊天界面提供服务，可通过部署的推理引擎访问，或在开发阶段通过ADK Web UI访问。完全相同的代理代码处理完全相同的购物查询，本地运行以便检查：

UI左侧的代理图确认了单代理架构（product_search_agent → retrieve_docs）。右侧面板追踪了每个工具调用。响应基于Vector Search的真实目录条目："Sony无线耳机 · 价格：199.99美元 · 品牌：Sony · 评分：4.5/5（库存50件） · 配备令人印象深刻的30小时电池续航的高端降噪头戴耳机"。没有生成任何虚构产品；Vector Search集合基于BigQuery，是数据来源。

这就是零售插件为团队提供的能力。该插件通过对话式安装流程一次性编码数据管道设置，任何代码助手均可执行。contrib代理是可部署为五种形态的运行服务，任何组织均可将其作为起点并替换自己的目录。contrib/python/retail-virtual-tryon中的虚拟试穿对应实现遵循相同模式：一个较小的根代理协调try_on_product_image和try_on_product_video工具，以相同五种形态部署，基于虚拟试穿插件的一次性设置。

为什么这很重要

没有垂直领域的参考框架只是玩具；没有可部署成果的垂直技能只是幻象；没有参考模式的可部署代理只是无法复现的原型。在一个仓库中同时提供这三个组件，通过共享的清单模式和治理流水线，使开发者或代码助手可以双向遍历整个堆栈，所有Agent Platform界面都读取相同的数据源。

实际效果是降低了从"我需要能执行X的代理"到运行生产服务的门槛：代码助手可搭建Horizon形状的代理，安装垂直插件配方，无需在仓库间转换或协调清单格式即可直接访问contrib/中的部署记录。对于构建垂直解决方案的团队，插件配方一次性封装领域专业知识，并通过相同的安装流程和质量门禁分发给所有市场上的代码助手。

入门指南

code
# 安装Agents CLI
uvx --from google-agents-cli agents-cli setup

# 创建Horizon形状的代理
uvx --from google-agents-cli agents-cli create my-agent

# 将零售技能安装到你的代码助手中
npx skills add google/adk-recipes --skill retail-product-search --full-depth

# 作为托管工件启动可部署的零售代理
uvx --from google-agents-cli agents-cli create retail-product-search
  • 仓库：github.com/google/adk-recipes
  • 配方手册：github.com/google/adk-recipes/tree/main/docs/recipe-handbook
  • Agents CLI文档：uvx --from google-agents-cli agents-cli --help
  • Agent Plugins v1.0.0规范：agent-plugins.org/specification

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

发布在：

  • AI
  • 云
  • 公告
  • 解决方案
  • 学习
  • ADK
  • 插件
  • 代理花园
  • 影响力
  • 代理

上一篇

下一篇

相关文章

列表

AI

云

公告

问题解决

宣布 Apigee hybrid 支持 MCP：在您自己的集群中运行的智能工具

2026年10月14日

案例研究

Gemini 4 Argon 在机器人技术中的应用

2026年10月13日

最佳实践

行业趋势

评估 AI 代理：超越直觉判断

导航点