热点

AI SCORE

开源项目2026-10-16 01:27

谷歌 ADK 配方库贯通 Agent 开发部署

Google Developers Blog#Agent#谷歌#开源

Editor brief · 编辑速览

google/adk-recipes 以 core、plugins 和 contrib 三层组织参考模式、模块化技能与社区资源。开发者可将零售搜索、虚拟试穿等技能接入编程助手，并参考多语言服务的云端部署实现。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

这个经过精选的 ADK 配方库，为 Google Cloud 的 Agents CLI、Agent Garden 和 Gemini Enterprise app 提供支持。

如今，在 Google Cloud 上开发的开发者，可以从终端为具备长期记忆能力的智能体生成项目骨架，用一行命令将零售行业技能安装到编程助手中，还能将一个各项组件均已接通的生产服务部署到 Cloud Run、Agent Runtime、Agent Garden 或 Gemini Enterprise app——所有这些都来自同一棵经过精选的源码树。这棵源码树就是 google/adk-recipes，它由 google/adk-samples 重组而来，如今作为唯一事实来源，为 Agent Platform 提供支持。

ADK 配方对智能体很友好：我们让你的智能体能够轻松地 1）发现适用于各种智能体用例的相关配方，2）从你常用的运行框架中自动安装和使用这些配方。

google/adk-recipes 将内容划分为三个顶层文件夹：core/ 存放由 Agents CLI 和 DevRel 团队精选的参考模式；plugins/ 存放可安装的行业技能，以符合 Agent Plugins v1.0.0 规范的 Plugin Recipe 形式打包；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 Platform 的哪些部分提供支持

adk-recipes 是三个使用其内容的 Agent Platform 产品界面中，ADK 内容的唯一事实来源。每个界面都通过各自的协议读取仓库。

Agents CLI 读取 core/。当开发者运行 uvx --from google-agents-cli agents-cli create my-agent 时，Agents CLI 可以按需根据 core/ 中的配方生成项目骨架。这个 CLI 于今年早些时候在 Google Cloud Next 上发布，覆盖了从生成骨架 → 部署 → 评估 → 发布的完整生命周期；它提供的基础内容来自我们的配方。下文将介绍的参考运行框架 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 保存会话状态。零售商品搜索 Plugin Recipe 将 Gemini Enterprise Agent Platform 上的 Vector Search 2.0 与 BigQuery 配合使用。零售虚拟试穿 Plugin Recipe 使用 Gemini 图像模型生成静态合成图，并使用 Veo 3.1 Reference-to-Video 生成动画输出。这些配方不仅与 Agent Platform 并存，还通过实际用法为它提供文档。

对于使用 Google Cloud 工具体系之外的编程助手（Claude Code、Antigravity、Cursor、Windsurf、Zed 等）的开发者，Plugin Recipe 还支持通过 vercel-labs 维护的开放式 npx skills CLI 安装。

Horizon：core/ 的参考模式

构建一个能处理单次对话的智能体，已经是一个有成熟解决思路的问题。但要构建一个能够胜任持续数天交互、记住用户昨天做过什么，并为明天规划任务的智能体，则是难度明显不同的一项工作。无论智能体的具体用途是什么，这类长期运行系统的难点都一样：跨会话记忆、按用户隔离工具执行的沙箱、密钥管理、防止行为失控的护栏，以及让多步骤任务能够恢复执行的编排原语。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 执行这些评判标准。

向运行中的后端发起第一轮聊天，即可确认记忆层已正确接通：

Horizon 是我们让编程助手在构建更复杂系统之前先行研究的运行框架。当开发者要求助手构建一个需要支持持续数天交互的智能体时，正确的下一步就是运行 uvx google-agents-cli create，以 Horizon 生成项目骨架，运行框架的其余部分便会随之就位。

零售 Plugin Recipe

Horizon 封装了一种参考模式，但并不面向某个垂直行业。为此，仓库的第二层提供了 Plugin Recipe，每个配方都针对一个特定行业领域。本次发布中，第一个得到完整覆盖的垂直行业是零售，相关内容位于 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 的 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

virtual-tryon 技能的交互式演示更快。直接调用 generate_tryon_image，传入用户肖像和商品图片，大约十秒就能生成本节开头展示的照片级逼真合成图。将相同输入传给 generate_tryon_video，并通过 Veo Reference-to-Video 处理，就能把这张静态图转换成一段八秒的摄影棚走秀动画，让合成图中的人物动起来。

这条流水线不依赖特定商品类别。将商品图片换成一副太阳镜，并设置 product_category='eyewear'，就会调用同一个 generate_tryon_image，无须任何额外配置，即可生成符合该类别的合成图：

零售是第一个以这种形式实现完整覆盖的垂直领域。后续的垂直领域将分别以独立文件夹的形式加入 plugins/，沿用相同的结构和 Agent Plugins 规范，因此开发者可以期待跨行业一致的安装体验。

contrib/：基于插件构建的零售智能体

contrib/ 层负责将 ADK 配方变成可端到端部署的服务。目前这里有十二个 Python 智能体，涵盖了实践中通常使用 ADK 构建的应用类型：金融（财务顾问、小企业贷款处理器）、评估（LLM 审计器）、文档与知识流水线（大批量文档分析器、多格式混合 RAG）、内容与品牌（符合品牌风格的演示文稿、品牌搜索优化、符合品牌调性的生成式媒体）、零售（商品搜索、虚拟试穿），以及框架示例（agent-skills 教程、分阶段 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 访问。下面是在本地运行完全相同的智能体代码、回答完全相同的购物查询时的情况，便于检查：

UI 左侧的智能体图确认了其单智能体架构（product_search_agent → retrieve_docs）。右侧面板则跟踪每一次工具调用。回答以 Vector Search 中的一条真实商品目录记录为依据：“Sony 无线耳机 · 价格：199.99 美元 · 品牌：Sony · 评分：4.5/5（库存 50 件）· 高端包耳式降噪耳机，拥有长达 30 小时的出色续航。”没有任何商品是凭空编造的；建立在 BigQuery 之上的 Vector Search 集合才是事实依据。

这就是零售插件为团队提供的能力。插件将数据流水线的设置过程一次性编码下来，任何编程助手都可以通过对话式安装执行。contrib 智能体则是实际运行的服务，支持五种部署形态，任何组织都可以将其作为起点，替换成自己的商品目录。对应的 contrib/python/retail-virtual-tryon 也遵循同样的模式：一个更精简的根智能体，负责编排 try_on_product_image 和 try_on_product_video 工具，支持相同的五种部署形态，并建立在 virtual-tryon 插件的一次性设置之上。

没有垂直领域应用的参考运行框架只是个玩具；没有可部署产物的垂直领域技能只是一张幻灯片；没有参考模式的可部署智能体则是一个无人能够复现的原型。将这三者一同放在同一个仓库中，共用清单模式和治理流水线，开发者或编程助手就能沿着技术栈双向探索，而 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

代码仓库：github.com/google/adk-recipes

Recipe 手册：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 官方支持的产品。Recipes 仅用于演示和作为开发起点，不适用于生产环境。