תיעוד 133
קלט בהזרמה (Streaming Input)
הבנת שני מצבי הקלט עבור Claude Agent SDK ומתי להשתמש בכל אחד מהם
#סקירה כללית
ה-Claude Agent SDK תומך בשני מצבי קלט נפרדים לאינטראקציה עם סוכנים:
- מצב קלט מוזרם (
Streaming Input Mode): הפעלה אינטראקטיבית ומתמשכת - קלט הודעה בודדת (
Single Message Input): שאילתות חד-פעמיות המשתמשות במצב ההפעלה ובחידוש שלה
#מצב קלט מוזרם (מומלץ)
מצב קלט מוזרם הוא הדרך המועדפת לשימוש ב-Claude Agent SDK. הוא מספק גישה מלאה ליכולות הסוכן ומאפשר חוויות עשירות ואינטראקטיביות.
הוא מאפשר לסוכן לפעול כתהליך מאריך ימים שמקבל קלט משתמש, מטפל בהפרעות, מציג בקשות להרשאה ומטפל בניהול ההפעלה.
#יתרונות
במצב קלט מוזרם, אתה עובד בהפעלה מתמשכת עם היכולות הבאות:
- העלאת תמונות: צירוף תמונות ישירות להודעות לצורך ניתוח והבנה חזותיים
- הודעות בתור: שליחת מספר הודעות שמעובדות ברצף, עם יכולת לקטוע או להפריע
- שילוב כלים: גישה מלאה לכל הכלים ולשרתי MCP מותאמים אישית במהלך ההפעלה
- משוב בזמן אמת: צפייה בתגובות בזמן יצירתן, ולא רק בתוצאות הסופיות
- שימור הקשר: שמירה על הקשר השיחה לאורך מספר סבבים באופן טבעי
#דוגמת יישום
דוגמאות אלה קוראות תמונה בשם diagram.png מספריית העבודה. צור תמונה כזו שם תחילה, או שנה את שם הקובץ כך שיצביע על תמונה משלך.
#TypeScript
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);
}
}#Python
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())כאשר מריצים את הדוגמה, גרסת ה-TypeScript מדפיסה כל תגובה עם השלמתה. לולאת ה-receive_response() בגרסת ה-Python מסתיימת בהודעת התוצאה הראשונה, ולכן היא מדפיסה את ניתוח האבטחה. כדי לקרוא את שתי התגובות, השתמש בצמד אחד של query() ו-receive_response() לכל הודעה, כפי שמוצג בדוגמה של המשך שיחה במדריך ה-Python.
הערה: ב-TypeScript SDK, אם מחולל ההודעות שלך זורק שגיאה, למשל כאשר קובץ שהוא קורא חסר, הזרם מסתיים בשגיאה שבה נכתב
Claude Code process aborted by userבמקום השגיאה המקורית, לכן בדוק תחילה את הקוד בתוך המחולל שלך כאשר אתה רואה הודעה זו. לפני הודעת השגיאה עשויה להופיע גם שורה ארוכה ומכווצת (minified) של קוד מקור ארוז של ה-SDK, לכן קרא עד סוף הפלט כדי למצוא את טקסט השגיאה.ב-Python SDK, חריגה במחולל נרשמת ביומן ברמת debug וההפעלה נתקעת מבלי להעלות שגיאה, לכן אם הפעלת הזרמה נתקעת ללא פלט, הפעל רישום ברמת debug ובדוק את המחולל שלך.
#קלט הודעה בודדת (Single Message Input)
קלט הודעה בודדת הוא פשוט יותר, אך מוגבל יותר.
#מתי להשתמש בקלט הודעה בודדת
השתמש בקלט הודעה בודדת כאשר:
- אתה זקוק לתגובה חד-פעמית
- אינך זקוק לקבצים מצורפים של תמונות או לשיטות שליטה באמצע ההפעלה
- אתה צריך לפעול בסביבה ללא שמירת מצב (stateless), כגון פונקציית lambda
#מגבלות
אזהרה: מצב קלט הודעה בודדת אינו תומך ב:
- צירוף תמונות ישיר בהודעות
- ניהול דינמי של הודעות בתור
- הפרעה בזמן אמת
- שיחות טבעיות מרובות סבבים
אם שאילתה מסתיימת בתוצאת שגיאה, כגון error_max_turns, קריאת query() של הודעה בודדת מעלה שגיאה הכוללת את טקסט הכישלון לאחר הפקת הודעת התוצאה הסופית, לכן עטוף את הלולאה בבלוק try אם הקוד שלך צריך להמשיך. ראה טיפול בתוצאה עבור סוגי המשנה של התוצאה.
#דוגמת יישום
#TypeScript
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}`);
}#Python
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())כאשר מריצים את הדוגמה, כל שאילתה מדפיסה את טקסט התוצאה הסופי שלה: תחילה ההסבר על האימות, ולאחר מכן ההסבר על ההרשאה.