ツール使用の実装方法

モデルの選択

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

シンプルなツールには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文を目指し、ツールが複雑な場合はそれ以上を目指してください。
• 説明を例より優先してください。 ツールの使用方法の例をその説明またはそれに付随するプロンプトに含めることができますが、これはツールの目的とパラメータの明確で包括的な説明を持つことほど重要ではありません。説明を完全に充実させた後にのみ例を追加してください。

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

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

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

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

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

基本的な使用方法

Claudeの出力の制御

ツール使用の強制

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

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

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

• autoを使用すると、Claudeは提供されたツールを呼び出すかどうかを決定できます。これはtoolsが提供されるときのデフォルト値です。
• anyは、Claudeが提供されたツールの1つを使用する必要があることを示していますが、特定のツールを強制しません。
• 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はしばしば実行している内容についてコメントしたり、ツールを呼び出す前にユーザーに自然に応答したりします。

例えば、プロンプト「サンフランシスコの現在の天気は何ですか、そしてそこの時刻は何ですか？」が与えられた場合、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. roleがuserで、以下の情報を含む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値でリクエストを再試行する必要があります。

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

pause_turn停止理由の処理

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

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

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
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
    }]
)

# 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-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でツールを使用する場合、いくつかの異なるタイプのエラーが発生する可能性があります：