agent-starter-pack enhance 命令实战指南不新建目录将现有项目原地升级为生产级 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-packenhance是 agent-starter-pack CLI 中与create对应的原地升级命令它不需要新建目录而是把 agent-starter-pack 的部署、CI/CD、数据管道等能力直接注入你已有的项目让原型 Agent 就地演进为生产级应用。阅读本文后你将掌握enhance的完整参数体系、基础模板继承机制、版本锁定与保存配置复用、Smart-Merge 智能合并原理以及从原型到生产的标准操作流程。本文以 enhance 命令文档 为主线结合仓库内 enhance.py 及其工具模块源码展开深入讲解所有命令与行为均以当前仓库实现为准。enhance 是什么原地增强而非重新生成与 create 在指定目录下从零生成一个新项目不同enhance的设计目标是为已有项目原地追加 agent-starter-pack 能力。其核心使用场景包括用create --prototype创建的极简原型现在需要补上 CI/CD 与 Terraform 基础设施已有自己的 Agent 代码app/agent.py或root_agent.yaml希望接入云部署、数据管道、评估测试等能力希望从基础 Agent 模板升级到更高级的模板或切换基础模板继承关系。从源码看enhance的命令入口enhance.py本质上是对create命令的包装它始终以--in-folder模式调用create把模板文件直接落到当前目录并额外承担了项目结构校验、保存配置检测、版本锁定和智能合并等增强逻辑。命令用法与参数体系基本用法uvx agent-starter-pack enhance [TEMPLATE_PATH] [OPTIONS]TEMPLATE_PATH是可选参数源码中click.argument(..., default.)默认当前目录共有四种取值方式取值含义示例.默认以当前目录为模板源uvx agent-starter-pack enhance本地目录路径以其他本地目录为模板源uvx agent-starter-pack enhance ./my-agentAgent 名称使用内置 Agent 模板uvx agent-starter-pack enhance adk远程模板使用远程模板简写uvx agent-starter-pack enhance adkgemini-fullstack在源码实现中这四种取值会被归一化为create的--agent参数当前目录映射为local.本地目录映射为local/绝对路径其余按 Agent 名称或远程模板原样传递见 enhance.py。共享选项与 create 完全一致enhance通过shared_template_options装饰器create.py继承create的全部选项下表整理自 create 文档选项简写说明--name-n项目名默认取当前目录名--deployment-target-d部署目标agent_engine、cloud_run、gke--cicd-runner—CI/CDgoogle_cloud_build、github_actions、skip--prototype-p极简模式无 CI/CD、无 Terraform--datastore-ds数据存储vertex_ai_search、vertex_ai_vector_search、cloud_sql指定后自动启用数据摄入--session-type—会话存储in_memory、cloud_sql、agent_engine--region—GCP 区域默认us-east1--google-api-key--api-key/-k使用 Google AI Studio API Key不带值时生成.env占位文件--auto-approve--yes/-y跳过所有确认提示使用默认值--skip-checks—跳过 GCP 认证与 Vertex AI 连接校验--debug—开启调试日志需要注意的一个行为差异当使用--auto-approve但未指定--cicd-runner时enhance会打印警告并将 CI/CD 默认设为skip见 enhance.py。因此在 CI/CD 场景中建议显式传入--cicd-runner。enhance 专属选项除共享选项外enhance还提供若干专属能力选项说明--base-template覆盖基础模板继承见下节--agent-directory/-dir指定 Agent 代码目录默认app--adk--base-template adk的快捷方式与--base-template互斥--force跳过 Smart-Merge 三方比较强制覆盖全部文件--dry-run预览变更而不实际应用需要项目已保存 ASP 元数据--prefer-new冲突时优先采用新模板版本源码对互斥与前置条件做了显式校验--adk与--base-template同时使用会抛出Cannot use --adk with --base-template异常--dry-run与--force不兼容--dry-run在没有保存元数据pyproject.toml缺少[tool.agent-starter-pack]且没有指定变更参数时报错退出见 enhance.py。--base-template基础模板继承与切换--base-template用于覆盖你的项目所继承的基础模板。文档明确列出三种可选基础模板adk— 基础 Agent 模板默认基于 Google ADKlanggraph— 基于 LangGraph 的 ReAct Agentagentic_rag— 支持 RAG检索增强生成的 Agent 模板。从仓库结构看内置 Agent 目录 agent_starter_pack/agents/ 还包含adk_a2a、adk_live、adk_ts、adk_go、adk_java等变体交互式选择列表display_base_template_selection见 enhance.py会读取整个内置 Agent 目录作为候选集并在当前继承的基础模板旁标注(current)。基础模板的继承层级如下Your Existing Project ↓ (inherits from) Base Template (adk, langgraph, etc.) ↓ (provides) Core Infrastructure Capabilities当TEMPLATE_PATH是本地目录local.或local/path时enhance会通过load_remote_template_config读取项目配置并用get_base_template_name展示当前继承的基础模板未指定--base-template且非--auto-approve时弹出交互式选择列表默认选中当前模板使用--base-template时以 CLI 参数为准覆盖pyproject.toml中记录的基础模板。注意不同的基础模板要求 Agent 文件中暴露的变量名不同。源码 language.py 中的LANGUAGE_CONFIGS表明Python 要求root_agent、Go 要求RootAgent、Java 要求ROOT_AGENT、TypeScript 要求rootAgentADK 类模板检查root_agentLangGraph 类模板检查agent。--agent-directoryAgent 目录的识别与自动检测--agent-directory简写-dir决定 Agent 代码文件在项目中的位置默认是app。它遵循CLI 参数 配置检测 语言默认值的优先级见 enhance.py语言默认值Go 项目默认agentJava 项目默认src/main/java其余默认app配置检测读取已保存的 ASP 配置中的agent_directory字段Python 项目自动检测解析pyproject.toml中[tool.hatch.build.targets.wheel.packages]配置取第一个非frontend的包名作为 Agent 目录。这一点与文档描述一致对应的测试用例位于 test_enhance.py。例如uvx agent-starter-pack enhance . --agent-directory chatbot当未通过 CLI 指定且未开启--auto-approve时enhance会调用display_agent_directory_selection展示当前目录下的候选子目录自动排除.git、node_modules、.venv、build、dist等见 enhance.py并对每个目录标注检测提示如(has root_agent.yaml)、(has Agent.java)、(has agent.go)、(has agent.ts)、(has agent.py)实现见 language.py。也可以选择输入自定义目录名该名称会经过validate_agent_directory_name校验。YAML 配置 Agent 与 agent.py shimfind_agent_filelanguage.py会优先在 Agent 目录中查找root_agent.yaml。若存在 YAML 配置 Agent命令行会提示 Found ... (YAML config agent)自动生成一个agent.pyshim通过config_agent_utils与from_config(str(_AGENT_DIR / root_agent.yaml))加载 YAML 配置并定义root_agent与app App(...)app名称与 Agent 目录名一致以保证部署兼容性原始root_agent.yaml内容保持不变。对应的行为验证见 test_enhance.py 中的TestEnhanceYamlAgentShim测试类。项目结构校验三种典型输出enhance在应用模板前会对项目结构做校验并给出指引文档给出了三种典型情况。✅ 理想结构Agent 代码放在独立目录Python 场景默认app/your-project/ ├── app/ │ └── agent.py # Python agent with root_agent │ └── root_agent.yaml # OR YAML config agent (auto-detected) ├── tests/ └── README.md若 Agent 文件存在enhance会通过validate_agent_file校验其中是否定义了部署所必需的变量如root_agent缺失时给出警告示例root_agent YourAgentClass()并要求确认是否继续。⚠️ 缺少 Agent 目录当目录不存在时命令行打印 PROJECT STRUCTURE WARNING 块说明期望结构并提示两种解决方式——创建/agent-directory目录迁移 Agent 代码或使用--agent-directory指定现有目录。非--auto-approve模式下会二次确认是否继续见 enhance.py。 自定义 Agent 目录uvx agent-starter-pack enhance . --agent-directory my_agent实战示例全集基础增强# 使用默认模板增强当前项目 uvx agent-starter-pack enhance # 使用指定的 Agent 模板增强 uvx agent-starter-pack enhance adkgemini-fullstack # 自定义项目名增强 uvx agent-starter-pack enhance --name my-enhanced-agent高级选项# 自定义 Agent 目录 uvx agent-starter-pack enhance . --agent-directory chatbot # 指定部署目标 uvx agent-starter-pack enhance adkdata-science --deployment-target cloud_run # 添加数据摄入能力datastore 自动启用数据管道 uvx agent-starter-pack enhance --datastore cloud_sql # 自定义会话存储 uvx agent-starter-pack enhance --session-type cloud_sql基础模板继承切换# 为当前项目引入 LangGraph 能力 uvx agent-starter-pack enhance . --base-template langgraph # 切换为 RAG 基础模板 uvx agent-starter-pack enhance . --base-template agentic_rag典型应用场景原型到生产create --prototype创建的项目不含 CI/CD 与 Terraform之后用 enhance 补齐# 为原型补充 Google Cloud Build CI/CD uvx agent-starter-pack enhance --cicd-runner google_cloud_build # 或应用一个生产级模板 uvx agent-starter-pack enhance adkproduction-ready添加基础设施为已有 Agent 补充 Cloud Run 部署能力Terraform、Dockerfile、FastAPI 入口等uvx agent-starter-pack enhance --deployment-target cloud_run添加数据管道数据摄入文件的生成与--datastore强关联。从模板配置 template.py 中的CONDITIONAL_FILES可以看到data_ingestion/目录仅在vertex_ai_vector_search时生成vertex_ai_search与vertex_ai_vector_search各自对应不同的 Terraform 与脚本文件组对照仓库 agentic_rag/data_ingestion 的结构。升级 Agent 底座uvx agent-starter-pack enhance adkgemini-fullstack # 或直接切换基础模板 uvx agent-starter-pack enhance . --base-template langgraph此外还有一个值得注意的实现细节当部署目标为agent_engine时enhance会自动剥离--session-type参数因为 Agent Engine 内部管理会话见 enhance.py--datastore同样会通过cli_override_args透传给合并逻辑用于重新生成模板并比较差异。工作原理本质是 create --in-folder 的别名enhance的核心逻辑是对create命令的包装。文档明确说明其等价命令为uvx agent-starter-pack create PROJECT_NAME --agent TEMPLATE --in-folder源码 enhance.py 中的ctx.invoke(create, ...)调用证实了这一点其中项目名默认取当前目录名除非指定--name见 enhance.pyin_folderTrue被硬编码为始终开启skip_welcomeTrue避免欢迎横幅重复输出Agent 目录、基础模板等通过cli_overrides传入create。在调用create之前enhance还会做一轮前置检查若有保存配置且存在 CLI 覆盖参数或用户选择交互式定制则优先走 Smart-Merge 路径见下文Smart-Merge 失败时降级为标准覆盖模式。版本锁定与保存配置复用当增强一个由 agent-starter-pack 创建的项目时enhance会自动使用生成该项目时的 CLI 版本确保行为一致从配置文件中读取asp_versionPython 为pyproject.toml的[tool.agent-starter-pack]段若与当前 CLI 版本不同则通过uvx agent-starter-pack{version}以锁定版本重新执行复用保存的create_params保证配置完全一致。版本判定逻辑位于_should_use_different_versionenhance.py当环境变量ASP_SKIP_VERSION_LOCK未设为1、项目版本非空、当前版本非0.0.0且两者不同时触发锁定。锁定版本的子进程执行会检查uvx是否可用并在失败时回退到当前版本并提示兼容性不保证。# 跳过版本锁定使用当前 CLI 版本 ASP_SKIP_VERSION_LOCK1 uvx agent-starter-pack enhance ...需要说明的是asp_version与create_params并不只存在于 Python 项目get_project_asp_configenhance.py会根据语言读取不同配置文件并做结构归一化——Go/TypeScript 读取.asp.toml的[project]段Java 读取pom.xml中asp.*前缀的 Maven 属性。运行enhance时若检测到保存配置命令行会先打印 Detected saved configuration from previous setup 列出base_template、agent_directory、asp_version及各create_params见_display_saved_config。非--auto-approve模式下会进入交互式定制流程_prompt_customize_overrides每个参数都以上次保存值为默认值直接回车即保持现状--auto-approve模式下则直接复用保存配置通过子进程执行参数构建见build_args_from_config会自动附加--skip-deps --skip-welcome。Smart-Merge三方比较保护你的代码当项目存在保存元数据且未使用--force时enhance默认走 Smart-Merge_run_smart_mergeenhance.py。其流程为在临时目录中分别生成旧模板用保存的原始参数与新模板合并增强参数后的参数对当前项目、旧模板、新模板三份文件做三方比较three_way_compare见 upgrade.py按结果分组展示并应用变更。文件按 FILE_CATEGORIES 分为四类处理策略截然不同类别策略覆盖范围agent_code永不修改app/agent.py、app/tools/**、agent.go、**/*.java、agent.ts等config_files永不覆盖deployment/vars/*.tfvars、.envdependencies特殊合并pyproject.toml、go.mod、go.sum、.asp.toml、pom.xml、package.json等其他脚手架三方比较按哈希决定 auto-update / preserve / conflict / new / removed三方比较的判定规则three_way_compare非常直观当前文件与旧模板一致 → 自动更新为新模板你没改过旧模板与新模板一致 → 保留你的版本ASP 没变三者均不同 → 冲突。Agent 代码和配置文件永远不会被工具覆盖这是对用户代码最重要的保护。Python 项目的依赖会单独合并merge_pyproject_dependencies以新模板依赖为基础保留你额外添加的依赖用户新增 当前 − 旧模板并区分 updated / added / kept / removed 四种变更最终通过uv add --frozen/uv remove --frozen只改写pyproject.toml而不触碰锁文件。出现冲突时两者都改过的文件交互式提示提供六个选择(v)iew diff, (k)eep yours, (K)eep all, (u)se new, (U)se all, (s)kipv会以内建 difflib 渲染 unified diff超过 2000 字符截断显示。--auto-approve下默认保留你的版本--prefer-new则反转这一默认。合并完成后update_asp_metadata会把deployment_target、base_template等新参数写回配置文件并在部署目标非cloud_run时清理已失效的session_type键。自动备份修改前的安全网enhance在应用任何模板变更前会自动创建项目完整备份位置~/.agent-starter-pack/backups/[dirname]_[timestamp]源码常量 backup.py内容项目目录的完整副本排除.git、.venv、node_modules、__pycache__、dist、build、.terraform等完整排除清单见 backup.py时机在任何模板文件应用之前执行Smart-Merge 路径中位于apply_changes之前见 enhance.py。若备份创建失败非--auto-approve模式会询问 Continue without backup?选择取消则抛出click.Abort终止流程。--dry-run模式下不会创建备份。最佳实践检查备份增强前确认~/.agent-starter-pack/backups/下已生成最新备份遵循目录结构将 Agent 代码组织在/app/agent.py或通过--agent-directory指定自定义目录以获得最佳兼容性先在本地交互测试CI/CD 中使用-y自动批准但首次建议交互式运行确认 Smart-Merge 的文件分组与冲突结果审查变更增强后检查生成的文件与配置尤其是pyproject.toml依赖与deployment/下的 Terraform 文件。故障排查Project structure warning项目结构警告将 Agent 代码整理到/app目录或用--agent-directory指定实际目录用-y跳过确认提示。Enhancement cancelled增强被取消创建/app目录并放入agent.py定义root_agent重新运行命令。Dependency conflicts依赖冲突检查并解决pyproject.toml中的依赖冲突建议使用虚拟环境uv / venv隔离项目依赖。若需进一步了解与enhance配合使用的命令可阅读 create 命令文档共享选项的完整定义与 list 命令文档查看可用模板与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考