Claude Platform Docs
Messagesツール

サーバーツール

Anthropicが実行するツールを扱います：server_tool_useブロック、pause_turnによる継続、サーバーツールとクライアントツールが混在するターン、ドメインフィルタリング。

サーバーで実行されるツールには、次の共通の仕組みがあります：server_tool_useブロック、pause_turnによる継続、サーバーツールとクライアントツールが混在するターン、「Zero Data Retention」（ゼロデータ保持）、すなわちZDRの適格性、そして「domain filtering」（ドメインフィルタリング）です。個々のツールについては、ツールリファレンスを参照してください。

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"で終了します。APIは、次のリクエストでクライアントのtool_resultブロックを返したときにツールを実行します。

サーバー側ループとpause_turn

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

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

client = anthropic.Anthropic()

# Web検索を使用した最初のリクエスト
response = client.messages.create(
    model="claude-opus-5-5",
    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-5-5",
        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とユーザー定義ツールを一緒に呼び出す場合です。クライアントツールとは、コードで実行されtool_useブロックを生成するツールのことで、ユーザー定義のものか、BashツールのようなAnthropicスキーマのクライアントツールかは問いません。このような場合、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ブロックに対して1つずつ、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メッセージとして保持します。

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）の対象です。

「dynamic filtering」（動的フィルタリング）を備えた_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で拒否されます。

Claude Managed Agentsは、エージェントツールセットのweb_searchおよびweb_fetchエントリで同じallowed_domainsおよびblocked_domainsフィールドを使用します。Managed Agentsでは、各リストに含められるエントリは最大64件で、web_fetchに指定するドメインにはパスを含めることができず、max_uses、citations、cache_controlなどのMessages APIツール固有のフィールドは使用できません。完全なルールについては、ウェブ検索とウェブフェッチのドメインを制限するを参照してください。

Claude Consoleにおける組織レベルのウェブ検索およびウェブフェッチの設定は、Messages APIリクエストにのみ適用されます。Managed Agentsのセッションには適用されず、セッションではエージェントツールセット上のツールごとのリストのみが使用されます。

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

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

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

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

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

バッチリクエスト

すべてのサーバーツールは「batch processing」（バッチ処理）をサポートしています。バッチでは、エージェントループは同期リクエストの場合と同じように実行されますが、ターンごとの反復回数の上限がより高くなります。ループがその上限に達すると、レスポンスはstop_reason: "pause_turn"で終了します。返されたコンテンツを使ってフォローアップリクエストを送信することで継続できます。詳細については、サーバーツールとエージェントループを参照してください。

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

次のステップ

ツール使用のトラブルシューティング

症状から修正方法を導く診断表を使って、最も一般的なツール使用のエラーを修正します。

ウェブ検索ツール

ウェブを検索し、結果を引用します。

ウェブフェッチツール

特定のURLからコンテンツを取得して読み込み、ライブのウェブコンテンツでClaudeのコンテキストを拡張します。

コード実行ツール

サンドボックス化されたコンテナでPythonとbashのコードを実行し、データの分析、ファイルの生成、ソリューションの反復改善を行います。

ツール検索ツール

必要に応じてツールを検出して読み込みます。

Was this page helpful?