Streaming Input
Memahami dua mode input untuk Claude Agent SDK dan kapan menggunakan masing-masing
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 bernama diagram.png dari direktori kerja. Buat satu di sana terlebih dahulu, atau ubah nama file untuk menunjuk ke gambar Anda sendiri.
import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
import { readFile } from "fs/promises";
async function* generateMessages(): AsyncGenerator<SDKUserMessage> {
// First message
yield {
type: "user",
message: {
role: "user",
content: "Analyze this codebase for security issues"
},
parent_tool_use_id: null
};
// Wait for conditions or user input
await new Promise((resolve) => setTimeout(resolve, 2000));
// Follow-up with image
yield {
type: "user",
message: {
role: "user",
content: [
{
type: "text",
text: "Review this architecture diagram"
},
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: await readFile("diagram.png", "base64")
}
}
]
},
parent_tool_use_id: null
};
}
// Process streaming responses
for await (const message of query({
prompt: generateMessages(),
options: {
maxTurns: 10,
allowedTools: ["Read", "Grep"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
AssistantMessage,
TextBlock,
)
import asyncio
import base64
async def streaming_analysis():
async def message_generator():
# First message
yield {
"type": "user",
"message": {
"role": "user",
"content": "Analyze this codebase for security issues",
},
}
# Wait for conditions
await asyncio.sleep(2)
# Follow-up with image
with open("diagram.png", "rb") as f:
image_data = base64.b64encode(f.read()).decode()
yield {
"type": "user",
"message": {
"role": "user",
"content": [
{"type": "text", "text": "Review this architecture diagram"},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
],
},
}
# Use ClaudeSDKClient for streaming input
options = ClaudeAgentOptions(max_turns=10, allowed_tools=["Read", "Grep"])
async with ClaudeSDKClient(options) as client:
# Send streaming input
await client.query(message_generator())
# Process responses
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text)
asyncio.run(streaming_analysis())
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.
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, 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
import { query } from "@anthropic-ai/claude-agent-sdk";
// Simple one-shot query
// query() throws after an error result, such as error_max_turns
try {
for await (const message of query({
prompt: "Explain the authentication flow",
options: {
maxTurns: 5,
allowedTools: ["Read", "Grep"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
console.error(`Query failed: ${error}`);
}
// Continue conversation with session management
try {
for await (const message of query({
prompt: "Now explain the authorization process",
options: {
continue: true,
maxTurns: 5
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
console.error(`Query failed: ${error}`);
}
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio
async def single_message_example():
# Simple one-shot query using query() function
# query() raises ResultError after an error result, such as error_max_turns
try:
async for message in query(
prompt="Explain the authentication flow",
options=ClaudeAgentOptions(max_turns=5, allowed_tools=["Read", "Grep"]),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
except Exception as e:
print(f"Query failed: {e}")
# Continue conversation with session management
try:
async for message in query(
prompt="Now explain the authorization process",
options=ClaudeAgentOptions(continue_conversation=True, max_turns=5),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
except Exception as e:
print(f"Query failed: {e}")
asyncio.run(single_message_example())
Ketika Anda menjalankan contoh, setiap kueri mencetak teks hasil akhirnya: pertama penjelasan autentikasi, kemudian penjelasan otorisasi.