火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟Managed Agents委派任务给 Agent使用 Vaults 认证
复制全文
下载 pdf使用 Vaults 认证
文档反馈
问问助手当你使用 Managed Agents 构建需要访问第三方服务的应用时，可以通过 Vaults（凭据保管库）保存并隔离每个应用用户的凭据。你的服务端只需为每个用户创建 Vault、写入 Credential，并保存用户与 vault_id 的映射，无需自行维护密钥存储，也无需在每次调用中重复传递 token。
创建 Session 时，通过 vault_ids 传入当前用户的 Vault ID；Agent 调用 MCP 服务时会自动使用对应的 Credential 完成鉴权。这样，同一个 Agent 可以安全地服务多个用户，并分别访问各自有权限的第三方资源。
示例
你使用 Managed Agents 构建了一个 GitHub 代码助手。Alice 发起任务时，服务端创建 Session 并绑定 Alice 的 Vault，Agent 使用 Alice 的 GitHub 权限；Bob 发起任务时，服务端绑定 Bob 的 Vault，Agent 使用 Bob 的 GitHub 权限。
准备工作
开始前你需要：
- 已创建的 API Key：配置为环境变量 ARK_API_KEY，详情请参见 API Key 管理。
- 已创建的 Agent：详情请参见 定义 Agent。
- 已创建的 Environment：详情请参见 配置云环境。
创建 Vaults
注意
作用域。 Vaults 与凭据按工作空间隔离，同工作空间的 API Key 都能引用。要撤销访问，删除对应 Vaults 或凭据。
Vaults 是绑定到某个终端用户的凭据集合。给它一个 display_name，可选用 metadata 标记以便映射回你自己的用户记录：
curl https://ark.cn-beijing.volces.com/api/v3/vaults \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Alice",
"metadata": {"external_user_id": "usr_abc123"}
}'
响应是完整的 Vaults 记录：
{
"type": "vault",
"id": "vlt-20260701120000-pqrst",
"display_name": "Alice",
"metadata": {"external_user_id": "usr_abc123"},
"created_at": "2026-06-29T10:00:00Z",
"updated_at": "2026-06-29T10:00:00Z"
}
添加凭据——三种类型
类型 | 适用场景 | 注入方式 |
mcp_oauth | MCP 服务器用 OAuth 2.0 | 平台代刷 token，Session 连接 MCP URL 时自动注入 |
static_bearer | MCP 用固定 Bearer token（API Key、个人访问令牌） | 无刷新流程，直接注入 |
environment_variable | 通过环境变量鉴权的命令行、SDK、直接 API 调用 | 沙箱内是不透明占位符，出口处替换为真实值，Agent 永远看不到密钥 |
你提供的实际密钥（token、access_token、refresh_token、client_secret、secret_value） 被视为敏感的只写字段，永远不会在 API 响应中返回。
MCP OAuth 凭据
当 MCP 服务器使用 OAuth 2.0 时，用 mcp_oauth。提供 refresh 块后，平台会在 access token 过期时代你刷新。
refresh.token_endpoint_auth.type 三选一：
- none：公共客户端。
- client_secret_basic：使用 client_secret 的 HTTP Basic 鉴权。
- client_secret_post：把 client_secret 放在 POST 请求体里。
curl https://ark.cn-beijing.volces.com/api/v3/vaults/vlt-20260701120000-pqrst/credentials \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Alice Slack",
"auth": {
"type": "mcp_oauth",
"mcp_server_url": "https://mcp.slack.com/mcp",
"access_token": "xoxp-...",
"expires_at": "2099-12-31T23:59:59Z",
"refresh": {
"token_endpoint": "https://slack.com/api/oauth.v2.access",
"client_id": "1234567890.0987654321",
"scope": "channels:read chat:write",
"refresh_token": "xoxe-1-...",
"token_endpoint_auth": {
"type": "client_secret_post",
"client_secret": "abc123..."
}
}
}
}'
MCP 静态 Bearer 凭据
当 MCP 服务器接受固定 Bearer token（API Key、个人访问令牌） 时，用 static_bearer。无需刷新流程：
curl https://ark.cn-beijing.volces.com/api/v3/vaults/vlt-20260701120000-pqrst/credentials \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Linear API key",
"auth": {
"type": "static_bearer",
"mcp_server_url": "https://mcp.linear.app/mcp",
"token": "lin_api_your_linear_key"
}
}'
环境变量凭据
用 environment_variable 通过环境变量对外部服务鉴权，适用于命令行、SDK 或直接 API 调用。
networking.allowed_hosts 控制密钥可以被替换到哪些出站主机：
- "type": "limited" + 显式主机列表（推荐）。
- "type": "unrestricted"（仅当调用方访问的域名无法提前枚举时使用）。
curl https://ark.cn-beijing.volces.com/api/v3/vaults/vlt-20260701120000-pqrst/credentials \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Notion API key for sandbox",
"auth": {
"type": "environment_variable",
"secret_name": "NOTION_API_KEY",
"secret_value": "sk-your-secret-here",
"networking": {
"type": "limited",
"allowed_hosts": ["api.notion.com"]
}
}
}'
注意
- 替换发生在沙箱出口处，不在沙箱内。 沙箱里的进程看到的是不透明占位符，而不是真实值。两点影响：
- 启动时校验凭据格式的客户端可能拒绝占位符。
- 用密钥做请求签名的客户端（例如 AWS SigV4） 会生成无效签名。
- 环境变量凭据只适合「把密钥值原样塞进出站请求头」的客户端。
- networking.allowed_hosts 控制密钥能替换到哪些出站主机，强烈建议用 type: limited + 显式主机列表，避免密钥被发到未授权主机。此外，该域名还必须在 Environment 网络白名单 中允许，两层都包含才能成功。
说明
替换仅出站方向。 如果客户端使用存储的密钥来交换 session token（例如 OAuth 客户端凭据授权），返回的 token 会以未脱敏形式到达沙箱。对于基于交换的流程，请自行执行交换，把交换后的 token 存进 Vaults 。
说明
最小权限原则。 把 API Key 的权限范围限定为 Agent 所需的最小集合。Agent 可以执行该 Key 允许的任何操作，过权 Key 会在 Agent 异常时扩大事故影响范围。
凭据约束
- 每 Vaults 内 key 必须唯一。 mcp_server_url（MCP 凭据） 和 secret_name（环境变量凭据） 在 Vaults 的活跃凭据中必须唯一。创建重复返回 409。
- key 不可变。 要改 mcp_server_url、secret_name，删除旧凭据再创建新的。
- 每 Vaults 最多 20 个凭据。
MCP 类型凭据（mcp_oauth、static_bearer）在创建时会立即连接目标 MCP 服务器探测握手，无效凭据会直接返回 4xx 错误、创建失败；environment_variable 类型凭据不在创建时校验，无效密钥会在 Session 运行期间访问对应主机时以鉴权错误或下游错误的形式出现，该错误会被发出，但不会阻止 Session 继续。
在创建 Session 时引用 Vaults
创建 Session 时传 vault_ids 数组，把一个或多个 Vaults 挂到 Session：
curl https://ark.cn-beijing.volces.com/api/v3/sessions \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": "agent-20260701120000-abcde",
"environment_id": "env-20260701120000-fghij",
"vault_ids": ["vlt-20260701120000-pqrst"],
"title": "Alice Slack digest"
}'
运行时行为：
- 当 Agent 连接到某 MCP URL 时，没有任何凭据匹配 mcp_server_url → 尝试匿名连接；若服务器要求鉴权则报错。
- 多个 Vaults 都包含匹配凭据 → 第一个匹配的 Vaults 优先。
- 在 多 Agent 中，Vaults 凭据按线程生效；若某 Agent 自身定义里声明了匹配的 MCP 服务器，该 Agent 用这些凭据鉴权。
轮换凭据
密钥值和 display_name 可以更新。结构性字段（mcp_server_url、secret_name、token_endpoint、client_id） 在创建后即被锁定。要修改结构性字段，删除旧凭据再创建新的：
curl https://ark.cn-beijing.volces.com/api/v3/vaults/vlt-20260701120000-pqrst/credentials/vcrd-20260701120500-uvwxy \
-X POST \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"auth": {
"type": "mcp_oauth",
"access_token": "xoxp-new-...",
"expires_at": "2099-12-31T23:59:59Z",
"refresh": {"refresh_token": "xoxe-1-new-..."}
}
}'
凭据生命周期
凭据会在 Session 期间与 Vaults 生命周期内周期性重新解析。这确保凭据的轮换、删除、刷新失败都能传播到正在运行的 Session，无需重启。
对于 mcp_oauth 凭据，重新解析还会在 access token 过期时刷新它。如果刷新失败，系统会记录失败事件。未来版本将支持通过 Webhook 订阅 vault.* / vault_credential.* 事件，届时可在本节订阅这些生命周期事件。
事件 | 触发 |
vault.deleted | Vaults 被删除（级联触发底层凭据 vault_credential.deleted） |
vault_credential.deleted | 凭据被删除（直接删除或因 Vaults 删除） |
vault_credential.refresh_failed | mcp_oauth 凭据刷新失败（refresh token 无效，或 OAuth 服务器返回不可恢复错误） |
其他操作
- 列出 Vaults 、凭据：GET /vaults 或 GET /vaults/{id}/credentials；分页返回，按最新优先排序。
- 删除 Vaults 、凭据：硬删除，所有相关记录与密钥一并清除，不可恢复。
最近更新时间：2026.09.14 21:18:07
这个页面对您有帮助吗？
有用
有用
无用
无用