火山方舟
火山方舟
资源
请输入
- 文档首页
火山方舟实践教程Managed Agent[进阶] 使用 Vaults 让开发 Agent 以用户身份提交 GitHub PR
复制全文
下载 pdf[进阶] 使用 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 服务器 URL 与 Token 的配对；支持 static_bearer、mcp_oauth、environment_variable 三种类型 |
Session 级凭据绑定 | 创建 Session 时传入 vault_ids，运行时按 URL 自动匹配凭据并注入；Agent 定义不感知任何用户信息 |
GitHub MCP | 通过 MCP 协议把 GitHub 的仓库、分支、PR 操作暴露为 Agent 工具 |
工作流程
前置条件
- 已开通方舟 Managed Agents 和目标模型服务。
- 已创建 API Key，详情请参见 API Key 管理。
- 每个使用助手的成员，需在 GitHub「Settings → Developer settings → Fine-grained tokens」创建一个 PAT，按最小权限收敛。
将 API Key 与 Base URL 配置为环境变量：
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：
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 记录：
{
"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 类型，无需刷新流程：
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 能代表不同用户行动的前提。
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_server_name 字段与之对应引用，反之亦然。
若 MCP 服务器暴露的工具很多，可以在 mcp_toolset 上用 default_config: {"enabled": false} 加 configs 白名单按需开启。
创建 Environment（name 在当前 project 内须唯一）：
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} 对象）：
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。
运行时的凭据匹配机制：
Agent 声明 mcp_servers[].url = https://api.githubcopilot.com/mcp/
Session 携带 vault_ids = [vlt_alice]
运行时 在 vlt_alice 中查找 mcp_server_url 精确等于该 URL 的凭据
命中 : 连接 MCP 服务器时自动注入 Alice 的 PAT
未命中 : 尝试匿名连接（服务器要求鉴权则报错）
多个命中 : 第一个匹配的 Vault 优先
多用户隔离在这一步自然成立：
一份 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 开始工作：
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 描述写清根因分析。"
}]
}]
}'
任务执行的关键步骤：
- 定位与开发：Agent 通过 GitHub MCP 读取仓库——从这一刻起使用 Alice 的 PAT——把代码拉进云沙箱，定位到金额计算中分转元使用浮点除法的问题，改为整数分运算并补充测试。
- 沙箱内自测：运行测试套件，确认新增用例通过、存量用例不回归。
- 以 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} | 成员离职时使用，级联删除其全部凭据，不可恢复 |
警告
删除是唯一的撤权手段且不可恢复。执行删除操作前，请确认对象是否正确。
说明
凭据会在 Session 运行期间周期性重新解析，轮换、删除都会自动传播到运行中的 Session，无需重启。
凭据失效的处理
凭据失效的暴露时机分两段：
- 首次校验失败：MCP 类凭据可能在创建或首次使用阶段暴露配置问题。
- 运行期失效：存入后才失效的凭据，会在 Session 访问 GitHub 时表现为鉴权错误。
应用侧应根据事件与 Session 状态判断是否可继续，不能统一假设错误不会终止 Session。监听到错误后，可凭 Vault metadata 中的 external_user_id 反查用户，引导其轮换 Token；是否复用原 Session，应以当次错误语义和官方恢复机制为准。
最近更新时间：2026.09.14 15:01:49
这个页面对您有帮助吗？
有用
有用
无用
无用