ストリーミング出力

このトピックでは、Cortex Codeエージェント 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 でのみ表示されます