> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# agentkit.yaml

AgentKit CLI 当前使用两类 `agentkit.yaml`：

* 根目录 `agentkit.yaml`：由 `agentkit init` 或 `agentkit config --init` 创建，供 `build`、`deploy`、`launch`、`status` 与 `destroy` 读取，用于生命周期式构建与部署。
* `.agentkit/agentkit.yaml`：由 `agentkit release config` 创建，供 `release`、`release build` 与 `release apply` 读取，用于包含消息渠道和前端 BFF 的完整云端发布流程。

本页先说明根目录生命周期配置，再说明 `.agentkit/agentkit.yaml` 发布配置。两类配置不要混用：生命周期命令默认读取根目录 `agentkit.yaml`，`release` 默认读取 `.agentkit/agentkit.yaml`。

## 生命周期配置

根目录 `agentkit.yaml` 描述智能体应用如何构建、部署和查询状态。`common.launch_type` 决定当前使用的策略：`local` 表示本地 Docker 构建和本地容器部署，`cloud` 表示云端构建和云端运行时部署，`hybrid` 表示本地构建后部署到云端运行时。

```yaml title="agentkit.yaml" lines theme={null}
common:
  agent_name: my-agent
  entry_point: agent.py
  description: AgentKit project my-agent
  language: Python
  language_version: "3.12"
  agent_type: Basic App
  dependencies_file: requirements.txt
  runtime_envs:
    MODEL_AGENT_API_KEY: ${MODEL_AGENT_API_KEY}
  launch_type: cloud
  cloud_provider: volcengine

launch_types:
  cloud:
    region: cn-beijing
    tos_bucket: agentkit-platform-{{account_id}}
    tos_prefix: agentkit-builds
    image_tag: "{{timestamp}}"
    cr_instance_name: agentkit-platform-{{account_id}}
    cr_namespace_name: agentkit
    cr_repo_name: my-agent
    cr_auto_create_instance_type: Micro
    build_timeout: 3600
    cp_workspace_name: agentkit-cli-workspace
    cp_pipeline_name: Auto
    project_name: default
    runtime_id: Auto
    runtime_name: Auto
    runtime_role_name: Auto
    runtime_auth_type: key_auth
    runtime_apikey_name: Auto
    runtime_apikey: Auto
    runtime_jwt_allowed_clients: []
    runtime_envs: {}
    runtime_bindings: {}
    runtime_network: {}

docker_build:
  base_image:
  build_script:
```

### 通用字段

| 字段 | 说明 | 默认值 |
| - | - | - |
| `common.agent_name` | 智能体应用名称，只能包含字母、数字、下划线和连字符。 | — |
| `common.entry_point` | 应用入口文件，例如 `agent.py`、`main.go` 或 `build.sh`。 | `agent.py` |
| `common.description` | 应用描述。 | — |
| `common.language` | 应用语言，当前配置向导支持 `Python` 与 `Golang`。 | `Python` |
| `common.language_version` | 语言版本；Python 默认 `3.12`，Go 默认 `1.24`。 | 按语言决定 |
| `common.agent_type` | 应用类型说明。 | `Basic App` |
| `common.dependencies_file` | 依赖文件；Python 默认 `requirements.txt`，Go 默认 `go.mod`。 | 按语言决定 |
| `common.runtime_envs` | 所有发布模式共享的运行时环境变量。 | `{}` |
| `common.launch_type` | 发布模式：`local`、`cloud` 或 `hybrid`。 | `cloud` |
| `common.cloud_provider` | 云厂商：`volcengine` 或 `byteplus`。 | 当前云环境 |

### 本地策略

