Skip to main content

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 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 bernama diagram.png dari direktori kerja. Buat satu di sana terlebih dahulu, atau ubah nama file untuk menunjuk ke gambar Anda sendiri.
Ketika Anda menjalankan contoh, versi TypeScript mencetak setiap respons saat selesai. Loop 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

Single message input mode tidak mendukung:
  • Lampiran gambar langsung dalam pesan
  • Antrian pesan dinamis
  • Gangguan real-time
  • Percakapan multi-turn alami
Jika kueri berakhir dengan hasil kesalahan, seperti error_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.

Contoh Implementasi

Ketika Anda menjalankan contoh, setiap kueri mencetak teks hasil akhirnya: pertama penjelasan autentikasi, kemudian penjelasan otorisasi.