agent-starter-pack

有信心的人，永远不会失败。——亚伯拉罕·林肯

从零到生产：Google Cloud Agent Starter Pack 全面上手指南

仓库地址：GoogleCloudPlatform/agent-starter-pack
官方文档（部署/可观测性/CI/CD）：Documentation
项目定位：在 Google Cloud 上构建、评估、部署、观测 GenAI Agent 的「生产级模板包」
一句话：你专注写 Agent 的业务逻辑，基础设施、CI/CD、可观测、安全都交给 Starter Pack。

---

为什么是 Agent Starter Pack？

如果你正在尝试把 GenAI Agent 从 Demo 推进到生产环境，现实会立刻让人“清醒”：

• 环境管理、依赖清单、权限配置要标准化；
• 数据检索、RAG 管线需要可运维可扩展；
• 部署目标（Cloud Run 或 Vertex AI Agent Engine）需要 CI/CD；
• 日志、Tracing、监控指标要能看、能做容量评估；
• 安全与合规、成本控制、评测与回归，都要考虑。

Agent Starter Pack 提供了一套「即插即用的生产就绪模板」，覆盖：

• 模板化的 Agent 代码（ReAct、RAG、多Agent、Live API 等）
• 评测（Vertex AI Evaluation）与交互式 Playground
• 部署到 Cloud Run 或 Agent Engine 的完整流水线
• 可观测性（Tracing、日志、指标）、基础设施 IaC（Terraform）
• 一键创建工程骨架，且支持与 Gemini CLI 集成

---

1 分钟快启：创建一个生产级 Agent 项目

官方推荐使用 uv（Astral 的 Python 包管理器/运行器）进行极速启动：

uvx agent-starter-pack create

若你喜欢 pip 也没问题（README 中给出了替代流程）：

• 创建虚拟环境，安装 agent-starter-pack 包
• 使用 CLI 初始化工程骨架（包含部署脚本、CI/CD、Terraform、目录结构等）

进一步体验：

• 一键在 Cloud Shell 中打开：Launch in Cloud Shell
• 在 Firebase Studio 模板里试跑（README 顶部按钮）

---

工程结构与“生产级”骨架

Starter Pack 使用 Cookiecutter 模板生成工程，并按你的选择（Cloud Run 或 Agent Engine、CI/CD Runner 等）生成不同的结构。来自基础模板的 README 展示了典型布局：

{{cookiecutter.project_name}}/
├── {{cookiecutter.agent_directory}}/                 # 核心 Agent 代码
│   ├── agent.py         # 主 Agent 逻辑
│   ├── fast_api_app.py  # FastAPI 后端（若部署到 Cloud Run）
│   ├── agent_engine_app.py # Agent Engine 应用逻辑（若选 Agent Engine）
│   └── app_utils/       # 工具与辅助模块
│       ├── executor/    # A2A 协议的执行器（选 LangGraph + A2A 时生成）
│       └── converters/  # A2A 消息转换器
├── .cloudbuild/ 或 .github/   # 选用 Cloud Build 或 GitHub Actions 时的 CI/CD 配置
├── deployment/          # Terraform 与部署脚本
├── notebooks/           # 用于原型验证与评测的 Notebook
├── tests/               # 单元、集成、负载测试
├── Makefile             # 常用命令集合（安装、编译、部署、评测）
├── GEMINI.md            # 与 Gemini CLI 集成的工程上下文配置
└── pyproject.toml       # 依赖与工程配置

简而言之：你拿到的是一个“能跑能部署可观测”的完整工程，不只是代码片段。

---

内置 Agent 模板：从最小可用到复杂场景

Starter Pack 提供多个可直接使用或扩展的 Agent 模板（位于 agent_starter_pack/agents/），你可以根据场景选择：

• ADK Minimal（adk_base）：用 Google Agent Development Kit (ADK) 构建的最简版 Agent，配两个示例工具：
  • get_weather（天气模拟）
  • get_current_time（当前时间模拟）
• ADK Live（adk_live）：基于 Gemini Live Audio 的实时会话 Agent，支持音视频与文本互动，前端为 React 控制台，后端可部署到 Cloud Run/Agent Engine
• Agentic RAG（agentic_rag）：生产级数据摄入管线，基于 Vertex AI Pipelines +（Vertex AI Search 或 Vector Search）构建检索增强（RAG）应用，支持定时/触发、嵌入生成与大规模数据处理
• ADK + A2A（adk_a2a_base）：支持 Agent2Agent (A2A) 协议的 ADK Agent，便于跨框架与语言的分布式 Agent 互操作
• LangGraph Base ReAct + A2A（langgraph_base）：基于 LangGraph 构建的 ReAct Agent，带 A2A 支持、流式响应与示例工具集成

所有模板都集成了 CI/CD、Terraform 部署、可观测性、测试与 Notebook 等生产要素，帮助你快速走完“Demo → 可部署 → 可观测 → 可迭代”的路径。

---

本地开发与快速验证

基础模板在 README 中给出最简本地验证命令：

make install && make playground

这通常会：

• 安装依赖（使用 uv 统一管理）
• 启动本地 Playground（取决于模板）
• 在本地测试核心 Agent 能力（例如工具调用、对话、RAG 查询等）

若你启用了 ADK（或 Live 模型），本地即可用简单问题测试，比如：

• “旧金山天气如何？”（触发 get_weather 工具）
• “现在几点了？”（触发 get_current_time 工具）
• “给我读一段文档并回答问题”（RAG 模板）

---

