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

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

Managed Agentsの標準ツール一覧と、有効化・無効化・実行前の確認・ドメイン制限・カスタムツール追加の設定方法をまとめます。

読了目安 約24分

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

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

ツール名前(name)できること
Bash名前(name)bashできることサンドボックス内でシェルコマンドを実行する
Read名前(name)readできることサンドボックスのファイルを読む
Write名前(name)writeできることサンドボックスにファイルを書く
Edit名前(name)editできることファイル内の文字列を置換する
Glob名前(name)globできることglobパターンでファイルを高速検索する
Grep名前(name)grepできること正規表現でテキストを検索する
Web fetch名前(name)web_fetchできることURLからコンテンツを取得する
Web search名前(name)web_searchできることWeb検索を実行する

configs配列の各エントリは、この表のnameで識別します。typeにも同じ値を書けますが、省略できます。

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

一部だけ止めたいか、一部だけ使わせたいか

ツールセットはエージェント作成時にagent_toolset_20260401として指定し、個別の設定はconfigs配列に書きます。どちらの書き方を選ぶかは、許可したいツールと止めたいツールのどちらが少数派かで決まります。

くらべる

ツール設定の2つの起点

止めたいツールが少数

全部オンから始める

configsに止めたいツールだけをenabled: falseで書きます。書かなかったツールは既定どおり有効のままです。役割が広いエージェントで、8つのうち1〜2個だけ外したいときに向きます。

使わせたいツールが少数

全部オフから始める

default_config.enabledをfalseにして全ツールのベースラインを落とし、使わせたいツールだけconfigsでenabled: trueにします。役割が狭く固定されたエージェントに向きます。

web_fetchとweb_searchだけを止める例です。

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

bash・read・writeの3つだけを使わせる例です。default_configは全ツールの土台で、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を意図せず使わせない、といった権限の絞り込みに使えます。

APIのJSONではなく、CLIのant applyでエージェントを作る場合は、Markdownファイルの先頭にYAMLで同じ内容を書きます。

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---
ant apply agent.md

ant applyが出力するのはエージェントのIDで、configs配列は表示されません。設定が意図どおりに入ったかを見たいときは、API経由で作成したレスポンスのtools[0].configsをjqで取り出す方法があります。

有効にしたまま「実行前に確認を挟む」には

有効・無効とは別に、有効なツールの呼び出しを自動で通すかどうかをpermission_policyで決められます。ポリシーは3種類です。

ポリシー動き
always_allow動き確認なしで自動実行する
always_ask動きセッションが止まり、承認を待ってから実行する
auto動き呼び出しごとにサーバーが評価し、実行・拒否・承認待ちのいずれかにする

既定値はツールセットの種類ごとに違います。標準ツールセットはalways_allow、MCPツールセットはalways_askです。MCPが慎重側に倒れているのは、MCPサーバー側で後から増えたツールが承認なしに動かないようにするためです。

ツールセット全体の既定はdefault_config.permission_policy、個別のツールはconfigsの各エントリで指定します。標準ツールは全部自動で通しつつ、bashだけ確認を必須にするなら次の形です。

{
  "type": "agent_toolset_20260401",
  "default_config": {
    "permission_policy": { "type": "always_allow" }
  },
  "configs": [
    { "name": "bash", "permission_policy": { "type": "always_ask" } }
  ]
}

always_askのツールを呼ぼうとすると、セッションはsession.status_idleイベントで止まり、stop_reason.typeがrequires_actionになります。承認待ちは無期限で、user.tool_confirmationイベントにallowかdenyを載せて返すと再開します。ant beta:sessions connectを使えば、ターミナル上で待機中の呼び出しを見ながら許可・拒否も返せます。

autoの拒否は、人の確認ではありません。サーバーが高リスクと判定した呼び出しは、エージェントにPermission to use {tool_name} has been denied.というエラー結果が返り、クライアント側からは覆せません。逆に、安全と判定された呼び出しは誰も見ないまま実行されるため、人のレビューが必要なツールにはalways_askを指定します。

有効・無効と承認ポリシーは、同じエントリに並べても役割が違います。ポリシーが制御するのは有効なツールがいつ動くかで、ツールを外したいときはenabled: falseにします。無効なツールの名前をエージェントが呼び出した場合は、ポリシーの評価に入らずにサーバーが拒否します。

設定の反映範囲にも注意が必要です。実行中のセッションは、作成時のツール設定を保ったままです。エージェントを更新した内容は、その後に作るセッションから効きます。

MCPサーバーのツールは別の枠で絞る

MCPサーバー経由のツールは、標準ツールセットではなくMCPコネクタのmcp_toolsetで扱います。構造は標準ツールと同じで、default_configとconfigsの組み合わせです。社内のMCPサーバーのツールだけを絞り、標準ツールは手つかずにする、といった切り分けが別々の設定でできます。

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "get_issue", "enabled": true },
    { "name": "list_issues", "enabled": true }
  ]
}

MCPのconfigsエントリが受け付けるのはname・enabled・permission_policyの3つだけです。標準ツールセットと違ってtypeは取らず、nameにはサーバーが返すツール名をそのまま書きます。サーバーが多数のツールを公開していて使うのが数個なら、全オフ起点にしておくと、サーバー側で後から足されたツールもレビューするまで止まったままになります。特定のツールだけ外したいときは、default_configを省いてenabled: falseを個別に書きます。

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

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

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"],
      "user_location": {
        "type": "approximate",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

ドメイン以外にも、Webツールのエントリには2つの設定があります。web_fetchのmax_content_tokensは、取得したページ内容がコンテキストに入る量の上限です。正の整数で指定します。web_searchのuser_locationは検索結果の地域化に使い、Messages APIの同名パラメーターと同じ形のオブジェクトです。

登録したドメインは、そのホストとサブドメインすべてに適用されます。example.comを登録するとdocs.example.comも含みますが、docs.example.comを登録してもexample.comは含みません。制限に反するURLへのweb_fetchは、agent.tool_resultイベントにis_error: trueが付き、url_not_allowedのエラーコードが返ります。web_searchは許可されない結果を一覧から除外します。

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

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

web_searchにパスを付けられるといっても、検索プロバイダーはパスサフィックスをURLパターンとして照合し、厳密なホスト規則としては扱いません。web_searchでも素のホスト名で書くほうが挙動を読みやすくなります。

組織単位の設定との関係も押さえておきます。Consoleで設定する組織レベルのWeb検索・Web Fetch制限はMessages APIにのみ適用され、Managed Agentsのセッションには効きません。環境のnetworking設定も、サンドボックス自身の外向き通信を制御するだけです。web_searchとweb_fetchはAnthropicのサーバー側で動くので、クラウドでも自己ホスト型でも影響を受けません。Managed Agents側を制限する手段は、ツールセットのallowed_domainsとblocked_domainsだけです。

Consoleのエージェントフォームなら、Built-in toolsカードのweb_search・web_fetchの行でドメインを設定できます。max_content_tokensとuser_locationは、設定画面のRawビューで編集します。

マルチエージェントでは、ほかにも次の挙動があります。

  • max_content_tokensとuser_locationは合成されず、そのスレッド自身の設定、なければ呼び出し元、なければコーディネーターの順で採用される
  • {"type": "self"}のロースターエントリは自前のWeb設定を持たず、コーディネーターの現在の設定に従う
  • アウトカム駆動セッションの採点役は、これらの設定にかかわらずweb_searchとweb_fetchなしで動く
  • アイドル中のセッションなら、ツール設定を更新してドメインリストを変更できる。新しいリストは残りのセッションに効き、マルチエージェントでは各スレッドが次のターンから適用する

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

ドメイン設定の書式違反や上限超過は、エージェントの作成・更新や、toolsを渡してのセッション作成・更新の時点で400エラー(invalid_request_error)として即座に弾かれます。両方のリストを設定したエントリにはOnly one of allowed_domains or blocked_domains may be set.、空のリストにはallowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.のようなメッセージが返ります。書式違反のメッセージは、リスト名と0始まりの位置まで示すため、allowed_domains.0: IP addresses are not supportedのように該当箇所を特定しやすくなっています。

同じリクエストで、検索・取得プロバイダーに依存する3つの設定も弾かれます。Anthropicのクローラーがアクセスを許可されていないドメインをallowed_domainsに入れた場合、検索プロバイダーが対応していないuser_location.country、IANA名として無効なuser_location.timezoneです。

それでも、作成後にそのツールが初めて初期化されるタイミングで設定が再チェックされます。そこで無効と判定されると、session.errorイベントが発火し、セッションはリトライせずにidleへ戻ります。復旧の手順は次のとおりです。

手順

session.errorからの復旧

  1. 1

    セッションのツール設定を直す

    エラーで止まったセッションのtoolsを修正し、問題のあった設定を取り除くか書き換えます。

  2. 2

    エージェント側も同じ内容に直す

    セッションだけ直してエージェントを放置すると、新しいセッションが同じエラーを再現します。

  3. 3

    新しい user.message を送る

    エラーで止まったセッションは自動では再開しません。user.messageを送って続行させます。

Messages APIのdomain filteringと同じ書き方で通らない点

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

項目Managed Agentsでの扱い
1リストの上限Managed Agentsでの扱い64ドメイン
web_fetchのパス指定Managed Agentsでの扱い不可
国際化ドメイン名Managed Agentsでの扱いASCIIのPunycode(xn--)形式が必須
max_uses / citations / cache_controlManaged Agentsでの扱いツールセットでは使えない

Messages API側で動いていた設定をそのまま流用すると、Unicode表記のドメインやパス付きのweb_fetchドメインで引っかかりやすくなります。

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

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

標準ツールセットと同じtools配列に、type: "custom"のエントリを並べます。

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

カスタムツールは実行も呼び出し側が握っているため、権限ポリシーの対象外です。agent.custom_tool_useイベントにはevaluated_permissionもevaluationも付きません。承認を挟みたいなら、アプリケーション側で呼び出しを受け取った時点に判断を置く設計になります。

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

設計

カスタムツール定義の4つのコツ

  • 説明を厚く書く

    何をするツールか、いつ使い(使わない)べきか、各パラメータの意味と挙動への影響、注意点まで含めて3〜4文が目安です。複雑なツールならさらに増やします。

  • 関連する操作は1つにまとめる

    create_pr / review_pr / merge_prを別々に作るのではなく、actionパラメータを持つ1つのツールに集約します。選択の曖昧さが減ります。

  • 名前に名前空間を付ける

    複数のサービス・リソースをまたぐなら、db_queryやstorage_readのように接頭辞でリソースを明示します。

  • 返す情報を絞る

    不透明な内部IDではなくスラッグやUUIDのような安定した識別子を返し、次の判断に必要なフィールドだけを含めます。

自己ホスト型サンドボックスでセッションを動かしている場合は、環境ワーカー側からカスタムツールを提供することもできます。社内ネットワーク内のMCPサーバーをラップしたツールも、環境ワーカーから提供できます。

まとめ

ツール設定を変えたときは、アイドル中のセッションを更新するか新しいセッションを作り、実際の呼び出しで効き方を試してから本番に出す流れが安全です。

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

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

関連する記事

Agent SDK をもっと見る →