Loading...
    • 构建
    • 管理
    • 模型与定价
    • 客户端 SDK
    • API 参考
    Search...
    ⌘K
    入门步骤
    Claude 简介快速入门
    使用 Claude 构建
    功能概览使用 Messages API处理停止原因
    模型能力
    扩展思考自适应思考努力程度快速模式(测试版:研究预览)结构化输出引用流式消息批量处理搜索结果流式拒绝多语言支持嵌入
    工具
    概览工具使用原理网页搜索工具网页抓取工具代码执行工具记忆工具Bash 工具计算机使用工具文本编辑器工具
    工具基础设施
    工具搜索程序化工具调用细粒度工具流式传输
    上下文管理
    上下文窗口压缩上下文编辑提示词缓存Token 计数
    文件处理
    Files APIPDF 支持图像与视觉
    技能
    概览快速入门最佳实践企业级技能API 中的技能
    MCP
    远程 MCP 服务器MCP 连接器
    提示词工程
    概览提示词最佳实践Console 提示词工具
    测试与评估
    定义成功标准并构建评估在 Console 中使用评估工具降低延迟
    加强安全护栏
    减少幻觉提高输出一致性防范越狱减少提示词泄露
    资源
    术语表
    发布说明
    Claude Platform
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    将工作委托给智能体

    使用保险库进行身份验证

    在创建会话时注册每个用户的凭证。

    保险库和凭证是身份验证原语,允许您为第三方服务注册凭证一次,然后在会话创建时通过 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 是不可变的。 要指向不同的服务器,请存档此凭证并创建一个新的。
    • 每个保险库最多 20 个凭证。 这与每个代理的最大 MCP 服务器数量相匹配。

    轮换凭证

    只有密钥有效负载和少数几个元数据字段是可变的。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
    )

    运行时行为:

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

    其他操作

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