流式输出

本主题介绍了如何从 Cortex Code Agent SDK 获取实时流式响应。

默认情况下，SDK 会在模型完成每条响应的生成后，才产出完整的 AssistantMessage 对象。要在生成文本和思维块时接收增量更新，请通过将 includePartialMessages (TypeScript) 或``include_partial_messages`` (Python) 设置为 true 来启用部分消息流式传输。

启用部分消息后，Cortex Code 会针对部分文本和思维内容发出 StreamEvent 对象。完整的工具调用仍作为 AssistantMessage 对象到达，而工具结果仍作为 UserMessage 对象到达。

启用流式输出

启用后，SDK 除了输出通常的 AssistantMessage、UserMessage 和 ResultMessage 对象外，还会输出包含部分流式事件的 StreamEvent 消息。您的代码需要：

  1. 检查每条消息的类型，以区分 StreamEvent 和其他类型。

  2. 对于 StreamEvent，提取 event 字段并检查其 type。

  3. 查找 delta.type 为 text_delta 的 content_block_delta 事件。

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "List the files in my project",
  options: {
    cwd: process.cwd(),
    includePartialMessages: true,
    allowedTools: ["Bash", "Read"],
  },
})) {
  if (message.type === "stream_event") {
    const event = message.event;
    if (event.type === "content_block_delta") {
      if (event.delta.type === "text_delta") {
        process.stdout.write(event.delta.text);
      }
    }
  }
}

StreamEvent 参考

启用部分消息后，您会收到封装在对象中的原始流事件：

interface SDKPartialAssistantMessage {
  type: "stream_event";
  event: Record<string, unknown>;  // Raw streaming event
  parent_tool_use_id: string | null;
  uuid: string;
  session_id: string;
}

event 字段包含由 Cortex Code 发出的原始部分流式事件。常见事件类型：

事件类型

描述

content_block_start

新文本或思维块的开始

content_block_delta

增量文本或思维更新

content_block_stop

当前文本或思维块的结尾

消息流

启用部分消息后，您通常会按以下顺序接收消息：

SystemMessage -- session initialization
StreamEvent (content_block_start) -- text or thinking block
StreamEvent (content_block_delta) -- text_delta or thinking_delta chunks...
StreamEvent (content_block_stop)
AssistantMessage -- complete text/thinking block, or complete tool_use block
UserMessage -- complete tool_result block
... more assistant/user turns ...
ResultMessage -- final result

如果不启用部分消息，您仍会收到相同的完整助手、用户和结果消息，但不会收到 StreamEvent。根据会话情况，SDK 还可以发出 system 事件，如初始化、状态和后台任务通知。

实现流式文本响应

为了在文本生成时同步显示，请查找 delta.type 为 text_delta 的 content_block_delta 事件。

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "Explain how databases work",
  options: { cwd: process.cwd(), includePartialMessages: true },
})) {
  if (message.type === "stream_event") {
    const event = message.event;
    if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
      process.stdout.write(event.delta.text);
    }
  }
}
console.log(); // Final newline

构建流式 UI

以下示例在一个本地缓冲区中累积流式文本，并在每次新的 text_delta 到达时重新渲染当前响应。在实际应用中，请将 render 函数替换为您所用框架的状态更新逻辑：

import { query } from "cortex-code-agent-sdk";

let currentText = "";

function render(text: string) {
  console.clear();
  console.log("Assistant:\n");
  process.stdout.write(text);
}

for await (const message of query({
  prompt: "Explain how databases work",
  options: {
    cwd: process.cwd(),
    includePartialMessages: true,
  },
})) {
  if (message.type === "stream_event") {
    const event = message.event;
    if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
      currentText += event.delta.text;
      render(currentText);
    }
  } else if (message.type === "result") {
    console.log("\n\n--- Complete ---");
  }
}

已知限制

功能

对流式传输的影响

结构化输出

JSON 结果仅出现在 ResultMessage.structured_output 中，不会作为流式增量出现