GoogleCloudPlatform/agent-starter-pack · 上手攻略

仓库：GoogleCloudPlatform/agent-starter-pack
链接：https://github.com/GoogleCloudPlatform/agent-starter-pack
分类：ai（Google Cloud GenAI Agent 模板 / MLOps 脚手架）
作者：spark
更新：2026-07-15

是什么

Agent Starter Pack（ASP） 是 Google Cloud 官方出的 生产级 GenAI Agent 模板项目：用 Python 包形式提供一整套「Agent + 后端 + 前端 + 部署基础设施 + 监控 + CI/CD」的项目骨架，让开发者只关心 agent 业务逻辑。

它支持多种 agent 框架 / 模式（自带模板）：

adk：基于 Google Agent Development Kit (ADK) 的 ReAct agent。
adk_a2a：在 ADK 上加 Agent2Agent (A2A) Protocol 的多机代理通信。
agentic_rag：基于 Vertex AI Search / Vector Search 的检索增强生成 agent。
langgraph：基于 LangChain LangGraph 的 ReAct agent。
adk_java：ADK 的 Java 版本。
adk_live：基于 Gemini 的实时多模态（音频 / 视频 / 文本）RAG agent。

重要变更：README 第一段明确写了——ASP 活跃开发已迁移到 google/agents-cli，ASP 仓库只接收 critical bugfix，不再添加新功能 / 新模板 / 新部署目标。新项目建议直接用 agents-cli；老项目有迁移指南。本攻略覆盖的是 ASP 当前可用状态 + 迁移路径。

解决什么问题

Agent demo 跑得起来，但上不了生产：CI/CD、IAM、Terraform、监控、日志、灰度发布都得自己拼；ASP 一行命令搞定。
不知道 Google Cloud 上 AI Agent 该怎么组织：Vertex AI / Cloud Run / Agent Engine 怎么选？ASP 的模板给出现成范式。
评估 / 可观测性缺失：自带 Vertex AI Evaluation + Cloud Trace / Logging 接入。
多框架选型难：ADK / LangGraph / A2A / Live API / RAG 都有现成模板，能直接横向对比。
从零搭太慢：一条命令 60 秒生成可上 Cloud Run 的项目。

快速安装

前置

Python 3.10+
Google Cloud SDK（gcloud 已登录并设了 project）
Terraform（部署用）
make
推荐装 uv

一键创建

# 用 uv 跑（无需安装到全局）
uvx agent-starter-pack create

或走 pip：

python -m venv .venv && source .venv/bin/activate
pip install --upgrade agent-starter-pack
agent-starter-pack create

按交互提示：选 agent 模板（adk / langgraph / agentic_rag ...）、项目名、region。完成后目录里就是完整项目。

给已有 agent 加 ASP 部署能力

uvx agent-starter-pack enhance

在你已有项目根目录跑，会自动补 CI/CD、Terraform、observability。

零本地环境试用

Firebase Studio 模板：浏览器里直接跑。
Cloud Shell 一键：云端 IDE 内启动。

核心用法（可直接复制）

1. 创建 ADK ReAct agent

uvx agent-starter-pack create my-agent --template adk
cd my-agent

生成出来的结构（简化）：

my-agent/
├── app/                     # Agent 代码（ADK 实现）
│   ├── agent.py
│   └── ...
├── deployment/              # Terraform 部署
├── tests/                   # 单元 + e2e
├── .github/workflows/       # CI/CD
├── Makefile                 # run / deploy / eval 等命令
└── GEMINI.md                # Gemini CLI 上下文

启动本地调试：

make playground   # 浏览器交互式调试
make run          # 起后端服务
make test         # 单测

部署到 Cloud Run：

make deploy

make deploy 内部会 terraform apply，把后端、前端、Cloud Run、Artifact Registry、Secret Manager 一并建好。

2. RAG agent（Vertex AI Search）

uvx agent-starter-pack create rag-bot --template agentic_rag
cd rag-bot

补一份文档数据（GCS 路径）：

export DATA_STORE_ID=my-datastore
gcloud ai search-engines create --display-name=$DATA_STORE_ID \
  --data-store-id=$DATA_STORE_ID --search-engine-type=...

把 PDF / HTML 灌进 datastore 后，agent 直接接 Vertex AI Search 做检索。

3. Live API 多模态

uvx agent-starter-pack create live-bot --template adk_live
cd live-bot && make run

模板自带 WebSocket 通道，前端用 Gemini Live API 与浏览器音频 / 视频流互动。

4. LangGraph 模板