| 字段 | 说明 | 默认值 |
| - | - | - |
| `launch_types.local.image_tag` | 本地镜像标签。 | `latest` |
| `launch_types.local.invoke_port` | 应用调用端口。 | `8000` |
| `launch_types.local.container_name` | 本地容器名；为空时按应用名生成。 | — |
| `launch_types.local.ports` | Docker 端口映射列表。 | `["8000:8000"]` |
| `launch_types.local.volumes` | Docker volume 挂载列表。 | `[]` |
| `launch_types.local.restart_policy` | Docker 重启策略。 | `unless-stopped` |
| `launch_types.local.memory_limit` | 本地容器内存限制。 | `1g` |
| `launch_types.local.cpu_limit` | 本地容器 CPU 限制。 | `1` |
| `launch_types.local.runtime_envs` | 本地策略专属运行时环境变量。 | `{}` |

### 云端与混合策略

`cloud` 与 `hybrid` 共用多数运行时、鉴权、网络和镜像仓库字段。`cloud` 还包含 TOS 与 Code Pipeline 字段；`hybrid` 使用本地构建结果，不包含这些云端构建字段。

| 字段 | 说明 | 默认值 |
| - | - | - |
| `region` | AgentKit Runtime 区域。 | 云厂商默认区域 |
| `region_overrides` | 针对 `agentkit`、`cr`、`cp`、`tos` 等服务覆盖区域。 | `{}` |
| `tos_bucket` | `cloud` 模式的构建产物 TOS bucket。 | `agentkit-platform-{{account_id}}` |
| `tos_prefix` | `cloud` 模式的构建产物前缀。 | `agentkit-builds` |
| `image_tag` | 镜像标签，支持 `{{timestamp}}`。 | `{{timestamp}}` |
| `cr_instance_name` | Container Registry 实例名。 | `agentkit-platform-{{account_id}}` |
| `cr_namespace_name` | Container Registry 命名空间。 | `agentkit` |
| `cr_repo_name` | Container Registry 仓库名。 | 智能体应用名称 |
| `cr_auto_create_instance_type` | 自动创建 CR 实例时的规格。 | `Micro` |
| `build_timeout` | `cloud` 模式云端构建超时时间，单位秒。 | `3600` |
| `cp_workspace_name` | `cloud` 模式 Code Pipeline 工作区名称。 | `agentkit-cli-workspace` |
| `cp_pipeline_name` | `cloud` 模式 Code Pipeline 流水线名称。 | `Auto` |
| `cp_pipeline_id` | 已创建的 Code Pipeline 流水线 ID。 | — |
| `project_name` | AgentKit 项目名称。 | `default` |
| `runtime_id` | 已部署运行时 ID；`Auto` 表示自动创建或解析。 | `Auto` |
| `runtime_name` | 运行时名称；`Auto` 表示按应用名生成。 | `Auto` |
| `runtime_role_name` | 运行时 IAM 角色名称。 | `Auto` |
| `runtime_auth_type` | 运行时网关鉴权类型：`key_auth` 或 `custom_jwt`。 | `key_auth` |
| `runtime_apikey_name` | `key_auth` 使用的 API Key 名称。 | `Auto` |
| `runtime_apikey` | 部署后记录的 API Key 值。 | `Auto` |
| `runtime_jwt_discovery_url` | `custom_jwt` 使用的 OIDC discovery URL。 | — |
| `runtime_jwt_allowed_clients` | `custom_jwt` 允许的客户端 ID 列表。 | `[]` |
| `runtime_endpoint` | 部署后记录的运行时端点。 | — |
| `runtime_envs` | 当前策略专属运行时环境变量，会与 `common.runtime_envs` 合并。 | `{}` |
| `runtime_bindings.knowledge_id` | 绑定的知识库 ID。 | — |
| `runtime_bindings.memory_id` | 绑定的记忆库 ID。 | — |
| `runtime_bindings.tool_id` | 绑定的工具 ID。 | — |
| `runtime_bindings.mcp_toolset_id` | 绑定的 MCP 工具集 ID。 | — |
| `runtime_network.mode` | 网络模式；设置为 `private` 时启用私有网络。 | 平台默认 |
| `runtime_network.vpc_id` | 私有网络使用的 VPC ID。 | — |
| `runtime_network.subnet_ids` | 私有网络使用的子网 ID 列表。 | `[]` |
| `runtime_network.security_group_ids` | 私有网络使用的安全组 ID 列表。 | `[]` |
| `runtime_network.enable_shared_internet_access` | 私有网络下是否启用共享公网出口。 | 平台默认 |

