部署 MPA 智能体

MPA（Managed Production Agent）是 VeADK 提供的托管智能体运行模式。通过 veadk mpa 命令可以一键准备前置资源（网络、APIG、PostgreSQL、Skill Space、Worker）并部署智能体到 AgentKit Runtime，无需检出 agentkit-mpa-agent 源码。Studio 和 CLI 共用同一编排实现。 MPA 智能体使用预构建的容器镜像，支持账号共享 APIG 注册和元数据初始化。部署后可通过 veadk mpa control 子命令组管理智能体生命周期，包括查看绑定关系、创建和更新智能体、管理配置版本和会话配置。

MPA 智能体部署会创建或更新云端 Runtime、VeFaaS 应用、APIG 网关、PostgreSQL 数据库和网络等云资源，并可能产生费用。执行前确认云账号、地域、访问鉴权和数据库配置。

前置条件

已安装 veadk-python（Preview 源码安装方式见安装）。
已配置火山引擎访问凭据（VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY，可选 VOLCENGINE_SESSION_TOKEN）。
已准备 PostgreSQL 数据库（可使用 AIDAP 自动准备，也可手动创建）。
已准备预构建的 MPA 智能体容器镜像。
部署账号须具备 AgentKit Runtime、Skill Space、Tool、VPC/子网、APIG/IM Gateway 及 GetCallerIdentity 操作权限。

命令总览

veadk mpa 命令组包含以下子命令：

子命令	说明
`provision`	从 YAML 配置准备前置资源并部署 MPA 智能体。
`create`	通过命令行选项创建 MPA 智能体实例，支持 `--config` YAML 提供默认值。
`init-admin-db`	初始化 MPA 管理数据库，支持从旧注册库迁移。
`control`	MPA 控制面子命令组，管理智能体生命周期。

使用 YAML 配置部署

veadk mpa provision 从 YAML 配置文件准备前置资源（网络、共享 APIG、数据库、Skill Space 和 Worker），然后部署 Runtime。适合可重复部署和团队协作场景。

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

veadk mpa provision \
  --config mpa-create.config.yaml \
  --agent-id my-mpa-agent \
  --description "Customer support MPA agent"

--agent-id 为稳定标识，复用同一 ID 可恢复失败的部署。使用 --dry-run 可在本地验证配置并查看资源计划，不执行任何云操作。

选项	类型	默认值	说明
`--config`	`str`（必填）	—	YAML 配置文件路径。配置中可包含 PostgreSQL、OpenViking、模型、网络等设置。文件不应提交到 Git。
`--agent-id`	`str`（必填）	—	智能体稳定标识，用于恢复失败部署。1–64 个小写字母、数字、下划线或连字符。
`--description`	`str`	`""`	智能体描述。
`--dry-run`	标志	关闭	验证配置并输出资源计划，不执行云操作或数据库写入。

YAML 配置支持自动准备 PostgreSQL（managed.postgres.mode: auto），无需手动提供数据库地址和凭据。示例配置参考仓库中的 prd-spec/features/mpa-agent-oneclick-provision/mpa-create.config.example.yaml。

通过命令行创建

veadk mpa create 通过命令行选项创建 MPA 智能体实例，编排流程为：确认工作负载身份 → 确认 Skill Space → 确认 Tool → 预置元数据 → 计算面部署 → 校验绑定 → 验证实例。支持 --config 传入 YAML 文件提供选项默认值，显式命令行选项优先级更高。

veadk mpa create \
  --image "registry.example.com/mpa/mpa_agent:latest" \
  --registry-name "my-registry" \
  --account-id "1234567890" \
  --pg-host "pg.example.com" \
  --pg-database "mpa_db" \
  --pg-user "mpa" \
  --pg-password "$PG_PASSWORD" \
  --model-provider "volcengine" \
  --model-api-base "https://ark.cn-beijing.volces.com/api/v3" \
  --model-api-key "$MODEL_API_KEY" \
  --model-name "doubao-seed-2-1-pro-260628" \
  --user-pool-name "my-user-pool" \
  --user-pool-client-name "my-client" \
  --identity-callback-url "https://studio.example.com/oauth/callback" \
  --region cn-beijing

