Claude Platform Docs
Managed Agents將工作委派給您的代理

使用 vault 進行驗證

在建立 session 時註冊每位使用者的憑證。

Vault（保管庫）與 credential（憑證）是驗證基本元件，讓您只需為第三方服務註冊一次憑證，之後在建立 session 時即可透過 ID 參照它們。這表示您不需要自行運行機密儲存庫、在每次呼叫時傳送權杖，也不會搞不清楚代理是代表哪位終端使用者執行操作。

Vault 參照是每個 session 的參數，因此您可以在 agent 資源的粒度管理您的產品，並在 session 資源的粒度管理您的使用者。

建立 vault

Vault 是與某位終端使用者相關聯的 credentials 集合。請為它指定 display_name，並可選擇性地以 metadata 加上標記，以便您將其對應回您自己的使用者記錄。

vault = client.beta.vaults.create(
    display_name="Alice",
    metadata={"external_user_id": "usr_abc123"},
)
print(vault.id)  # "vlt_01ABC..."

回應為完整的 vault 記錄：

{
  "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 憑證（mcp_oauth、static_bearer）：每個憑證以 mcp_server_url 作為鍵。當代理在 session 執行期間連線至該 URL 的伺服器時，權杖會自動注入。
  • 環境變數（environment_variable）：每個憑證以 secret_name（環境變數名稱）作為鍵，並以不透明的佔位符形式儲存在沙箱中。當代理發起對外請求時，不透明佔位符會在出口處被替換為真正的機密。代理永遠不會看到機密值。任何透過環境變數進行驗證的服務都可使用此方式，例如 CLI、SDK 或直接的 API 呼叫。

您提供的實際憑證值（token、access_token、refresh_token、client_secret、secret_value）會被視為敏感的唯寫欄位，永遠不會在 API 回應中傳回。

當 MCP 伺服器使用 OAuth 2.0 時，請使用 mcp_oauth。如果您提供 refresh 區塊，Anthropic 會在存取權杖過期時代您重新整理。

refresh.token_endpoint_auth.type 欄位指示如何驗證重新整理呼叫：

  • none：公開用戶端
  • client_secret_basic：使用用戶端密鑰的 HTTP Basic 驗證
  • client_secret_post：將用戶端密鑰放在 POST 主體中
credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Alice's Slack",
    auth={
        "type": "mcp_oauth",
        "mcp_server_url": "https://mcp.slack.com/mcp",
        "access_token": "xoxp-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {
            "token_endpoint": "https://slack.com/api/oauth.v2.user.access",
            "client_id": "1234567890.0987654321",
            "scope": "channels:read chat:write",
            "refresh_token": "xoxe-1-...",
            "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."},
        },
    },
)

請將 refresh.token_endpoint 設定為核發重新整理權杖之 OAuth 流程的權杖端點，因為 Anthropic 會將每個重新整理請求傳送到該 URL，且該欄位在憑證建立後無法變更。

憑證會依所提供的內容儲存，直到 session 執行期間才會進行驗證。無效的憑證會在 session 期間以驗證錯誤或下游錯誤的形式呈現，該錯誤會被發出，但不會阻止 session 繼續進行。

限制條件：

  • 每個 vault 內鍵必須唯一。 mcp_server_url（MCP 憑證）與 secret_name（環境變數憑證）在 vault 內的有效憑證之間必須唯一。建立重複項目會傳回 409。
  • 鍵不可變更。 若要變更 mcp_server_url 或 secret_name，請封存該憑證並建立新的憑證。
  • 每個 vault 最多 20 個憑證。

在建立 session 時參照 vault

建立 session 時傳入 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_server_url 相符時，會嘗試以未驗證的方式連線，若伺服器要求驗證則會發生錯誤。
  • 當多個 vault 包含相符的憑證時，以第一個相符的 vault 為準。
  • 在多代理 session 中，vault 憑證適用於每個執行緒。自身定義中宣告了相符 MCP 伺服器的代理會使用這些憑證進行驗證。請參閱將代理連線至 MCP 伺服器。

輪替憑證

機密值、display_name 以及（環境變數憑證上的）injection_location 可以更新。injection_location 的更新會依欄位合併，如新增憑證的「環境變數」分頁所述。對於執行中的 session，injection_location 的更新會以與機密輪替相同的方式傳播：session 的憑證會在不重新啟動的情況下重新解析，如憑證生命週期所述，而更新後的位置會套用至該 session 後續的對外請求。結構性欄位（mcp_server_url、secret_name、token_endpoint、client_id）在建立後即鎖定。若要變更它們，請封存該憑證並建立新的憑證。

client.beta.vaults.credentials.update(
    credential.id,
    vault_id=vault.id,
    auth={
        "type": "mcp_oauth",
        "access_token": "xoxp-new-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {"refresh_token": "xoxe-1-new-..."},
    },
)

憑證生命週期

憑證會定期重新解析，無論是在 session 期間還是在 vault 生命週期期間。這可確保憑證的輪替、封存或刪除能在不重新啟動的情況下傳播至執行中的 session。

若要在憑證被封存、刪除或重新整理失敗時收到通知，您可以訂閱與這些生命週期變更相關聯的 vault 與憑證 webhook。

事件觸發條件
vault.archivedVault 已封存。同時會為每個底層憑證發出 vault_credential.archived 事件。
vault.deletedVault 已刪除。同時會為每個底層憑證發出 vault_credential.deleted 事件。
vault_credential.archived憑證已封存，無論是直接封存或因 vault 封存所致。
vault_credential.deleted憑證已刪除，無論是直接刪除或因 vault 刪除所致。
vault_credential.refresh_failedmcp_oauth 憑證無法重新整理（重新整理權杖無效，或來自 OAuth 伺服器的無法復原錯誤）。

對於 mcp_oauth 憑證，重新解析也會在存取權杖過期時重新整理它。如果重新整理失敗，會發出 vault_credential.refresh_failed 事件。

診斷 OAuth 重新整理失敗

若要診斷重新整理失敗的原因，請呼叫 POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate（或在 SDK 中使用 client.beta.vaults.credentials.mcp_oauth_validate(...)）。這可讓您決定如何處理失敗；正確的處理方式取決於錯誤類型。

頂層的 status 會告訴您下一步該怎麼做：

  • valid：權杖有效；無需採取任何動作。
  • invalid：授權已不存在，或 OAuth 伺服器以 4xx 拒絕了重新整理。請提示終端使用者重新授權。
  • unknown：暫時性錯誤（5xx、429 或網路失敗）。請稍候並重試。
validation = client.beta.vaults.credentials.mcp_oauth_validate(
    credential.id,
    vault_id=vault.id,
)
print(validation.status)  # "valid", "invalid", or "unknown"

回應為 vault_credential_validation 物件。mcp_probe 包含失敗的 MCP 交握步驟；refresh 包含所嘗試之重新整理的結果。

{
  "type": "vault_credential_validation",
  "credential_id": "vcrd_01ABC...",
  "vault_id": "vlt_01XYZ...",
  "validated_at": "2026-04-29T17:12:00Z",
  "has_refresh_token": false,
  "status": "invalid",
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  },
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  }
}

其他操作

  • 列出 vault 或憑證： 分頁顯示，最新的在前。預設排除已封存的記錄（傳入 include_archived=true 以包含它們）。
  • 封存 vault： POST /v1/vaults/{id}/archive。會連帶套用至所有憑證。機密會被清除；記錄會保留以供稽核。未來參照此 vault 的 session 會失敗；執行中的 session 會繼續。
  • 封存憑證： POST /v1/vaults/{id}/credentials/{cred_id}/archive。清除機密酬載；憑證鍵（mcp_server_url 或 secret_name）仍然可見，並釋出以供替代憑證使用。
  • 刪除 vault 或憑證： 硬刪除。記錄不會保留。如果您需要稽核軌跡，請使用封存。

Was this page helpful?