ツール使用の実装方法

モデルの選択

複雑なツールや曖昧なクエリには、最新のClaude Opus（4.6）モデルの使用をお勧めします。複数のツールをより適切に処理し、必要に応じて明確化を求めます。

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

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

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

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

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

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

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

ツール使用時にClaudeから最高のパフォーマンスを引き出すために、以下のガイドラインに従ってください：

• 非常に詳細な説明を提供してください。 これはツールのパフォーマンスにおいて最も重要な要素です。説明には、ツールに関するすべての詳細を含める必要があります：
  • ツールが何をするか
  • いつ使用すべきか（いつ使用すべきでないか）
  • 各パラメータの意味とツールの動作への影響
  • ツール名が不明確な場合にツールが返さない情報など、重要な注意事項や制限事項。ツールについてClaudeにより多くのコンテキストを提供するほど、いつどのように使用するかの判断が向上します。ツールの説明は少なくとも3〜4文を目指し、複雑なツールの場合はそれ以上にしてください。
• 説明を優先しつつ、複雑なツールにはinput_examplesの使用を検討してください。 明確な説明が最も重要ですが、複雑な入力、ネストされたオブジェクト、またはフォーマットに敏感なパラメータを持つツールの場合、input_examplesフィールド（ベータ）を使用してスキーマ検証済みの例を提供できます。詳細はツール使用例の提供を参照してください。

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

ツール使用例の提供

有効なツール入力の具体的な例を提供して、Claudeがツールをより効果的に使用する方法を理解できるようにすることができます。これは、ネストされたオブジェクト、オプションパラメータ、またはフォーマットに敏感な入力を持つ複雑なツールに特に有用です。

基本的な使用方法

ツール定義にオプションのinput_examplesフィールドを追加し、入力オブジェクトの例の配列を指定します。各例はツールのinput_schemaに従って有効である必要があります：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    betas=["advanced-tool-use-2025-11-20"],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature"
                    }
                },
                "required": ["location"]
            },
            "input_examples": [
                {
                    "location": "San Francisco, CA",
                    "unit": "fahrenheit"
                },
                {
                    "location": "Tokyo, Japan",
                    "unit": "celsius"
                },
                {
                    "location": "New York, NY"  # 'unit' is optional
                }
            ]
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
)

例はツールスキーマと一緒にプロンプトに含まれ、Claudeに適切に構成されたツール呼び出しの具体的なパターンを示します。これにより、Claudeはオプションパラメータをいつ含めるか、どのフォーマットを使用するか、複雑な入力をどのように構造化するかを理解できます。

要件と制限事項

• スキーマ検証 - 各例はツールのinput_schemaに従って有効である必要があります。無効な例は400エラーを返します
• サーバーサイドツールではサポートされません - ユーザー定義ツールのみが入力例を持つことができます
• トークンコスト - 例はプロンプトトークンに加算されます：シンプルな例で約20〜50トークン、複雑なネストされたオブジェクトで約100〜200トークン

ツールランナー（ベータ）

ツールランナーは、Claudeでツールを実行するためのすぐに使えるソリューションを提供します。ツール呼び出し、ツール結果、会話管理を手動で処理する代わりに、ツールランナーは自動的に以下を行います：

• Claudeがツールを呼び出した際にツールを実行
• リクエスト/レスポンスサイクルの処理
• 会話状態の管理
• 型安全性と検証の提供

ほとんどのツール使用実装にはツールランナーの使用をお勧めします。

基本的な使用方法

SDKヘルパーを使用してツールを定義し、ツールランナーを使用して実行します。

ツール関数は、テキスト、画像、またはドキュメントブロックを含むコンテンツブロックまたはコンテンツブロック配列を返す必要があります。これにより、ツールはリッチでマルチモーダルなレスポンスを返すことができます。返された文字列はテキストコンテンツブロックに変換されます。構造化されたJSONオブジェクトをClaudeに返したい場合は、返す前にJSON文字列にエンコードしてください。数値、ブール値、その他の非文字列プリミティブも文字列に変換する必要があります。

ツールランナーのイテレーション

ツールランナーは、Claudeからのメッセージを生成するイテラブルです。これは一般的に「ツール呼び出しループ」と呼ばれます。各イテレーションで、ランナーはClaudeがツール使用をリクエストしたかどうかを確認します。リクエストがあった場合、ツールを呼び出して結果を自動的にClaudeに送り返し、次のメッセージを生成してループを継続します。

