> ## 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 currently uses two `agentkit.yaml` files:

* Root `agentkit.yaml`: created by `agentkit init` or `agentkit config --init`, read by `build`, `deploy`, `launch`, `status`, and `destroy` for lifecycle-style build and deploy.
* `.agentkit/agentkit.yaml`: created by `agentkit release config`, read by `release`, `release build`, and `release apply` for the full cloud release flow that can include IM channels and frontend BFF.

This page covers the root lifecycle config first, then the `.agentkit/agentkit.yaml` release config. Do not mix the two: lifecycle commands read root `agentkit.yaml` by default, while `release` reads `.agentkit/agentkit.yaml` by default.

## Lifecycle Config

Root `agentkit.yaml` describes how an agent application is built, deployed, and inspected. `common.launch_type` selects the active strategy: `local` means local Docker build and local container deploy, `cloud` means cloud build and cloud runtime deploy, and `hybrid` means local build followed by cloud runtime deploy.

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

| Field | Description | Default |
| - | - | - |
| `common.agent_name` | Agent application name; only letters, digits, underscores, and hyphens are allowed. | — |
| `common.entry_point` | Application entry file, such as `agent.py`, `main.go`, or `build.sh`. | `agent.py` |
| `common.description` | Application description. | — |
| `common.language` | Application language; the config wizard currently supports `Python` and `Golang`. | `Python` |
| `common.language_version` | Language version; Python defaults to `3.12`, Go defaults to `1.24`. | By language |
| `common.agent_type` | Application type label. | `Basic App` |
| `common.dependencies_file` | Dependency file; Python defaults to `requirements.txt`, Go defaults to `go.mod`. | By language |
| `common.runtime_envs` | Runtime environment variables shared by all launch modes. | `{}` |
| `common.launch_type` | Launch mode: `local`, `cloud`, or `hybrid`. | `cloud` |
| `common.cloud_provider` | Cloud provider: `volcengine` or `byteplus`. | Current cloud environment |

### Local Strategy

| Field | Description | Default |
| - | - | - |
| `launch_types.local.image_tag` | Local image tag. | `latest` |
| `launch_types.local.invoke_port` | Application invoke port. | `8000` |
| `launch_types.local.container_name` | Local container name; generated from the app name when empty. | — |
| `launch_types.local.ports` | Docker port mappings. | `["8000:8000"]` |
| `launch_types.local.volumes` | Docker volume mounts. | `[]` |
| `launch_types.local.restart_policy` | Docker restart policy. | `unless-stopped` |
| `launch_types.local.memory_limit` | Local container memory limit. | `1g` |
| `launch_types.local.cpu_limit` | Local container CPU limit. | `1` |
| `launch_types.local.runtime_envs` | Runtime environment variables for local mode. | `{}` |

### Cloud And Hybrid Strategies

`cloud` and `hybrid` share most runtime, auth, networking, and container registry fields. `cloud` also includes TOS and Code Pipeline fields; `hybrid` uses the local build result and omits those cloud-build fields.