生产部署：Cloud Run 与 Agent Engine

官方推荐使用 CLI 一键部署：

• 在项目根目录运行 agent-starter-pack setup-cicd
  自动完成基础设施（Terraform）、CI/CD（Cloud Build/GitHub Actions）、服务账号与权限配置，之后你的工程将具备“推送即部署”的能力。

如果你希望手工操作：

• deployment/ 目录包含 Terraform 配置
• 官方 Deployment Guide：Agent Starter Pack Deployment Guide

选项说明：

• Cloud Run：容器化部署，HTTP 接口，灵活扩缩容，易与现有服务集成
• Agent Engine（Vertex AI）：面向 Agent 的托管引擎，适合更强的原生 Agent 能力与生态整合

---

可观测性与评估：不止“能跑”，还要“看得见”

• 可观测性：官方文档有详解（Tracing、日志、指标），部署后默认开启元数据日志（本地关闭），并集成 Cloud Trace、Cloud Logging、BigQuery 等（按环境与模板不同有所差异）
  文档链接：Observability Guide
• 评测与 Playground：内置 Vertex AI Evaluation 支持，帮助你用标准数据集评估 Agent，在高迭代频率下保证鲁棒性和一致性。

---

RAG 数据摄入管线：从数据到可检索的知识

Agentic RAG 模板在 agent_starter_pack/data_ingestion/ 中提供完整的管线：

• 支持 Vertex AI Search 或 Vertex AI Vector Search
• 自动化数据加载、切分（chunking）、向量嵌入（Vertex AI Embeddings）、索引导入
• 基于 Vertex AI Pipelines，可定时、可触发、可监控
• 通过 Terraform 部署基础设施、通过 CI/CD 自动化上线

快速操作示例

首先设置项目 ID：

export PROJECT_ID="YOUR_PROJECT_ID"

初始化开发环境（Terraform 配置与数据存储）：

make setup-dev-env

执行一次数据摄入（提交到 Vertex AI Pipelines）：

make data-ingestion

如果你选择了 Vertex AI Search，会自动带上像 --data-store-id、--data-store-region 这样的参数；如果是 Vector Search，则会传入 --vector-search-index、--vector-search-index-endpoint、--vector-search-data-bucket-name 等。同时还会带上通用参数如 --project-id、--region、--service-account、--pipeline-root、--pipeline-name。

要定时执行（生产环境常见），可以用 --schedule-only、--cron-schedule 等选项创建定时任务。

---

A2A 协议与跨框架互操作

模板（如 adk_a2a_base 或 langgraph_base）内置 A2A Inspector 工具用于校验你的 A2A 实现：

make inspector

支持两种传输：

• JSON-RPC 2.0（Cloud Run）：本地 http://localhost:8000 测试或连接已部署的 Cloud Run
• HTTP-JSON（Agent Engine）：需先部署再连接对应 URL

这让你的 Agent 能与其它框架/语言的 Agent 互通，是迈向“多 Agent 分布式协作”的关键一步。

---

Live API：语音/视频/文本的实时多模态

adk_live 模板通过 Gemini Live Audio 模型 + React 前端实现了一个“可即刻对话”的实时 Agent：

• 后端：Python + ADK + 原生工具调用
• 前端：React 控制台（音频/视频/文本）
• 部署目标：Cloud Run 或 Agent Engine

Demo 场景：

• 启动后点击播放按钮连接，问：“旧金山天气如何？”
• Agent 会进行流式互动并调用工具返回结果

---

与 Gemini CLI 的结合：AI 辅助开发

每个生成项目中包含 GEMINI.md，Starter Pack 已预配置工程上下文，方便你直接用 Gemini CLI 做“AI 辅助开发”：

• 根据项目结构与模板，自动为你提供更准确的开发辅助
• 逐步将“编写工具/Agent/配置/部署”变得更流畅

---

常见工作流：从创建到上线

1. uvx agent-starter-pack create 创建工程骨架
2. make install && make playground 本地验证
3. 选择模板（ADK/LangGraph/RAG/Live），填充你的业务逻辑（agent.py、工具函数等）
4. agent-starter-pack setup-cicd 一键配置 CI/CD 与 Terraform 基建
5. 推送代码 → 自动构建与部署到 Cloud Run/Agent Engine
6. 打开可观测面板，观察日志与追踪；配置 Vertex AI Evaluation 进行评测
7. RAG 场景：make setup-dev-env → make data-ingestion 初始化与摄入数据
8. 需要跨框架通信？使用 A2A 模板并运行 make inspector 校验协议实现

---

总结：让 GenAI Agent 真正“走进生产”的工具包

Agent Starter Pack 是一个非常务实的「落地工具」。相比常见示例代码，它直接涵盖了生产环境最重要的环节：

• 模板齐全、部署就绪、评测与监控闭环
• Cloud Run / Agent Engine 选型灵活
• Terraform + CI/CD 降低团队上线门槛
• 与 Google Cloud 生态深度集成（Vertex AI 等）
• 轻松打造从 RAG 到多模态实时对话的完整 Agent 系统

如果你正在寻找“把 Agent 变成生产服务”的路径，Agent Starter Pack 值得立刻试试。

现在就动手：

• 1 分钟创建项目：uvx agent-starter-pack create
• 文档与指南：googlecloudplatform.github.io/agent-starter-pack
• 浏览模板代码：agent_starter_pack/agents/

让你的 Agent 不再停留在 Demo，与团队一起做出“可上线、可监控、可迭代”的真实产品吧！🚀