uvx agent-starter-pack create lg-bot --template langgraph

app/ 里的 agent 是 LangGraph 写的；CI/CD / 部署 / 监控与 ADK 模板一致，能横向对比两套框架在 GCP 上的落地差异。

5. 评估 + 对比

make eval                # 跑 Vertex AI Evaluation
make eval-compare        # 比较两次评估结果

模板默认带一个评测集（goldens.jsonl），跑完会输出 metric（answer_relevancy、faithfulness、groundedness 等）。

6. Gemini CLI 集成

模板根目录有 GEMINI.md，在装了 Gemini CLI 的终端里直接问「这个模板怎么改？」Gemini 会读 GEMINI.md 作为上下文给建议。

7. 一键接入 CI/CD

agent-starter-pack setup-cicd

把项目推到 GitHub / Cloud Build 后，每次 push 自动跑 test + eval + 部署到 dev / staging / prod。

典型适用场景

想尽快把 agent 跑在 GCP 上：模板把 Cloud Run + Vertex AI + Terraform 一条龙配齐，60 秒出 MVP。
多 agent 通信原型：用 adk_a2a 模板先做 A2A 协议 POC，再扩展到生产。
RAG 落地：agentic_rag 模板把 Vertex AI Search / Vector Search 的 ingestion pipeline 也包了。
多模态实时交互：adk_live 一键生成 Gemini Live API 的浏览器 / 移动端 demo。
横向对比 agent 框架：同一个 ASP 项目里换 ADK / LangGraph 模板，能直接对比部署、可观测、扩展成本。
团队模板定制：ASP 支持 Remote Templates，把内部模板打成私有 Git repo 当 starter 包。

坑与注意

仓库已迁：ASP 现在是维护模式，新功能在 google/agents-cli。新项目应该直接用 agents-cli；uvx google-agents-cli setup 即可上手，老 ASP 项目按官方 migration guide 几分钟迁完。
强依赖 Google Cloud：部署目标是 Cloud Run / Agent Engine / Vertex AI；想跑 AWS / Azure 几乎要重写。
要付费：Cloud Run、Vertex AI、Artifact Registry、Cloud Build 都要看账单；评测集反复跑也会烧钱。删 demo 项目时记得 terraform destroy。
gcloud 项目 + 权限：默认用你的 gcloud config get-value project；权限不够的话 make deploy 会卡在 Terraform 的 IAM 上。常见需要：roles/run.admin、roles/iam.serviceAccountAdmin、roles/aiplatform.user。
模板版本和 SDK 漂移：Agent Engine / ADK 迭代快，模板里的 framework_version 字符串偶有变更，跑 make run 报错先升级 pip install -U agent-starter-pack。
评估数据隐私：默认评测集常走 Vertex AI Evaluation 上传到 Google；企业敏感数据要改用自建评估 pipeline。
make 而非裸命令：项目大量命令走 Makefile，第一次看 make help 才不迷路。
Terraform state：默认本地 terraform.tfstate，团队多人部署要迁 GCS backend（模板有提示，但不会自动做）。

与同类对比

项目 / 工具	出品方	定位	与 ASP 区别
google/agents-cli（后继者）	Google	统一 CLI + 模板	ASP 升级版；新项目首选
google/adk-python	Google	Agent 开发框架（Python）	ASP 的 `adk` 模板底层就是它
Vertex AI Agent Engine	Google Cloud	托管 agent 运行时	ASP 把它当作一种部署目标之一
LangGraph / LangChain	LangChain	通用 agent 框架	ASP `langgraph` 模板底层就是它们
Coze / Dify / n8n	社区 / 字节 / 商业	可视化 agent 平台	ASP 是代码侧，不带可视化编排
amazon-sagemaker-examples	AWS	ML/Agent 示例 + 部署	对标 AWS 侧；ASP 强绑 GCP
Vellum / Arize	商业	Agent 评估 / 可观测	ASP 用 Vertex AI Evaluation；商业工具评估维度更全

ASP 的差异化是「GCP 全栈原生 + 多框架模板 + 自带 CI/CD + Terraform」：一条命令出 Cloud Run 部署，比手搓快得多。代价是绑死 GCP。

一句话推荐结论

GCP 上的 agent 落地脚手架：如果你确定走 Google Cloud + Vertex AI，并且接受「Cloud Run + Terraform + Vertex 评估」这套范式，ASP（及其后继 agents-cli）是 60 秒出生产骨架的最高效路径；如果你在新项目，请直接用 google/agents-cli，ASP 已进入维护期。