| Field | Description | Default |
| - | - | - |
| `region` | AgentKit Runtime region. | Provider default region |
| `region_overrides` | Per-service region overrides for services such as `agentkit`, `cr`, `cp`, and `tos`. | `{}` |
| `tos_bucket` | TOS bucket for `cloud` build artifacts. | `agentkit-platform-{{account_id}}` |
| `tos_prefix` | Object prefix for `cloud` build artifacts. | `agentkit-builds` |
| `image_tag` | Image tag; supports `{{timestamp}}`. | `{{timestamp}}` |
| `cr_instance_name` | Container Registry instance name. | `agentkit-platform-{{account_id}}` |
| `cr_namespace_name` | Container Registry namespace. | `agentkit` |
| `cr_repo_name` | Container Registry repository name. | Agent application name |
| `cr_auto_create_instance_type` | Instance type when auto-creating CR. | `Micro` |
| `build_timeout` | Cloud build timeout in seconds for `cloud` mode. | `3600` |
| `cp_workspace_name` | Code Pipeline workspace name for `cloud` mode. | `agentkit-cli-workspace` |
| `cp_pipeline_name` | Code Pipeline pipeline name for `cloud` mode. | `Auto` |
| `cp_pipeline_id` | Existing Code Pipeline pipeline id. | — |
| `project_name` | AgentKit project name. | `default` |
| `runtime_id` | Deployed runtime id; `Auto` means create or resolve automatically. | `Auto` |
| `runtime_name` | Runtime name; `Auto` means generated from the app name. | `Auto` |
| `runtime_role_name` | Runtime IAM role name. | `Auto` |
| `runtime_auth_type` | Runtime gateway auth type: `key_auth` or `custom_jwt`. | `key_auth` |
| `runtime_apikey_name` | API key name for `key_auth`. | `Auto` |
| `runtime_apikey` | API key value recorded after deployment. | `Auto` |
| `runtime_jwt_discovery_url` | OIDC discovery URL for `custom_jwt`. | — |
| `runtime_jwt_allowed_clients` | Allowed client ids for `custom_jwt`. | `[]` |
| `runtime_endpoint` | Runtime endpoint recorded after deployment. | — |
| `runtime_envs` | Runtime environment variables for the current strategy, merged with `common.runtime_envs`. | `{}` |
| `runtime_bindings.knowledge_id` | Bound knowledge base id. | — |
| `runtime_bindings.memory_id` | Bound memory collection id. | — |
| `runtime_bindings.tool_id` | Bound tool id. | — |
| `runtime_bindings.mcp_toolset_id` | Bound MCP toolset id. | — |
| `runtime_network.mode` | Network mode; `private` enables private networking. | Platform default |
| `runtime_network.vpc_id` | VPC id for private networking. | — |
| `runtime_network.subnet_ids` | Subnet ids for private networking. | `[]` |
| `runtime_network.security_group_ids` | Security group ids for private networking. | `[]` |
| `runtime_network.enable_shared_internet_access` | Whether shared internet access is enabled for private networking. | Platform default |

### Build Fields

| Field | Description | Default |
| - | - | - |
| `docker_build.base_image` | Base image used when generating a Dockerfile; empty means selected from language and cloud provider. | — |
| `docker_build.build_script` | Custom build script used when generating a Dockerfile. | — |

## Release Config

`.agentkit/agentkit.yaml` is the `release` config. Generate it with `agentkit release config`; `agentkit release`, `release build`, and `release apply` all read from it. In the generated file, required and common fields are active, and optional fields are shown commented-out with their full shape, so you uncomment and fill them to enable them.

Secrets are not written in plaintext; instead, reference the deploy environment with `${VAR}`, resolved by the CLI at deploy time:

* `${VAR}` — required; the deploy fails if it is unset;
* `${VAR:-default}` — use the default when unset or empty;
* `${VAR:?message}` — required; fail with `message` when unset;
* `$$` — a literal `$`.

The CLI loads the project's `.env` (from the working directory) before resolving these, so it is enough to put the values in `.env` — no manual `export` is needed. Variables already set in your shell take precedence, and `.env` is never uploaded to the runtime.

## Release Config Full Example

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

# ── 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 → agentkit-platform-<account-id>
    object_prefix: agentkit-builds
