Claude Media
Managed AgentsにVault(認証情報保管庫)で秘密情報を渡す
Agent SDKチュートリアル

Managed AgentsにVault(認証情報保管庫)で秘密情報を渡す

Managed AgentsのVaultとCredentialの仕組みを、作成・登録・ローテーション・失効検知まで手順とともに解説します。

読了目安 約18分

Vault(認証情報保管庫)とCredentialは何を解決するか

Managed AgentsのVault(認証情報保管庫)は、第三者サービスの認証情報を一度登録しておき、セッション作成時にIDで参照する仕組みです。独自のシークレットストアを運用したり、呼び出しのたびにトークンを送信したりする必要がなくなり、どのエンドユーザーの代理でエージェントが動いたかも追いやすくなります。Vaultの参照はセッション単位のパラメーターなので、エージェント自体はプロダクト単位で、Vaultは利用者単位で分けて管理できます。

前提条件

Managed Agents APIのリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です。VaultとCredentialはワークスペース単位のリソースで、そのワークスペースにアクセスできるAPIキーであれば誰でも参照できます。アクセスを取り消したい場合はVaultまたはCredentialそのものを削除します。

ステップ1 — Vaultを作成する

Vault(認証情報保管庫)はエンドユーザー1人に対応するcredentialsの集合です。display_nameを付け、必要ならmetadataで自社のユーザーIDと紐づけます。

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..."

ステップ2 — Credentialを登録する

Credential(個々の認証情報)には2種類あります。MCPサーバー宛ての認証(mcp_oauth、static_bearer)はmcp_server_urlをキーに、環境変数として渡す認証(environment_variable)はsecret_nameをキーに登録します。実際のトークンや秘密の値(token、access_token、refresh_token、client_secret、secret_value)は書き込み専用の項目として扱われ、APIレスポンスに含まれることはありません。

MCPサーバーの認証を登録する

OAuth 2.0を使うMCPサーバーにはmcp_oauthを使います。refreshブロックを渡しておくと、アクセストークンが失効したタイミングでAnthropic側が自動でリフレッシュします。固定のベアラートークンで済むMCPサーバーにはstatic_bearerを使い、リフレッシュの仕組みは不要です。

{
  "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.access",
      "client_id": "1234567890.0987654321",
      "scope": "channels:read chat:write",
      "refresh_token": "xoxe-1-...",
      "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."}
    }
  }
}

MCPサーバーとの接続まわりの実装変化はリモートMCPのOAuth認証で扱っているので、リフレッシュの仕組み自体を理解したい場合はあわせて参照してください。

環境変数として秘密情報を渡す

CLIやSDK、直接のAPI呼び出しのように環境変数で認証するサービスにはenvironment_variableを使います。エージェントのサンドボックス内には実際の値ではなく不透明なプレースホルダーが置かれ、エージェントが外部へリクエストを送信するタイミング(egress)で本物の値へ差し替えられます。エージェント自身は秘密の値を見ることがありません。

{
  "display_name": "Notion API key for sandbox",
  "auth": {
    "type": "environment_variable",
    "secret_name": "NOTION_API_KEY",
    "secret_value": "ntn_your-secret-here",
    "networking": {
      "type": "limited",
      "allowed_hosts": ["api.notion.com"]
    },
    "injection_location": {"header": true}
  }
}

networking.allowed_hostsは、どの送信先ホストに対してこの秘密を差し替えるかを制御します。エージェントが実際にそのホストへ到達できるかどうかは別の話で、Environment側でも同じドメインを許可しておく必要があります。injection_locationはリクエストのどこ(headerまたはbody)に差し込むかを指定するもので、両方省略すると両方が有効になります。作成時にどちらか一方だけを指定すると、指定しなかった側は無効になります。

1つのVaultに登録できるCredentialは最大20件です。mcp_server_urlやsecret_nameはVault内で一意である必要があり、重複登録は409エラーになります。また、これらのキー自体は作成後に変更できません。変更したい場合はCredentialをアーカイブして作り直します。

環境変数Credentialのスコープを絞り込む

environment_variableタイプのCredentialは、渡す権限の範囲を小さく保つほど安全になります。エージェントはCredentialが許可する範囲であれば何でも実行できてしまうため、必要以上に広い権限のAPIキーを登録すると、エージェントが想定外の挙動をしたときの被害範囲がそのぶん広がります。実務では、そのセッションでエージェントに任せるタスクに必要な最小限のスコープだけを持つキーを発行し、それをCredentialとして登録すれば被害範囲を小さく保てます。networking.allowed_hostsをunrestrictedにするのは、接続先を事前に列挙できない場合の最終手段として扱い、可能な限りlimitedで具体的なホスト名を列挙します。

ステップ3 — セッション作成時にVaultを参照する

作成したVaultは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 Credentialが無いままエージェントがMCPサーバーへ接続しようとすると、未認証のまま接続が試みられ、そのサーバーが認証を要求していればエラーになります。複数のVaultに一致するCredentialがある場合は、先に指定したVaultが優先されます。マルチエージェントセッションでは、Vaultの認証情報は全スレッドに適用され、自分の定義でそのMCPサーバーを宣言しているエージェントだけがこの認証情報で接続します。

Credentialをローテーションする

