メッセージを作成する際、"stream": true を設定することで、server-sent events (SSE) を使用してレスポンスを段階的にストリーミングできます。

SDKでのストリーミング

PythonTypescript の SDK では、複数のストリーミング方法を提供しています。Python SDK では、同期ストリームと非同期ストリームの両方が可能です。詳細については、各 SDK のドキュメントを参照してください。

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}],
    model="claude-3-opus-20240229",
) as stream:
  for text in stream.text_stream:
      print(text, end="", flush=True)

イベントタイプ

各サーバーセントイベントには、名前付きのイベントタイプと関連する JSON データが含まれています。各イベントは SSE イベント名 (例: event: message_stop) を使用し、データ内に一致するイベント type を含めます。

各ストリームは、次のイベントフローを使用します:

  1. message_start: 空の content を持つ Message オブジェクトを含みます。
  2. 一連のコンテンツブロック。各ブロックには content_block_start、1つ以上の content_block_delta イベント、および content_block_stop イベントがあります。各コンテンツブロックには、最終的な Message content 配列内のインデックスに対応する index があります。
  3. 1つ以上の message_delta イベント。最終的な Message オブジェクトのトップレベルの変更を示します。
  4. 最後の message_stop イベント。

Ping イベント

イベントストリームには、任意の数の ping イベントが含まれる場合があります。

エラーイベント

イベントストリームでエラーを送信する場合があります。例えば、使用率が高い期間中、非ストリーミングコンテキストでは通常 HTTP 529 に対応する overloaded_error を受け取る可能性があります:

エラーの例
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "オーバーロード"}}

その他のイベント

バージョニングポリシーに従って、新しいイベントタイプを追加する場合があります。コードでは、未知のイベントタイプを適切に処理する必要があります。

デルタタイプ

content_block_delta イベントには、特定の indexcontent ブロックを更新する型の delta が含まれています。

テキストデルタ

text コンテンツブロックデルタは次のようになります:

テキストデルタ
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "こんにちは"}}

入力 JSON デルタ

入力 JSON デルタブロックは、ツール使用ベータ版の一部です。

tool_use コンテンツブロックのデルタは、ブロックの input フィールドの更新に対応しています。最大限の粒度をサポートするために、デルタは 部分的な JSON 文字列 ですが、最終的な tool_use.input は常に オブジェクト です。

Pydantic のようなライブラリを使用して部分的な JSON 解析を行うか、SDK を使用して解析済みの増分値にアクセスするヘルパーを提供することで、文字列デルタを蓄積し、content_block_stop イベントを受け取ったときに JSON を解析できます。

tool_use コンテンツブロックデルタは次のようになります:

入力 JSON デルタ
event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"サンフラ"}}}

注: 現在のモデルは、input から一度に1つの完全なキーと値のプロパティのみをエミットできます。そのため、ツールを使用する場合、モデルが動作している間、ストリーミングイベント間に遅延が発生する可能性があります。input のキーと値が蓄積されると、それらを複数の content_block_delta イベントとしてチャンク化された部分的な JSON としてエミットするので、将来のモデルでより細かい粒度を自動的にサポートできるようになります。

生の HTTP ストリームレスポンス

ストリーミングモードを使用する場合は、クライアント SDK の使用を強くお勧めします。ただし、直接 API 統合を構築する場合は、これらのイベントを自分で処理する必要があります。

ストリームレスポンスは次のものから構成されます:

  1. message_start イベント
  2. 複数のコンテンツブロックの可能性。各ブロックには以下が含まれます: a. content_block_start イベント b. 複数の content_block_delta イベントの可能性 c. content_block_stop イベント
  3. message_delta イベント
  4. message_stop イベント

レスポンス全体に ping イベントが分散している場合もあります。フォーマットの詳細については、イベントタイプを参照してください。

基本的なストリーミングリクエスト

リクエスト
curl https://api.anthropic.com/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: messages-2023-12-15" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data \
'{
  "model": "claude-3-opus-20240229",
  "messages": [{"role": "user", "content": "こんにちは"}],
  "max_tokens": 256,
  "stream": true
}'
レスポンス
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-opus-20240229", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "こんにちは"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

ツール使用を伴うストリーミングリクエスト

このリクエストでは、Claude にツールを使用して天気を教えるよう依頼します。

リクエスト
  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" \
    -H "anthropic-beta: tools-2024-05-16" \
    -d '{
      "model": "claude-3-opus-20240229",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "指定された場所の現在の天気を取得する",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "都市と州、例: サンフランシスコ、CA"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "any"},
      "messages": [
        {
          "role": "user",
          "content": "サンフランシスコの天気はどうですか?"
        }
      ],
      "stream": true
    }'
レスポンス
event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-3-haiku-20240307","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"わかりました"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"。"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"サンフランシスコ"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"、"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"の"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"天気"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"を"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"確認"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"し"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"ましょう"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"サンフラン"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"シスコ"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"、"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}