本教程演示如何使用方舟 Managed Agents 的 **Vaults 凭据托管** 能力，构建一个接入 GitHub 的团队开发助手：团队成员提交需求或缺陷描述，Agent 在云沙箱中完成开发，并以成员本人的身份创建分支、提交 PR。全程凭据由平台托管，Agent 与业务代码都接触不到明文 Token。 # 场景说明一个典型的团队开发助手工作方式如下：成员在 IM 或内部平台用自然语言提交需求或缺陷（例如「结算页两券叠加时金额多 0.01 元，修一下」），Agent 在云沙箱中拉取代码、定位问题、开发自测，最后回到 GitHub 创建分支、提交 PR。整个过程成员不需要打开 IDE。这里绕不开一个问题：Agent 操作 GitHub 时，用谁的身份？共享一个机器人账号是最容易想到的做法，也是问题最多的做法： |维度 |共享机器人账号 |以用户身份（本教程方案） | |---|---|---| |权限边界 |机器人需要开通所有成员会用到的仓库权限，权限必然过大 |复用每个成员自己的仓库权限，天然收敛 | |审计追溯 |所有 PR 都是同一个 author，出了问题查不到人 |PR author 即需求提交人，审计链路不断 | |协作体验 |Reviewer 不知道该找谁讨论方案 |直接 @ PR 作者本人 | Vaults 是「以用户身份」这条路的基础设施。它不是全局配置中心，而是每个终端用户一只的凭据保险柜——平台在 Agent 粒度上管理产品配置，在 Session 粒度上管理用户凭据。 # 核心概念 |能力点 |说明 | |---|---| |Vault |绑定到某个终端用户的凭据集合，存放该用户的第三方服务 Token；通过 `metadata` 与业务系统的用户 ID 双向映射 | |Credential |Vault 内的一条凭据 = MCP 服务器 URL 与 Token 的配对；支持 `static_bearer`、`mcp_oauth`、`environment_variable` 三种类型 | |Session 级凭据绑定 |创建 Session 时传入 `vault_ids`，运行时按 URL 自动匹配凭据并注入；Agent 定义不感知任何用户信息 | |GitHub MCP |通过 MCP 协议把 GitHub 的仓库、分支、PR 操作暴露为 Agent 工具 | # 工作流程 ![图片](https://arkdocs.tos-cn-beijing.volces.com/flowcharts/tutorials/new-202607241247.svg) # 前置条件 * 已开通方舟 Managed Agents 和目标模型服务。 * 已创建 API Key，详情请参见 [API Key 管理](https://www.volcengine.com/docs/82379/1361424)。 * 每个使用助手的成员，需在 GitHub「Settings → Developer settings → Fine\-grained tokens」创建一个 PAT，按最小权限收敛。将 API Key 与 Base URL 配置为环境变量： ```Bash export ARK_API_KEY="your_api_key_here" export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" ``` # 第 1 步：准备 GitHub Fine\-grained PAT 推荐按下表配置 PAT 权限，只授予助手需要的仓库和最小权限： |配置项 |建议值 |用途 | |---|---|---| |Repository access |只勾选目标仓库（如 `payments-web`），不选 All repositories |收敛可访问仓库范围 | |Contents |Read and write |拉代码、推分支 | |Pull requests |Read and write |创建 PR | |Metadata |Read\-only |GitHub 强制要求 |

警告

PAT 的权限就是 Agent 能力的上限，也是出事时的止损边界。Agent 可以执行该 Key 允许的任何操作，过权 Key 会在 Agent 异常时扩大事故影响范围。宁可先给窄、用到再加——Vaults 隔离的是「谁的凭据」，管不了「这个凭据本身有多大权力」。

# 第 2 步：为用户创建 Vault 成员 Alice 首次使用助手时，为她创建一只 Vault： ```Bash curl "$ARK_BASE_URL/vaults" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Alice", "metadata": { "external_user_id": "usr_alice_001", "team": "payments" } }' ``` 响应是完整的 Vault 记录： ```JSON { "type": "vault", "id": "vlt-20260701120000-pqrst", "display_name": "Alice", "metadata": {"external_user_id": "usr_alice_001", "team": "payments"}, "created_at": "2026-07-08T10:00:00Z", "updated_at": "2026-07-08T10:00:00Z" } ``` 请求字段说明： |参数 |必填 |说明 | |---|---|---| |`display_name` |是 |控制台展示名 | |`metadata` |否 |任意键值对，用于把 Vault 映射回业务系统的用户记录；后续凭据失效需要找人重新授权，靠它反查 | 将返回的 `id` 存入业务系统的用户表——这是该用户在 Managed Agents 中的身份锚点。

注意

Vaults 与凭据按工作空间隔离，同工作空间的 API Key 都能引用；要撤销访问，删除对应 Vault 或凭据即可。