display_nameや実際の秘密の値、環境変数Credentialのinjection_locationは更新できます。mcp_server_urlやsecret_name、token_endpoint、client_idのような構造的なフィールドは作成後にロックされ、変更したい場合はCredentialをアーカイブして新規作成します。ローテーション後は実行中のセッションであっても、再起動を挟まずに新しい認証情報へ切り替わります。

Credentialのライフサイクルと失効検知

CredentialはセッションおよびVaultのライフサイクルの中で定期的に再解決され、ローテーション・アーカイブ・削除は実行中のセッションにも再起動を挟まず反映されます。vault.archived・vault.deleted・vault_credential.archived・vault_credential.deleted・vault_credential.refresh_failedの各イベントをwebhookで購読しておけば、失効やリフレッシュ失敗にすぐ気づけます。

mcp_oauthのリフレッシュが失敗した原因をあらためて調べたいときは、mcp_oauth_validateエンドポイントを呼び出します。返ってくるstatusがvalidならそのまま使えて対応不要、invalidならリフレッシュトークン自体が失効しているのでエンドユーザーに再認可を促し、unknownなら5xxや429のような一時的なエラーなので待って再試行します。

アーカイブと削除、どちらを使うか

VaultやCredentialを使わなくなったときの操作は、アーカイブと削除の2種類があり、監査の要件によって使い分けます。

操作挙動向いている場面
アーカイブ(POST /archive)挙動秘密の値は破棄されるが、レコード自体は監査目的で残る。Vaultをアーカイブすると配下の全Credentialも連鎖してアーカイブされる向いている場面いつ・誰の認証情報を無効化したかを後から追跡したい場合
削除(DELETE)挙動レコードごと完全に削除され、復元できない向いている場面記録自体を残す必要がなく、完全に消し去りたい場合

Vaultをアーカイブすると、それを参照する新規セッションの作成は失敗しますが、すでに実行中のセッションはそのまま継続します。Credentialのキー(mcp_server_urlやsecret_name)は、アーカイブ後も表示上は残り、同じキーで新しいCredentialを登録し直せる状態になります。VaultやCredentialの一覧取得はページングされ、新しい順に返され、既定ではアーカイブ済みのレコードは含まれません。含めたい場合はinclude_archived=trueを指定します。

よくあるつまずき

  • injection_locationを省略したつもりで片方だけ有効になる: 作成時にオブジェクトを渡すと、書かなかったフィールドはfalse扱いになります。両方有効にしたい場合はオブジェクト自体を省略します。
  • サンドボックス内でシークレットの値を検証しようとして失敗する: 環境変数Credentialの実体はegress時にしか差し替わりません。サンドボックス内で値のフォーマットを検証したり、AWS SigV4のように秘密からリクエスト署名を計算したりするクライアントは、プレースホルダーのまま処理してしまい失敗します。
  • OAuthのトークン交換フローで秘密が漏れると誤解する: クライアントクレデンシャルグラントのように、保存した秘密を使ってセッショントークンを取得するフローでは、取得したトークン自体はサンドボックスにそのまま届きます。交換が必要な認証方式は、事前に交換を済ませて得られたトークンをVaultに保存する設計にします。
  • Vaultをアーカイブしても実行中セッションが即座に止まると思い込む: Vaultのアーカイブは新規セッションでの参照を失敗させますが、すでに実行中のセッションは継続します。
  • アーカイブと削除を同じ操作だと思い込む: アーカイブは秘密の値だけを破棄してレコードを監査用に残しますが、削除はレコードごと完全に消え復元できません。監査証跡が必要な運用では、原則としてアーカイブを使います。
  • Console(管理画面)から作成したCredentialでbody injectionが効かない: Consoleで作成したCredentialはheader injectionのみが既定で有効になります。フォームエンコードのトークンリクエストのようにリクエストボディへ秘密を送るクライアントでは、プレースホルダーがそのまま本文に残って通信先の認証エラーになります。Console上のフォームでbody injectionを有効にするか、作成後に{"injection_location": {"body": true}}で更新します。
  • 不正なCredentialを登録してもエラーにならず安心してしまう: CredentialはAPI呼び出し時点では値の妥当性を検証されず、登録された内容がそのまま保存されます。実際の検証はセッション実行時になって初めて行われ、不正な値は認証エラーやダウンストリームのエラーとして表面化しますが、そのエラーが出てもセッション自体は止まらずに続行します。登録直後に「エラーが出ないから正しい」と判断しないことが重要です。

まとめ

Managed AgentsのVaultとCredentialは、MCPサーバー向けの認証(mcp_oauth・static_bearer)と環境変数向けの認証(environment_variable)を使い分け、セッション作成時にvault_idsで参照する構成です。環境変数Credentialは送信時(egress)にしか実体化しないため、サンドボックス内でのフォーマット検証やリクエスト署名の計算には使えない点、ローテーションやアーカイブは実行中セッションにも再起動なしで反映される点を押さえておけば、エンドユーザーごとの認証情報を安全に受け渡す設計がしやすくなります。実行中セッションへのファイルの受け渡しは実行中セッションでのファイル操作、セッション・ハーネス・サンドボックスの分離設計はManaged Agentsの設計思想を参照してください。

この記事を共有:XはてブLinkedIn

関連する記事

Agent SDK をもっと見る →