---
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の[ツールランナー](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` に準拠します。

[コンピューター使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool)または[ブラウザ使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool)ツールセットのメンバーに対する `tool_use` ブロックには、`toolset_name` フィールド（`"computer"` または `"browser"`）も含まれます。その `name` は、`screenshot` や `navigate` など、Claudeが呼び出しているメンバーツールであるため、これらのブロックは両方のフィールドに基づいてディスパッチしてください。

<Accordion title="`tool_use` コンテンツブロックを含むAPIレスポンスの例">
  ```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" }
      }
    ]
  }
  ```
</Accordion>

クライアントツールに対するツール使用レスポンスを受け取ったら、次の手順に従います。

1. 各 `tool_use` ブロックについて、そのブロックが指定するツールを実行し、その `input` を渡します。
2. 新しいリクエストで、以前のメッセージを保持し、レスポンスの `content` を変更せずに `assistant` メッセージとして追加します。
3. そのcontent内の各 `tool_use` ブロックに対して1つずつ `tool_result` ブロックを含む `user` メッセージを追加します。ツールが失敗した場合も同様です。
4. 最初のリクエストと同じ `tools` を指定してリクエストを送信します。Claudeはツールの結果を使用してレスポンスを続けます。
5. 次のレスポンスの `stop_reason` も `tool_use` の場合は、これらの手順を繰り返します。その他の値については、[停止理由のクイックリファレンス](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons#quick-reference)を参照してください。

これらの手順を完全なプログラムとして確認するには、[チュートリアル：ツールを使用するエージェントを構築する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/build-a-tool-using-agent)を参照してください。

各 `tool_result` ブロックでは、`type` が `tool_result` に設定され、さらに次のフィールドを持ちます。

* `tool_use_id`：この結果が応答する `tool_use` ブロックの `id`。
* `content`（オプション）：ツールの結果。文字列またはコンテンツブロックのリストとして指定します。これらのコンテンツブロックでは、`text`、`image`、`document`、または [`search_result`](https://platform.claude.com/docs/ja/build-with-claude/search-results) タイプを使用できます。
* `is_error`（オプション）：ツールが失敗した場合、または呼び出しが無効だった場合は `true` に設定します。

たとえば、成功したツール結果は次のようになります：

```json JSON
{
  "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`](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)はそのブロックのみを返します）。

<Note>
  **重要なフォーマット要件：**

  * ツール結果ブロックは、メッセージ履歴内で対応するツール使用ブロックの直後に配置する必要があります。アシスタントのツール使用メッセージとユーザーのツール結果メッセージの間に、他のメッセージを含めることはできません。
  * ツール結果を含むユーザーメッセージでは、`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)を参照してください。

  「tool\_use ids were found without tool\_result blocks immediately after」のようなエラーを受け取った場合は、ツール結果が正しくフォーマットされているか確認してください。
</Note>

<Warning>
  ツール結果には、Webページ、受信メール、ユーザーのアップロード、サードパーティのAPIなど、管理外のソースからのコンテンツが含まれることがよくあります。そのようなコンテンツは信頼できないものとして扱ってください。それに影響を与えられる攻撃者が、Claudeの動作をそらそうとする指示を埋め込む可能性があります（間接的なプロンプトインジェクション）。信頼できないコンテンツは、`system`プロンプトや通常のユーザー`text`ブロックではなく、`tool_result`ブロック内に保持してください。さらなる強化策については、[ジェイルブレイクとプロンプトインジェクションを軽減する](https://platform.claude.com/docs/ja/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection)を参照してください。
</Warning>

<AccordionGroup>
  <Accordion title="画像を含むツール結果の例">
    ```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..."
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="空のツール結果の例">
    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="ドキュメントを含むツール結果の例">
    ```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"
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="ツール結果の前後に置くテキストの例">
    たとえば、次の例は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
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

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

Claudeはツールを内部で実行し、追加のユーザー操作を必要とせずに、その結果を応答に直接組み込みます。

<Note>
  応答には、クライアントの`tool_use`ブロックと、結果ブロックを持たない`server_tool_use`ブロックの両方が含まれる場合があります。そのサーバーツール呼び出しはまだ完了しておらず、その結果ブロックは後の応答で届きます。クライアントツールの`tool_result`ブロックのみを含むユーザーメッセージで返信し、同じ`tools`配列を維持してください。Claudeが直接呼び出したサーバーツールの場合、APIはそのリクエストでツールを実行し、次の応答はその結果ブロックから始まります。[停止理由とフォールバック](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons#tool-use)を参照してください。
</Note>

<Tip>
  **他のAPIとの違い**

  ツール使用を分離したり、`tool` や `function` のような特別なロールを使用したりするAPIとは異なり、Claude APIはツールを `user` と `assistant` のメッセージ構造に直接統合しています。

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

## is\_error によるエラー処理

クライアントツールが失敗した場合、または呼び出しが無効な場合は、`is_error` を `true` に設定した `tool_result` ブロックを送信します。その後、Claudeは新しい `tool_use` ブロックでツールを再度呼び出す可能性があるため、ループで許可する再試行回数を制限してください。

<AccordionGroup>
  <Accordion title="ツール実行エラー">
    ツール自体が実行中にエラーをスローした場合（たとえば、天気データの取得時のネットワークエラー）、`"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はツールを再度呼び出すか、何が起きたかをユーザーに伝えることができます。たとえば、Claudeは「申し訳ありませんが、天気サービスAPIが利用できないため、現在の天気を取得できませんでした。後でもう一度お試しください。」のように応答する場合があります。

    <Tip>
      有益なエラーメッセージを記述してください。`"failed"`のような汎用的なエラーではなく、何が問題だったのか、Claudeが次に何を試すべきかを含めてください（例：`"Rate limit exceeded. Retry after 60 seconds."`）。これにより、Claudeは推測することなく回復または適応するために必要なコンテキストを得られます。
    </Tip>
  </Accordion>

  <Accordion title="無効なツール呼び出し">
    Claudeのツール使用の試みが無効な場合（例：必須パラメーターの欠落）、通常はClaudeがツールを正しく使用するための情報が不十分だったことを意味します。開発中の最善のアプローチは、ツール定義の`description`値をより詳細にしてリクエストを再試行することです。

    ただし、エラーを示す`tool_result`で会話を続けることもできます：

    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "Error: Missing required 'location' parameter",
          "is_error": true
        }
      ]
    }
    ```

    その後、Claudeは欠落している情報を補ってツールを再度呼び出すことができます。

    <Tip>
      無効なツール呼び出しを完全になくすには、ツール定義で`strict: true`を指定して[厳密なツール使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/strict-tool-use)を使用してください。これにより、ツールの入力が常にスキーマと完全に一致することが保証され、パラメーターの欠落や型の不一致を防ぐことができます。
    </Tip>
  </Accordion>

  <Accordion title="サーバーツールのエラー">
    クライアントツールとは異なり、サーバーツールについては`is_error`の結果を送信しません。Web検索中のネットワークの問題など、サーバーツールでエラーが発生した場合、APIはツールの結果ブロック内にエラーを返します。ほとんどの場合、Claudeはその後、別のアプローチで続行するか、ユーザーに説明を提供します。

    Web検索のエラーコードについては、[Web検索ツールのエラー](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool#errors)を参照してください。
  </Accordion>
</AccordionGroup>

## 次のステップ

<CardGroup cols={3}>
  <Card title="並列ツール使用" icon="grid" href="https://platform.claude.com/docs/ja/agents-and-tools/tool-use/parallel-tool-use">
    Claudeが1回のターンで複数のツールを呼び出すレスポンスを処理します。
  </Card>

  <Card title="ツールランナー（SDK）" icon="wrench" href="https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-runner">
    `tool_use` ループ、結果のフォーマット、再試行をSDKに任せます。
  </Card>

  <Card title="ツールの定義" icon="hammer" href="https://platform.claude.com/docs/ja/agents-and-tools/tool-use/define-tools">
    Claudeを適切なツールへ導くスキーマと説明を記述します。
  </Card>
</CardGroup>
