Skip to main content
Secara default, Agent SDK menghasilkan 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.
Halaman ini mencakup output streaming (menerima token secara real-time). Untuk input modes (cara Anda mengirim pesan), lihat Kirim pesan ke agents. Anda juga dapat stream responses using the Agent SDK via the CLI.

Enable streaming output

Untuk mengaktifkan streaming, atur include_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:
  1. Memeriksa tipe setiap pesan untuk membedakan StreamEvent dari tipe pesan lainnya
  2. Untuk StreamEvent, ekstrak field event dan periksa type-nya
  3. Cari event content_block_delta di mana delta.type adalah text_delta, yang berisi chunk teks aktual
Contoh di bawah mengaktifkan streaming dan mencetak chunk teks saat tiba. Perhatikan pemeriksaan tipe bersarang: pertama untuk 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: Keduanya berisi raw Claude API events, bukan teks terakumulasi. Anda perlu mengekstrak dan mengakumulasi text deltas sendiri. Field 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 mengeluarkan AssistantMessage 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:
Tanpa pesan parsial diaktifkan, Anda menerima semua jenis pesan kecuali 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 menerima message_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 dimulai
  • content_block_delta dengan input_json_delta: chunk input tiba
  • content_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 flag in_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_delta yang tidak divalidasi dari tool call, dan hanya hasil yang divalidasi yang mencapai ResultMessage.structured_output akhir. Lihat structured outputs untuk detail.

Langkah selanjutnya

Sekarang bahwa Anda dapat stream teks dan tool calls secara real-time, jelajahi topik terkait ini: