Agent Starter Pack 模板配置参考templateconfig.yaml 与 pyproject.toml 全字段指南【免费下载链接】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 的模板配置体系展开系统讲解内置模板使用的templateconfig.yaml与远程模板使用的pyproject.toml[tool.agent-starter-pack.settings]段中每一个顶层字段与settings子字段的作用、类型、默认值及底层消费逻辑。读完本文你将掌握如何阅读、修改和自定义模板配置从部署目标agent_engine/cloud_run/gke、前端类型adk_live_react/inspector、数据接入与会话存储开关到adk标签带来的框架级集成并能结合源码理解每个字段如何影响生成项目的结构与运行命令。模板配置的两种载体与统一字段模型Agent Starter Pack 的模板配置支持两种来源且两种来源的字段完全一致模板类型配置文件位置说明内置模板Built-in templatestemplateconfig.yaml位于每个内置 Agent 的.template/目录下例如agent_starter_pack/agents/adk/.template/templateconfig.yaml远程模板Remote templatespyproject.toml的[tool.agent-starter-pack.settings]段远程模板仓库根目录的pyproject.toml中声明可被list命令发现两种载体最终都会被加载为同一个配置字典dict供 CLI 消费因此配置字段在两处完全通用。源码层面的证据在 agent_starter_pack/cli/utils/template.pyload_template_config()读取内置模板目录下的TEMPLATE_CONFIG_FILE即templateconfig.yamlTemplateConfig.from_file()对配置做 YAML 解析与必填字段校验要求name、description、settings三个字段必须存在远程模板则由load_remote_template_config()位于 agent_starter_pack/cli/utils/remote_template.py读取pyproject.toml中tool.agent-starter-pack下的配置并支持按[tool.agent-starter-pack]→[project]→ 智能默认值的优先级回退。顶层字段详解顶层字段控制模板的元数据与基础行为完整清单如下字段类型必填说明base_templatestring仅远程模板必填远程模板所继承的内置 Agent 名称例如adk、agentic_ragnamestring是模板显示名称会出现在list命令输出中descriptionstring是模板简介同样展示在list命令中example_questionstring否示例问题或提示词会写入生成项目的README.mdsettingsobject否嵌套对象包含模板的详细功能配置见下一节base_template远程模板的继承基础base_template仅对远程模板有意义它声明远程模板以哪个内置 Agent 作为地基远程模板只覆盖其中与自身相关的文件。例如 docs/remote-templates/creating-remote-templates.md 中的示例[tool.agent-starter-pack] base_template adk处理远程模板时process_template()会通过get_base_template_name()解析该字段并定位到对应的内置 Agent 目录作为文件来源。该函数还支持向后兼容的旧名称别名见 agent_starter_pack/cli/utils/template.py例如adk_base→adk、langgraph_base→langgraph、custom/custom_a2a→langgraph。若未显式配置默认回退为adk。name 与 description模板的可发现性name与description直接影响模板在uvx agent-starter-pack list中的展示。远程模板的场景下如果[tool.agent-starter-pack]段没有显式给出这两个字段加载逻辑会自动回退到pyproject.toml的[project]段name、description再没有则使用仓库目录名与空描述——这一回退链在load_remote_template_config()中有明确实现。example_question注入生成项目的引导问题example_question是一个可选但很有价值的字段它会在项目生成后出现在 README 与 Makefile 的交互提示中作为用户快速体验 Agent 的引导问题。两个证据在process_template()中example_question被写入 cookiecutter 上下文agent_starter_pack/cli/utils/template.py在 agent_starter_pack/base_templates/python/Makefile 中make dev/make playground等命令的横幅会输出 Try asking: {{cookiecutter.example_question}}。以内置模板为例agent_starter_pack/agents/adk/.template/templateconfig.yaml 中的example_question: Whats the weather in San Francisco?就是生成项目里展示的默认引导问题。settings 对象控制生成项目的功能开关settings是一个嵌套对象其中的字段控制生成项目的特性与行为是模板配置的核心。完整字段如下字段类型说明deployment_targetslist(string)模板支持的部署目标列表可选值agent_engine、cloud_run、gketagslist(string)分类标签adk标签会启用与 Agent Development Kit 的特殊集成frontend_typestring指定要使用的前端示例adk_live_react、inspector默认None无前端agent_directorystringAgent 代码存放目录名默认app可被 CLI 的--agent-directory参数覆盖requires_data_ingestionboolean为true时会提示用户配置数据存储datastorerequires_sessionboolean为true时在cloud_run目标下会提示用户选择会话存储类型如cloud_sqlinteractive_commandstringAgent 代码创建完成后用于启动 Agent 的make命令如make playground、make dev默认playgroundextra_dependencieslist(string)注意远程模板会忽略此字段。它仅供 Starter Pack 内置模板内部使用依赖的唯一事实来源是你的pyproject.tomllanguagestring模板使用的语言python/go/java/typescript由 agent_starter_pack/cli/utils/template.py 中的SUPPORTED_LANGUAGES定义校验下面逐个深入每个字段的实际消费逻辑与真实配置示例。deployment_targets声明支持的部署目标deployment_targets声明模板可以部署到哪里可选值包括agent_engineVertex AI 托管平台cloud_runServerless 容器平台gke托管 KubernetesAutopilotnone不部署到云端本地原型模式。底层逻辑在get_deployment_targets()与prompt_deployment_target()agent_starter_pack/cli/utils/template.pyCLI 创建项目时从配置中读取该列表并渲染为选择菜单如果用户传入的--deployment-target不在该列表中process_template()会抛出错误。list命令也通过它来过滤支持指定部署目标的 Agent见get_available_agents()。真实内置模板示例agent_starter_pack/agents/langgraph/.template/templateconfig.yamlsettings: deployment_targets: [agent_engine, cloud_run, gke, none]tags分类与框架级集成开关tags是字符串列表用于分类更重要的是其中包含语义开关。process_template()会基于 tags 派生以下布尔值agent_starter_pack/cli/utils/template.pyis_adkadk in tags—— 是否启用 Agent Development Kit 集成is_adk_liveadk_live in tags—— 是否启用实时语音/视频能力is_a2aa2a in tags—— 是否启用 Agent2AgentA2A协议集成。这些派生值随后驱动文件复制与条件文件逻辑apply_conditional_files()中的CONDITIONAL_FILES映射agent_starter_pack/cli/utils/template.py例如is_a2a且 Agent 为langgraph时才会保留app_utils/executor与app_utils/converters目录is_adk_live时才会保留app_utils/gcs.py与app_utils/expose_app.py。同时get_available_agents()用 tags 判断框架归属含langgraph标签归为langgraph框架含adk标签归为adk框架。真实示例agent_starter_pack/agents/adk/.template/templateconfig.yamltags: [adk]agent_starter_pack/agents/adk_live/.template/templateconfig.yamltags: [adk, adk_live]agent_starter_pack/agents/langgraph/.template/templateconfig.yamltags: [langgraph, a2a]frontend_type为生成项目装配前端frontend_type指定生成项目使用的前端默认值为None无前端。支持类型由copy_frontend_files()消费agent_starter_pack/cli/utils/template.pyadk_live_react随项目打包 React 前端文件直接从agent_starter_pack/frontends/adk_live_react复制到项目根目录inspector运行时通过make inspector安装生成阶段不复制文件None/ 空值跳过前端文件。真实示例agent_starter_pack/agents/adk_live/.template/templateconfig.yaml 中frontend_type: adk_live_react而 agent_starter_pack/agents/langgraph/.template/templateconfig.yaml 中frontend_type: inspector。agent_directory定制 Agent 代码目录agent_directory控制 Agent 代码放置的目录名默认app。其取值会替换CONDITIONAL_FILES中的{agent_directory}占位符影响条件文件的路径判断。有两个值得注意的细节CLI 覆盖CLI 的--agent-directory参数cli_overrides优先级高于模板配置get_agent_directory()会先检查cli_overrides[settings][agent_directory]agent_starter_pack/cli/utils/template.pyPython 模块名校验对于 Python 项目目录名必须是合法 Python 标识符——不能包含连字符-只能使用小写字母、数字和下划线且不能以数字开头见validate_agent_directory_name()。这是因为该目录名会作为 Python 模块名使用。此外还有一个特殊值.表示扁平结构flat structureAgent 代码位于模板根目录生成时目标目录名从模板文件夹名推导连字符转下划线。真实示例agent_starter_pack/agents/adk_go/.template/templateconfig.yaml 使用agent_directory: agentagent_starter_pack/agents/adk_ts/.template/templateconfig.yaml 使用默认的agent_directory: app。requires_data_ingestion是否提示配置数据存储requires_data_ingestion: true表示模板包含数据接入管道创建项目时会提示用户配置数据存储datastore。该逻辑在prompt_datastore_selection()agent_starter_pack/cli/utils/template.py中若requires_data_ingestion为true直接展示数据存储选择菜单不再询问是否需要数据管道若配置中存在该键但为false则询问用户是否要包含数据管道可选数据存储类型由 agent_starter_pack/cli/utils/datastores.py 中的DATASTORES定义vertex_ai_searchVertex AI Search托管无服务器文档存储与vertex_ai_vector_searchVertex AI Vector Search基于 ScaNN 的向量检索。选定数据存储后CONDITIONAL_FILES会据此决定保留哪套 Terraform 与脚本vertex_ai_search保留vertex_ai_search*.tf与数据连接器脚本vertex_ai_vector_search保留vector_search*.tf与向量集合脚本agent_starter_pack/cli/utils/template.py。真实示例agent_starter_pack/agents/agentic_rag/.template/templateconfig.yaml 中requires_data_ingestion: true配以extra_dependencies: [google-adk1.15.0,2.0.0, google-cloud-vectorsearch]。requires_session是否提示选择会话存储requires_session: true表示模板在cloud_run部署目标下会提示用户选择会话存储类型。会话类型定义于prompt_session_type_selection()agent_starter_pack/cli/utils/template.pyin_memory无状态数据在内存中cloud_sqlPostgreSQL 持久化agent_engine托管会话服务。会话选择还受语言与部署目标约束agent_starter_pack/cli/commands/create.pyGo Agent 仅支持in_memory会话Python 的adk与agentic_rag模板在cloud_run/gke下支持会话类型选择--session-type不能与agent_engine部署目标同时使用Agent Engine 内部管理会话部署目标为none时强制in_memory。会话类型最终通过 cookiecutter 上下文中的session_type注入模板进而驱动 Terraform 条件逻辑例如deployment/terraform/dev/apis.tf中{%- if cookiecutter.is_adk and cookiecutter.session_type cloud_sql %}会追加 Cloud SQL 相关 API 启用。真实示例agent_starter_pack/agents/adk/.template/templateconfig.yaml 与 agent_starter_pack/agents/agentic_rag/.template/templateconfig.yaml 中均为requires_session: true。interactive_command定义创建后的启动命令interactive_command指定项目创建完成后提示用户运行的make命令默认值为playground。它被消费于 agent_starter_pack/cli/commands/create.py创建成功横幅中的make {interactive_command}直接取自config.get(settings, {}).get(interactive_command, playground)。例如某模板希望用户用make dev启动本地开发可配置settings: interactive_command: dev创建完成后 CLI 会提示cd project make install make dev。extra_dependencies内置模板专用字段远程模板忽略extra_dependencies是一个重要且容易误用的字段远程模板会忽略它。它仅用于 Starter Pack 内置模板内部作为基础模板依赖声明的补充对远程模板而言pyproject.toml才是依赖的唯一事实来源single source of truth。内置模板中的真实用法agent_starter_pack/agents/adk_live/.template/templateconfig.yaml 声明了google-adk1.16.0,2.0.0、click、uvicorn、fastapi、backoff等依赖。远程模板如需自定义依赖应直接在模板根目录的pyproject.toml中声明并提交uv.lock锁文件推荐生成时这些文件会原样复制到项目。从配置到项目字段如何驱动生成流程理解每个字段之后可以把它们放回完整的生成流程中。process_template()agent_starter_pack/cli/utils/template.py的装配顺序如下复制共享基础模板base_templates/_shared语言无关复制语言基础模板base_templates/language按settings.language选择复制部署目标文件deployment_targets/target/language按deployment_targets与用户选择处理前端文件按frontend_type复制 Agent 专属文件覆盖基础模板按base_template与agent_directory远程模板文件叠加覆盖优先级最高将settings、tags、派生布尔值等写入 cookiecutter.json驱动整个模板渲染渲染并合并 Makefile远程 Makefile 命令优先缺失的基础命令自动补全按datastore_type、cicd_runner、is_adk等执行条件文件逻辑apply_conditional_files()删除不匹配的文件。其中第 7 步是整个配置落地的关键cookiecutter_config中几乎包含了settings的全部派生值——is_adk、is_adk_live、is_a2a、requires_data_ingestion、language、deployment_target、cicd_runner、session_type、frontend_type、extra_dependencies、datastore_type、agent_directory等agent_starter_pack/cli/utils/template.py后续所有 Jinja2 条件渲染都基于这份上下文。完整配置示例一份麻雀虽小五脏俱全的模板综合以上字段一个功能完整的远程模板配置可以是[project] name my-rag-agent-template version 0.1.0 description Document QA agent with RAG pipeline dependencies [ google-adk1.15.0,2.0.0, google-cloud-vectorsearch, ] [tool.agent-starter-pack] # 继承内置的 agentic_rag 模板仅远程模板需要 base_template agentic_rag # 模板元数据可选缺省回退到 [project] 段 name My RAG Agent Template description A document QA template with vector search [tool.agent-starter-pack.settings] # 支持全部四种部署目标 deployment_targets [agent_engine, cloud_run, gke, none] # 分类与框架开关标签 tags [adk] # 无前端 frontend_type None # Agent 代码目录默认 app agent_directory app # 强制数据接入配置 requires_data_ingestion true # Cloud Run 下提示会话存储选择 requires_session true # 创建完成后提示运行 make playground interactive_command playground对应的内置模板等价写法YAML可参考 agent_starter_pack/agents/agentic_rag/.template/templateconfig.yaml。常见问题与排错建议结合源码行为配置时容易踩的坑集中在以下几点远程模板中设置了extra_dependencies却不生效这是预期行为。该字段被远程模板忽略请把依赖写进远程模板根目录的pyproject.toml并提交uv.lockPython 项目使用带连字符的agent_directory会直接报错因为目录名必须是合法 Python 标识符validate_agent_directory_name()模板在list中不出现list命令只展示含显式[tool.agent-starter-pack]配置的远程模板见 agent_starter_pack/cli/commands/list.py请确认配置段书写正确部署目标不匹配process_template()会校验deployment_target必须出现在settings.deployment_targets中否则抛出包含可用目标列表的错误--session-type与agent_engine冲突Agent Engine 内部管理会话CLI 会拒绝该组合并提示。延伸阅读docs/guide/template-config-reference.md本文所依据的原始配置参考文档docs/remote-templates/creating-remote-templates.md远程模板的完整创建、发布与版本锁定指南agent_starter_pack/cli/utils/template.py配置加载、校验与条件文件逻辑的核心实现agent_starter_pack/cli/utils/remote_template.py远程模板配置解析与 Makefile 合并实现docs/guide/deployment.md部署目标与基础设施定制说明内置模板配置实例agent_starter_pack/agents/adk/.template/templateconfig.yaml、agent_starter_pack/agents/adk_live/.template/templateconfig.yaml、agent_starter_pack/agents/agentic_rag/.template/templateconfig.yaml、agent_starter_pack/agents/langgraph/.template/templateconfig.yaml。【免费下载链接】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），仅供参考