ツール使用の実装方法

モデルの選択

一般的に、複雑なツールや曖昧なクエリには Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5（非推奨）、または Claude Opus 3（非推奨）を使用してください。これらは複数のツールをより適切に処理し、必要に応じて明確化を求めます。

単純なツールには Claude Haiku 3.5 または Claude Haiku 3 を使用しますが、不足しているパラメータを推測する場合があることに注意してください。

Claude Sonnet 3.7 をツール使用と拡張思考と組み合わせて使用する場合は、詳細についてこちらのガイドを参照してください。

クライアントツールの指定

クライアントツール（Anthropic定義とユーザー定義の両方）は、APIリクエストのtoolsトップレベルパラメータで指定されます。各ツール定義には以下が含まれます：

パラメータ	説明
name	ツールの名前。正規表現 ^[a-zA-Z0-9_-]{1,64}$ に一致する必要があります。
description	ツールが何をするか、いつ使用すべきか、どのように動作するかの詳細なプレーンテキストの説明。
input_schema	ツールの期待されるパラメータを定義する JSON Schema オブジェクト。

シンプルなツール定義の例

JSON

{
  "name": "get_weather",
  "description": "指定された場所の現在の天気を取得する",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "都市と州、例：San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "温度の単位、'celsius' または 'fahrenheit' のいずれか"
      }
    },
    "required": ["location"]
  }
}

このツール get_weather は、必須の location 文字列と、“celsius” または “fahrenheit” のいずれかでなければならないオプションの unit 文字列を含む入力オブジェクトを期待します。

ツール使用システムプロンプト

tools パラメータを使用して Anthropic API を呼び出すと、ツール定義、ツール設定、およびユーザー指定のシステムプロンプトから特別なシステムプロンプトを構築します。構築されたプロンプトは、指定されたツールを使用し、ツールが適切に動作するために必要なコンテキストを提供するようにモデルに指示するように設計されています：

この環境では、ユーザーの質問に答えるために使用できるツールのセットにアクセスできます。
{{ フォーマット指示 }}
文字列とスカラーパラメータはそのまま指定し、リストとオブジェクトはJSON形式を使用する必要があります。文字列値のスペースは削除されないことに注意してください。出力は有効なXMLである必要はなく、正規表現で解析されます。
JSONSchema形式で利用可能な関数は次のとおりです：
{{ JSON SCHEMA でのツール定義 }}
{{ ユーザーシステムプロンプト }}
{{ ツール設定 }}

ツール定義のベストプラクティス

Claude でツールを使用する際に最高のパフォーマンスを得るには、以下のガイドラインに従ってください：

• 極めて詳細な説明を提供する。 これはツールのパフォーマンスにおいて最も重要な要因です。説明には以下を含むツールに関するすべての詳細を説明する必要があります：
  • ツールが何をするか
  • いつ使用すべきか（そしていつ使用すべきでないか）
  • 各パラメータが何を意味し、ツールの動作にどのように影響するか
  • ツール名が不明確な場合にツールが返さない情報など、重要な注意事項や制限。Claude にツールについてより多くのコンテキストを提供するほど、いつどのように使用するかをより適切に決定できるようになります。ツールの説明には少なくとも3〜4文を目指し、ツールが複雑な場合はそれ以上にしてください。
• 例よりも説明を優先する。 ツールの説明や付随するプロンプトにツールの使用例を含めることはできますが、これはツールの目的とパラメータの明確で包括的な説明を持つことよりも重要ではありません。説明を完全に肉付けした後にのみ例を追加してください。

良いツール説明の例

JSON

{
  "name": "get_stock_price",
  "description": "指定されたティッカーシンボルの現在の株価を取得します。ティッカーシンボルは、NYSEやNASDAQなどの主要な米国証券取引所で公開取引されている企業の有効なシンボルである必要があります。このツールは最新の取引価格をUSDで返します。ユーザーが特定の株式の現在または最新の価格について尋ねた場合に使用する必要があります。株式や企業に関するその他の情報は提供しません。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "株式ティッカーシンボル、例：Apple Inc.の場合はAAPL"
      }
    },
    "required": ["ticker"]
  }
}

