Web検索とWebフェッチのドメインを制限する

エージェントのWebツールがアクセスできるサイトを制御するには、エージェントツールセットのweb_searchおよびweb_fetchエントリにドメインリストを設定します。これらの各configsエントリは、次の2つのリストのいずれかを受け取ります。

• allowed_domains： ツールはこれらのホストにのみアクセスできます。
• blocked_domains： ツールはこれらのホストには決してアクセスできません。

各ツールはそれぞれ独自のリストを持つため、web_searchとweb_fetchに異なる制限を設定できます。

エージェントにドメインリストを設定する

次の例では、web_searchを2つのサイトに制限し、web_fetchに対して1つのホストをブロックするエージェントを作成します。また、設定で説明するuser_locationとmax_content_tokensも設定します。その後、この例ではレスポンスからconfigs配列を出力します。

ant apply agent.md

---
name: Research Agent
model: claude-opus-5-5
tools:
  - 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
---

limitedのネットワーキングを持つクラウド環境では、環境のallowed_hostsもweb_searchとweb_fetchに適用されます。有効になっているWebツールのallowed_domainsにallowed_hostsの範囲外のエントリがある場合、セッションの作成は400エラーで失敗します。そのようなエントリを追加するセッションの更新も同様です。これを修正するには、ホストをallowed_hostsに追加するか、allowed_domainsからエントリを削除します。実行時に、allowed_hostsに一致しないホスト上のURLに対するweb_fetch呼び出しは、url_not_allowedエラー結果を返します。web_searchはそのようなホストからの結果を除外します。2つのリストは一致の仕方が異なります。ツールのエントリはそのサブドメインもカバーしますが、allowed_hostsのエントリは*.で始まらない限り、1つの完全一致するホストにのみ一致します。たとえば、ツールのエントリdocs.example.comは["example.com"]のallowed_hostsの範囲内ではありませんが、["docs.example.com"]または["*.example.com"]の範囲内です。

Claude Consoleでは、エージェントフォームのBuilt-in toolsカードにあるweb_searchおよびweb_fetchの行から、許可またはブロックするドメインを設定します。max_content_tokensとuser_locationは、エージェントの設定のRawビューで設定します。

設定

enabledとpermission_policyに加えて、Webツールのエントリは次の設定を受け付けます。

SDKがこれらのエントリをどのように型付けしているかについては、SDKにおける設定エントリの型を参照してください。

ドメインが許可されていない場合

web_searchは、そのドメインリストで許可されていない結果を除外します。ドメインリストで許可されていないURLに対するweb_fetch呼び出しは、エージェントにエラー結果を返します。agent.tool_resultイベントにはis_error: trueが含まれ、そのコンテンツにはエラーコードurl_not_allowedが示されます。

ドメインリストのルール

これらのルールはallowed_domainsとblocked_domainsの両方に適用されます。ルールに違反するリクエストは、検証エラーで説明するとおり拒否されます。

• エントリごとに1つのリスト： エントリにはallowed_domainsまたはblocked_domainsのいずれかを設定し、両方は設定しないでください。
• リストのサイズ： 各リストには1〜64個のドメインを含めることができ、各ドメインは1〜255文字です。
• 空のリストは不可： 制限を適用しない場合は、フィールドを省略するかnullを送信してください。
• 重複不可： 1つのドメインはリスト内に1回しか出現できません。www.example.comとexample.comは異なるドメインとして扱われます。

リストに記載したドメインが一致する範囲

リストに記載したドメインは、そのホストとそのすべてのサブドメインに一致します。example.comはdocs.example.comをカバーしますが、docs.example.comはexample.comやapi.example.comをカバーしません。

先頭のwww.は他と同様のサブドメインであるため、www.example.comはexample.comをカバーしません。両方をカバーするには、ベアドメインを記載してください。

ホスト名は大文字と小文字を区別せずに比較されます。

ドメインの形式

各ドメインは、登録可能なドメイン名またはそのサブドメインであり、プレーンなホスト名として記述します。ASCII文字、数字、ハイフン、アンダースコア、ドットを含めることができます。末尾の単一の/は無視されます。

認証情報や空白を含むドメイン、またはいずれかのラベルがハイフンで始まるか終わるドメインも拒否されます。localhost、および.localhost、.local、.internal、.localdomain、.invalidで終わるホストも拒否されます。

Web検索ドメインのパスサフィックス

web_searchのドメインには、example.com/blogのようなパスサフィックスを付けることができます。パスには、スペース、?、#、または$ , | ^ !のいずれの文字も含めることはできません。

web_searchでもプレーンなホスト名を使用することをお勧めします。検索プロバイダーは、パスサフィックスを厳密なホストルールとしてではなく、URLパターンとして照合します。

検証エラー

APIは、エージェントを作成するとき、またはエージェントを更新するときにこれらの設定を検証します。また、toolsを指定するセッションを作成または更新するときにも検証します。

形式および制限の違反は、400 invalid_request_errorで拒否されます。

同じリクエストにおいて、APIは検索プロバイダーおよびフェッチプロバイダーに依存する次の3つの設定も拒否します。

• Anthropicのクローラーがアクセスを許可されていない、allowed_domains内のドメイン。
• 検索プロバイダーがサポートしていないuser_location.country。メッセージはuser_location.country: not a country the search provider supportsで終わります。
• 有効なIANA名ではないuser_location.timezone。

limitedのネットワーキングを持つクラウド環境では、セッションの作成と更新の際に、allowed_domainsが環境のallowed_hostsに照らしてチェックされます。エージェントにドメインリストを設定するのルールを参照してください。

受け付けられた設定が有効でなくなった場合

セッションは、ツールを最初に初期化するときに設定を再度チェックします。以前に受け付けられた設定がその時点で有効でなくなっている場合、セッションはsession.errorイベントを発行します。その後、再試行せずにidleに戻ります。

セッションを続行するには、次の手順を実行します。

1. セッションのツールを更新して設定を修正します。
2. 新しいセッションが修正済みの設定で開始されるように、エージェントも更新します。
3. 新しいuser.messageを送信します。

マルチエージェントセッションとアウトカム駆動セッション

マルチエージェントセッションでは、スレッドに適用されるすべてのドメインリストが同時に適用されます。コーディネーターのロスターに含まれるエージェントは、次の3組のリストに拘束されます。

• 自身のallowed_domainsとblocked_domains
• それを呼び出したエージェントのリスト
• コーディネーターの現在のリスト

設定は次のように組み合わされます。

したがって、ロスターエージェントはツールがアクセスできる範囲を狭めることはできますが、広げることはできません。

• blocked_domainsを設定したロスターエージェントは、コーディネーターのallowed_domainsを維持し、その範囲内でそれらのホストをブロックします。
• 独自のallowed_domainsを設定したロスターエージェントは、自身のリストとコーディネーターのリストの両方がカバーするホストにのみアクセスできます。

{"type": "self"}のロスターエントリは独自のWeb設定を持たず、コーディネーターの現在の設定に従います。

組み合わされたallowed_domainsリストに共通のドメインがない場合、ツールはそのエージェントで引き続き利用可能ですが、すべての呼び出しが失敗します。各呼び出しは、許可されているドメインがないことを示すurl_not_allowedエラーを返します。ツールの説明もモデルに同じことを伝えます。これを避けるには、各ロスターエージェントのallowed_domainsをコーディネーターのリストの範囲内に収めてください。

アウトカム駆動セッションのグレーダーは、これらの設定にかかわらず、web_searchとweb_fetchなしで実行されます。

セッション中にリストを変更する

アイドル状態のセッションでは、ツールを更新することでリストを変更できます。新しいリストはセッションの残りの部分に適用されます。

マルチエージェントセッションでは、すべてのスレッドが次のターンから新しいリストを適用します。この更新によってロスターエージェント自身のリストは変更されません。それらは、セッション作成時にエージェントの定義で設定されたままになります。

Messages APIのツールとの違い

これらの設定は、Messages APIのサーバーツールにおけるドメインフィルタリングと同じallowed_domainsおよびblocked_domainsフィールドを使用します。Managed Agentsは次の4点で異なります。

• 各リストは64ドメインが上限です。
• web_fetchに記載するドメインにはパスを含めることができません。
• ドメインはASCIIである必要があります。Messages APIはUnicodeのエントリを受け付けますが、使用は推奨していません。
• max_uses、citations、cache_controlはツールセットでは利用できません。

次のステップ