# 第 3 步：写入 GitHub 凭据凭据把「MCP 服务器 URL」和「访问它用的 Token」配成一对。GitHub PAT 属于固定 Bearer token，用 `static_bearer` 类型，无需刷新流程： ```Bash curl "$ARK_BASE_URL/vaults/$VAULT_ID/credentials" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Alice GitHub PAT", "auth": { "type": "static_bearer", "mcp_server_url": "https://api.githubcopilot.com/mcp/", "token": "github_pat_xxxxxxxxxxxx" } }' ``` 三种凭据类型按目标服务的认证方式选择： |类型 |适用 |密钥字段 | |---|---|---| |`static_bearer` |固定 API Key / PAT（GitHub、Linear 等）——本教程场景 |`token` | |`mcp_oauth` |OAuth 2.0 的 MCP 服务（Slack、Google Drive 等），提供 `refresh` 块后平台代刷令牌 |`access_token` + `refresh` | |`environment_variable` |沙箱内 CLI / SDK 走环境变量鉴权的场景，用 `allowed_hosts` 限制密钥可发往的主机 |`secret_name` + `secret_value` | 三个值得知道的行为： * 创建即校验：MCP 类凭据（`static_bearer` / `mcp_oauth`）创建时，平台会立即连接目标 MCP 服务器探测握手。PAT 写错会直接返回 4xx、创建失败，不会拖到 Session 运行时才暴露。 * 密钥 write\-only：`token` 等实际密钥被视为敏感的只写字段，永远不会在 API 响应中返回。 * `mcp_server_url` 唯一且不可变：`mcp_server_url` 在 Vault 的活跃凭据中必须唯一（重复返回 409），且创建后锁定——要改 URL 只能删旧建新。每个 Vault 最多 20 个凭据。 # 第 4 步：创建 Agent 与 Environment Agent 定义只声明「要连接哪些 MCP 服务器」，不含任何凭据——平台把 MCP 配置明确拆成两层：Agent 定义层声明连接目标，Session 运行层注入凭据。这是同一个 Agent 能代表不同用户行动的前提。 ```Bash curl "$ARK_BASE_URL/agents" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "team-dev-assistant", "model": {"id": "doubao-seed-2-1-pro-260628"}, "system": "你是团队开发助手。收到需求或缺陷描述后，在沙箱中完成开发与自测，并通过 GitHub 工具以当前用户身份创建分支、提交 PR。", "mcp_servers": [ { "type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/" } ], "tools": [ {"type": "agent_toolset_20260701"}, {"type": "mcp_toolset", "mcp_server_name": "github"} ] }' ``` 两条声明约束： * `mcp_servers` 里的 `name` 在同一个 Agent 内必须唯一。 * 每个 `mcp_servers` 条目必须有同名的 `mcp_toolset` 与之对应，反之亦然。若 MCP 服务器暴露的工具很多，可以在 `mcp_toolset` 上用 `default_config: {"enabled": false}` 加 `configs` 白名单按需开启。创建 Environment（`name` 在当前 project 内须唯一）： ```Bash curl "$ARK_BASE_URL/environments" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "dev-assistant-env", "config": {"type": "cloud", "networking": {"type": "unrestricted"}} }' ```

注意

unrestricted 只适合演示和受控测试。生产环境应按 GitHub MCP、代码仓库和必要依赖配置最小网络白名单，并与 Vault 凭据的允许主机共同收敛出口。

