流式输入 vs 单消息输入

SDK 支持两种输入模式：流式输入（推荐）将 Agent 作为长期运行进程，支持图片上传、消息队列、中断等完整功能；单消息输入适合简单的一次性查询。

核心机制

流式输入模式（推荐）：通过 AsyncGenerator 持续发送消息，Agent 作为长期进程运行。支持：

• 图片上传（base64 编码的 image content block）
• 消息队列（多条消息顺序处理）
• 中断/取消
• 权限请求处理
• 会话管理

单消息输入模式：每次调用传入完整字符串，适合无需交互的一次性任务。不支持：图片附件、动态消息队列、实时中断、Hook 集成。

关键细节

流式输入（TypeScript）：

async function* generateMessages(): AsyncGenerator<SDKUserMessage> {
    yield {
        type: "user",
        message: { role: "user", content: "Analyze this codebase" },
        parent_tool_use_id: null
    };
    // 等待条件或用户输入
    await new Promise(resolve => setTimeout(resolve, 2000));
    // 发送带图片的后续消息
    yield {
        type: "user",
        message: {
            role: "user",
            content: [
                { type: "text", text: "Review this diagram" },
                { type: "image", source: { type: "base64", media_type: "image/png", data: "..." } }
            ]
        },
        parent_tool_use_id: null
    };
}
 
for await (const message of query({ prompt: generateMessages(), options: {...} })) { ... }

流式输入（Python）：使用 ClaudeSDKClient：

async with ClaudeSDKClient(options) as client:
    await client.query(message_generator())
    async for message in client.receive_response():
        ...

单消息输入：

async for message in query(
    prompt="Explain the authentication flow",
    options=ClaudeAgentOptions(max_turns=1),
):
    if isinstance(message, ResultMessage):
        print(message.result)

与其他概念的关联

• streaming-output - 输出流式（接收 token 增量），与输入模式正交
• sessions - 流式输入模式下的会话管理
• user-input - canUseTool 回调需要流式输入模式（Python）

实践要点

• Python 中 canUseTool 回调需要流式输入模式，且需要一个 dummy PreToolUse Hook 保持流连接
• 大多数生产场景推荐流式输入，获得完整 Agent 能力
• 无状态环境（Lambda 函数）适合单消息输入，配合 resume 选项恢复会话
• 流式输入中可以在 generator 中等待用户响应，实现真正的交互式对话