主要选项如下表所示：

选项	类型	默认值	说明
`--config`	`str`	—	YAML 配置文件，提供选项默认值。显式命令行选项优先。文件不应提交到 Git。
`--image`	`str`（必填）	—	预构建的 MPA 智能体容器镜像地址。
`--registry-name`	`str`（必填）	—	VPC 隧道使用的容器仓库名称。
`--mpa-agent-id`	`str`	自动生成	MPA 实例 ID（`mi-*`）。省略时自动生成全局唯一 ID。
`--account-id`	`str`（必填）	—	云账号 ID，用于 `resource_account_id` 和派生的 `CLAW_SPACE_ID`。
`--region`	`str`	`cn-beijing`	部署地域。
`--pg-host`	`str`（必填）	—	PostgreSQL 主机地址。
`--pg-port`	`str`	`5432`	PostgreSQL 端口。
`--pg-database`	`str`（必填）	—	PostgreSQL 数据库名称。
`--pg-user`	`str`（必填）	—	PostgreSQL 用户名。
`--pg-password`	`str`（必填）	—	PostgreSQL 密码。
`--pg-sslmode`	`str`	`require`	PostgreSQL SSL 模式。
`--model-provider`	`str`（必填）	—	模型提供方。
`--model-api-base`	`str`（必填）	—	模型 API 地址。
`--model-api-key`	`str`（必填）	—	模型 API Key。
`--model-name`	`str`（必填）	—	模型名称。
`--selectable-model`	多值	—	可在 Studio 会话中选择的额外模型 ID，可重复使用。
`--compute-plane`	`runtime` \| `vefaas`	`runtime`	计算面类型。`runtime` 使用 AgentKit CreateRuntime；`vefaas` 使用 `deploy_image`。
`--agentkit-tool-id`	`str`	—	已有的 Codex Worker Tool ID。设置后跳过 Tool 创建。
`--tool-image`	`str`	—	Codex Worker 镜像。设置后创建新 Tool。
`--skill-space-id`	`str`	—	已有的 Skill Space ID。
`--skill-space-name`	`str`	—	创建或选择 Skill Space 并注入 `SKILL_SPACE_ID`。
`--min-instance`	`int`	`1`	Runtime 最小实例数。
`--max-instance`	`int`	`1`	Runtime 最大实例数。
`--user-pool-name`	`str`（必填）	—	VeIdentity 用户池名称，可由 `MPA_USER_POOL_NAME` 环境变量提供。
`--user-pool-client-name`	`str`（必填）	—	VeIdentity 用户池客户端名称，可由 `MPA_USER_POOL_CLIENT_NAME` 环境变量提供。
`--identity-callback-url`	`str`（必填）	—	Studio 公网回调地址，以 `/oauth/callback` 结尾，可由 `IDENTITY_CALLBACK_URL` 环境变量提供。
`--openviking-url`	`str`	—	OpenViking 服务地址。
`--openviking-resource-id`	`str`	—	OpenViking 资源 ID。
`--openviking-api-key`	`str`	—	OpenViking API Key。
`--tos-bucket`	`str`	—	TOS 存储桶，挂载到 `/data/output`。使用 IAM Role 模式时仅提供存储桶名称；使用 AK/SK 模式时需同时提供 `--tos-access-key` 和 `--tos-secret-key`。
`--dry-run`	标志	关闭	解析并输出资源计划，密钥脱敏，不执行云或数据库写入。

compute-plane 为 runtime 时，须提供 --tool-image 以创建专用 Tool，或通过 --agentkit-tool-id 指定已有 Tool。TOS 挂载设置要求创建新 Tool，不能与 --agentkit-tool-id 同时使用。Studio 创建 MPA 智能体时，TOS 输出存储使用 IAM Role 模式：仅选择以 agentkit-platform- 开头的已有存储桶，不要求 TOS AK/SK。创建流程会为 Worker Tool 角色增量绑定存储桶专属策略，保留已有策略。YAML 配置中通过 managed.worker.tos-credential-type: iam_role 和 managed.worker.tos-bucket 启用。历史 AK/SK 模式保持兼容。

初始化管理数据库

veadk mpa init-admin-db 在配置的管理 Workspace 上准备 mpa_admin_db。自动模式下（managed.postgres.mode: auto），会通过 AIDAP 自动准备 PostgreSQL Workspace；手动模式下使用已有 PostgreSQL 实例。

veadk mpa init-admin-db \
  --config mpa-create.config.yaml

从旧注册库迁移时，通过 --source-url-env 指定保存旧注册库 URL 的环境变量名称。命令会原子复制注册记录，不搬迁业务库，不修改运行中 Runtime 的环境变量。

选项	类型	默认值	说明
`--config`	`str`（必填）	—	YAML 配置文件路径。
`--source-url-env`	`str`	—	保存旧注册库 URL 的环境变量名称。用于迁移场景。

控制面命令

veadk mpa control 子命令组通过 AgentKit Studio BFF 管理 MPA 智能体生命周期。所有命令支持 --studio-url、--token 和 --timeout 全局选项，可分别通过 VEADK_MPA_STUDIO_URL、VEADK_MPA_STUDIO_TOKEN 环境变量提供。

全局选项	类型	默认值	说明
`--studio-url`	`str`	—	AgentKit Studio BFF 地址。
`--token`	`str`	—	Studio Bearer Token。
`--timeout`	`float`	`30.0`	HTTP 请求超时（秒）。

查看智能体

veadk mpa control view \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --mpa-instance-id "mi-abc123"

选项	类型	默认值	说明
`--mpa-instance-id`	`str`（必填）	—	MPA 实例 ID。
`--runtime-id`	`str`	—	Runtime ID。
`--region`	`str`	`all`	地域。

创建智能体

veadk mpa control create \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --request operation.json \
  --idempotency-key "create-abc-001"

选项	类型	默认值	说明
`--request`	`str`（必填）	—	操作请求 JSON 文件路径，`-` 表示从标准输入读取。
`--idempotency-key`	`str`（必填）	—	调用方持久化的幂等键，同一逻辑写入复用。

更新智能体

veadk mpa control update \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --mpa-instance-id "mi-abc123" \
  --request operation.json \
  --idempotency-key "update-abc-001"

选项	类型	默认值	说明
`--mpa-instance-id`	`str`（必填）	—	MPA 实例 ID。
`--request`	`str`（必填）	—	操作请求 JSON 文件路径，`-` 表示从标准输入读取。
`--idempotency-key`	`str`（必填）	—	幂等键。

操作管理

# 列出活跃操作
veadk mpa control operation list \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN"

# 查看单个操作
veadk mpa control operation get \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --operation-id "op-xyz789"

# 重试操作
veadk mpa control operation retry \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --operation-id "op-xyz789" \
  --request operation.json

子命令	选项	说明
`operation list`	—	列出当前认证主体拥有的活跃操作。
`operation get`	`--operation-id`（必填）	查看单个活跃或已终止操作。
`operation retry`	`--operation-id`（必填）、`--request`（必填）	使用原始请求重试操作。

配置版本管理

# 查看当前配置版本
veadk mpa control profile status \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --mpa-instance-id "mi-abc123" \
  --runtime-id "r-abc123"

# 应用新配置版本
veadk mpa control profile apply \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --mpa-instance-id "mi-abc123" \
  --runtime-id "r-abc123" \
  --source-profile-id "profile-001" \
  --profile profile.json \
  --idempotency-key "apply-001"

子命令	说明
`profile status`	查看当前 Profile 版本及其 ETag。
`profile apply`	向 Runtime 绑定应用新的 Profile 版本。`--create` 用于首次应用，`--runtime-revision` 指定当前版本用于更新。

会话配置管理

# 查看会话配置
veadk mpa control session config-get \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --session-id "session-001" \
  --runtime-id "r-abc123"

# 更新会话配置
veadk mpa control session config-patch \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --session-id "session-001" \
  --runtime-id "r-abc123" \
  --etag "etag-001" \
  --changes changes.json

# 升级会话配置版本
veadk mpa control session profile-upgrade \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --session-id "session-001" \
  --runtime-id "r-abc123" \
  --etag "etag-001" \
  --target-profile-revision 2 \
  --idempotency-key "upgrade-001"