# 第 5 步：创建 Session 并绑定 Vault Session 是绑定发生的地方——`vault_ids` 一传，这条 Session 里 Agent 对 GitHub 的所有调用都会自动带上 Alice 的 PAT。`agent` 字段传字符串 ID 即使用该 Agent 的最新版本（需要锁定版本做灰度时，改传 `{"type": "agent", "id": "...", "version": 1}` 对象）： ```Bash curl "$ARK_BASE_URL/sessions" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent": "'"$AGENT_ID"'", "environment_id": "'"$ENV_ID"'", "vault_ids": ["'"$VAULT_ID"'"], "title": "fix: 结算页金额四舍五入缺陷" }' ``` 响应中 `status` 为 `idle`：创建 Session 只完成沙箱配置，不会启动任何工作。这个解耦让开发者可以先挂好 Vaults 凭据、检查环境，再发送首个事件启动 Agent。运行时的凭据匹配机制： ```Text Agent 声明 mcp_servers[].url = https://api.githubcopilot.com/mcp/ Session 携带 vault_ids = [vlt_alice] 运行时在 vlt_alice 中查找 mcp_server_url 精确等于该 URL 的凭据命中 : 连接 MCP 服务器时自动注入 Alice 的 PAT 未命中 : 尝试匿名连接（服务器要求鉴权则报错）多个命中 : 第一个匹配的 Vault 优先 ``` 多用户隔离在这一步自然成立： ```Text 一份 Agent 定义（全团队复用） mcp_servers: github -> https://api.githubcopilot.com/mcp/ Alice 的 Vault (vlt-...pqrst) Bob 的 Vault (vlt-...uvwxy) PAT: github_pat_alice_... PAT: github_pat_bob_... Session A: vault_ids=[vlt_alice] -> 提交的 PR author 是 Alice Session B: vault_ids=[vlt_bob] -> 提交的 PR author 是 Bob ``` # 第 6 步：下发任务并观察执行向 Session 的事件入口发送 Alice 的缺陷描述。`user.message` 事件发出后，Session 从 `idle` 切换到 `running`，Agent 开始工作： ```Bash curl "$ARK_BASE_URL/sessions/$SESSION_ID/events" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "events": [{ "type": "user.message", "content": [{ "type": "text", "text": "结算页缺陷：叠加使用满减券和折扣券时，应付金额比手算结果多 0.01 元，疑似分转元时的浮点精度问题。1、在 payments-web 仓库定位金额计算逻辑并修复；2、补充单元测试，覆盖两券叠加的边界用例；3、创建分支提交 PR，PR 描述写清根因分析。" }] }] }' ``` 任务执行的关键步骤： 1. 定位与开发：Agent 通过 GitHub MCP 读取仓库——从这一刻起使用 Alice 的 PAT——把代码拉进云沙箱，定位到金额计算中分转元使用浮点除法的问题，改为整数分运算并补充测试。 2. 沙箱内自测：运行测试套件，确认新增用例通过、存量用例不回归。 3. 以 Alice 身份提 PR：Agent 调用 GitHub MCP 的分支与 PR 工具，创建 `fix/coupon-rounding` 分支并提交 PR。打开 GitHub 验证效果：PR 的 author 是 Alice 本人，commit 归属、通知、review 流程与她手工提交完全一致。期间可通过 SSE 流实时跟踪进度（`GET /sessions/{session_id}/events/stream`，`Accept: text/event-stream`）。把 `agent.message` 当阶段结果，把 `session.status_idle` 当完成信号；`agent.tool_use` 可用于展示工具进度。

注意

不要以连接关闭或单条文本作为终态。客户端应记录事件 ID、去重，并在断线后通过事件历史或官方恢复机制补齐，再继续订阅。

# 安全模型与多租户隔离 Token 全链路不可见，这是 Vaults 与「把 Token 塞进 prompt 或沙箱环境变量」的本质区别： |环节 |行为 | |---|---| |API 层 |凭据 write\-only，任何读接口不返回密钥值 | |沙箱内 |Agent 看不到明文；`environment_variable` 类型在沙箱内呈现为不透明占位符 | |出口注入 |替换发生在沙箱出口处，不在沙箱内——真实值不经过模型上下文 | |网络限制 |`environment_variable` 类型用 `allowed_hosts` 限制密钥可发往的主机；该域名还须同时在 Environment 网络白名单中允许，两层都过才能成功 |

注意

Vault 能显著降低明文 Token 进入模型上下文或业务日志的风险，但不等于阻止越权操作：一旦 Agent 被错误指令控制，仍可能在该用户凭据允许的范围内调用工具。真正的安全边界来自最小权限 PAT、网络白名单、工具白名单、写操作确认和完整审计的组合。

# 生命周期管理 |操作 |接口 |行为 | |---|---|---| |轮换密钥 |`POST /vaults/{vault_id}/credentials/{credential_id}` |可更新密钥值与 `display_name`；结构性字段（`mcp_server_url` 等）创建后锁定，要改只能删旧建新 | |删除凭据 |`DELETE .../credentials/{credential_id}` |硬删除，相关记录与密钥一并清除，不可恢复 | |删除 Vault |`DELETE /vaults/{vault_id}` |成员离职时使用，级联删除其全部凭据，不可恢复 | |诊断 OAuth 凭据 |`POST .../credentials/{credential_id}/mcp_oauth_validate` |返回 `valid` / `invalid` / `unknown` 三种状态（本教程 PAT 场景用不到） |

警告

删除是唯一的撤权手段且不可恢复。执行删除操作前，请确认对象是否正确。

说明

凭据会在 Session 运行期间周期性重新解析，轮换、删除都会自动传播到运行中的 Session，无需重启。

# 凭据失效的处理凭据失效的暴露时机分两段： * 首次校验失败：MCP 类凭据可能在创建或首次使用阶段暴露配置问题。 * 运行期失效：存入后才失效的凭据，会在 Session 访问 GitHub 时表现为鉴权错误。应用侧应根据事件与 Session 状态判断是否可继续，不能统一假设错误不会终止 Session。监听到错误后，可凭 Vault `metadata` 中的 `external_user_id` 反查用户，引导其轮换 Token；是否复用原 Session，应以当次错误语义和官方恢复机制为准。

火山方舟