Managed Agentsのレート制限とMCP対応・ブランディング規定

Managed Agentsのレート制限は、組織単位で作成系が毎分300リクエスト、読み取り系が毎分1,200リクエストです。これとは別に、1セッションの支出を絞るセッション予算(budget)があり、MCPサーバーの接続とブランド表記にも決まりがあります。本番投入の前に引っかかりやすいのは、この4つの境目です。

レート制限は組織単位で、作成系と読み取り系に分かれる

数字は上の図のとおりです。APIキーが何本あっても、同じ組織なら同じ枠を分け合います。この枠はMessages APIのレート制限とは別に数えられ、組織の使用量ティアに応じた上限や月間のスペンドリミットも並行して適用されます。

目安を計算で置いておきます。1,200回/分は平均すると毎秒20回です。40セッションを5秒おきに1回ずつ取得すると毎分480回で、読み取り枠の4割を使います。作成側は毎秒5回にあたるので、1,000セッションを一括で起動するなら、作成リクエストだけで3分以上かかります。

ティアごとの月間スペンドキャップに達したときは、挙動が別になります。Messages APIでは429が返り、retry-afterヘッダーは付きません。自分で設定した上限に達した場合は、400(invalid_request_error)です。SDKの自動リトライも、アクセスが戻るまで失敗し続けます。待てば戻る毎分の上限と違い、同じ429でも戻る条件が別です。

組織とワークスペースに現在かかっている上限は、Rate Limits APIでプログラムから読めます。Scaleティアを超える上限が要る場合は、ConsoleのRate limitsページから営業チームに相談する経路が案内されています。

セッション予算は、レート制限とは別に支出を止める

レート制限が縛るのは1分あたりのリクエスト数で、1セッションがいくら使うかには関与しません。支出の側を絞るのが、セッション作成時に渡すbudgetです。

{
  "agent": "agent_...",
  "environment_id": "env_...",
  "budget": {
    "type": "limit",
    "max_list_cost": { "amount": "125", "currency": "USD" }
  }
}

amountは米セント単位の整数を文字列で書きます。"125"は1.25ドルです。"25.00"のような小数、0以下の値、USD以外の通貨は400で拒否されます。

上限と比べられるのは、公開の一覧料金で積算したセッションの消費額(list cost)です。内訳は、モデルのトークン、ウェブ検索1,000回あたり10ドル、セッションの稼働時間1時間あたり0.08ドルの3つです。契約で割引がある組織でも、一覧料金の合計が上限に届いた時点で止まるので、実際の請求額は上限より低くなることがあります。

消費額はセッションオブジェクトのusageで読めます。usage.list_costが積算した金額、usage.active_secondsが稼働時間の課金に使う秒数です。報告される金額はセント単位に丸められ、上限との比較に使う厳密な値と最大で0.5セントずれます。スレッドごとのusageは個別に丸められ、稼働時間の費用を含まないので、合計してもセッションのlist_costとは一致しません。上限と比べられるのは、セッション側の値です。

session.usageイベントは、その時点の累計トークン数、list_cost、active_seconds、ウェブ検索のリクエスト数(web_search_requests)とbudgetの写しを持つスナップショットです。idleになる直前に必ず1つ出るので、予算以外で止まった場合も含め、止まった時点の消費額をイベント履歴から追えます。web_fetch_requestsは常に0で、ウェブフェッチには1回ごとの課金がなく、計測されないためです。

ツールの承認待ち(requires_action)のスレッドがあるセッションは、別のスレッドがbudget_reachedで止まっていても、セッション全体ではrequires_actionと報告されます。承認への返答は上限があっても通るイベントなので、先に答えます。

止まっている間も受け付けるのは、user.tool_confirmation・user.tool_result・user.custom_tool_result・user.interruptだけです。user.messageのように新しい作業を始めるイベントは400になります。追加の指示を送りたいときは、先に予算を引き上げます。

予算の設定は作成時に限られます。予算なしで作ったセッションに後から付けると400で拒否され、一度外した予算の付け直しも同じです。デプロイメントに設定した予算は、起動する各セッションに同じ値がコピーされます。デプロイメント全体の累計ではなく、1回の実行ごとの上限です。マルチエージェントのセッションでは、全スレッドで1つの予算を共有します。

