Streaming pesan

Saat membuat sebuah Message, Anda dapat mengatur "stream": true untuk melakukan streaming respons secara bertahap menggunakan server-sent events (SSE).

Streaming dengan SDK

Python SDK dan TypeScript SDK menawarkan beberapa cara untuk melakukan streaming. PHP SDK menyediakan streaming melalui createStream(). Python SDK mendukung stream sinkron maupun asinkron. Lihat dokumentasi di masing-masing SDK untuk detailnya.

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-5-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Mendapatkan pesan akhir tanpa menangani event

Jika Anda tidak perlu memproses teks saat teks tersebut tiba, SDK menyediakan cara untuk menggunakan streaming secara internal sambil mengembalikan objek Message lengkap, identik dengan yang dikembalikan oleh client.messages.create(). Ini sangat berguna untuk permintaan dengan nilai max_tokens yang besar, di mana SDK mengharuskan streaming untuk menghindari timeout HTTP.

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-5-5",
) as stream:
    message = stream.get_final_message()

for block in message.content:
    if block.type == "text":
        print(block.text)

Pemanggilan .stream() menjaga koneksi HTTP tetap aktif dengan server-sent events, lalu helper akumulasi pesan milik SDK, stream.get_final_message(), mengumpulkan semua event menjadi objek Message yang lengkap.

Jenis event

Setiap server-sent event menyertakan jenis event bernama dan data JSON terkait. Setiap event menggunakan nama event SSE (misalnya, event: message_stop), dan menyertakan type event yang sesuai di dalam datanya.

Setiap stream menggunakan alur event berikut:

1. message_start: berisi objek Message dengan content kosong. Di bawah header beta thinking-binding-controls-2026-08-01, objek Message ini juga membawa array input_transformations. Setelah fallback sisi server di tengah stream, event message_delta terakhir membawa array tersebut lagi dengan entri dari model yang melayani.
2. Serangkaian blok konten, yang masing-masing memiliki event content_block_start, sejumlah event content_block_delta (berapa pun jumlahnya), dan event content_block_stop. Setiap blok konten memiliki index yang sesuai dengan indeksnya dalam array content Message akhir. Beberapa blok tiba secara utuh, tanpa delta: blok redacted_thinking, hasil alat server seperti web_search_tool_result, dan blok fallback di setiap batas model dari fallback sisi server.
3. Satu atau lebih event message_delta, yang menunjukkan perubahan tingkat atas pada objek Message akhir.
4. Event message_stop terakhir.

Event ping

Stream event juga dapat menyertakan sejumlah event ping.

Event error

API terkadang dapat mengirimkan error dalam stream event. Misalnya, selama periode penggunaan tinggi, Anda mungkin menerima overloaded_error, yang biasanya sesuai dengan HTTP 529 dalam konteks non-streaming:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Event lainnya

Sesuai dengan kebijakan pembuatan versi, jenis event baru dapat ditambahkan, dan kode Anda harus menangani jenis event yang tidak dikenal dengan baik.

Jenis delta blok konten

Setiap event content_block_delta berisi delta dengan jenis yang memperbarui blok content pada index tertentu.

Delta teks

Delta blok konten text terlihat seperti:

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

Delta JSON input

Delta untuk blok konten tool_use berkaitan dengan pembaruan pada field input dari blok tersebut. Untuk mendukung granularitas maksimum, delta berupa string JSON parsial, sedangkan tool_use.input akhir selalu berupa objek.

Anda dapat mengakumulasi delta string dan mengurai JSON setelah menerima event content_block_stop, dengan menggunakan library seperti Pydantic untuk melakukan penguraian JSON parsial, atau dengan menggunakan helper streaming dari SDK. Di Python dan TypeScript SDK, helper ini juga memberi Anda akses ke input yang telah diurai secara bertahap, seiring proses streaming.

Delta blok konten tool_use terlihat seperti:

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

Secara default, API melakukan buffering pada setiap kunci dan nilai dalam input hingga lengkap. Dengan alat, mungkin ada jeda antar event streaming selama model menghasilkan sebuah nilai. Setelah API memiliki kunci dan nilai input yang lengkap, API mengirimkannya sebagai beberapa event content_block_delta dengan JSON parsial yang dipecah-pecah.

Delta thinking

Saat menggunakan pemikiran dengan streaming diaktifkan, Anda akan menerima konten pemikiran melalui event thinking_delta. Delta ini sesuai dengan field thinking dari blok konten thinking.

Untuk konten thinking, event signature_delta khusus dikirim tepat sebelum event content_block_stop. Signature ini digunakan untuk memverifikasi integritas blok thinking.

