Skip to main content
默认情况下,Agent SDK 在 Claude 完成生成每个非空内容块(例如文本块或工具调用)后会产生完整的 AssistantMessage。要在文本和工具调用生成时接收增量更新,请启用部分消息流式传输。
本页面涵盖输出流式传输(实时接收令牌)。有关输入模式(如何发送消息),请参阅向代理发送消息。您也可以通过 CLI 使用 Agent SDK 流式传输响应。

启用流式输出

要启用流式传输,请在选项中将 include_partial_messages(Python)或 includePartialMessages(TypeScript)设置为 true。这会导致 SDK 产生包含原始 API 事件的 StreamEvent 消息,这些事件在到达时产生,除了通常的 AssistantMessage 和 ResultMessage 之外。 您的代码需要:
  1. 检查每条消息的类型以区分 StreamEvent 和其他消息类型
  2. 对于 StreamEvent,提取 event 字段并检查其 type
  3. 查找 content_block_delta 事件,其中 delta.type 是 text_delta,这些事件包含实际的文本块
下面的示例启用流式传输并在文本块到达时打印它们。注意嵌套的类型检查:首先是 StreamEvent,然后是 content_block_delta,最后是 text_delta:

StreamEvent 参考

启用部分消息时,您会收到包装在对象中的原始 Claude API 流事件。该类型在每个 SDK 中有不同的名称: 两者都包含原始 Claude API 事件,而不是累积的文本。您需要自己提取和累积文本增量。 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。有关详细信息,请参阅结构化输出。

后续步骤

现在您可以实时流式传输文本和工具调用,请探索这些相关主题: