サーバーツール

サーバー実行ツールは、server_tool_useブロック、pause_turnの継続、サーバーツールとクライアントツールが混在するターン、「Zero Data Retention」（ゼロデータ保持）、すなわち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で応答する必要はありません。ツールの結果ブロック（たとえば、ウェブ検索の場合はweb_search_tool_result）は、同じアシスタントターン内でserver_tool_useブロックの後に続き、tool_use_idによってペアになります。Claudeが同時にクライアントツールのいずれかを呼び出した場合、server_tool_useブロックは結果なしで表示され、レスポンスはstop_reason: "tool_use"で終了します。次のリクエストでクライアントのtool_resultブロックを返すと、APIがツールを実行します。



サーバー側ループとpause_turn

ウェブ検索などのサーバーツールを使用する場合、APIはサーバー側のエージェントループでツール呼び出しを実行します。長時間実行されるターンでは、APIがそのループを一時停止し、pause_turnという停止理由を返すことがあります。

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

client = anthropic.Anthropic()

# ウェブ検索を使用した初回リクエスト
response = client.messages.create(
    model="claude-opus-4-8",
    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}],
)

# レスポンスのstop_reasonがpause_turnかどうかを確認
if response.stop_reason == "pause_turn":
    # 一時停止されたコンテンツで会話を継続
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # 継続リクエストを送信
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

pause_turnを処理する際は、次の点に注意してください。

• 会話を継続する： 一時停止されたレスポンスをそのまま後続のリクエストに渡して、Claudeがターンを継続できるようにします。
• ツールの状態を保持する： 継続リクエストに同じツールを含めます。一時停止されたターンは、まだ実行されていないツールのserver_tool_useブロックで終わることがあり、そのツールが継続リクエストに含まれていない場合、APIはバリデーションエラーを返します。
• 必要に応じて繰り返す： 継続されたターンが再び一時停止することもあります。各レスポンスのstop_reasonを確認し、異なる停止理由が返されるまで継続します。他のリトライループと同様に、継続回数に上限を設けてください。

その他のstop_reason値と一般的な処理パターンについては、停止理由とフォールバックを参照してください。



1つのターンでサーバーツールとクライアントツールを混在させる

Claudeは、同じ並列ツール呼び出しグループ内でサーバーツールとクライアントツールを呼び出すことができます。たとえば、web_fetchとユーザー定義ツールを同時に呼び出すことができます。クライアントツールとは、ユーザー定義ツールであるか、BashツールのようなAnthropicスキーマのクライアントツールであるかにかかわらず、コードが実行してtool_useブロックを生成するツールのことです。このような場合、APIはサーバーツールを実行しません。クライアントツールを先に実行できるように、すぐに返します。

• stop_reasonは"pause_turn"ではなく"tool_use"です。
• contentにはserver_tool_useブロックとクライアントのtool_useブロックが含まれますが、サーバーツールの結果ブロックは含まれません。その呼び出しはまだ完了していません。
• 他にマーカーはありません。レスポンス内でidに対応する結果ブロックがないserver_tool_useブロックを探すことで、この状態を検出します。MCPコネクタからのmcp_tool_useブロックも同じように動作します。同じレスポンス内にすでに結果ブロックがあるサーバーツール呼び出しは完了しており、何もする必要はありません。

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "text",
      "text": "I'll fetch the article and check your system at the same time."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_fetch",
      "input": { "url": "https://example.com/article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

ターンを継続するには、クライアントツールを実行し、そのレスポンス内の各tool_useブロックに対応するtool_resultブロックのみを内容とするユーザーメッセージを送信します。同じtools配列を維持してください。待機中のサーバーツールを定義しなくなった再開リクエストは、but no `web_fetch` tool was providedで終わるメッセージを持つ400エラーで失敗します。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

APIは結果をまだ開いているアシスタントターンに添付し、遅延されたサーバーツールを実行し（一時停止されたコード実行の場合は再開し）、その後Claudeに継続させます。Claudeが直接呼び出したサーバーツールの場合、次のレスポンスは、前のレスポンスのserver_tool_useのidに対応する結果ブロックで始まり、その後に新しく生成されたコンテンツと新しいstop_reasonが続きます。

{
  "stop_reason": "end_turn",
  "content": [
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          }
        }
      }
    },
    {
      "type": "text",
      "text": "The article argues that... and your machine is running Linux..."
    }
  ]
}

server_tool_useブロックとその結果ブロックは、位置ではなくtool_use_idによってペアになります。このフローでは、それらは2つの異なるレスポンスで到着し、server_tool_useブロックは2番目のレスポンスでは繰り返されません。後続のリクエストでは、やり取り全体をmessages配列に順番に保持してください。最初のレスポンスをassistantメッセージとして、tool_resultユーザーメッセージ、そして次のレスポンスを別のassistantメッセージとして、他のツール使用のやり取りを蓄積するのと同じ方法で保持します。

`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block

`tool_use` ids were found without `tool_result` blocks immediately after: toolu_01PjgRJLbXrXEMZwDNYLnBqk. Each `tool_use` block must have a corresponding `tool_result` block in the next message.

pause_turnとの違い： pause_turnレスポンスも、まだ実行されていないserver_tool_useブロックで終わることがありますが、クライアントのtool_useブロックがあなたの対応を待っている状態になることはありません。そのため、アシスタントのコンテンツをそのまま再送信することで継続します。クライアントのtool_useブロックがあなたの対応を待っているレスポンスのstop_reasonがpause_turnになることはありません。Claudeがツールを呼び出すために停止した場合、stop_reasonはtool_useであり、レスポンスを再送信するのではなく、クライアントのtool_resultブロックを送信することで継続します。どちらの場合も、APIは次のリクエストの開始時に保留中のサーバーツールを実行します。

次の例では、ユーザー定義のrun_commandツールとともにウェブフェッチを有効にし、混在したレスポンスを処理します。

client = anthropic.Anthropic()

tools = [
    {"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
    {
        "name": "run_command",
        "description": "Run a shell command on this computer and return its output.",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"],
        },
    },
]
messages = [
    {
        "role": "user",
        "content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
    }
]

response = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages
)

tool_results = [
    {
        "type": "tool_result",
        "tool_use_id": block.id,
        # ここでツールを実行します。この例では固定文字列を返します。
        "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
    }
    for block in response.content
    if block.type == "tool_use"
]

if response.stop_reason == "tool_use" and tool_results:
    # このレスポンス内に結果ブロックがない server_tool_use ブロックは未完了であり、その結果は後続のレスポンスで届きます。
    # 同じツールを指定して、クライアント側の tool_result ブロックのみを返送します。
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        tools=tools,
        messages=[
            *messages,
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results},
        ],
    )
    # web_fetch が保留されていた場合、このリクエストで実行され、その
    # web_fetch_tool_result が continuation.content の最初のブロックになります。
    print(continuation)
else:
    print(response)

このコードは、Claudeが2種類の呼び出しを混在させない場合でも正しく動作します。クライアントのtool_useブロックのみのターンは同じ継続パスをたどり、サーバーツール呼び出しのみのターンはクライアントのtool_resultブロックを必要としません。その結果ブロックは通常すでに存在しており、pause_turnレスポンスのように一時停止状態で返ってきたものは、代わりにそのまま再送信されます。



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_callersは、ツールの呼び出し方法を制御します。Claudeによる直接呼び出し（"direct"）、コード実行コンテナ内からの呼び出し（たとえば"code_execution_20260120"）、またはその両方です。ウェブツールの_20260209バージョンは、デフォルトでコード実行呼び出し元のみになります。それ以前のバージョンは["direct"]がデフォルトです。プログラマティックツール呼び出しをサポートしていないモデルでは、これらのバージョンにはallowed_callers: ["direct"]が必要です。これがない場合、APIはそれを設定するように指示するバリデーションエラーを返します。



ドメインフィルタリング

ウェブにアクセスするサーバーツールは、Claudeがアクセスできるドメインを制御するためにallowed_domainsおよびblocked_domainsパラメータを受け付けます。どちらもツールオブジェクトのフィールドです。

{
  "type": "web_search_20250305",
  "name": "web_search",
  "allowed_domains": ["example.com", "docs.python.org"]
}

ドメインフィルターを使用する際は、次の点に注意してください。

• ドメインには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にマッチします）。
• ウェブフェッチはドメインのみでマッチします。パスを含むエントリはウェブフェッチURLにマッチしません。
• allowed_domainsまたはblocked_domainsのいずれかを使用できますが、同じリクエストで両方を使用することはできません。

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

• ワイルドカード（*）はドメイン自体には使用できず、その後のパスにのみ使用できます。
• 有効：example.com/*、example.com/*/articles
• 無効：*.example.com、ex*.com

無効なドメイン形式は、リクエスト時に400 invalid_request_errorで拒否されます。



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

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



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

サーバーツールイベントは、通常の「server-sent events」（サーバー送信イベント）、すなわちSSEフローの一部としてストリーミングされます。Claudeが直接呼び出すserver_tool_useブロックは、クライアントのtool_useブロックと同様にストリーミングされます。content_block_startイベントの後にinput_json_deltaイベントが続きます。結果ブロックは、デルタなしで単一のcontent_block_startイベントで完全な形で到着します。

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



バッチリクエスト

すべてのサーバーツールはバッチ処理をサポートしています。バッチでは、エージェントループは同期リクエストと同様に実行されますが、ターンごとの反復制限が高くなります。ループがその制限に達すると、レスポンスはstop_reason: "pause_turn"で終了します。返されたコンテンツを含むフォローアップリクエストを送信することで継続できます。詳細については、サーバーツールとエージェントループを参照してください。

一般的なバッチワークロードには、ウェブからの情報でデータセットを充実させること、大量のドキュメントを最新のソースと照合すること、多数のファイルに対して分析コードを実行することなどがあります。



次のステップ