### 构建字段

| 字段 | 说明 | 默认值 |
| - | - | - |
| `docker_build.base_image` | 生成 Dockerfile 时使用的基础镜像；为空时按语言和云厂商选择。 | — |
| `docker_build.build_script` | 生成 Dockerfile 时使用的自定义构建脚本。 | — |

## 发布配置

`.agentkit/agentkit.yaml` 是 `release` 发布配置。先用 `agentkit release config` 生成它；`agentkit release`、`release build` 与 `release apply` 都从中读取。生成的文件里必填与常用字段处于启用状态，其余可选字段以注释形式给出完整结构，取消注释并填值即可启用。

密钥不写入明文，而是用 `${VAR}` 引用部署环境，由 CLI 在部署时解析：

* `${VAR}` —— 必填，未设置则部署报错；
* `${VAR:-default}` —— 未设置或为空时使用默认值；
* `${VAR:?message}` —— 必填，未设置时以 `message` 报错；
* `$$` —— 表示字面量 `$`。

CLI 在解析前会先加载项目目录下的 `.env`，因此把取值写入 `.env` 即可，无需手动 `export`。已在 shell 中设置的变量优先级更高；`.env` 不会被上传到运行时。

## 发布配置完整示例

```yaml title=".agentkit/agentkit.yaml" lines theme={null}
# agentkit.yaml — AgentKit release configuration (fully yaml-driven).
#
# `agentkit release` reads everything from this file — no flags required.
# Secrets are NOT written here in plaintext: reference the deploy environment
# with ${VAR}. Forms: ${VAR} (required) · ${VAR:-default} · ${VAR:?message} ·
# $$ for a literal $. Values are resolved by the CLI at deploy time.

# ── Project ──────────────────────────────────────────────
name: my-agent
description: ""
cloud_provider: volcengine      # volcengine | byteplus
region: cn-beijing
project: default

# ── Runtime resources ────────────────────────────────────
runtime:
  region: cn-beijing
  project: default
  cpu_milli: 2000              # CPU in milli-cores (2000 = 2 vCPU)
  memory_mb: 4096              # memory in MB (4096 = 4 GiB)
  min_instance: 1              # keep one warm instance by default
  max_instance: 5
  max_concurrency: 20          # concurrent requests per instance
  # tags:
  #   owner: team-name
  # network:
  #   enable_public_network: true
  #   enable_private_network: false
  #   vpc_id: ${VPC_ID}
  #   subnet_ids:
  #     - ${SUBNET_ID}
  #   security_group_ids:
  #     - ${SECURITY_GROUP_ID}
  #   enable_shared_internet_access: true

# ── Harness Sidecar optimization (optional) ─────────────
# Enabling any component selects the managed Sidecar Runtime. Initial support is
# Volcengine cn-shanghai, CPython 3.12, linux/amd64, and exactly one instance;
# set runtime.min_instance/max_instance to 1. The private Runtime artifact is
# supplied by the platform and must never be written into this file.
# harness_sidecar:
#   enabled: true
#   profile: default
#   component_overrides:
#     context_engine: true
#     compressor: false
#     verifier: false
#     long_run_control: false   # Studio name: Goal任务控制
#     mcp_resilience: false     # automatically includes SQL readonly protection

# ── Build ────────────────────────────────────────────────
# Defaults to .agentkit/Dockerfile (or ./Dockerfile if present).
# dockerfile: .agentkit/Dockerfile

# ── Runtime environment variables (injected into the runtime) ────
# Use ${VAR} for secrets — resolved from the deploy env, never committed here.
envs:
  # MODEL_AGENT_API_KEY: ${MODEL_AGENT_API_KEY:?set MODEL_AGENT_API_KEY in your env}
  # LOG_LEVEL: ${LOG_LEVEL:-info}

# ── Model / associated resources (optional) ──────────────
# model_agent_name: ep-xxxxxxxx
# knowledge_id: ${KNOWLEDGE_ID}
# memory_id: ${MEMORY_ID}
# tool_id: ${TOOL_ID}
# mcp_toolset_id: ${MCP_TOOLSET_ID}

# ── Gateway auth (optional; pick one type) ───────────────
# When `frontend` (below) is enabled, this is derived automatically from its
# userpool — you do NOT need to repeat it here.
# auth:
#   type: custom_jwt           # key_auth | custom_jwt
#   # --- key_auth ---
#   api_key_name: ""           # auto-created if omitted
#   api_key_location: header   # header | query
#   # --- custom_jwt ---
#   discovery_url: ${USERPOOL_DISCOVERY_URL}
#   allowed_clients:
#     - ${USERPOOL_CLIENT_ID}

# ── IM channels (optional) ───────────────────────────────
# Deploys a bot proxy to VeFaaS after the runtime. Credentials via ${VAR}.
im:
  region: cn-beijing
  project: default
#   feishu:
#     enabled: true
#     app_id: ${FEISHU_APP_ID}
#     app_secret: ${FEISHU_APP_SECRET}
#   wecom:
#     enabled: true
#     bot_id: ${WECOM_BOT_ID}
#     bot_secret: ${WECOM_BOT_SECRET}
#   dingtalk:
#     enabled: true
#     client_id: ${DINGTALK_CLIENT_ID}
#     client_secret: ${DINGTALK_CLIENT_SECRET}

# ── Frontend BFF (optional) ──────────────────────────────
# Public VeFaaS front door: OAuth login at the edge, then reverse-proxy to the
# runtime forwarding the user's JWT (no shared key). The runtime's gateway auth
# is auto-set to custom_jwt from this userpool. The callback is auto-registered
# and OAUTH2_REDIRECT_URI auto-derived — you only declare the userpool here.
frontend:
  enabled: false
  region: cn-beijing
  project: default
#   gateway: ${VEFAAS_SERVERLESS_GATEWAY}
#   oauth2:
#     region: cn-shanghai
#     project: identity-project
#     user_pool_id: ${USERPOOL_ID}
#     client_id: ${USERPOOL_CLIENT_ID}
#     client_secret: ${USERPOOL_CLIENT_SECRET}

# ── Observability (optional) ─────────────────────────────
# apmplus: true                # enable APMPlus monitoring

# ── Advanced (optional) ──────────────────────────────────
# role_name: ""                # IAM role; auto-created when omitted

# ── Infrastructure ───────────────────────────────────────
# Where the image is built and stored. "Auto" = created & managed for you.
infrastructure:
  container_registry:          # Volcengine Container Registry (CR)
    region: cn-beijing
    project: default
    instance_name: Auto        # Auto → agentkit-platform-<account-id>
    namespace_name: agentkit
    repo_name: my-agent         # defaults to the app name
  tos:                         # TOS (build artifacts)
    region: cn-beijing
    project: default
    bucket_name: Auto          # Auto → provider/region-safe account bucket
    object_prefix: agentkit-builds
  # code_pipeline:
  #   workspace_name: agentkit-cli-workspace
  #   workspace_id: ""           # optional; pins an existing workspace
  #   pipeline_name: my-agent
  #   pipeline_id: ""            # optional; pins an existing compatible pipeline
```