悪いツール説明の例

JSON

{
  "name": "get_stock_price",
  "description": "ティッカーの株価を取得します。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

良い説明では、ツールが何をするか、いつ使用するか、どのようなデータを返すか、ticker パラメータが何を意味するかを明確に説明しています。悪い説明は簡潔すぎて、Claude にツールの動作と使用法について多くの未解決の質問を残しています。

Claude の出力の制御

ツール使用の強制

場合によっては、Claude がツールを使用せずに答えを提供できると考えていても、ユーザーの質問に答えるために特定のツールを使用させたい場合があります。これは、次のように tool_choice フィールドでツールを指定することで実行できます：

tool_choice = {"type": "tool", "name": "get_weather"}

tool_choice パラメータを使用する場合、4つの可能なオプションがあります：

• auto は、提供されたツールを呼び出すかどうかを Claude に決定させます。これは tools が提供された場合のデフォルト値です。
• any は、提供されたツールのいずれかを使用する必要があることを Claude に伝えますが、特定のツールを強制しません。
• tool は、常に特定のツールを使用するように Claude を強制できます。
• none は、Claude がツールを使用することを防ぎます。これは tools が提供されていない場合のデフォルト値です。

プロンプトキャッシングを使用する場合、tool_choice パラメータの変更はキャッシュされたメッセージブロックを無効にします。ツール定義とシステムプロンプトはキャッシュされたままですが、メッセージコンテンツは再処理する必要があります。

この図は各オプションがどのように機能するかを示しています：

tool_choice が any または tool の場合、ツールの使用を強制するためにアシスタントメッセージを事前入力することに注意してください。これは、明示的に要求された場合でも、モデルが tool_use コンテンツブロックの前に思考の連鎖 text コンテンツブロックを出力しないことを意味します。

ツール使用で拡張思考を使用する場合、tool_choice: {"type": "any"} と tool_choice: {"type": "tool", "name": "..."} はサポートされておらず、エラーが発生します。拡張思考と互換性があるのは tool_choice: {"type": "auto"}（デフォルト）と tool_choice: {"type": "none"} のみです。

私たちのテストでは、これがパフォーマンスを低下させるべきではないことが示されています。特定のツールの使用を要求しながら思考の連鎖（特にOpusで）を維持したい場合は、tool_choice に {"type": "auto"}（デフォルト）を使用し、user メッセージに明示的な指示を追加できます。例：ロンドンの天気はどうですか？応答でget_weatherツールを使用してください。

JSON出力

ツールは必ずしもクライアント関数である必要はありません — 提供されたスキーマに従うJSON出力をモデルに返させたい場合はいつでもツールを使用できます。例えば、特定のスキーマを持つ record_summary ツールを使用する場合があります。完全な動作例については、Claude でのツール使用を参照してください。

思考の連鎖

ツールを使用する場合、Claude はしばしば「思考の連鎖」、つまり問題を分解し、どのツールを使用するかを決定するために使用する段階的な推論を示します。Claude Opus 3（非推奨）モデルは、tool_choice が auto に設定されている場合にこれを行います（これはデフォルト値です。ツール使用の強制を参照）。Sonnet と Haiku はプロンプトでこれを行うように促すことができます。

例えば、「サンフランシスコの現在の天気はどうで、そこの時間は何時ですか？」というプロンプトが与えられた場合、Claude は次のように応答する場合があります：

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "この質問に答えるために、私は次のことを行います：1. get_weather ツールを使用してサンフランシスコの現在の天気を取得します。2. get_time ツールを使用してサンフランシスコ、CAをカバーするAmerica/Los_Angelesタイムゾーンの現在時刻を取得します。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

この思考の連鎖は Claude の推論プロセスへの洞察を提供し、予期しない動作をデバッグするのに役立ちます。

Claude は思考の連鎖を示すためにさまざまな形式を使用する場合があることに注意することが重要です。コードは思考の連鎖を他のアシスタント生成テキストと同様に扱い、特定のフォーマット規則に依存しないようにする必要があります。

並列ツール使用

デフォルトでは、Claude はユーザークエリに答えるために複数のツールを使用する場合があります。この動作は次の方法で無効にできます：

• tool_choice タイプが auto の場合に disable_parallel_tool_use=true を設定すると、Claude が最大1つのツールを使用することが保証されます
• tool_choice タイプが any または tool の場合に disable_parallel_tool_use=true を設定すると、Claude が正確に1つのツールを使用することが保証されます

完全な並列ツール使用の例

メッセージ履歴で並列ツール呼び出しを適切にフォーマットする方法を示す完全な例は次のとおりです：

Python

import anthropic

client = anthropic.Anthropic()

# ツールを定義
tools = [
    {
        "name": "get_weather",
        "description": "指定された場所の現在の天気を取得する",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "都市と州、例：San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "指定されたタイムゾーンの現在時刻を取得する",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "タイムゾーン、例：America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# 初期リクエスト
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "SFとNYCの天気はどうで、そこの時間は何時ですか？"
        }
    ]
)

