AssistantMessage。要在文本和工具调用生成时接收增量更新,请启用部分消息流式传输。
启用流式输出
要启用流式传输,请在选项中将include_partial_messages(Python)或 includePartialMessages(TypeScript)设置为 true。这会导致 SDK 产生包含原始 API 事件的 StreamEvent 消息,这些事件在到达时产生,除了通常的 AssistantMessage 和 ResultMessage 之外。
您的代码需要:
- 检查每条消息的类型以区分
StreamEvent和其他消息类型 - 对于
StreamEvent,提取event字段并检查其type - 查找
content_block_delta事件,其中delta.type是text_delta,这些事件包含实际的文本块
StreamEvent,然后是 content_block_delta,最后是 text_delta:
StreamEvent 参考
启用部分消息时,您会收到包装在对象中的原始 Claude API 流事件。该类型在每个 SDK 中有不同的名称:- Python:
StreamEvent(从claude_agent_sdk.types导入) - TypeScript:
SDKPartialAssistantMessage,其中type: 'stream_event'
parent_tool_use_id 字段在 Python 中始终为 None,在 TypeScript 中始终为 null。流事件仅针对主会话发出;来自子代理的令牌级增量不会被转发。要将输出归属于子代理,请使用完整消息,这些消息携带 parent_tool_use_id。请参阅检测子代理调用。
Claude Code 在轮次的第一个非 ping 流事件上设置 user_message_uuid,以及当轮次回答的消息更改时再次设置,条件在 user_message_uuid 中。Python StreamEvent 不公开此字段。
event 字段包含来自 Claude API 的原始流事件。常见的事件类型包括:
消息流
Claude Code 在每个非空内容块完成时发出一个AssistantMessage,因此包含文本块和工具调用的响应会产生两个 AssistantMessage 对象。每个对象仅携带其自己的内容块,两者共享相同的消息 ID,在 TypeScript 中读作 message.message.id,在 Python 中读作 message.message_id。启用部分消息后,每个 AssistantMessage 在该块的 content_block_stop 事件之前到达,你会按以下顺序接收消息:
StreamEvent 之外的所有消息类型。常见类型包括 SystemMessage(会话初始化)、AssistantMessage(完整内容块)、ResultMessage(最终结果)和一个紧凑边界消息,指示何时压缩了对话历史记录(TypeScript 中为 SDKCompactBoundaryMessage;Python 中为带有子类型 "compact_boundary" 的 SystemMessage)。
处理被中断的流
如果流在消息中途被中断,例如当您中断该轮次或连接断开时,您仍会在该轮次结束前收到该消息的message_stop。被中断的文本块或思考块也会收到其 content_block_stop。被中断的工具调用则不会,因此如果 message_stop 到达时某个工具调用的块仍处于打开状态,请将该调用的输入视为不完整。
在 Claude Code v2.1.290 之前,被中断的流可能会在没有 message_stop 的情况下结束轮次,因此您根据流事件渲染的回复可能会一直显示为进行中。TypeScript Agent SDK 从 v0.3.290 起捆绑 Claude Code v2.1.290 或更高版本,Python Agent SDK 则从 v0.2.164 起捆绑。如果轮次结束后回复仍显示为进行中,请更新 SDK。
流式传输工具调用
工具调用也会增量流式传输。您可以跟踪工具何时开始、在生成时接收其输入,以及查看它们何时完成。下面的示例跟踪当前被调用的工具并在流式传输时累积 JSON 输入。它使用三种事件类型:content_block_start:工具开始content_block_delta,带有input_json_delta:输入块到达content_block_stop:工具调用完成
构建流式 UI
此示例将文本和工具流式传输结合到一个有凝聚力的 UI 中。它跟踪代理当前是否正在执行工具(使用in_tool 标志)以显示状态指示器,如 [Using Read...],同时工具运行。当不在工具中时文本正常流式传输,工具完成会触发”完成”消息。此模式对于需要在多步骤代理任务期间显示进度的聊天界面很有用。
已知限制
- 结构化输出:启用部分消息时,JSON 作为工具调用的未验证
input_json_delta块进行流式传输,只有验证后的结果才会到达最终的ResultMessage.structured_output。有关详细信息,请参阅结构化输出。