Agent Starter Pack 模板配置参考：templateconfig.yaml 与 pyproject.toml 全字段指南-酒店常州论坛

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 templates）	`templateconfig.yaml`	位于每个内置 Agent 的`.template/`目录下，例如`agent_starter_pack/agents/adk/.template/templateconfig.yaml`
远程模板（Remote templates）	`pyproject.toml`的`[tool.agent-starter-pack.settings]`段	远程模板仓库根目录的`pyproject.toml`中声明，可被`list`命令发现

两种载体最终都会被加载为同一个配置字典（dict）供 CLI 消费，因此配置字段在两处完全通用。源码层面的证据在 agent_starter_pack/cli/utils/template.py：

load_template_config()读取内置模板目录下的TEMPLATE_CONFIG_FILE（即templateconfig.yaml）；
TemplateConfig.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_template`	string	仅远程模板必填	远程模板所继承的内置 Agent 名称，例如`adk`、`agentic_rag`
`name`	string	是	模板显示名称，会出现在`list`命令输出中
`description`	string	是	模板简介，同样展示在`list`命令中
`example_question`	string	否	示例问题或提示词，会写入生成项目的`README.md`
`settings`	object	否	嵌套对象，包含模板的详细功能配置（见下一节）

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: "What's the weather in San Francisco?"就是生成项目里展示的默认引导问题。

settings 对象：控制生成项目的功能开关

settings是一个嵌套对象，其中的字段控制生成项目的特性与行为，是模板配置的核心。完整字段如下：

字段	类型	说明
`deployment_targets`	list(string)	模板支持的部署目标列表，可选值：`agent_engine`、`cloud_run`、`gke`
`tags`	list(string)	分类标签；`adk`标签会启用与 Agent Development Kit 的特殊集成
`frontend_type`	string	指定要使用的前端，示例：`adk_live_react`、`inspector`，默认`None`（无前端）
`agent_directory`	string	Agent 代码存放目录名，默认`app`，可被 CLI 的`--agent-directory`参数覆盖
`requires_data_ingestion`	boolean	为`true`时，会提示用户配置数据存储（datastore）
`requires_session`	boolean	为`true`时，在`cloud_run`目标下会提示用户选择会话存储类型（如`cloud_sql`）
`interactive_command`	string	Agent 代码创建完成后用于启动 Agent 的`make`命令（如`make playground`、`make dev`），默认`playground`
`extra_dependencies`	list(string)	注意：远程模板会忽略此字段。它仅供 Starter Pack 内置模板内部使用；依赖的唯一事实来源是你的`pyproject.toml`
`language`	string	模板使用的语言（`python`/`go`/`java`/`typescript`），由 agent_starter_pack/cli/utils/template.py 中的`SUPPORTED_LANGUAGES`定义校验

下面逐个深入每个字段的实际消费逻辑与真实配置示例。

deployment_targets：声明支持的部署目标

deployment_targets声明模板可以部署到哪里，可选值包括：

agent_engine：Vertex AI 托管平台；
cloud_run：Serverless 容器平台；
gke：托管 Kubernetes（Autopilot）；
none：不部署到云端（本地原型模式）。

底层逻辑在get_deployment_targets()与prompt_deployment_target()（agent_starter_pack/cli/utils/template.py）：CLI 创建项目时从配置中读取该列表并渲染为选择菜单；如果用户传入的--deployment-target不在该列表中，process_template()会抛出错误。list命令也通过它来过滤支持指定部署目标的 Agent（见get_available_agents()）。

真实内置模板示例（agent_starter_pack/agents/langgraph/.template/templateconfig.yaml）：

settings: deployment_targets: ["agent_engine", "cloud_run", "gke", "none"]

tags：分类与框架级集成开关

tags是字符串列表，用于分类，更重要的是其中包含语义开关。process_template()会基于 tags 派生以下布尔值（agent_starter_pack/cli/utils/template.py）：

is_adk："adk" in tags—— 是否启用 Agent Development Kit 集成；
is_adk_live："adk_live" in tags—— 是否启用实时语音/视频能力；
is_a2a："a2a" in tags—— 是否启用 Agent2Agent（A2A）协议集成。

这些派生值随后驱动文件复制与条件文件逻辑（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.yaml：tags: ["adk"]
agent_starter_pack/agents/adk_live/.template/templateconfig.yaml：tags: ["adk", "adk_live"]
agent_starter_pack/agents/langgraph/.template/templateconfig.yaml：tags: ["langgraph", "a2a"]

frontend_type：为生成项目装配前端

frontend_type指定生成项目使用的前端，默认值为None（无前端）。支持类型（由copy_frontend_files()消费，agent_starter_pack/cli/utils/template.py）：

adk_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.py）；
Python 模块名校验：对于 Python 项目，目录名必须是合法 Python 标识符——不能包含连字符（-），只能使用小写字母、数字和下划线，且不能以数字开头（见validate_agent_directory_name()）。这是因为该目录名会作为 Python 模块名使用。

此外还有一个特殊值.，表示扁平结构（flat structure）：Agent 代码位于模板根目录，生成时目标目录名从模板文件夹名推导（连字符转下划线）。

真实示例：agent_starter_pack/agents/adk_go/.template/templateconfig.yaml 使用agent_directory: "agent"，agent_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_search（Vertex AI Search，托管无服务器文档存储）与vertex_ai_vector_search（Vertex 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-adk>=1.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.py）：

in_memory：无状态，数据在内存中；
cloud_sql：PostgreSQL 持久化；
agent_engine：托管会话服务。

会话选择还受语言与部署目标约束（agent_starter_pack/cli/commands/create.py）：

Go 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-adk>=1.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 Q&A agent with RAG pipeline" dependencies = [ "google-adk>=1.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 Q&A 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.lock；
Python 项目使用带连字符的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 会拒绝该组合并提示。

企业官网建设流程全解析