# 並列ツール呼び出しでのClaude の応答
print("Claude がツールを使用したい:", response.stop_reason == "tool_use")
print("ツール呼び出しの数:", len([c for c in response.content if c.type == "tool_use"]))

# ツール結果で会話を構築
messages = [
    {
        "role": "user",
        "content": "SFとNYCの天気はどうで、そこの時間は何時ですか？"
    },
    {
        "role": "assistant",
        "content": response.content  # 複数のtool_useブロックを含む
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # tool_useのIDと一致する必要があります
                "content": "サンフランシスコ：68°F、部分的に曇り"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "ニューヨーク：45°F、晴天"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "サンフランシスコ時間：午後2:30 PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "ニューヨーク時間：午後5:30 EST"
            }
        ]
    }
]

# 最終応答を取得
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

並列ツール呼び出しを含むアシスタントメッセージは次のようになります：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "サンフランシスコとニューヨーク市の両方の天気と時間を確認します。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

並列ツールの完全なテストスクリプト

並列ツール呼び出しが正しく動作していることをテストおよび検証するための完全で実行可能なスクリプトは次のとおりです：

Python

#!/usr/bin/env python3
"""Anthropic API で並列ツール呼び出しを検証するテストスクリプト"""

import os
from anthropic import Anthropic

# クライアントを初期化
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# ツールを定義
tools = [
    {
        "name": "get_weather",
        "description": "指定された場所の現在の天気を取得する",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "都市と州、例：San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "指定されたタイムゾーンの現在時刻を取得する",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "タイムゾーン、例：America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# 並列ツール呼び出しでのテスト会話
messages = [
    {
        "role": "user",
        "content": "SFとNYCの天気はどうで、そこの時間は何時ですか？"
    }
]

# 初期リクエストを実行
print("並列ツール呼び出しを要求中...")
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# 並列ツール呼び出しをチェック
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude は {len(tool_uses)} 個のツール呼び出しを行いました")

if len(tool_uses) > 1:
    print("✓ 並列ツール呼び出しが検出されました！")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ 並列ツール呼び出しが検出されませんでした")

# ツール実行をシミュレートし、結果を正しくフォーマット
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "サンフランシスコ：68°F、部分的に曇り"
        else:
            result = "ニューヨーク：45°F、晴天"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "午後2:30 PST"
        else:
            result = "午後5:30 EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# ツール結果で会話を続行
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # すべての結果を1つのメッセージに！
])

# 最終応答を取得
print("\n最終応答を取得中...")
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude の応答:\n{final_response.content[0].text}")

# フォーマットを検証
print("\n--- 検証 ---")
print(f"✓ ツール結果が単一のユーザーメッセージで送信されました：{len(tool_results)} 個の結果")
print("✓ コンテンツ配列のツール結果の前にテキストなし")
print("✓ 将来の並列ツール使用のために会話が正しくフォーマットされました")

このスクリプトは以下を実証します：

• 並列ツール呼び出しと結果を適切にフォーマットする方法
• 並列呼び出しが行われていることを検証する方法
• 将来の並列ツール使用を促進する正しいメッセージ構造
• 避けるべき一般的な間違い（ツール結果の前のテキストなど）

このスクリプトを実行して実装をテストし、Claude が効果的に並列ツール呼び出しを行っていることを確認してください。

並列ツール使用の最大化

Claude 4 モデルはデフォルトで優れた並列ツール使用機能を持っていますが、対象を絞ったプロンプトですべてのモデルで並列ツール実行の可能性を高めることができます：

並列ツール使用のシステムプロンプト

Claude 4 モデル（Opus 4.1、Opus 4、Sonnet 4）の場合、システムプロンプトに以下を追加してください：

最大の効率のために、複数の独立した操作を実行する必要がある場合は、順次ではなく同時にすべての関連ツールを呼び出してください。

さらに強力な並列ツール使用（デフォルトが十分でない場合に推奨）には、以下を使用してください：

<use_parallel_tool_calls>
最大の効率のために、複数の独立した操作を実行する場合は、順次ではなく同時にすべての関連ツールを呼び出してください。可能な限り並列でツールを呼び出すことを優先してください。例えば、3つのファイルを読み取る場合、3つのツール呼び出しを並列で実行して、すべての3つのファイルを同時にコンテキストに読み込みます。`ls` や `list_dir` などの複数の読み取り専用コマンドを実行する場合は、常にすべてのコマンドを並列で実行してください。あまりにも多くのツールを順次実行するよりも、並列ツール呼び出しを最大化する側に偏ってください。
</use_parallel_tool_calls>

ユーザーメッセージプロンプト

特定のユーザーメッセージ内で並列ツール使用を促すこともできます：

# 以下の代わりに：
"パリの天気はどうですか？ロンドンもチェックしてください。"

# 以下を使用：
"パリとロンドンの天気を同時にチェックしてください。"

# または明示的に：
"パリ、ロンドン、東京の天気を同時に取得するために並列ツール呼び出しを使用してください。"

Claude Sonnet 3.7 での並列ツール使用

Claude Sonnet 3.7 は、disable_parallel_tool_use を設定していない場合でも、応答で並列ツール呼び出しを行う可能性が低い場合があります。これを回避するために、トークン効率的ツール使用を有効にすることをお勧めします。これにより、Claude が並列ツールを使用することが促進されます。このベータ機能は、レイテンシを削減し、出力トークンを平均14%節約します。

トークン効率的ツール使用ベータにオプトインしたくない場合は、他のツールへの呼び出しを同時にラップするメタツールとして機能する「バッチツール」を導入することもできます。このツールが存在する場合、モデルはそれを使用して複数のツールを並列で同時に呼び出すことがわかります。

この回避策の使用方法については、クックブックのこの例を参照してください。

ツール使用とツール結果コンテンツブロックの処理

Claude の応答は、クライアントツールまたはサーバーツールを使用するかによって異なります。

クライアントツールからの結果の処理

応答には tool_use の stop_reason と、以下を含む1つ以上の tool_use コンテンツブロックがあります：

• id：この特定のツール使用ブロックの一意の識別子。これは後でツール結果をマッチアップするために使用されます。
• name：使用されているツールの名前。
• input：ツールの input_schema に準拠して、ツールに渡される入力を含むオブジェクト。

`tool_use` コンテンツブロックを含むAPI応答の例

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "get_weather を使用する必要があり、ユーザーは SF を望んでいます。これはおそらくサンフランシスコ、CA です。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

