ツール呼び出しの処理
tool_use ブロックの解析、tool_result レスポンスのフォーマット、is_error によるエラー処理について説明します。
Claudeのレスポンスに tool_use ブロックが含まれている場合、コードで各ツールを実行し、エラーも含めて tool_result ブロックを返送します。ツール実行をカスタム制御する必要がある場合は、このコードを自分で記述してください。それ以外の場合は、SDKのツールランナーを使用してください。ツールランナーがツールを実行し、結果を送信します。
Claudeのレスポンスは、クライアントツールとサーバーツールのどちらを使用するかによって異なります。
クライアントツールからの結果の処理
応答には、stop_reasonがtool_useであることと、以下を含む1つ以上のtool_useコンテンツブロックが含まれます:
id:この特定のツール使用ブロックの一意の識別子です。後でツールの結果を照合するために使用されます。name:使用されるツールの名前。input:ツールに渡される入力を含むオブジェクト。ツールのinput_schemaに準拠します。
コンピューター使用またはブラウザ使用ツールセットのメンバーに対する tool_use ブロックには、toolset_name フィールド("computer" または "browser")も含まれます。その name は、screenshot や navigate など、Claudeが呼び出しているメンバーツールであるため、これらのブロックは両方のフィールドに基づいてディスパッチしてください。
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}クライアントツールに対するツール使用レスポンスを受け取ったら、次の手順に従います。
- 各
tool_useブロックについて、そのブロックが指定するツールを実行し、そのinputを渡します。 - 新しいリクエストで、以前のメッセージを保持し、レスポンスの
contentを変更せずにassistantメッセージとして追加します。 - そのcontent内の各
tool_useブロックに対して1つずつtool_resultブロックを含むuserメッセージを追加します。ツールが失敗した場合も同様です。 - 最初のリクエストと同じ
toolsを指定してリクエストを送信します。Claudeはツールの結果を使用してレスポンスを続けます。 - 次のレスポンスの
stop_reasonもtool_useの場合は、これらの手順を繰り返します。その他の値については、停止理由のクイックリファレンスを参照してください。
これらの手順を完全なプログラムとして確認するには、チュートリアル:ツールを使用するエージェントを構築するを参照してください。
各 tool_result ブロックでは、type が tool_result に設定され、さらに次のフィールドを持ちます。
tool_use_id:この結果が応答するtool_useブロックのid。content(オプション):ツールの結果。文字列またはコンテンツブロックのリストとして指定します。これらのコンテンツブロックでは、text、image、document、またはsearch_resultタイプを使用できます。is_error(オプション):ツールが失敗した場合、または呼び出しが無効だった場合はtrueに設定します。
たとえば、成功したツール結果は次のようになります:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}コンピューター使用またはブラウザ使用のメンバーブロックに応答する tool_result は、tool_use ブロックと同じ toolset_name の値もそのまま返す必要があります。これを省略したメンバー結果は拒否されます。また、その content はより限定されています。メンバー結果には text ブロックと image ブロックのみを含めることができ、ブラウザ使用の結果には1つの browser_state ブロックを追加できます(タブ管理メンバーはそのブロックのみを返します)。
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}たとえば、次の例は400エラーを引き起こします:
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before 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?" } // ✅ Text after tool_result
]
}サーバーツールからの結果の処理
Claudeはツールを内部で実行し、追加のユーザー操作を必要とせずに、その結果を応答に直接組み込みます。
is_error によるエラー処理
クライアントツールが失敗した場合、または呼び出しが無効な場合は、is_error を true に設定した tool_result ブロックを送信します。その後、Claudeは新しい tool_use ブロックでツールを再度呼び出す可能性があるため、ループで許可する再試行回数を制限してください。
ツール自体が実行中にエラーをスローした場合(たとえば、天気データの取得時のネットワークエラー)、"is_error": true とともにエラーメッセージを content で返すことができます。
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}その後、Claudeはツールを再度呼び出すか、何が起きたかをユーザーに伝えることができます。たとえば、Claudeは「申し訳ありませんが、天気サービスAPIが利用できないため、現在の天気を取得できませんでした。後でもう一度お試しください。」のように応答する場合があります。
Claudeのツール使用の試みが無効な場合(例:必須パラメーターの欠落)、通常はClaudeがツールを正しく使用するための情報が不十分だったことを意味します。開発中の最善のアプローチは、ツール定義のdescription値をより詳細にしてリクエストを再試行することです。
ただし、エラーを示すtool_resultで会話を続けることもできます:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}その後、Claudeは欠落している情報を補ってツールを再度呼び出すことができます。
クライアントツールとは異なり、サーバーツールについてはis_errorの結果を送信しません。Web検索中のネットワークの問題など、サーバーツールでエラーが発生した場合、APIはツールの結果ブロック内にエラーを返します。ほとんどの場合、Claudeはその後、別のアプローチで続行するか、ユーザーに説明を提供します。
Web検索のエラーコードについては、Web検索ツールのエラーを参照してください。
次のステップ
Claudeが1回のターンで複数のツールを呼び出すレスポンスを処理します。
tool_use ループ、結果のフォーマット、再試行をSDKに任せます。
Claudeを適切なツールへ導くスキーマと説明を記述します。
このページは役に立ちましたか?