Managed Agentsのツール一覧と有効化・無効化の設定方法

Managed Agentsで使える標準ツールは8種類

Managed Agentsのエージェントには、あらかじめ8種類の標準ツールが用意されています。エージェント作成時にツールセットを含めると、これらはすべてデフォルトで有効になります。

ツールの出力が10万文字(おおよそ2万5,000トークン)を超えると、その全文は自動的にサンドボックス内のファイルへ書き出されます。モデルにはファイルパス付きの要約プレビューだけが渡され、必要ならそこから全文を読み直せます。巨大なgrep結果やビルドログをそのままコンテキストに流し込まなくて済む仕組みです。

MCPサーバー経由のツールを追加したい場合は、このツールセットとは別にMCPコネクタを使います。標準ツールの有効・無効設定とは独立して構成できるため、社内のMCPサーバーだけ止めて標準ツールは残す、といった切り分けも別々の設定で行えます。

有効化・無効化はツールセットのconfigs配列で行う

ツールセット全体は、エージェント作成時にagent_toolset_20260401として指定します。個別ツールの有効・無効を切り替えるには、configs配列にそのツールのnameとともにエントリを追加します。

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

configsに書かなかったツールは、標準の有効状態(すべて有効)のまま残ります。「このツールだけ止めたい」という消去法の設定に向いています。

特定のツールだけを有効にする — default_configで全部オフから始める

逆に「使わせたいツールだけを明示したい」場合は、default_config.enabledをfalseにしてベースラインを全オフへ倒し、必要なツールだけconfigsで個別に有効化します。

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}

コードレビュー専用エージェントにbashとreadだけを渡し、writeやweb_searchを意図せず使わせない、といった権限の絞り込みに向いた書き方です。どちらの方式を選ぶかは単純です。許可する側と禁止する側のどちらが少数派かで決めます。エージェントの役割が広ければconfigsだけの消去法、役割が狭く固定されているならdefault_configでの全オフ起点、という判断基準になります。

有効/無効だけでなく「実行前に確認を挟む」設定もできる

configsの各エントリには、enabledのほかにpermission_policyも設定できます。これは「そのツールの呼び出しを自動承認するか、実行前に確認を挟むか」を制御するフィールドです。bashのように破壊的な操作ができるツールだけ確認を必須にし、readやgrepのような読み取り専用ツールは自動承認する、という粒度の使い分けが可能です。ポリシーの種類ごとの詳細な設定値は権限ポリシーの仕様が正になります。ここでは「enabledとは別軸の設定項目である」という位置付けだけ押さえておけば十分です。

両方を同じエントリに書いたときの評価順にも注意が必要です。enabled: falseを指定したツールは、同じエントリにpermission_policyを書いても呼び出し自体が発生しないため、その設定は無視されます。逆にenabled: true(または未指定でデフォルト有効)のツールにだけpermission_policyが意味を持ちます。つまり有効/無効の判定が先に効き、承認要否の判定はそのあとに続く独立したチェックだという順番で読むと、configs配列の設計で両者を混同しません。

Web検索・Web Fetchはドメイン単位で制限できる

web_searchとweb_fetchは、allowed_domains(許可リスト)かblocked_domains(禁止リスト)のどちらか一方をエントリに設定して、到達できるサイトを絞り込めます。両方は設定できません。

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"]
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

登録したドメインは、そのホストとサブドメインすべてに適用されます(example.comを登録するとdocs.example.comも含む、逆は含まない)。制限に反するURLへのweb_fetchはurl_not_allowedエラーを返し、web_searchは許可されない結果を結果一覧から除外します。

ドメイン指定には細かい制約があり、ここで弾かれると作成・更新リクエストが400エラーになります。

