> ## 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.yaml` 是部署配置的唯一来源。先用 `agentkit init` 创建项目，再执行 `agentkit deploy config`，即会在项目的 `.agentkit/` 下生成它；`agentkit deploy`、`deploy build` 与 `deploy apply` 都从中读取，无需额外传参。生成的文件里必填与常用字段处于启用状态，其余可选字段以注释形式给出完整结构——取消注释并填值即可启用。

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

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

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

## 完整示例

```yaml .agentkit/agentkit.yaml lines theme={null}
# agentkit.yaml — AgentKit deploy configuration (fully yaml-driven).
#
# `agentkit deploy` 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
region: cn-beijing              # cn-beijing | cn-shanghai
project: default

# ── Runtime resources ────────────────────────────────────
runtime:
  cpu_milli: 1000              # CPU in milli-cores (1000 = 1 vCPU)
  memory_mb: 2048              # memory in MB
  min_instance: 0              # 0 = scale to zero when idle
  max_instance: 5
  max_concurrency: 20          # concurrent requests per instance

# ── 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: doubao-seed-1-6-250615
# 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:
#   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: true
#   gateway: ${VEFAAS_SERVERLESS_GATEWAY:-}   # reuse an existing serverless gateway (recommended)
#   oauth2:
#     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)
    instance_name: Auto        # Auto → agentkit-platform-<account-id>
    namespace_name: agentkit
    repo_name: my-agent         # defaults to the app name
  tos:                         # TOS (build artifacts)
    bucket_name: Auto          # Auto → agentkit-platform-<account-id>
    object_prefix: agentkit-builds
```

## 项目

顶层的基本标识，均为必填。

| 字段 | 说明 | 默认值 |
| - | - | - |
| `name` | 运行时/应用名称，运行时按此名称幂等创建或更新。 | — |
| `region` | 部署区域，`cn-beijing` 或 `cn-shanghai`。 | — |
| `project` | 所属 AgentKit 项目。 | `default` |

## 运行时资源

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

| 字段 | 说明 | 默认值 |
| - | - | - |
| `cpu_milli` | CPU，单位毫核（`1000` = 1 vCPU）。 | `1000` |
| `memory_mb` | 内存，单位 MB。 | `2048` |
| `min_instance` | 最小实例数，`0` 表示空闲时缩容到零。 | `0` |
| `max_instance` | 最大实例数。 | `5` |
| `max_concurrency` | 单实例并发请求数。 | `20` |

## 环境变量

`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}
```

供值方式见[构建与部署 · 环境变量](/productions/agentkit-cli/archives/0.46.6/zh/commands/deploy#环境变量)：本地部署可导出变量或写入本机 `.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.feishu.enabled` | 是否启用飞书渠道。 |
| `im.feishu.app_id` | 飞书应用 App ID。 |
| `im.feishu.app_secret` | 飞书应用 App Secret。 |

### 企业微信

| 字段 | 说明 |
| - | - |
| `im.wecom.enabled` | 是否启用企业微信渠道。 |
| `im.wecom.bot_id` | 企业微信机器人 ID。 |
| `im.wecom.bot_secret` | 企业微信机器人密钥。 |

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

### 钉钉

| 字段 | 说明 |
| - | - |
| `im.dingtalk.enabled` | 是否启用钉钉渠道。 |
| `im.dingtalk.client_id` | 钉钉应用 Client ID（AppKey）。 |
| `im.dingtalk.client_secret` | 钉钉应用 Client Secret（AppSecret）。 |

## 前端

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

| 字段 | 说明 |
| - | - |
| `frontend.enabled` | 是否启用前端前门。 |
| `frontend.gateway` | 复用已有的 serverless 网关（推荐）。 |
| `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.instance_name` | 容器镜像仓库实例。`Auto` → `agentkit-platform-<account-id>`。 | `Auto` |
| `container_registry.namespace_name` | 镜像命名空间。 | `agentkit` |
| `container_registry.repo_name` | 镜像仓库名。 | 应用名 |
| `tos.bucket_name` | 存放构建产物的对象存储桶。`Auto` → `agentkit-platform-<account-id>`。 | `Auto` |
| `tos.object_prefix` | 构建产物的对象前缀。 | `agentkit-builds` |

## 构建

`dockerfile` 字段指定构建镜像所用的 Dockerfile 路径，默认为 `.agentkit/Dockerfile`；若项目根目录存在 `./Dockerfile` 则改用它。容器如何启动、以及必须监听 `0.0.0.0:8000` 的约定，见[构建与部署 · 容器入口与端口](/productions/agentkit-cli/archives/0.46.6/zh/commands/deploy#容器入口与端口)。