---
title: ツール呼び出しの処理
url: https://platform.claude.com/docs/ja/agents-and-tools/tool-use/handle-tool-calls
description: tool_use ブロックの解析、tool_result レスポンスのフォーマット、is_error によるエラー処理について説明します。
---
このページでは、ツール呼び出しのライフサイクルについて説明します。Claudeのレスポンスから `tool_use` ブロックを読み取り、返信で `tool_result` ブロックをフォーマットし、エラーを通知する方法です。これを自動的に処理するSDKの抽象化については、[Tool Runner](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-runner)を参照してください。
**Tool Runnerを使えばより簡単に：** このページで説明する手動のツール処理は、[Tool Runner](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-runner)によって自動的に管理されます。ツール実行をカスタム制御する必要がある場合に、このページを使用してください。
Claudeのレスポンスは、[クライアントツールとサーバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/overview#how-tool-use-works)のどちらを使用するかによって異なります。
## クライアントツールからの結果の処理
レスポンスの `stop_reason` は `tool_use` となり、以下を含む1つ以上の `tool_use` コンテンツブロックが含まれます。
* `id`：この特定のツール使用ブロックの一意の識別子。後でツール結果と照合するために使用されます。
* `name`：使用されるツールの名前。
* `input`：ツールに渡される入力を含むオブジェクト。ツールの `input_schema` に準拠します。
[computer use](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool)または[browser use](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool)ツールセットのメンバーに対する `tool_use` ブロックには、`toolset_name` フィールド（`"computer"` または `"browser"`）も含まれます。その `name` は、`screenshot` や `navigate` など、Claudeが呼び出しているメンバーツールであるため、これらのブロックは両方のフィールドに基づいてディスパッチしてください。
```json JSON
{
"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" }
}
]
}
```
クライアントツールに対するツール使用レスポンスを受け取ったら、次のようにします。
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`、または [`search_result`](https://platform.claude.com/docs/ja/build-with-claude/search-results) タイプを使用できます。
* `is_error`（オプション）：ツールの実行がエラーになった場合は `true` に設定します。
computer useまたはbrowser useのメンバーブロックに応答する `tool_result` は、`tool_use` ブロックと同じ `toolset_name` の値もそのまま返す必要があります。これを省略したメンバー結果は拒否されます。また、その `content` はより限定されています。メンバー結果には `text` ブロックと `image` ブロックのみを含めることができ、browser useの結果には1つの [`browser_state`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) ブロックを追加できます（[タブ管理メンバー](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#tab-management-results)はそのブロックのみを返します）。
**重要なフォーマット要件：**
* ツール結果ブロックは、メッセージ履歴内で対応するツール使用ブロックの直後に配置する必要があります。アシスタントのツール使用メッセージとユーザーのツール結果メッセージの間に、他のメッセージを含めることはできません。
* ツール結果を含むユーザーメッセージでは、tool\_result ブロックを content 配列の最初に配置する必要があります。テキストはすべてのツール結果の後に配置する必要があります。
* アシスタントのターンで、まだ結果ブロックのない[サーバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools)も呼び出された場合、ユーザーメッセージには `tool_result` ブロックのみを含める必要があります。結果の後にテキストがあるとターンが早期に終了します。Claudeが直接呼び出したサーバーツールの場合、リクエストは未解決のサーバーツールの名前を示す400エラーで失敗します。[停止理由とフォールバック](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons#tool-use)を参照してください。
たとえば、次の場合は400エラーが発生します。
```json
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
]
}
```
アシスタントのターンがクライアントツールのみを呼び出す場合、次の形式が正しいです。
```json
{
"role": "user",
"content": [
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
{ "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
]
}
```
「tool\_use ids were found without tool\_result blocks immediately after」のようなエラーを受け取った場合は、ツール結果が正しくフォーマットされているか確認してください。
ツール結果には、Webページ、受信メール、ユーザーのアップロード、サードパーティAPIなど、制御できないソースからのコンテンツが含まれることがよくあります。そのようなコンテンツは信頼できないものとして扱ってください。それに影響を与えられる攻撃者は、Claudeを誘導しようとする指示を埋め込む可能性があります（間接的プロンプトインジェクション）。信頼できないコンテンツは、`system` プロンプトやプレーンなユーザー `text` ブロックではなく `tool_result` ブロック内に保持し、さらなる強化策については[ジェイルブレイクとプロンプトインジェクションの軽減](https://platform.claude.com/docs/ja/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection)を参照してください。
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
```json JSON
{
"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..."
}
}
]
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
```json JSON
{
"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"
}
}
]
}
]
}
```
ツール結果を受け取った後、Claudeはその情報を使用して、元のユーザープロンプトに対するレスポンスの生成を続けます。
## サーバーツールからの結果の処理
Claudeはツールを内部で実行し、追加のユーザー操作を必要とせずに結果をレスポンスに直接組み込みます。
レスポンスには、クライアントの `tool_use` ブロックと、結果ブロックのない `server_tool_use` ブロックの両方が含まれる場合があります。そのサーバーツール呼び出しはまだ完了しておらず、その結果ブロックは後のレスポンスで届きます。クライアントツールの `tool_result` ブロックのみを含むユーザーメッセージで返信し、同じ `tools` 配列を維持してください。Claudeが直接呼び出したサーバーツールの場合、APIはそのリクエストでツールを実行し、次のレスポンスはその結果ブロックから始まります。[停止理由とフォールバック](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons#tool-use)を参照してください。
**他のAPIとの違い**
ツール使用を分離したり、`tool` や `function` のような特別なロールを使用したりするAPIとは異なり、Claude APIはツールを `user` と `assistant` のメッセージ構造に直接統合しています。
メッセージには `text`、`image`、`tool_use`、`tool_result` ブロックの配列が含まれます。`user` メッセージにはクライアントのコンテンツと `tool_result` が含まれ、`assistant` メッセージにはAIが生成したコンテンツと `tool_use` が含まれます。
## is\_error によるエラー処理
Claudeでツールを使用する際に発生する可能性のあるエラーには、いくつかの種類があります。
ツール自体が実行中にエラーをスローした場合（たとえば、天気データの取得時のネットワークエラー）、`"is_error": true` とともにエラーメッセージを `content` で返すことができます。
```json JSON
{
"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はこのエラーをユーザーへのレスポンスに組み込みます。たとえば、「申し訳ありませんが、天気サービスAPIが利用できないため、現在の天気を取得できませんでした。後でもう一度お試しください。」のようになります。
有益なエラーメッセージを書いてください。`"failed"` のような一般的なエラーではなく、何が問題だったのか、Claudeが次に何を試すべきかを含めてください（例：`"Rate limit exceeded. Retry after 60 seconds."`）。これにより、Claudeは推測することなく回復または適応するために必要なコンテキストを得られます。
Claudeによるツール使用の試みが無効な場合（たとえば、必須パラメータの欠落）、通常はClaudeがツールを正しく使用するための情報が不足していたことを意味します。開発中の最善の方法は、ツール定義の `description` の値をより詳細にしてリクエストを再試行することです。
ただし、エラーを示す `tool_result` で会話を先に進めることもでき、Claudeは不足している情報を補ってツールを再度使用しようとします。
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
ツールリクエストが無効であるかパラメータが不足している場合、Claudeはユーザーに謝罪する前に、修正を加えて2〜3回再試行します。
無効なツール呼び出しを完全に排除するには、ツール定義で `strict: true` を指定して[厳密なツール使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/strict-tool-use)を使用してください。これにより、ツール入力が常にスキーマと正確に一致することが保証され、パラメータの欠落や型の不一致を防ぐことができます。
サーバーツールでエラーが発生した場合（たとえば、Web検索でのネットワークの問題）、Claudeはこれらのエラーを透過的に処理し、ユーザーに代替のレスポンスや説明を提供しようとします。クライアントツールとは異なり、サーバーツールの `is_error` 結果を処理する必要はありません。
特にWeb検索の場合、考えられるエラーコードは次のとおりです。
* `too_many_requests`：レート制限を超過
* `invalid_input`：無効な検索クエリパラメータ
* `max_uses_exceeded`：Web検索ツールの最大使用回数を超過
* `query_too_long`：クエリが最大長を超過
* `unavailable`：内部エラーが発生
## 次のステップ
Claudeが1回のターンで複数のツールを呼び出すレスポンスを処理します。
`tool_use` ループ、結果のフォーマット、再試行をSDKに任せます。
Claudeを適切なツールへ導くスキーマと説明を記述します。