Claudeでツール使用とストリーミングを組み合わせると、AIがツールの引数を生成する際にリアルタイムで更新を受け取ることができます。これによりより応答性の高いユーザー体験が生まれますが、その裏側でどのように動作しているかについて理解すべき重要な詳細がいくつかあります。
基本的なツールストリーミング
ストリーミングを有効にすると、Claudeはリクエストを処理する際に異なる種類のイベントを返します。通常のテキスト生成におけるContentBlockDeltaのようなイベントについては既にご存知でしょう。ツール使用の場合、InputJsonEventという新しいイベントタイプも処理する必要があります。

各InputJsonEventには2つの重要なプロパティが含まれています:
- partial_json - ツール引数の一部を表すJSONのチャンク
- snapshot - これまでに受信したすべてのチャンクから構築された累積JSON
ストリーミングパイプラインでこれらのイベントを処理する方法は次のとおりです:
for chunk in stream:
if chunk.type == "input_json":
# 部分的なJSONチャンクを処理する
print(chunk.partial_json)
# またはこれまでの完全なスナップショットを使用する
current_args = chunk.snapshot
JSON検証の仕組み
ここで興味深い点があります。Anthropic APIは、Claudeが生成するすべてのチャンクを即座に送信するわけではありません。代わりに、チャンクをバッファリングし、まず検証を行います。

APIは、何かを送信する前に完全なトップレベルのキーと値のペアを待ちます。例えば、ツールが次のような構造を期待している場合:
{
"abstract": "This paper presents a novel...",
"meta": {
"word_count": 847,
"review": "This paper introduces QuanNet..."
}
}APIは次のことを行います:
abstractの値全体が完成するまで待つ- そのキーと値のペアをスキーマに対して検証する
abstractのためにバッファリングされたすべてのチャンクを一度に送信するmetaオブジェクトについてこのプロセスを繰り返す

この検証プロセスにより、ストリーミングが有効になっていても、遅延の後にテキストがまとめて表示される理由が説明できます。チャンクは、完全で有効なトップレベルのキーと値のペアが準備できるまで保留されています。

細粒度のツール呼び出し
より高速で、より細かいストリーミングが必要な場合 - 例えばユーザーに即時の更新を表示したり、部分的な結果の処理を迅速に開始したりする場合 - 細粒度のツール呼び出しを有効にすることができます。

細粒度のツール呼び出しは主に1つのことを行います:API側でのJSON検証を無効にします。これは次のことを意味します:
- Claudeが生成するとすぐにチャンクを取得できる
- トップレベルのキー間でのバッファリング遅延がない
- より従来型のストリーミング動作
- 重要: JSON検証が無効になっているため、コードは無効なJSONを処理する必要があります
APIコールにfine_grained=Trueを追加することで有効にできます:
run_conversation(
messages,
tools=[save_article_schema],
fine_grained=True
)細粒度のツール呼び出しを使用すると、metaオブジェクト全体が完成するのを待たずに、ストリームのかなり早い段階でword_countの値を受け取ることができる場合があります。
無効なJSONの処理
細粒度のツール呼び出しを使用する場合、Claudeは適切な数値の代わりに"word_count": undefinedのような無効なJSONを生成する可能性があります。アプリケーションはこれらのケースを適切に処理する必要があります:
try:
parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
# 無効なJSONを適切に処理する
print("Received invalid JSON, continuing...")細粒度のツール呼び出しを使用しない場合、APIの検証がこのエラーを捕捉し、問題のある値を文字列でラップする可能性がありますが、これは期待するスキーマと一致しない場合があります。
細粒度のツール呼び出しを使用すべき場合
次の場合に細粒度のツール呼び出しを有効にすることを検討してください:
- ツール引数の生成についてユーザーにリアルタイムの進行状況を表示する必要がある
- 部分的なツール結果の処理をできるだけ早く開始したい
- バッファリングの遅延がユーザー体験に悪影響を与えている
- 堅牢なJSONエラー処理を実装することに抵抗がない
ほとんどのアプリケーションでは、検証を伴うデフォルトの動作で十分です。しかし、その追加の応答性が必要な場合、細粒度のツール呼び出しにより、Claudeが生成できる速さでチャンクを取得する制御が可能になります。