子命令	说明
`session config-get`	查看会话生效配置及其 ETag。
`session config-patch`	使用 CAS（`--etag`）应用显式会话配置变更。`--changes` 为变更数组 JSON 文件。
`session profile-upgrade`	将会话升级到更高的不可变 Profile 版本。

删除预览

veadk mpa control delete-preview \
  --studio-url "https://studio.example.com" \
  --token "$STUDIO_TOKEN" \
  --mpa-instance-id "mi-abc123" \
  --runtime-id "r-abc123"

预览授权清理影响，不删除实际资源。删除 MPA Runtime 时，Studio 会先清理该智能体拥有的独占云资源（如 Worker 模板），再删除 Runtime 本身。资源归属通过注册库记录与运行时环境变量交叉校验，避免误删非本实例资源。删除过程中会校验活跃操作和会话绑定，存在活跃操作时拒绝删除。

在 Studio 中使用

部署 Studio 后，Studio 自动复用已部署 Studio 的 UserPool、客户端、Identity 地域和 /oauth/callback 进行 MPA 智能体托管创建。Studio 无需创建 YAML，直接使用代码内置的北京地域配置。选择智能体 → MPA 智能体 → 创建 MPA 智能体进入三步创建流程：填写基础信息、PostgreSQL 自动准备说明，以及 OpenViking 准备说明。填写 Runtime 名称（4–64 个 ASCII 字母、数字、下划线或连字符），服务端生成智能体 ID 并注入 Agent 和 Worker。北京地域新请求自动使用默认 VLM 和 Embedding 模型创建独立 OpenViking 库，无需手动填写服务地址和 API Key；BytePlus 和已提交的手动请求仍需填写 OpenViking 服务地址、资源 ID 和 API Key。提交后依次准备账号网络、APIG、Worker、独立业务库和 Skill Space，然后部署并检查 Runtime 就绪状态。成功后刷新列表查看。

新创建的 MPA 智能体默认使用独立业务 Workspace：每个智能体使用独立的业务数据库，通过 managed.postgres.business-workspace-mode: per-agent 和 managed.postgres.business-database-name: aidb 配置。省略这两项则沿用共享业务库布局。运行时名称在创建前会进行可用性预检，避免与已存在的 Runtime 或 Worker 模板重名。

Studio 内置配置使用北京地域的默认镜像和模型。模型 API Key 从 VEADK_MPA_CONFIG_MODEL_AGENT_API_KEY 环境变量读取。选择其他地域时 Studio 会返回配置错误。

Studio 托管创建 MPA 智能体时，配置中引用的 latest 镜像标签会在部署前被匿名解析为同一公共仓库中已发布且 manifest digest 完全一致的具体版本标签，并持久化该选择。即使 latest 后续移动，重试部署时仍验证已保存的版本标签，确保部署内容不变。镜像发布方须在每次发布 latest 的同时保留对应的版本标签，且不得覆盖已有标签。若无匹配的版本标签、公共读取不可用或保存内容发生变更，部署将明确失败。使用固定版本标签的部署、已有智能体和独立 CLI 部署不受此行为影响。

创建 MPA 智能体失败时，Studio 会显示本地化的安全原因，并支持展开和复制失败阶段、操作，以及可选的已校验错误码与请求 ID；不展示原始 SDK、SQL 或异常文本。已知的配额、鉴权、超时和资源状态错误会给出对应的安全说明，缺失的细节会明确标注为未知。成功创建与通用智能体视图不受影响。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

前置条件

命令总览

使用 YAML 配置部署

通过命令行创建

初始化管理数据库

控制面命令

查看智能体

创建智能体

更新智能体

操作管理

配置版本管理

会话配置管理

删除预览

在 Studio 中使用

​前置条件

​命令总览

​使用 YAML 配置部署

​通过命令行创建

​初始化管理数据库

​控制面命令

​查看智能体

​创建智能体

​更新智能体

​操作管理

​配置版本管理

​会话配置管理

​删除预览

​在 Studio 中使用

前置条件

命令总览

使用 YAML 配置部署

通过命令行创建

初始化管理数据库

控制面命令

查看智能体

创建智能体

更新智能体

操作管理

配置版本管理

会话配置管理

删除预览

在 Studio 中使用