一覧料金が公開されていないモデルは、予算で測れません。そのモデルを使うエージェントで予算付きのセッションを作ると400になります。作成後に使用量へ入ってきた場合は、セッションがbudget_reachedで止まり、予算の変更も拒否されるので、予算を外して再開します。運用の細部はManaged Agentsのセッション予算と、止まった後の再開を扱うManaged Agentsの予算到達後の再開にあります。

MCPサーバーは、置き場所で接続方式が決まる

接続できるのは、HTTPエンドポイントを公開するリモートMCPサーバーと、MCPトンネル経由のプライベートなサーバーの2系統です。

エージェントにはサーバーの宣言だけを書く

エージェント作成時にmcp_serversでサーバーを宣言し、toolsに対応するmcp_toolsetを並べます。認証情報はここに含めません。

{
  "mcp_servers": [
    { "type": "url", "name": "github",
      "url": "https://api.githubcopilot.com/mcp/" }
  ],
  "tools": [
    { "type": "agent_toolset_20260401" },
    { "type": "mcp_toolset", "mcp_server_name": "github" }
  ]
}

宣言できるのは1エージェントあたり20台までで、名前は配列内で重複できません。mcp_serversの各項目は、いずれかのmcp_toolsetから参照される必要があります。mcp_toolsetが存在しない名前を指していても同じで、どちらの食い違いもAPIがエージェント定義ごと拒否します。

mcp_toolsetの既定の権限ポリシーはalways_askで、ツールを呼ぶたびにユーザーの承認が要ります。自動で走らせたいエージェントでは、権限ポリシーの設定が前提になります。考え方はManaged Agentsの権限ポリシーの設計にあります。

使わせるツールはdefault_configとconfigsで絞ります。default_config.enabledをfalseにして、必要なツール名だけconfigsで有効にすれば、多機能なサーバーから一部だけを許可できます。大半を使わせたいなら、無効にしたいツールだけをconfigsに並べます。ツールの出力が10万字を超えると、サンドボックス内のファイルに書き出されます。モデルに渡るのは、要約のプレビューとファイルのパスです。

認証はセッション作成時にvaultで渡す

セッション作成時にvault_idsを渡すと、vaultの認証情報がmcp_server_urlとURLの一致で選ばれます。比較の前に、スキームとホストの大文字小文字、既定ポート、末尾スラッシュがそろえられます。この3つの違いは、一致を妨げません。

パス・サブドメイン・非標準ポートが違えば、別のサーバーとして扱われます。一致する認証情報がなければ、未認証のまま接続が試みられます。

limitedのネットワーク設定の環境では、MCPサーバーが既定で遮断されます。allow_mcp_servers: trueを設定するか、allowed_hostsに各サーバーのホストを並べないと、セッションの作成が400で失敗します。

症状から原因を引く

セッション作成の時点では、MCPの接続も認証も検証されません。つながらないサーバーがあってもセッションは始まり、session.errorイベントが対象サーバーのmcp_server_nameとretry_status付きで届きます。接続は、セッションがidleからrunningに戻るたびに再試行されます。

OAuthの更新失敗は、Managed AgentsのvaultでOAuth更新が失敗するときで原因別に追えます。

パートナー製品にClaudeの名前をどう出すか

Claudeブランドの表示は任意です。使うなら、次の表記が許可されています。

不許可の3行に共通するのは、自社製品がClaude CodeやClaude Coworkそのものに見える点です。「Claude Code」「Claude Code Agent」という表記は、メニューの項目名でも使えません。ブランド準拠の個別の疑問は、Anthropicの営業チームが窓口です。この規定は、Managed Agentsを組み込んで外へ提供するパートナーが対象です。

まとめ

止まり方は3種類で、戻し方が違います。毎分の上限の429は待てば戻り、スペンドキャップの429は月をまたぐまで戻りません。予算はセッションをidleで止めるだけなので、引き上げれば作業が再開します。どれに当たったかを症状から切り分ければ、再試行・待機・上限変更のどれが要るかが決まります。

セッションの具体的な操作はManaged Agentsのセッション操作リファレンス、初期イベントでの起動はManaged Agentsのセッションを初期イベントでシードするにあります。全体像はAgent SDKのManaged Agentsの設計思想で追えます。