```

## Project

The top-level fields provide the default cloud provider, region, and project inherited by resource blocks. A resource block may override its region and project, but one release cannot mix cloud providers.

| Field | Description | Default |
| - | - | - |
| `name` | Runtime/app name; the runtime is created or updated idempotently by this name. | `agent` |
| `cloud_provider` | Cloud provider: `volcengine` or `byteplus`. Applies to Runtime, IAM/STS, CR, TOS, and Code Pipeline. | Current cloud environment |
| `region` | Default region inherited by resource blocks. | Provider default region |
| `project` | The AgentKit project it belongs to. | `default` |

## Runtime resources

The `runtime` block configures compute resources and the scaling policy.

| Field | Description | Default |
| - | - | - |
| `region` | Runtime region; inherits the top-level `region` when omitted. | Top-level `region` |
| `project` | Runtime project; inherits the top-level `project` when omitted. | Top-level `project` |
| `cpu_milli` | CPU in millicores (`2000` = 2 vCPU). | `2000` |
| `memory_mb` | Memory in MB. | `4096` |
| `min_instance` | Minimum instances. Set `0` to allow scale-to-zero when idle. | `1` |
| `max_instance` | Maximum instances. | `5` |
| `max_concurrency` | Concurrent requests per instance. | `20` |

### Runtime network

`runtime.network` is optional. Before enabling private networking, confirm that the VPC, subnets, and security groups are in the Runtime region.

| Field | Description | Default |
| - | - | - |
| `enable_public_network` | Whether to enable public networking. | Platform default |
| `enable_private_network` | Whether to enable private networking. | Platform default |
| `vpc_id` | VPC ID for private networking. | — |
| `subnet_ids` | Subnet IDs for private networking. | `[]` |
| `security_group_ids` | Security-group IDs for private networking. | `[]` |
| `enable_shared_internet_access` | Whether the private network uses shared internet access. | Platform default |

## Environment variables

`envs` declares the environment variables injected into the runtime. To keep secrets out of the repository, reference the deploy environment with `${VAR}` (syntax at the top of this page); the CLI resolves them at deploy time.

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

For local release, export the variables in your shell or put them in a local `.env`; in continuous deployment, configure them as repository secrets and export them into the release job environment. The `VOLCENGINE_*` release credentials are not injected into the runtime.

<Note>
  `${VAR}` replaces the older `AK_`-prefix injection: each variable is now declared explicitly in `envs` and read via `${VAR}`, which is clearer and reviewable. Secrets in the `auth`, `im`, and `frontend` blocks use `${VAR}` the same way.
</Note>

## Model and associated resources

All optional — specify the model the runtime uses and the platform resources it attaches.

| Field | Description |
| - | - |
| `model_agent_name` | The model the runtime uses. |
| `knowledge_id` | Associated knowledge base id. |
| `memory_id` | Associated memory collection id. |
| `tool_id` | Associated tool id. |
| `mcp_toolset_id` | Associated MCP toolset id. |

## Gateway auth

`auth` configures the runtime gateway's authentication, one type of two. When `frontend` (below) is enabled, gateway auth is set to `custom_jwt` automatically from its userpool, so you do not repeat it here.

| Field | Description |
| - | - |
| `type` | Auth type: `key_auth` (API key) or `custom_jwt` (JWT). |
| `api_key_name` | API key name for `key_auth`; auto-created if omitted. |
| `api_key_location` | Key location for `key_auth`: `header` or `query`. |
| `discovery_url` | OIDC discovery URL for `custom_jwt`; required. |
| `allowed_clients` | Optional client-id allow-list for `custom_jwt`. |

## IM channels

The `im` block deploys a bot proxy to VeFaaS after the runtime to connect a messaging channel. Provide credentials via `${VAR}`. Feishu, WeCom, and DingTalk are supported; enable any combination.

`im.region` and `im.project` control where the messaging proxies are deployed. They inherit the top-level `region` and `project` when omitted.

### Feishu

| Field | Description |
| - | - |
| `im.feishu.enabled` | Whether to enable the Feishu channel. |
| `im.feishu.app_id` | Feishu app App ID. |
| `im.feishu.app_secret` | Feishu app App Secret. |

### WeCom

| Field | Description |
| - | - |
| `im.wecom.enabled` | Whether to enable the WeCom channel. |
| `im.wecom.connection_mode` | Connection mode; currently only `websocket` is supported. |
| `im.wecom.bot_id` | WeCom bot id. |
| `im.wecom.bot_secret` | WeCom bot secret. |
| `im.wecom.websocket_url` | WebSocket endpoint. |
| `im.wecom.send_thinking_message` | Whether to send an interim “thinking” message; defaults to `true`. |

The WeCom proxy connects over WebSocket. The endpoint (`websocket_url`, default `wss://openws.work.weixin.qq.com`) and whether to send an interim "thinking" message (`send_thinking_message`, default `true`) can also be set but are rarely needed.