## 项目

顶层字段为各资源块提供默认的云厂商、区域和项目。资源块可以覆盖区域和项目，但一次发布不能混用不同云厂商。

| 字段 | 说明 | 默认值 |
| - | - | - |
| `name` | 运行时/应用名称，运行时按此名称幂等创建或更新。 | `agent` |
| `description` | 运行时描述。 | — |
| `cloud_provider` | 云厂商：`volcengine` 或 `byteplus`。同时用于 Runtime、IAM/STS、CR、TOS 与 Code Pipeline。 | 当前云环境 |
| `region` | 各资源块继承的默认区域。 | 云厂商默认区域 |
| `project` | 所属 AgentKit 项目。 | `default` |

## 运行时资源

`runtime` 块配置运行时的计算资源与伸缩策略。

| 字段 | 说明 | 默认值 |
| - | - | - |
| `region` | Runtime 区域；省略时继承顶层 `region`。 | 顶层 `region` |
| `project` | Runtime 项目；省略时继承顶层 `project`。 | 顶层 `project` |
| `cpu_milli` | CPU，单位毫核（`2000` = 2 vCPU）。 | `2000` |
| `memory_mb` | 内存，单位 MB。 | `4096` |
| `min_instance` | 最小实例数。设为 `0` 时允许空闲缩容到零。 | `1` |
| `max_instance` | 最大实例数。 | `5` |
| `max_concurrency` | 单实例并发请求数。 | `20` |
| `tags` | 创建新运行时时写入的标签键值对。已有运行时的标签不会在更新时自动改写。 | `{}` |

