AssistantMessage lengkap untuk setiap blok konten yang tidak kosong, seperti blok teks atau tool call, setelah Claude selesai menghasilkan blok tersebut. Untuk menerima pembaruan inkremental saat teks dan tool calls dihasilkan, aktifkan partial message streaming.
Enable streaming output
Untuk mengaktifkan streaming, aturinclude_partial_messages (Python) atau includePartialMessages (TypeScript) ke true dalam opsi Anda. Ini menyebabkan SDK menghasilkan pesan StreamEvent yang berisi raw API events saat tiba, selain AssistantMessage dan ResultMessage yang biasa.
Kode Anda kemudian perlu:
- Memeriksa tipe setiap pesan untuk membedakan
StreamEventdari tipe pesan lainnya - Untuk
StreamEvent, ekstrak fieldeventdan periksatype-nya - Cari event
content_block_deltadi manadelta.typeadalahtext_delta, yang berisi chunk teks aktual
StreamEvent, kemudian untuk content_block_delta, kemudian untuk text_delta:
StreamEvent reference
Ketika partial messages diaktifkan, Anda menerima raw Claude API streaming events yang dibungkus dalam objek. Tipe memiliki nama berbeda di setiap SDK:- Python:
StreamEvent(import dariclaude_agent_sdk.types) - TypeScript:
SDKPartialAssistantMessagedengantype: 'stream_event'
parent_tool_use_id selalu None di Python dan null di TypeScript. Stream events dipancarkan untuk sesi utama saja; token-level deltas dari subagents tidak diteruskan. Untuk mengatribusikan output ke subagent, gunakan complete messages, yang membawa parent_tool_use_id. Lihat Detect subagent invocation.
Claude Code menetapkan user_message_uuid pada stream event non-ping pertama giliran, dan lagi ketika pesan yang dijawab giliran berubah, di bawah kondisi dalam user_message_uuid. Python StreamEvent tidak mengekspos field ini.
Field event berisi raw streaming event dari Claude API. Tipe event umum meliputi:
Alur pesan
Claude Code mengeluarkanAssistantMessage saat setiap blok konten yang tidak kosong selesai, jadi respons dengan blok teks dan panggilan alat menghasilkan dua objek AssistantMessage. Masing-masing membawa hanya blok kontennya sendiri, dan keduanya berbagi ID pesan yang sama, yang Anda baca sebagai message.message.id di TypeScript dan message.message_id di Python. Dengan pesan parsial diaktifkan, setiap AssistantMessage tiba sebelum acara content_block_stop blok tersebut, dan Anda menerima pesan dalam urutan ini:
StreamEvent. Jenis umum termasuk SystemMessage (inisialisasi sesi), AssistantMessage (blok konten lengkap), ResultMessage (hasil akhir), dan pesan batas kompak yang menunjukkan kapan riwayat percakapan dikompres (SDKCompactBoundaryMessage di TypeScript; SystemMessage dengan subtipe "compact_boundary" di Python).
Menangani stream yang terputus
Jika sebuah stream terputus di tengah pesan, misalnya saat Anda menginterupsi giliran atau koneksi terputus, Anda tetap menerimamessage_stop untuk pesan tersebut sebelum giliran berakhir. Blok teks atau thinking block yang terputus juga mendapatkan content_block_stop-nya. Panggilan tool yang terputus tidak mendapatkannya, jadi jika message_stop tiba saat blok panggilan tool masih terbuka, anggap input panggilan tersebut tidak lengkap.
Sebelum Claude Code v2.1.290, stream yang terputus dapat mengakhiri giliran tanpa message_stop, sehingga balasan yang Anda render dari acara stream dapat tetap ditampilkan sebagai sedang berlangsung. TypeScript Agent SDK menyertakan Claude Code v2.1.290 atau yang lebih baru mulai dari v0.3.290, dan Python Agent SDK mulai dari v0.2.164. Jika balasan tetap ditampilkan sebagai sedang berlangsung setelah giliran berakhir, perbarui SDK.
Stream tool calls
Tool calls juga streaming secara inkremental. Anda dapat melacak kapan tools dimulai, menerima input mereka saat dihasilkan, dan melihat kapan mereka selesai. Contoh di bawah melacak tool yang sedang dipanggil dan mengakumulasi input JSON saat streaming masuk. Ini menggunakan tiga tipe event:content_block_start: tool dimulaicontent_block_deltadenganinput_json_delta: chunk input tibacontent_block_stop: tool call selesai
Build a streaming UI
Contoh ini menggabungkan text dan tool streaming menjadi UI yang kohesif. Ini melacak apakah agent saat ini mengeksekusi tool (menggunakan flagin_tool) untuk menampilkan indikator status seperti [Using Read...] saat tools berjalan. Teks streaming secara normal ketika tidak dalam tool, dan penyelesaian tool memicu pesan “done”. Pola ini berguna untuk antarmuka chat yang perlu menampilkan progress selama tugas agent multi-langkah.
Keterbatasan yang Diketahui
- Structured output: dengan partial messages diaktifkan, JSON mengalir sebagai chunks
input_json_deltayang tidak divalidasi dari tool call, dan hanya hasil yang divalidasi yang mencapaiResultMessage.structured_outputakhir. Lihat structured outputs untuk detail.
Langkah selanjutnya
Sekarang bahwa Anda dapat stream teks dan tool calls secara real-time, jelajahi topik terkait ini:- Interactive vs one-shot queries: pilih antara input modes untuk use case Anda
- Structured outputs: dapatkan respons JSON yang diketik dari agent
- Permissions: kontrol tools mana yang dapat digunakan agent