• IPアドレス(IPv4/IPv6/短縮表記いずれも)は指定不可。ドメイン名で指定する
• comやco.ukのような裸のトップレベルドメイン・レジストリサフィックスは不可
• localhost、.local、.internal、.localdomain、.invalid終わりのホストは不可
• web_fetchのドメインにパスは含められない(example.com/*は不可)。web_searchはパスサフィックスを付けられる
• 同一リスト内の重複は不可。www.example.comとexample.comは別ドメイン扱い(前者は後者をカバーしない)

なお、Consoleで設定する組織レベルのWeb検索・Web Fetch制限はMessages APIにのみ適用され、Managed Agentsセッションには効きません。Managed Agents側を制限したいときは、必ずツールセットのallowed_domainsかblocked_domainsで設定します。

設定はいつ検証されるか — 作成時とセッション初期化時の2段階

ドメイン設定の書式違反や上限超過は、エージェントの作成・更新や、toolsを渡してのセッション作成・更新の時点で400エラーとして即座に弾かれます。エラーメッセージはリストの何番目の要素が問題かまで示すため、allowed_domains.0: IP addresses are not supportedのように該当箇所を特定しやすくなっています。

ただし、書式は正しくても実際には使えない設定(Anthropicのクローラーがアクセスを許可されていないドメイン、検索プロバイダが対応していない国コード、無効なタイムゾーン名)は、作成時のチェックをすり抜けることがあります。この種の不整合は、セッションがそのツールを実際に初期化するタイミングで再チェックされ、そこで弾かれるとsession.errorイベントが発火してセッションはリトライせずにアイドルへ戻ります。直し方は、セッションのtoolsを更新して設定を修正し、以後のセッションにも同じ問題が起きないようエージェント側の設定も合わせて直したうえで、新しいuser.messageを送って再開させる、という順番になります。

Messages APIのdomain filteringとの違い

allowed_domains/blocked_domainsという語彙自体はMessages APIのサーバーツールのドメインフィルタリングと共通ですが、Managed Agents側には固有の制約があります。

Messages APIの実装をそのままManaged Agentsに移植しようとすると、この4点でリクエストが拒否されます。とくにUnicodeドメインとパス付きweb_fetchドメインは、Messages API側で動いていた設定をそのまま流用したときに引っかかりやすい箇所です。

カスタムツール — 自前実装をエージェントに持たせる

標準ツールに加えて、独自の入出力を持つカスタムツールを定義できます。Managed Agentsのモデルは何も自動実行しません。構造化されたツール呼び出しリクエストを発行するだけで、実際の処理は呼び出し側のアプリケーションが実行し、結果をイベントとして返します。

{
  "type": "custom",
  "name": "get_weather",
  "description": "指定した地名の現在の天気を取得する",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "都市名" }
    },
    "required": ["location"]
  }
}

カスタムツールの精度は、descriptionの書き方でほぼ決まります。公式が挙げるベストプラクティスは次の4点です。

• 説明を厚く書く: 何をするツールか、いつ使い(使わない)べきか、各パラメータの意味と挙動への影響、注意点まで含めて3〜4文が目安
• 関連する操作は1つのツールにまとめる: create_pr / review_pr / merge_prを別々に作るのではなく、actionパラメータを持つ1つのツールに集約する
• ツール名に意味のある名前空間を付ける: 複数のサービス・リソースをまたぐならdb_queryやstorage_readのように接頭辞でリソースを明示する
• 返す情報は高シグナルなものだけに絞る: 不透明な内部IDではなくスラッグやUUIDのような安定した識別子を返し、次の判断に必要なフィールドだけに絞る

自己ホスト型サンドボックスでセッションを動かしている場合、環境ワーカー側からカスタムツールを提供することもできます。社内ネットワーク内のMCPサーバーをラップしたツールを、外部公開せずにエージェントへ渡せる構成です。

まとめ

標準ツールの有効・無効はconfigs配列、全部オフから必要な分だけ足すならdefault_config.enabled: false、Web系ツールの到達範囲はallowed_domains/blocked_domainsで絞ります。マルチエージェント構成ではドメイン制限が積で効くことだけ覚えておけば、意図しない全滅も意図しない過剰な許可も避けられます。ドメイン設定は作成時とセッション初期化時の2段階でチェックされるため、書式エラーは即座に、実際に到達できるかどうかの問題はセッションを動かしてから分かる点も、エラー対応の設計に入れておくと想定外のsession.errorに慌てずに済みます。

ツールが呼ばれたあとの実行状況はConsoleのセッションビューアで追えます。詳しい画面構成はManaged AgentsをConsoleで可視化・デバッグする方法にまとめています。セッションの予算とアイドル管理はManaged Agentsの予算到達・アイドル再開・システムメッセージの実装パターン、設計思想の全体像はManaged Agentsの設計思想を参照してください。