### 运行时网络

`runtime.network` 为可选配置。启用私有网络前，确认 VPC、子网和安全组位于 Runtime 使用的区域。

| 字段 | 说明 | 默认值 |
| - | - | - |
| `enable_public_network` | 是否启用公网网络。 | 平台默认 |
| `enable_private_network` | 是否启用私有网络。 | 平台默认 |
| `vpc_id` | 私有网络使用的 VPC ID。 | — |
| `subnet_ids` | 私有网络使用的子网 ID 列表。 | `[]` |
| `security_group_ids` | 私有网络使用的安全组 ID 列表。 | `[]` |
| `enable_shared_internet_access` | 私有网络是否使用共享公网出口。 | 平台默认 |

## Harness Sidecar

`harness_sidecar` 为托管 Harness Runtime 启用 Product Component 能力。启用后，`release` 会使用平台提供的托管 Sidecar 基础镜像，在发布过程中写入 Sidecar 运行时配置，并在运行时就绪后校验 Sidecar、模型代理和所需 MCP 网关状态。启用该块时，至少需要在 `component_overrides` 中将一个可选组件设为 `true`。

<Warning>
  当前托管 Harness Sidecar 仅支持 Volcengine `cn-shanghai`、CPython 3.12、`linux/amd64`，并要求 `runtime.min_instance` 与 `runtime.max_instance` 都为 `1`。它还要求发布环境由平台提供托管 Sidecar 基础镜像配置；普通本地环境未提供该配置时，发布会失败。启用 Sidecar 时必须使用默认 `key_auth` 网关鉴权，不能与 `custom_jwt` 或前端 BFF 鉴权派生同时使用。
</Warning>

```yaml lines theme={null}
runtime:
  region: cn-shanghai
  min_instance: 1
  max_instance: 1

harness_sidecar:
  enabled: true
  profile: default
  component_overrides:
    context_engine: true
    compressor: true
    verifier: true
    long_run_control: true
    mcp_resilience: false
```