### DingTalk

| Field | Description |
| - | - |
| `im.dingtalk.enabled` | Whether to enable the DingTalk channel. |
| `im.dingtalk.connection_mode` | Connection mode; currently only `websocket` is supported. |
| `im.dingtalk.client_id` | DingTalk app Client ID (AppKey). |
| `im.dingtalk.client_secret` | DingTalk app Client Secret (AppSecret). |
| `im.dingtalk.send_thinking_message` | Whether to send an interim “thinking” message. |

## Frontend

The `frontend` block deploys a public front door on VeFaaS: OAuth login at the edge, then reverse-proxy to the runtime forwarding the user's JWT (no shared key). Once enabled, the runtime gateway auth is set to `custom_jwt` from this userpool, the callback is auto-registered, and `OAUTH2_REDIRECT_URI` is auto-derived, so you only declare the userpool here.

| Field | Description |
| - | - |
| `frontend.enabled` | Whether to enable the front door. |
| `frontend.region` | Region for the frontend function and gateway; inherits top-level `region` when omitted. |
| `frontend.project` | Project for the frontend function and gateway; inherits top-level `project` when omitted. |
| `frontend.gateway` | Serverless gateway name to pin. When omitted, the CLI reuses an existing gateway or creates one if none is available. |
| `frontend.oauth2.region` | Region used to locate the user pool. Omit to search known regions; multiple matches are rejected. |
| `frontend.oauth2.project` | Project used to locate the user pool. Omit to search all projects; multiple matches are rejected. |
| `frontend.oauth2.user_pool_id` | User pool id. |
| `frontend.oauth2.client_id` | User pool client id. |
| `frontend.oauth2.client_secret` | User pool client secret. Optional — auto-fetched from the user-pool client when omitted; set it only if the client exposes no secret or you want to override. |

## Observability

Set `apmplus` to `true` to enable APMPlus monitoring.

## Advanced

| Field | Description |
| - | - |
| `role_name` | IAM role name; auto-created when omitted. |

## Infrastructure

`infrastructure` specifies where the image is built and stored. `Auto` means the platform creates and manages it for you; replace a value with your own resource to reuse one.

| Field | Description | Default |
| - | - | - |
| `container_registry.region` | CR region; inherits top-level `region` when omitted. | Top-level `region` |
| `container_registry.project` | CR project; inherits top-level `project` when omitted. | Top-level `project` |
| `container_registry.instance_name` | Container Registry instance. `Auto` → `agentkit-platform-<account-id>`. | `Auto` |
| `container_registry.namespace_name` | Image namespace. | `agentkit` |
| `container_registry.repo_name` | Image repository name. | app name |
| `tos.region` | TOS region; inherits top-level `region` when omitted. | Top-level `region` |
| `tos.project` | TOS project; inherits top-level `project` when omitted. | Top-level `project` |
| `tos.bucket_name` | Object storage bucket for build artifacts. `Auto` → `agentkit-platform-<account-id>`. | `Auto` |
| `tos.object_prefix` | Object prefix for build artifacts. | `agentkit-builds` |

## Build

The `dockerfile` field sets the path to the Dockerfile used for the build, defaulting to `.agentkit/Dockerfile` (or `./Dockerfile` if one exists at the project root). The process inside the container must listen on `0.0.0.0:8000`; the runtime probes that port to decide whether an instance is ready.