Ketika display: "omitted" diatur pada konfigurasi thinking, tidak ada teks thinking yang di-stream. Blok thinking terbuka, menerima thinking_delta dengan string thinking kosong lalu satu signature_delta, kemudian tertutup. Dengan display: "updates" (beta), blok penalaran di-stream dengan cara yang sama, dan hanya pembaruan progres yang ditulis oleh beberapa model di antara pemanggilan alat yang men-stream event thinking_delta yang membawa teks. Lihat Mengontrol tampilan thinking.

Delta thinking yang umum terlihat seperti:

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

Delta signature terlihat seperti:

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

Respons stream HTTP lengkap

Gunakan SDK klien saat menggunakan mode streaming. Namun, jika Anda membangun integrasi API langsung, Anda perlu menangani event ini sendiri.

Respons stream terdiri dari:

1. Event message_start
2. Kemungkinan beberapa blok konten, yang masing-masing berisi:
   • Event content_block_start
   • Kemungkinan beberapa event content_block_delta
   • Event content_block_stop
3. Satu atau lebih event message_delta
4. Event message_stop

Mungkin juga ada event ping yang tersebar di sepanjang respons. Lihat Jenis event untuk detail lebih lanjut tentang formatnya.

Permintaan streaming dasar

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=256,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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": "Hello"}}

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"}

Permintaan streaming dengan penggunaan alat

Permintaan ini meminta Claude menggunakan alat untuk melaporkan cuaca.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "any"},
    messages=[
        {"role": "user", "content": "What is the weather like in San Francisco?"}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-5","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":"Okay"}}

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":" let"}}

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

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

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

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

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

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

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

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_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":" \"San"}}

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

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

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

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"}

Permintaan streaming dengan thinking

Permintaan ini mengaktifkan thinking dengan streaming. Pengaturan display: "summarized" men-stream ringkasan padat dari penalaran Claude alih-alih rantai pemikiran lengkap.

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=20000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            delta = event.delta
            match delta.type:
                case "thinking_delta":
                    print(delta.thinking, end="", flush=True)
                case "text_delta":
                    print(delta.text, end="", flush=True)

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null}}

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n147 = 7 × 21 + 0"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\nThe remainder is 0, so GCD(1071, 462) = 21."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

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": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

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

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

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

Permintaan streaming dengan penggunaan alat pencarian web

Permintaan ini meminta Claude mencari informasi cuaca terkini di web.

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
    messages=[
        {"role": "user", "content": "What is the weather like in New York City today?"}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-5-5","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":2679,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}}

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

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"I'll check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the current weather in New York City for you"}}

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

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":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","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":"{\"query"}}

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":" \"weather"}}

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

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

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

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

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}

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

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

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" in New York City"}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}

...

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

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10682,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":510,"server_tool_use":{"web_search_requests":1}}}

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

Pemulihan error

Claude 4.5 dan sebelumnya

Untuk model Claude 4.5 dan sebelumnya, Anda dapat memulihkan permintaan streaming yang terputus karena masalah jaringan, timeout, atau error lainnya dengan melanjutkan dari titik stream terputus. Pendekatan ini menghindarkan Anda dari pemrosesan ulang seluruh respons.

Strategi pemulihan dasar meliputi:

1. Tangkap respons parsial: Simpan semua konten yang berhasil diterima sebelum error terjadi.
2. Susun permintaan lanjutan: Buat permintaan API baru yang menyertakan respons asisten parsial sebagai awal dari pesan asisten baru.
3. Lanjutkan streaming: Lanjutkan menerima sisa respons dari titik terputusnya.

Claude 4.6 dan setelahnya

Untuk model Claude 4.6 dan setelahnya, strategi tangkap-dan-lanjutkan yang sama berlaku, tetapi langkah 2 berubah: alih-alih menempatkan respons parsial dalam pesan asisten, tambahkan pesan pengguna yang menginstruksikan model untuk melanjutkan dari titik terakhirnya.

1. Tangkap respons parsial: Simpan semua konten yang berhasil diterima sebelum error terjadi.
2. Susun permintaan lanjutan: Buat permintaan API baru dengan pesan pengguna yang berisi respons parsial dan instruksi untuk melanjutkan, misalnya:
   Sample prompt

   

   Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.

3. Lanjutkan streaming: Lanjutkan menerima sisa respons dari titik terputusnya.

Praktik terbaik pemulihan error

1. Gunakan fitur SDK: Andalkan kemampuan akumulasi pesan dan penanganan error bawaan SDK.
2. Tangani jenis konten: Perhatikan bahwa pesan dapat berisi beberapa blok konten (text, tool_use, thinking). Blok penggunaan alat dan pemikiran tidak dapat dipulihkan sebagian. Anda dapat melanjutkan streaming dari blok teks terbaru.

Langkah selanjutnya