文档中心

火山方舟

Managed Agent

[进阶] 使用 Vaults 让开发 Agent 以用户身份提交 GitHub PR

本教程演示如何使用方舟 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_oauth、static_bearer、mcp_static、environment_variable 和 env_oauth 五种类型；本教程使用 static_bearer
Session 级凭据绑定	创建 Session 时传入 vault_ids，运行时按 URL 自动匹配凭据并注入；Agent 定义不感知任何用户信息
GitHub MCP	通过 MCP 协议把 GitHub 的仓库、分支、PR 操作暴露为 Agent 工具

工作流程

前置条件

已开通方舟 Managed Agents 和目标模型服务。

方舟 API Key：已创建 API Key，详情请参见 API Key 管理。

每个使用助手的成员，需在 GitHub「Settings → Developer settings → Fine-grained tokens」创建一个 PAT，按最小权限收敛。

本地已安装 Bash、curl 7.76.0 或更高版本，以及 jq。

将 API Key 与 Base URL 配置为环境变量：

第 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：

响应是完整的 Vault 记录：

请求字段说明：

参数	必填	说明
display_name	是	控制台展示名
metadata	否	任意键值对，用于把 Vault 映射回业务系统的用户记录；后续凭据失效需要找人重新授权，靠它反查

将返回的 id 存入业务系统的用户表：这是该用户在 Managed Agents 中的身份锚点。

权限边界

Vault 和凭据在工作空间内共享，不按 API Key 单独隔离。持有同一工作空间任一 API Key 的服务，都可以通过 Vault ID 在 Session 中引用其中的凭据。仅向受信任的服务开放工作空间 API Key。

第 3 步：写入 GitHub 凭据

凭据把「MCP 服务器 URL」和「访问它用的 Token」配成一对。GitHub PAT 属于固定 Bearer token，使用 static_bearer 类型。以下脚本通过无回显输入读取 PAT，将密钥和请求体写入仅当前用户可读的临时文件，并在请求结束后删除文件：

脚本不会把 PAT 放进命令行参数或可持久化的命令文本。响应中的凭据 ID 会保存为 CREDENTIAL_ID。

五种凭据类型按目标服务的认证方式选择：

类型	适用	密钥字段
static_bearer	固定 API Key / PAT（GitHub、Linear 等）：本教程场景	token
mcp_oauth	OAuth 2.0 的 MCP 服务（Slack、Google Drive 等），提供 refresh 块后平台代刷令牌	access_token + refresh
mcp_static	MCP 使用固定密钥，需要以 Bearer、自定义 Header 或 URL 查询参数注入	token + injection_type，部分类型还需 injection_name
environment_variable	沙箱内 CLI / SDK 走环境变量鉴权的场景，用 allowed_hosts 限制密钥可发往的主机	secret_name + secret_value
env_oauth	沙箱内 CLI / SDK 从环境变量读取 OAuth 访问令牌	access_token + secret_name + networking

三个值得知道的行为：

创建即校验：MCP 类凭据（static_bearer、mcp_oauth、mcp_static）创建时，平台会立即连接目标 MCP 服务器探测握手。PAT 写错会直接返回 4xx、创建失败，不会拖到 Session 运行时才暴露。

密钥只写：字段 token 等实际密钥被视为敏感的只写字段，永远不会在 API 响应中返回。

MCP Server URL 唯一且不可变：字段 mcp_server_url 在 Vault 的活跃凭据中必须唯一（重复返回 409），且创建后锁定。要改 URL 只能删旧建新。每个 Vault 最多包含 100 个凭据。

第 4 步：创建 Agent 与 Environment

Agent 定义只声明「要连接哪些 MCP 服务器」，不含任何凭据：平台把 MCP 配置明确拆成两层：Agent 定义层声明连接目标，Session 运行层注入凭据。这是同一个 Agent 能代表不同用户行动的前提。

两条声明约束：

mcp_servers 里的 url 在同一个 Agent 内不能重复；name 冲突时，服务端会自动追加数字后缀，调用方无需保证名称唯一。

每个 mcp_servers 条目必须有一个 mcp_toolset 通过 mcp_server_name 字段与之对应引用，反之亦然。

若 MCP 服务器暴露的工具很多，可以在 mcp_toolset 上用 default_config: {"enabled": false} 加 configs 白名单按需开启。

创建 Environment（name 在当前 project 内须唯一）：

注意

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

第 5 步：创建 Session 并绑定 Vault

Session 是绑定发生的地方：vault_ids 一传，这条 Session 里 Agent 对 GitHub 的所有调用都会自动带上 Alice 的 PAT。agent 字段传字符串 ID 即使用该 Agent 的最新版本（需要锁定版本做灰度时，改传 {"type": "agent", "id": "...", "version": 1} 对象）：

响应中 status 为 idle：创建 Session 只完成沙箱配置，不会启动任何工作。这个解耦让开发者可以先挂好 Vaults 凭据、检查环境，再发送首个事件启动 Agent。

运行时的凭据匹配机制：

多用户隔离在这一步自然成立：

第 6 步：下发任务并观察执行

先加载可靠事件处理函数。该函数会建立 SSE 并等待 : ready，再发送 user.message；连接中断时，函数先重连，再分页补查历史事件并按事件 ID 去重：

发送 Alice 的缺陷描述：

任务执行的关键步骤：

定位与开发：Agent 通过 GitHub MCP 读取仓库：从这一刻起使用 Alice 的 PAT：把代码拉进云沙箱，定位到金额计算中分转元使用浮点除法的问题，改为整数分运算并补充测试。

沙箱内自测：运行测试套件，确认新增用例通过、存量用例不回归。

以 Alice 身份提 PR：Agent 调用 GitHub MCP 的分支与 PR 工具，创建 fix/coupon-rounding 分支并提交 PR。打开 GitHub 验证效果：PR 的 author 是 Alice 本人，commit 归属、通知、review 流程与她手工提交完全一致。

run_session_turn 只在收到 session.status_idle、stop_reason.type=end_turn 且已经收到完整 agent.message 时返回状态码 0。返回 2 表示 Session 仍在等待工具确认；返回 3 表示本轮重试耗尽；返回 4 表示 Session 已终止或发生不可恢复错误。

注意

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

安全模型与多租户隔离

Token 全链路不可见，这是 Vaults 与「把 Token 塞进 prompt 或沙箱环境变量」的本质区别：

环节	行为
API 层	凭据 write-only，任何读接口不返回密钥值
沙箱内	Agent 看不到明文；environment_variable 类型在沙箱内呈现为不透明占位符
出口注入	替换发生在沙箱出口处，不在沙箱内：真实值不经过模型上下文
网络限制	Credential 的 networking.allowed_hosts 限制凭据可以注入哪些出站主机

注意

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}	成员离职时使用，级联删除其全部凭据，不可恢复

警告

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

说明

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

凭据失效的处理

凭据失效的暴露时机分两段：

首次校验失败：MCP 类凭据可能在创建或首次使用阶段暴露配置问题。

运行期失效：存入后才失效的凭据，会在 Session 访问 GitHub 时表现为鉴权错误。

应用侧应根据事件与 Session 状态判断是否可继续，不能统一假设错误不会终止 Session。监听到错误后，可凭 Vault metadata 中的 external_user_id 反查用户，引导其轮换 Token；是否复用原 Session，应以当次错误语义和官方恢复机制为准。

最近更新时间：2026.10.28 19:53:17

这个页面对您有帮助吗？

有用

无用