クライアントツールのツール使用応答を受信した場合、以下を行う必要があります：

1. tool_use ブロックから name、id、input を抽出します。
2. そのツール名に対応するコードベース内の実際のツールを実行し、ツール input を渡します。
3. user の role と、tool_result タイプと以下の情報を含む content ブロックを持つ新しいメッセージを送信して会話を続けます：
   • tool_use_id：これが結果となるツール使用リクエストの id。
   • content：文字列としてのツールの結果（例："content": "15度"）、ネストされたコンテンツブロックのリスト（例："content": [{"type": "text", "text": "15度"}]）、またはドキュメントブロックのリスト（例："content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15度"}]）。これらのコンテンツブロックは text、image、または document タイプを使用できます。
   • is_error（オプション）：ツール実行がエラーになった場合は true に設定します。

重要なフォーマット要件：

• ツール結果ブロックは、メッセージ履歴内で対応するツール使用ブロックの直後に続く必要があります。アシスタントのツール使用メッセージとユーザーのツール結果メッセージの間にメッセージを含めることはできません。
• ツール結果を含むユーザーメッセージでは、tool_result ブロックがコンテンツ配列の最初に来る必要があります。テキストはすべてのツール結果の後に来る必要があります。

例えば、これは400エラーを引き起こします：

{"role": "user", "content": [
  {"type": "text", "text": "結果は次のとおりです："},  // ❌ tool_result の前のテキスト
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

これは正しいです：

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "次に何をすべきですか？"}  // ✅ tool_result の後のテキスト
]}

「tool_use ids were found without tool_result blocks immediately after」のようなエラーが発生した場合は、ツール結果が正しくフォーマットされていることを確認してください。

成功したツール結果の例

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15度"
    }
  ]
}

画像を含むツール結果の例

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15度"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

空のツール結果の例

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

ドキュメントを含むツール結果の例

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "天気は"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15度"
          }
        }
      ]
    }
  ]
}

ツール結果を受信した後、Claude はその情報を使用して元のユーザープロンプトへの応答の生成を続けます。

サーバーツールからの結果の処理

Claude はツールを内部で実行し、追加のユーザーインタラクションを必要とせずに結果を応答に直接組み込みます。

他のAPIとの違い

ツール使用を分離したり、tool や function などの特別な役割を使用する API とは異なり、Anthropic の API はツールを user と assistant メッセージ構造に直接統合します。

メッセージには text、image、tool_use、tool_result ブロックの配列が含まれます。user メッセージにはクライアントコンテンツと tool_result が含まれ、assistant メッセージには AI 生成コンテンツと tool_use が含まれます。

max_tokens 停止理由の処理

Claude の応答が max_tokens 制限に達したために切り捨てられ、切り捨てられた応答に不完全なツール使用ブロックが含まれている場合、完全なツール使用を取得するために、より高い max_tokens 値でリクエストを再試行する必要があります。

Python

# ツール使用中に応答が切り捨てられたかどうかをチェック
if response.stop_reason == "max_tokens":
    # 最後のコンテンツブロックが不完全な tool_use かどうかをチェック
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # より高い max_tokens でリクエストを送信
        response = client.messages.create(
            model="claude-opus-4-1-20250805",
            max_tokens=4096,  # 制限を増加
            messages=messages,
            tools=tools
        )

pause_turn 停止理由の処理

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

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

Python

import anthropic

client = anthropic.Anthropic()

# ウェブ検索での初期リクエスト
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "2025年の量子コンピューティングの画期的進歩について包括的な情報を検索してください"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# 応答に pause_turn 停止理由があるかどうかをチェック
if response.stop_reason == "pause_turn":
    # 一時停止されたコンテンツで会話を続行
    messages = [
        {"role": "user", "content": "2025年の量子コンピューティングの画期的進歩について包括的な情報を検索してください"},
        {"role": "assistant", "content": response.content}
    ]
    
    # 継続リクエストを送信
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