break文を使用して、任意のイテレーションでループを終了できます。ランナーは、Claudeがツール使用なしのメッセージを返すまでループを続けます。

中間メッセージが不要な場合は、最終メッセージを直接取得できます：

高度な使用方法

ループ内で、ツールランナーのMessages APIへの次のリクエストを完全にカスタマイズできます。ランナーはツール結果をメッセージ履歴に自動的に追加するため、手動で管理する必要はありません。オプションで、ログやデバッグのためにツール結果を検査したり、次のAPI呼び出しの前にリクエストパラメータを変更したりできます。

ツール実行のデバッグ

ツールが例外をスローした場合、ツールランナーはそれをキャッチし、is_error: trueのツール結果としてClaudeにエラーを返します。デフォルトでは、例外メッセージのみが含まれ、完全なスタックトレースは含まれません。

完全なスタックトレースとデバッグ情報を表示するには、ANTHROPIC_LOG環境変数を設定します：

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

有効にすると、SDKはツールが失敗した際に、完全なスタックトレースを含む例外の詳細をログに記録します（Pythonのloggingモジュール、TypeScriptのコンソール、またはRubyのロガーを使用）。

ツールエラーのインターセプト

デフォルトでは、ツールエラーはClaudeに渡され、Claudeが適切に応答できます。ただし、エラーを検出して異なる方法で処理したい場合があります。例えば、実行を早期に停止したり、カスタムエラーハンドリングを実装したりする場合です。

ツールレスポンスメソッドを使用して、ツール結果をインターセプトし、Claudeに送信される前にエラーを確認します：

ツール結果の変更

ツール結果をClaudeに送り返す前に変更できます。これは、ツール結果に対するプロンプトキャッシングを有効にするためのcache_controlなどのメタデータの追加や、ツール出力の変換に便利です。

ツールレスポンスメソッドを使用してツール結果を取得し、変更してから、変更したバージョンをメッセージに追加します：

ストリーミング

ストリーミングを有効にして、イベントが到着するたびに受信します。各イテレーションでは、イベントをイテレートできるストリームオブジェクトが生成されます。

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がanyまたはtoolの場合、ツールの使用を強制するためにアシスタントメッセージをプリフィルすることに注意してください。これは、明示的に求められた場合でも、モデルがtool_useコンテンツブロックの前に自然言語の応答や説明を出力しないことを意味します。

テストの結果、これによってパフォーマンスが低下することはないことが示されています。モデルに自然言語のコンテキストや説明を提供させつつ、特定のツールの使用を要求したい場合は、tool_choiceに{"type": "auto"}（デフォルト）を使用し、userメッセージに明示的な指示を追加できます。例：What's the weather like in London? Use the get_weather tool in your response.

JSON出力

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

ツールを使用したモデルの応答

ツールを使用する場合、Claudeはツールを呼び出す前に、何をしているかについてコメントしたり、ユーザーに自然に応答したりすることがよくあります。

例えば、「What's the weather like in San Francisco right now, and what time is it there?」というプロンプトに対して、Claudeは次のように応答する可能性があります：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

この自然な応答スタイルは、Claudeが何をしているかをユーザーが理解するのに役立ち、より会話的なインタラクションを作り出します。システムプロンプトやプロンプト内の<examples>を提供することで、これらの応答のスタイルと内容をガイドできます。

Claudeはアクションを説明する際にさまざまな表現やアプローチを使用する可能性があることに注意してください。コードはこれらの応答を他のアシスタント生成テキストと同様に扱い、特定のフォーマット規則に依存しないようにしてください。

並列ツール使用

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

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

並列ツール使用の最大化

Claude 4モデルはデフォルトで優れた並列ツール使用機能を備えていますが、ターゲットを絞ったプロンプティングにより、すべてのモデルで並列ツール実行の可能性を高めることができます：

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

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

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

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

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

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

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

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ tool_resultの前にテキスト
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ tool_resultの後にテキスト
]}

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

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

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

max_tokens停止理由の処理

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

# ツール使用中に応答が切り捨てられたかどうかを確認
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-6",
            max_tokens=4096,  # 増加した制限
            messages=messages,
            tools=tools
        )

pause_turn停止理由の処理

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

pause_turn停止理由の処理方法は以下の通りです：

import anthropic

client = anthropic.Anthropic()

# Web検索を使用した初期リクエスト
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    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
    }]
)

# 応答に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-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でツールを使用する際に発生する可能性のあるエラーにはいくつかの種類があります：