Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
保险库和凭证是身份验证原语,允许您为第三方服务注册凭证一次,然后在会话创建时通过 ID 引用它们。这意味着您不需要运行自己的密钥存储、在每次调用时传输令牌,或者丢失跟踪代理代表哪个最终用户行动的信息。
保险库引用是每个会话的参数,因此您可以在代理级别管理您的产品,在会话级别管理您的用户。
所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置 beta 标头。
保险库和凭证是工作区范围的,这意味着任何拥有 API 密钥访问权限的人都可以使用它们来授权代理完成任务。要撤销访问权限,请删除保险库或凭证。
保险库是与最终用户关联的 credentials 的集合。给它一个 display_name,并可选地用 metadata 标记它,以便您可以将其映射回您自己的用户记录。
Was this page helpful?
vault_id=$(curl --fail-with-body -sS https://api.anthropic.com/v1/vaults \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
--data @- <<'EOF' | jq -r '.id'
{
"display_name": "Alice",
"metadata": {"external_user_id": "usr_abc123"}
}
EOF
)
echo "$vault_id" # "vlt_01ABC..."响应是完整的保险库记录:
{
"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 与引用的保险库上的活跃凭证进行匹配,并注入令牌。
密钥字段(token、access_token、refresh_token、client_secret)是只写的。它们永远不会在 API 响应中返回。
凭证按提供的方式存储,在会话运行时之前不会进行验证。坏令牌会在会话期间显示为 MCP 身份验证错误,该错误会被发出但不会阻止会话继续。
约束条件:
mcp_server_url 只有一个活跃凭证。 为同一 URL 创建第二个凭证会返回 409。mcp_server_url 是不可变的。 要指向不同的服务器,请存档此凭证并创建一个新的。只有密钥有效负载和少数几个元数据字段是可变的。mcp_server_url、token_endpoint 和 client_id 在创建后被锁定。
curl --fail-with-body -sS \
"https://api.anthropic.com/v1/vaults/$vault_id/credentials/$credential_id" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
--data @- <<'EOF' > /dev/null
{
"auth": {
"type": "mcp_oauth",
"access_token": "xoxp-new-...",
"expires_at": "2026-05-15T00:00:00Z",
"refresh": {"refresh_token": "xoxe-1-new-..."}
}
}
EOF在创建会话时传递 vault_ids:
session_id=$(curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
--data @- <<EOF | jq -r '.id'
{
"agent": "$agent_id",
"environment_id": "$environment_id",
"vault_ids": ["$vault_id"],
"title": "Alice's Slack digest"
}
EOF
)运行时行为:
include_archived=true 以包含它们)。POST /v1/vaults/{id}/archive。级联到所有凭证。密钥被清除;记录被保留用于审计。引用此保险库的未来会话失败;运行中的会话继续。POST /v1/vaults/{id}/credentials/{cred_id}/archive。清除密钥有效负载;mcp_server_url 保持可见。释放 mcp_server_url 以供替换凭证使用。