pause_turn を処理する場合：

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

エラーのトラブルシューティング

Claude でツールを使用する際に発生する可能性のあるエラーにはいくつかの種類があります：

ツール実行エラー

ツール自体が実行中にエラーをスローした場合（例：天気データを取得する際のネットワークエラー）、"is_error": true と共に content でエラーメッセージを返すことができます：

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: 天気サービス API が利用できません (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude はこのエラーをユーザーへの応答に組み込みます。例：「申し訳ございませんが、天気サービス API が利用できないため、現在の天気を取得できませんでした。後でもう一度お試しください。」

無効なツール名

Claude のツール使用の試行が無効な場合（例：必須パラメータの欠如）、通常は Claude がツールを正しく使用するための十分な情報がなかったことを意味します。開発中の最善の策は、ツール定義でより詳細な description 値を使用してリクエストを再試行することです。

ただし、エラーを示す tool_result で会話を前進させることもでき、Claude は不足している情報を埋めてツールを再度使用しようとします：

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "エラー：必須の 'location' パラメータが不足しています",
      "is_error": true
    }
  ]
}

ツールリクエストが無効または不足しているパラメータがある場合、Claude はユーザーに謝罪する前に修正を加えて2〜3回再試行します。

<search_quality_reflection> タグ

Claude が <search_quality_reflection> タグで検索品質を反映することを防ぐには、プロンプトに「返された検索結果の品質について応答で反映しないでください」を追加してください。

サーバーツールエラー

サーバーツールがエラーに遭遇した場合（例：ウェブ検索でのネットワーク問題）、Claude はこれらのエラーを透過的に処理し、ユーザーに代替応答または説明を提供しようとします。クライアントツールとは異なり、サーバーツールの is_error 結果を処理する必要はありません。

ウェブ検索に関して、可能なエラーコードには以下が含まれます：

• too_many_requests：レート制限を超過
• invalid_input：無効な検索クエリパラメータ
• max_uses_exceeded：最大ウェブ検索ツール使用回数を超過
• query_too_long：クエリが最大長を超過
• unavailable：内部エラーが発生

並列ツール呼び出しが機能しない

期待される場合に Claude が並列ツール呼び出しを行わない場合は、これらの一般的な問題を確認してください：

1. 不正なツール結果フォーマット

最も一般的な問題は、会話履歴でツール結果を不正にフォーマットすることです。これは Claude に並列呼び出しを避けるように「教える」ことになります。

特に並列ツール使用について：

• ❌ 間違い：各ツール結果に対して別々のユーザーメッセージを送信
• ✅ 正しい：すべてのツール結果が単一のユーザーメッセージに含まれている必要があります

// ❌ これは並列ツール使用を減少させます
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // 別のメッセージ
]

// ✅ これは並列ツール使用を維持します
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // 単一のメッセージ
]

その他のフォーマット規則については、上記の一般的なフォーマット要件を参照してください。

2. 弱いプロンプト

デフォルトのプロンプトでは十分でない場合があります。より強い言葉を使用してください：

<use_parallel_tool_calls>
最大の効率のために、複数の独立した操作を実行する場合は、
順次ではなく同時にすべての関連ツールを呼び出してください。
可能な限り並列でツールを呼び出すことを優先してください。
</use_parallel_tool_calls>

3. 並列ツール使用の測定

並列ツール呼び出しが機能していることを確認するには：

# ツール呼び出しメッセージあたりの平均ツール数を計算
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"メッセージあたりの平均ツール数: {avg_tools_per_message}")
# 並列呼び出しが機能している場合は > 1.0 であるべきです

4. モデル固有の動作

• Claude Opus 4.1、Opus 4、Sonnet 4：最小限のプロンプトで並列ツール使用に優れています
• Claude Sonnet 3.7：より強いプロンプトまたはトークン効率的ツール使用が必要な場合があります
• Claude Haiku：明示的なプロンプトなしでは並列ツールを使用する可能性が低いです