Agent Starter Pack 快速上手：从零到生产级 AI Agent 项目的完整指南

Agent Starter Pack 快速上手：从零到生产级 AI Agent 项目的完整指南

【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack

本篇技术指南以agent-starter-pack的 Getting Started 文档为主体，完整讲解如何在几分钟内用 CLI 脚手架出一个可直接部署到 Google Cloud 的生产级 AI Agent 项目（含后端、可选前端与 Terraform 基础设施）。读完本文，你将掌握create/enhance/upgrade/extract等核心命令的用法、全部命令行参数语义、生成项目结构的解读，以及make驱动下从本地调试到云上部署的完整工作流，并能据此在 docs/guide/getting-started.md 之外直接上手操作。

快速开始前的前置条件

在运行脚手架命令之前，请确认本机环境满足以下要求（不同语言模板对应不同运行时的最低版本）：

其中uv是官方推荐的方式：CLI 本身通过uvx免安装运行，生成的 Python 项目也用uv sync管理依赖。若选择pip方式，则需自建虚拟环境（Windows 下激活命令为.venv\Scripts\activate，类 Unix 系统为source .venv/bin/activate）。

想要零环境配置体验？官方还提供了 Firebase Studio 与 Cloud Shell 的一键打开方式，可在云端浏览器编辑器里直接运行。

第一步：创建你的 Agent 项目

方式一：uvx一条命令（推荐）

无需预先安装 CLI 包，uvx会自动拉取并执行最新版本：

# 单条命令，无需安装 uvx agent-starter-pack create

方式二：pip安装后运行

# 创建并激活虚拟环境 # Windows 使用: .venv\Scripts\activate python -m venv .venv && source .venv/bin/activate # 安装并运行 pip install agent-starter-pack agent-starter-pack create

无论使用哪种方式，create命令都会引导你完成三件事：

• 选择一个Agent 模板（例如adk、adk_go、adk_ts、agentic_rag、langgraph、adk_live、adk_a2a、adk_java）；
• 选择一个部署目标（例如cloud_run、gke、agent_engine，或原型模式下的none）；
• 生成一套完整的项目结构（后端、可选前端、部署基础设施）。

常用创建示例

# Python agent + Agent Engine agent-starter-pack create my-adk-agent -a adk -d agent_engine # Go agent + Cloud Run agent-starter-pack create my-go-agent -a adk_go -d cloud_run # TypeScript agent + Cloud Run agent-starter-pack create my-ts-agent -a adk_ts -d cloud_run

create命令在交互模式下会显示按语言分组的模板菜单（🐍 Python / 🌐 Other Languages），并支持数字选择；也可以直接输入模板名或编号。源码中该命令定义于 agent_starter_pack/cli/commands/create.py，并通过 agent_starter_pack/cli/main.py 注册进 CLI 组。

create全量命令行参数详解

除了-a/--agent与-d/--deployment-target，create还支持一批由shared_template_options装饰器注入的共享参数（见 agent_starter_pack/cli/commands/create.py），与enhance命令共用：

源码层面的关键实现细节值得留意：

• 项目名校验与归一化：create.py中的normalize_project_name()会把包含大写字母或下划线的项目名自动转为小写、下划线替换为连字符，以保证与云资源命名兼容；项目名超过 26 个字符会直接报错，避免触碰 GCP 资源命名上限。
• --adk快捷模式：设置该标志后，--agent与--deployment-target会被强制覆盖为adk与agent_engine，并自动进入prototype+auto_approve，是最快的零交互体验路径。
• 条件文件机制：模板目录下的CONDITIONAL_FILES映射（见 agent_starter_pack/cli/utils/template.py）会根据cicd_runner、datastore_type、is_a2a、is_adk_live等配置决定保留还是重命名特定文件（如.cloudbuild/、wif.tf、vector_search.tf），从而生成最精简、不包含死代码的项目。
• 模板引擎：项目通过 CookieCutter 处理 Jinja2 模板，所有模板配置（模板名、描述、deployment_targets、language、requires_data_ingestion、requires_session等）都声明在各模板目录的.template/templateconfig.yaml中，get_available_agents()会动态扫描agent_starter_pack/agents/目录加载它们。

第二步：探索项目并在本地运行

创建完成后，进入新项目目录并执行安装与启动命令：

cd <your-project> && make install && make playground

各make目标由模板生成的 Makefile 提供（模板源见 agent_starter_pack/base_templates/python/Makefile）：

• make install：通过uv sync安装全部依赖（adk_live等带前端模板还会执行npm install）；
• make playground：启动本地交互式 Playground（ADK 模板使用uv run adk web . --port 8501 --reload_agents打开带热重载的 Web 界面；Cloud Run/GKE 目标则通常起uvicorn于localhost:8000）。

生成项目的目录结构解读

⚠️ 生成项目内的README.md是每个具体项目的"说明书"，包含针对该模板与部署目标定制的运行、测试与部署步骤，务必优先按它的指引操作。

第三步：后续路径与完整开发流程

create生成的项目只是起点。接下来的开发、数据接入、部署与观测可沿以下文档继续：

• 开发指南：从原型到生产的完整工作流；
• 数据接入指南：为 Agent 增加 RAG 能力（Vertex AI Search / Vector Search）；
• 部署指南：部署到 Google Cloud（Agent Engine / Cloud Run / GKE）；
• 可观测性指南：监控你的 Agent；
• Agent 模板总览：浏览全部内置模板。

命令速查表

项目搭建（Project Setup）

enhance的实现非常讲究：它会读取项目内保存的生成元数据（Python 项目存于pyproject.toml的[tool.agent-starter-pack]，Go/Java/TypeScript 各有对应配置文件，见 agent_starter_pack/cli/commands/enhance.py），再用"旧模板 vs 新模板 vs 当前项目"三方比对做智能合并：你手工改过的文件保留、未改的文件更新、依赖差异自动合并，冲突时逐文件询问；--dry-run可先预览变更，--force则跳过比对直接覆盖。

开发工作流（Development Workflow）

此外，ADK 模板还附带评估目标：make eval使用 ADK 的adk eval命令配合tests/eval/evalsets/basic.evalset.json与tests/eval/eval_config.json运行评估，make eval-all则遍历执行所有 evalset。

部署（Deployment）

维护与分享（Maintenance & Sharing）

常见问题与使用建议

• 交互被凭据检查卡住：create在交互模式下会验证 gcloud 登录账号与 Vertex AI 启用状态，并可现场选择Y/skip/edit切换账号；不想被询问可加-y（自动确认）或-s（跳过校验）。
• 原型项目如何转生产：create -p或--adk生成的项目不含 CI/CD 与 Terraform。CLI 会在结束时提示：uvx agent-starter-pack enhance，一键补齐部署能力。
• 本地起服务但报凭据错误：确认已执行gcloud auth application-default login，且当前项目启用了所需的 Vertex AI 相关 API；也可用-k切换到 Google AI Studio API Key 模式（无值时生成带占位符的.env）。
• 项目名被自动改写：My_Agent会提示并改写为my-agent，这是为了兼容 GCP 资源命名规则，属预期行为。

以 agent_starter_pack/cli/main.py 为入口，create、enhance、extract、list、setup-cicd、register-gemini-enterprise、upgrade七个命令构成了完整的"脚手架 → 开发 → 评估 → 部署 → 观测"闭环。按本文流程走一遍uvx agent-starter-pack create，几分钟内即可获得一个带测试、评估、CI/CD 与 Terraform 的 Agent 工程，把精力留给 Agent 逻辑本身。

【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack