サーバーツール

このページでは、サーバー実行ツールの共有メカニクスについて説明します：server_tool_useブロック、pause_turn継続、ZDRの考慮事項、およびドメインフィルタリングです。個別のツールについては、ツールリファレンスを参照してください。

server_tool_useブロック

server_tool_useブロックは、サーバー実行ツールが実行されるとClaudeの応答に表示されます。そのidフィールドはsrvtoolu_プレフィックスを使用して、クライアントツール呼び出しと区別します：

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

APIはツールを内部で実行します。呼び出しとその結果は応答に表示されますが、実行を処理する必要はありません。クライアントtool_useブロックとは異なり、tool_resultで応答する必要はありません。結果ブロックは同じアシスタントターン内のserver_tool_useブロックの直後に表示されます。

サーバー側ループとpause_turn

ウェブ検索などのサーバーツールを使用する場合、APIはpause_turn停止理由を返す可能性があり、これはAPIが長時間実行されるターンを一時停止したことを示します。

pause_turn停止理由を処理する方法は次のとおりです：

# Initial request with web search
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

pause_turnを処理する場合：

• 会話を続ける： 一時停止された応答をそのまま後続のリクエストで渡して、Claudeがターンを続行できるようにします
• 必要に応じて変更： 会話を中断またはリダイレクトしたい場合は、オプションで続行前にコンテンツを変更できます
• ツール状態を保持： 機能を維持するために、継続リクエストに同じツールを含めます

ZDRとallowed_callers

ウェブ検索の基本バージョン（web_search_20250305）とウェブフェッチ（web_fetch_20250910）は、Zero Data Retention（ZDR）の対象です。

動的フィルタリング付きの_20260209バージョンは、動的フィルタリングが内部でコード実行に依存しているため、デフォルトではZDR対象ではありません。

_20260209サーバーツールをZDRで使用するには、ツールで"allowed_callers": ["direct"]を設定して動的フィルタリングを無効にします：

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

これにより、ツールは直接呼び出しのみに制限され、内部コード実行ステップをバイパスします。

ドメインフィルタリング

ウェブにアクセスするサーバーツールは、allowed_domainsおよびblocked_domainsパラメータを受け入れて、Claudeが到達できるドメインを制御します。

ドメインフィルタを使用する場合：

• ドメインはHTTP/HTTPSスキームを含めないでください（https://example.comの代わりにexample.comを使用）
• サブドメインは自動的に含まれます（example.comはdocs.example.comをカバー）
• 特定のサブドメインは結果をそのサブドメインのみに制限します（docs.example.comはexample.comまたはapi.example.comからではなく、そのサブドメインからのみ結果を返す）
• サブパスはサポートされており、パスの後のすべてにマッチします（example.com/blogはexample.com/blog/post-1にマッチ）
• allowed_domainsまたはblocked_domainsのいずれかを使用できますが、同じリクエストで両方を使用することはできません

ワイルドカードサポート：

• ドメインエントリごとに1つのワイルドカード（*）のみが許可され、ドメイン部分の後（パス内）に表示される必要があります
• 有効：example.com/*、example.com/*/articles
• 無効：*.example.com、ex*.com、example.com/*/news/*

無効なドメイン形式はinvalid_tool_inputツールエラーを返します。

コード実行による動的フィルタリング

ウェブ検索とウェブフェッチの_20260209バージョンは、検索結果に対して動的フィルタを適用するために内部でコード実行を使用します。

サーバーツールイベントのストリーミング

サーバーツールイベントは通常のSSEフローの一部としてストリーミングされます。server_tool_useブロックとその結果は、テキストとクライアントツール呼び出しと同じ方法でcontent_block_startおよびcontent_block_deltaイベントとして到着します。

完全なイベントリファレンスについては、ストリーミングを参照してください。個別のツールページは、異なる場合はツール固有のイベント名を文書化します。

バッチリクエスト

すべてのサーバーツールはバッチ処理をサポートしています。バッチ処理を参照してください。

次のステップ