Gambaran Umum
Claude Agent SDK mendukung dua mode input yang berbeda untuk berinteraksi dengan agen:- Streaming Input Mode: sesi interaktif yang persisten
- Single Message Input: kueri sekali jalan yang menggunakan status sesi dan melanjutkan
Streaming Input Mode (Direkomendasikan)
Streaming input mode adalah cara yang lebih disukai untuk menggunakan Claude Agent SDK. Mode ini memberikan akses penuh ke kemampuan agen dan memungkinkan pengalaman interaktif yang kaya. Mode ini memungkinkan agen beroperasi sebagai proses yang berumur panjang yang menerima input pengguna, menangani gangguan, menampilkan permintaan izin, dan menangani manajemen sesi.Manfaat
Dalam streaming input mode, Anda bekerja dalam sesi yang persisten dengan kemampuan berikut:- Unggahan gambar: lampirkan gambar langsung ke pesan untuk analisis visual dan pemahaman
- Pesan antrian: kirim beberapa pesan yang diproses secara berurutan, dengan kemampuan untuk mengganggu
- Integrasi tool: akses penuh ke semua tools dan server MCP kustom selama sesi
- Umpan balik real-time: lihat respons saat dihasilkan, bukan hanya hasil akhir
- Persistensi konteks: pertahankan konteks percakapan di beberapa giliran secara alami
Contoh Implementasi
Contoh-contoh ini membaca gambar bernamadiagram.png dari direktori kerja. Buat satu di sana terlebih dahulu, atau ubah nama file untuk menunjuk ke gambar Anda sendiri.
receive_response() versi Python berakhir pada pesan hasil pertama, jadi mencetak analisis keamanan; untuk membaca kedua respons, gunakan satu pasangan query() dan receive_response() per pesan seperti yang ditunjukkan dalam contoh referensi Python tentang melanjutkan percakapan.
Jika source dari sebuah blok gambar tidak ada atau bukan berupa objek, SDK tidak melaporkan kesalahan. Claude Code mengirimkan catatan teks kepada Claude sebagai pengganti gambar, seperti [Image could not be processed: image block has no source object], dan sesi tetap berlanjut.
Dalam TypeScript SDK, jika generator pesan Anda melempar kesalahan, misalnya ketika file yang dibacanya hilang, aliran berakhir dengan kesalahan yang berbunyi
Claude Code process aborted by user alih-alih kesalahan asli, jadi periksa kode di dalam generator Anda terlebih dahulu ketika Anda melihat pesan itu. Kesalahan juga dapat didahului oleh baris minified panjang dari sumber SDK bundel, jadi baca hingga akhir output untuk teks kesalahan.Dalam Python SDK, pengecualian generator dicatat pada tingkat debug dan sesi macet tanpa menaikkan, jadi jika sesi streaming tergantung tanpa output, aktifkan logging debug dan periksa generator Anda.Single Message Input
Single message input lebih sederhana tetapi lebih terbatas.Kapan Menggunakan Single Message Input
Gunakan single message input ketika:- Anda membutuhkan respons sekali jalan
- Anda tidak memerlukan lampiran gambar atau metode kontrol mid-session
- Anda perlu beroperasi di lingkungan stateless, seperti fungsi lambda
Keterbatasan
Jika kueri berakhir dengan hasil kesalahan, sepertierror_max_turns, panggilan query() pesan tunggal akan memunculkan kesalahan yang mencakup teks kegagalan setelah menghasilkan pesan hasil akhir, jadi bungkus loop dalam blok try jika kode Anda perlu melanjutkan. Lihat Handle the result untuk subtipe hasil.