ツールインフラ

きめ細かいツールストリーミング

レイテンシに敏感なアプリケーションのために、ツール入力を1文字ずつストリーミングします。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

きめ細かいツールストリーミングは、すべてのモデルおよびすべてのプラットフォームで一般提供されています。バッファリングやJSON検証なしにツール使用パラメータ値のストリーミングを可能にし、大きなパラメータの受信開始までのレイテンシを削減します。

きめ細かいツールストリーミングを使用する場合、無効または不完全なJSON入力を受け取る可能性があります。コード内でこれらのエッジケースを考慮するようにしてください。

きめ細かいツールストリーミングの使い方

きめ細かいツールストリーミングは、すべてのモデルおよびすべてのプラットフォーム（Claude API、Amazon Bedrock、Google Vertex AI、Microsoft Foundry）で利用可能です。使用するには、きめ細かいストリーミングを有効にしたいユーザー定義ツールでeager_input_streamingをtrueに設定し、リクエストでストリーミングを有効にします。

APIでのきめ細かいツールストリーミングの使用例を以下に示します：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 65536,
    "tools": [
      {
        "name": "make_file",
        "description": "Write text to a file",
        "eager_input_streaming": true,
        "input_schema": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string",
              "description": "The filename to write text to"
            },
            "lines_of_text": {
              "type": "array",
              "description": "An array of lines of text to write to the file"
            }
          },
          "required": ["filename", "lines_of_text"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Can you write a long poem and make a file called poem.txt?"
      }
    ],
    "stream": true
  }'

この例では、きめ細かいツールストリーミングにより、Claudeはlines_of_textパラメータが有効なJSONかどうかを検証するためのバッファリングなしに、長い詩の行をツール呼び出しmake_fileにストリーミングできます。これにより、パラメータ全体がバッファリングされて検証されるのを待つことなく、到着するとすぐにパラメータのストリームを確認できます。

きめ細かいツールストリーミングでは、ツール使用チャンクのストリーミング開始が速くなり、チャンクが長くなり、単語の区切りが少なくなることが多いです。これはチャンキング動作の違いによるものです。

例：

きめ細かいストリーミングなし（15秒の遅延）：

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

きめ細かいストリーミングあり（3秒の遅延）：

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

きめ細かいストリーミングはバッファリングやJSON検証なしにパラメータを送信するため、結果のストリームが有効なJSON文字列として完了する保証はありません。特に、停止理由のmax_tokensに達した場合、ストリームはパラメータの途中で終了し、不完全になる可能性があります。一般的に、max_tokensに達した場合を処理するための特定のサポートを記述する必要があります。

ツール入力デルタの蓄積

tool_useコンテンツブロックがストリーミングされると、最初のcontent_block_startイベントにはinput: {}（空のオブジェクト）が含まれます。これはプレースホルダーです。実際の入力は、それぞれpartial_json文字列フラグメントを持つ一連のinput_json_deltaイベントとして到着します。コードはこれらのフラグメントを連結し、ブロックが閉じたら結果を解析する必要があります。

蓄積の契約：

type: "tool_use"のcontent_block_startで、空の文字列を初期化します：input_json = ""
type: "input_json_delta"の各content_block_deltaで、追加します：input_json += event.delta.partial_json
content_block_stopで、蓄積された文字列を解析します：json.loads(input_json)

最初のinput: {}（オブジェクト）とpartial_json（文字列）の型の不一致は設計によるものです。空のオブジェクトはコンテンツ配列のスロットをマークし、デルタ文字列が実際の値を構築します。

import json
import anthropic

client = anthropic.Anthropic()

tool_inputs = {}  # index -> accumulated JSON string

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "eager_input_streaming": True,
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
    messages=[{"role": "user", "content": "Weather in Paris?"}],
) as stream:
    for event in stream:
        if (
            event.type == "content_block_start"
            and event.content_block.type == "tool_use"
        ):
            tool_inputs[event.index] = ""
        elif (
            event.type == "content_block_delta"
            and event.delta.type == "input_json_delta"
        ):
            tool_inputs[event.index] += event.delta.partial_json
        elif event.type == "content_block_stop" and event.index in tool_inputs:
            parsed = json.loads(tool_inputs[event.index])
            print(f"Tool input: {parsed}")

PythonおよびTypeScript SDKは、この蓄積を自動的に行う高レベルのストリームヘルパー（stream.get_final_message()、stream.finalMessage()）を提供しています。上記の手動パターンは、ブロックが閉じる前に部分的な入力に反応する必要がある場合（進捗インジケーターのレンダリングや下流リクエストの早期開始など）にのみ使用してください。

ツールレスポンスでの無効なJSONの処理

きめ細かいツールストリーミングを使用する場合、モデルから無効または不完全なJSONを受け取る可能性があります。この無効なJSONをエラーレスポンスブロックでモデルに返す必要がある場合、適切な処理を確保するためにJSONオブジェクトでラップすることができます（適切なキーを使用して）。例えば：

{
  "INVALID_JSON": "<your invalid json string>"
}

このアプローチにより、モデルはコンテンツが無効なJSONであることを理解しながら、デバッグ目的で元の不正なデータを保持できます。

無効なJSONをラップする場合、ラッパーオブジェクトで有効なJSON構造を維持するために、無効なJSON文字列内の引用符や特殊文字を適切にエスケープするようにしてください。

次のステップ

ストリーミングメッセージ

サーバー送信イベントとストリームイベントタイプの完全なリファレンス。

ツール呼び出しの処理

ツールを実行し、必要なメッセージ形式で結果を返します。

ツールリファレンス

Anthropicスキーマツールとそのバージョン文字列の完全なディレクトリ。

Was this page helpful?

ツールインフラ

きめ細かいツールストリーミング

レイテンシに敏感なアプリケーションのために、ツール入力を1文字ずつストリーミングします。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

きめ細かいツールストリーミングの使い方

APIでのきめ細かいツールストリーミングの使用例を以下に示します：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 65536,
    "tools": [
      {
        "name": "make_file",
        "description": "Write text to a file",
        "eager_input_streaming": true,
        "input_schema": {
          "type": "object",
          "properties": {
            "filename": {
              "type": "string",
              "description": "The filename to write text to"
            },
            "lines_of_text": {
              "type": "array",
              "description": "An array of lines of text to write to the file"
            }
          },
          "required": ["filename", "lines_of_text"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Can you write a long poem and make a file called poem.txt?"
      }
    ],
    "stream": true
  }'

例：

きめ細かいストリーミングなし（15秒の遅延）：

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

きめ細かいストリーミングあり（3秒の遅延）：

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

ツール入力デルタの蓄積

蓄積の契約：

type: "tool_use"のcontent_block_startで、空の文字列を初期化します：input_json = ""
type: "input_json_delta"の各content_block_deltaで、追加します：input_json += event.delta.partial_json
content_block_stopで、蓄積された文字列を解析します：json.loads(input_json)

import json
import anthropic

client = anthropic.Anthropic()

tool_inputs = {}  # index -> accumulated JSON string

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "eager_input_streaming": True,
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
    messages=[{"role": "user", "content": "Weather in Paris?"}],
) as stream:
    for event in stream:
        if (
            event.type == "content_block_start"
            and event.content_block.type == "tool_use"
        ):
            tool_inputs[event.index] = ""
        elif (
            event.type == "content_block_delta"
            and event.delta.type == "input_json_delta"
        ):
            tool_inputs[event.index] += event.delta.partial_json
        elif event.type == "content_block_stop" and event.index in tool_inputs:
            parsed = json.loads(tool_inputs[event.index])
            print(f"Tool input: {parsed}")

ツールレスポンスでの無効なJSONの処理

{
  "INVALID_JSON": "<your invalid json string>"
}

このアプローチにより、モデルはコンテンツが無効なJSONであることを理解しながら、デバッグ目的で元の不正なデータを保持できます。

次のステップ

ストリーミングメッセージ

サーバー送信イベントとストリームイベントタイプの完全なリファレンス。

ツール呼び出しの処理

ツールを実行し、必要なメッセージ形式で結果を返します。

ツールリファレンス

Anthropicスキーマツールとそのバージョン文字列の完全なディレクトリ。

Was this page helpful?