使用保险库进行身份验证

保险库和凭证是身份验证原语，允许您为第三方服务注册凭证一次，然后在会话创建时通过 ID 引用它们。这意味着您不需要运行自己的密钥存储、在每次调用时传输令牌，或者丢失跟踪代理代表哪个最终用户行动的信息。

保险库引用是每个会话的参数，因此您可以在代理级别管理您的产品，在会话级别管理您的用户。

创建保险库

保险库是与最终用户关联的 credentials 的集合。给它一个 display_name，并可选地用 metadata 标记它，以便您可以将其映射回您自己的用户记录。

VAULT_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)

响应是完整的保险库记录：

{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}

添加凭证

每个凭证绑定到单个 mcp_server_url。当代理在会话运行时连接到 MCP 服务器时，API 会将服务器 URL 与引用的保险库上的活跃凭证进行匹配，并注入令牌。

凭证按提供的方式存储，在会话运行时之前不会进行验证。坏令牌会在会话期间显示为 MCP 身份验证错误，该错误会被发出但不会阻止会话继续。

约束条件：

• 每个保险库每个 mcp_server_url 只有一个活跃凭证。 为同一 URL 创建第二个凭证会返回 409。
• mcp_server_url 是不可变的。 要指向不同的服务器，请存档此凭证并创建一个新的。
• 每个保险库最多 20 个凭证。 这与每个代理的最大 MCP 服务器数量相匹配。

轮换凭证

只有密钥有效负载和少数几个元数据字段是可变的。mcp_server_url、token_endpoint 和 client_id 在创建后被锁定。

ant beta:vaults:credentials update \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" <<'EOF'
auth:
  type: mcp_oauth
  access_token: xoxp-new-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    refresh_token: xoxe-1-new-...
EOF

在会话创建时引用保险库

在创建会话时传递 vault_ids：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    title="Alice's Slack digest",
)

运行时行为：

• 凭证在会话期间定期重新解析，因此轮换或存档会传播到运行中的会话，无需重启。
• 当保险库没有 MCP 服务器的凭证时，连接会尝试未经身份验证的方式并产生错误。
• 当多个保险库覆盖 MCP 服务器时，第一个匹配的保险库获胜。

其他操作

• 列出保险库或凭证： 分页，最新的优先。默认情况下排除已存档的记录（传递 include_archived=true 以包含它们）。
• 存档保险库： POST /v1/vaults/{id}/archive。级联到所有凭证。密钥被清除；记录被保留用于审计。引用此保险库的未来会话失败；运行中的会话继续。
• 存档凭证： POST /v1/vaults/{id}/credentials/{cred_id}/archive。清除密钥有效负载；mcp_server_url 保持可见。释放 mcp_server_url 以供替换凭证使用。
• 删除保险库或凭证： 硬删除。记录不被保留。如果您需要审计跟踪，请使用存档。