| 字段 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `harness_sidecar.enabled` | boolean | `true`（存在对象时） | 是否启用托管 Sidecar。设为 `false` 或省略整个块时不启用。 |
| `harness_sidecar.profile` | string | `default` | Product Component profile，支持 `default` 与 `ops`。 |
| `harness_sidecar.catalog_version` | string | `2026.07.1` | 期望的 Catalog 版本；传入时必须与当前 CLI 支持版本一致。 |
| `harness_sidecar.runtime_version` | string | — | 目标托管 Runtime 版本；省略时由平台选择。 |
| `harness_sidecar.component_overrides` | object | `{}` | 可选组件开关。支持 `context_engine`、`compressor`、`verifier`、`long_run_control` 与 `mcp_resilience`，值必须为 boolean；启用 Sidecar 时至少需要一个 `true`。 |
| `harness_sidecar.fail_open` | boolean | `false` | Sidecar 故障时是否放行；托管 APIG 运行时要求保持 `false`。 |
| `harness_sidecar.transport` | `apig_runtime_port` \| `local` | `apig_runtime_port` | Sidecar 访问模型代理和 MCP 网关的传输方式。托管发布使用 `apig_runtime_port`。 |
| `harness_sidecar.model_proxy.enabled` | boolean | `true` | 是否启用模型代理；托管 APIG 运行时要求保持 `true`。 |
| `harness_sidecar.model_proxy.host` | string | `0.0.0.0` | 模型代理监听地址；托管 APIG 运行时必须对外可达。 |
| `harness_sidecar.model_proxy.port` | integer | `18787` | 模型代理监听端口。 |
| `harness_sidecar.model_proxy.upstream_base_url_env` | string | `MODEL_AGENT_API_BASE` | 指向上游模型 Base URL 的运行时环境变量名。 |
| `harness_sidecar.model_proxy.upstream_api_key_env` | string | `MODEL_AGENT_API_KEY` | 指向上游模型 API Key 的运行时环境变量名。 |
| `harness_sidecar.model_proxy.prefer_configured_upstream_api_key` | boolean | `true` | 托管 APIG 运行时要求使用配置中的上游 API Key。 |
| `harness_sidecar.model_proxy.compression_provider` | string | `noop` | 模型代理压缩提供方。 |
| `harness_sidecar.model_proxy.fail_open` | boolean | 继承 `harness_sidecar.fail_open` | 模型代理故障时是否放行。 |
| `harness_sidecar.mcp_gateway.enabled` | boolean | 由组件计划决定 | 是否启用 MCP 网关；启用 `mcp_resilience` 或 SQL 只读保护时会启用。 |
| `harness_sidecar.mcp_gateway.host` | string | `0.0.0.0` | MCP 网关监听地址；托管 APIG 运行时必须对外可达。 |
| `harness_sidecar.mcp_gateway.port` | integer | `18788` | MCP 网关监听端口。 |
| `harness_sidecar.mcp_gateway.upstreams_env` | string | `MCP_URLS` | 指向上游 MCP 地址列表的运行时环境变量名。 |
| `harness_sidecar.mcp_gateway.upstream_api_key_env` | string | `MCP_API_KEY` | 指向上游 MCP API Key 的运行时环境变量名。 |
| `harness_sidecar.mcp_gateway.prefer_configured_upstream_api_key` | boolean | 启用托管 MCP 网关时为 `true` | 托管 APIG 运行时要求使用配置中的上游 MCP API Key。 |
| `harness_sidecar.mcp_gateway.fail_open` | boolean | 继承 `harness_sidecar.fail_open` | MCP 网关故障时是否放行；托管 APIG 运行时要求保持 `false`。 |

可用组件如下。`mcp_resilience` 会自动带上 SQL 只读保护；`sql_readonly`、`browser`、`evaluation` 与 `shadow` 不是用户可直接选择的 `component_overrides` 项。

| 组件 ID | 说明 | 可直接选择 |
| - | - | - |
| `context_engine` | 治理上下文组装、任务锚定和上下文预算。 | 是 |
| `compressor` | 压缩长上下文和大型工具结果，降低 Token 成本。 | 是 |
| `verifier` | 校验证据和回答，在失败时执行修复或告警。 | 是 |
| `long_run_control` | 管理 Goal 任务的进度、续跑和结束条件。 | 是 |
| `mcp_resilience` | 治理 MCP 连接、超时、空结果、大返回和调用预算；自动包含 SQL 只读保护。 | 是 |
| `sql_readonly` | 对所选 MCP 路由提供 SQL 只读保护。 | 否 |
| `browser` | 浏览器任务增强；当前 Runtime 合约中不可用。 | 否 |
| `evaluation` | 在线评测；当前 Runtime 合约中不可用。 | 否 |
| `shadow` | Shadow 对照运行；当前 Runtime 合约中不可用。 | 否 |

发布前可用 [`harness sidecar resolve`](/productions/agentkit-cli/preview/zh/commands/harness#harness-sidecar-resolve) 校验选择结果。

## 环境变量

`envs` 声明注入运行时的环境变量。为避免把密钥写进仓库，值用 `${VAR}` 引用部署环境（语法见本页开头），由 CLI 在部署时解析后注入运行时。

```yaml lines theme={null}
envs:
  MODEL_AGENT_API_KEY: ${MODEL_AGENT_API_KEY:?set MODEL_AGENT_API_KEY in your env}
  LOG_LEVEL: ${LOG_LEVEL:-info}
```

本地发布时，可把变量导出到 shell，或写入本机 `.env`；持续部署则配成仓库 Secret，并在发布任务中导出到环境。用于发布鉴权的 `VOLCENGINE_*` 不会注入运行时。

<Note>
  `${VAR}` 取代了旧的 `AK_` 前缀注入：现在每个变量在 `envs` 里显式声明、用 `${VAR}` 取值，更清晰、可审阅。`auth`、`im`、`frontend` 等块里的密钥同样用 `${VAR}`。
</Note>

## 模型与关联资源

均为可选，用于指定运行时使用的模型，以及关联的平台资源。

| 字段 | 说明 |
| - | - |
| `model_agent_name` | 运行时使用的模型名称。 |
| `knowledge_id` | 关联的知识库 ID。 |
| `memory_id` | 关联的记忆库 ID。 |
| `tool_id` | 关联的工具 ID。 |
| `mcp_toolset_id` | 关联的 MCP 工具集 ID。 |

## 网关鉴权

`auth` 配置运行时网关的鉴权方式，二选一。启用下文的 `frontend` 时，网关鉴权会依据其用户池自动设为 `custom_jwt`，此处无需重复声明。

| 字段 | 说明 |
| - | - |
| `type` | 鉴权类型：`key_auth`（API Key）或 `custom_jwt`（JWT）。 |
| `api_key_name` | `key_auth` 时的 API Key 名称，省略则自动创建。 |
| `api_key_location` | `key_auth` 时 Key 的位置：`header` 或 `query`。 |
| `discovery_url` | `custom_jwt` 时的 OIDC discovery 地址，必填。 |
| `allowed_clients` | `custom_jwt` 时可选的客户端 ID 白名单。 |

## 消息渠道

`im` 块用于在运行时之后向 VeFaaS 部署一个机器人代理，把消息渠道接入运行时。凭据用 `${VAR}` 提供。目前支持飞书、企业微信与钉钉，可任意组合启用。

`im.region` 与 `im.project` 控制消息代理所在的区域和项目；省略时分别继承顶层 `region` 与 `project`。

### 飞书

| 字段 | 说明 |
| - | - |
| `im.feishu.enabled` | 是否启用飞书渠道。 |
| `im.feishu.app_id` | 飞书应用 App ID。 |
| `im.feishu.app_secret` | 飞书应用 App Secret。 |

### 企业微信

| 字段 | 说明 |
| - | - |
| `im.wecom.enabled` | 是否启用企业微信渠道。 |
| `im.wecom.connection_mode` | 连接方式，当前仅支持 `websocket`。 |
| `im.wecom.bot_id` | 企业微信机器人 ID。 |
| `im.wecom.bot_secret` | 企业微信机器人密钥。 |
| `im.wecom.websocket_url` | WebSocket 地址。 |
| `im.wecom.send_thinking_message` | 是否发送“思考中”过渡消息，默认 `true`。 |

企业微信代理通过 WebSocket 连接。接入地址（`websocket_url`，默认 `wss://openws.work.weixin.qq.com`）以及是否发送“思考中”过渡消息（`send_thinking_message`，默认 `true`）也可设置，但通常无需改动。

### 钉钉

| 字段 | 说明 |
| - | - |
| `im.dingtalk.enabled` | 是否启用钉钉渠道。 |
| `im.dingtalk.connection_mode` | 连接方式，当前仅支持 `websocket`。 |
| `im.dingtalk.client_id` | 钉钉应用 Client ID（AppKey）。 |
| `im.dingtalk.client_secret` | 钉钉应用 Client Secret（AppSecret）。 |
| `im.dingtalk.send_thinking_message` | 是否发送“思考中”过渡消息。 |

## 前端

`frontend` 块在 VeFaaS 上部署一个公网前门：在边缘完成 OAuth 登录，再反向代理到运行时并透传用户的 JWT（不使用共享密钥）。启用后，运行时网关鉴权会依据该用户池自动设为 `custom_jwt`，回调地址自动注册、`OAUTH2_REDIRECT_URI` 自动推导，因此只需在此声明用户池。

| 字段 | 说明 |
| - | - |
| `frontend.enabled` | 是否启用前端前门。 |
| `frontend.region` | 前端函数与网关所在区域；省略时继承顶层 `region`。 |
| `frontend.project` | 前端函数与网关所在项目；省略时继承顶层 `project`。 |
| `frontend.gateway` | 要固定复用的 serverless 网关名称。省略时优先复用已有网关；没有可用网关时自动创建。 |
| `frontend.oauth2.region` | 查询用户池的区域。省略时搜索已知区域；多条匹配会报错。 |
| `frontend.oauth2.project` | 查询用户池的项目。省略时搜索全部项目；多条匹配会报错。 |
| `frontend.oauth2.user_pool_id` | 用户池 ID。 |
| `frontend.oauth2.client_id` | 用户池客户端 ID。 |
| `frontend.oauth2.client_secret` | 用户池客户端密钥。可选 —— 省略时 CLI 自动从用户池客户端获取，仅在客户端未暴露 secret 或需覆盖时设置。 |

## 可观测

`apmplus` 设为 `true` 时启用 APMPlus 监控。

## 高级选项

| 字段 | 说明 |
| - | - |
| `role_name` | IAM 角色名称，省略时自动创建。 |

## 基础设施

`infrastructure` 指定镜像的构建与存储位置。`Auto` 表示由平台自动创建并托管，如需复用已有资源可替换为自己的值。

| 字段 | 说明 | 默认值 |
| - | - | - |
| `container_registry.region` | CR 区域；省略时继承顶层 `region`。 | 顶层 `region` |
| `container_registry.project` | CR 项目；省略时继承顶层 `project`。 | 顶层 `project` |
| `container_registry.instance_name` | 容器镜像仓库实例。`Auto` → `agentkit-platform-<account-id>`。 | `Auto` |
| `container_registry.namespace_name` | 镜像命名空间。 | `agentkit` |
| `container_registry.repo_name` | 镜像仓库名。 | 应用名 |
| `tos.region` | TOS 区域；省略时继承顶层 `region`。 | 顶层 `region` |
| `tos.project` | TOS 项目；省略时继承顶层 `project`。 | 顶层 `project` |
| `tos.bucket_name` | 存放构建产物的对象存储桶。`Auto` 会按云厂商、区域和账号生成避免跨区域冲突的默认名称。 | `Auto` |
| `tos.object_prefix` | 构建产物的对象前缀。 | `agentkit-builds` |
| `code_pipeline.workspace_name` | Code Pipeline 工作区名称；未设置 `workspace_id` 时按名称查找或创建。 | — |
| `code_pipeline.workspace_id` | 要固定复用的 Code Pipeline 工作区 ID。 | — |
| `code_pipeline.pipeline_name` | Code Pipeline 流水线名称；省略时使用应用名。 | 应用名 |
| `code_pipeline.pipeline_id` | 要固定复用的兼容流水线 ID。托管 Harness Sidecar 发布始终按名称解析当前兼容流水线。 | — |

## 构建

`dockerfile` 字段指定构建镜像所用的 Dockerfile 路径，默认为 `.agentkit/Dockerfile`；若项目根目录存在 `./Dockerfile` 则改用它。容器内进程必须监听 `0.0.0.0:8000`，运行时会探测该端口以判断实例是否就绪。