ストリーミング
Agents SDK は、モデルやその他の実行ステップからの出力を逐次配信できます。ストリーミングを使うと、UI の応答性を保ち、最終的な実行結果がすべて揃うのを待たずにユーザーに最新の情報を届けられます。
ストリーミングの有効化
Section titled “ストリーミングの有効化”Runner.run() に { stream: true } オプションを渡すと、完全な実行結果ではなくストリーミングオブジェクトを取得できます。
import { Agent, run } from '@openai/agents';
const agent = new Agent({ name: 'Storyteller', instructions: 'You are a storyteller. You will be given a topic and you will tell a story about it.',});
const result = await run(agent, 'Tell me a story about a cat.', { stream: true,});ストリーミングを有効にすると、返される stream は AsyncIterable インターフェイスを実装します。各イベントは、実行中に何が起きたかを表すオブジェクトです。ストリームは 3 種類のイベントのいずれかを生成し、それぞれがエージェントの実行の異なる部分を表します。ただし、ほとんどのアプリケーションで必要なのはモデルのテキストだけなので、ストリームにはヘルパーが用意されています。
テキスト出力の取得
Section titled “テキスト出力の取得”stream.toTextStream() を呼び出すと、出力されたテキストのストリームを取得できます。compatibleWithNodeStreams が true の場合、戻り値は通常の Node.js の Readable です。これを process.stdout や別の出力先に直接パイプできます。
import { Agent, run } from '@openai/agents';
const agent = new Agent({ name: 'Storyteller', instructions: 'You are a storyteller. You will be given a topic and you will tell a story about it.',});
const result = await run(agent, 'Tell me a story about a cat.', { stream: true,});
result .toTextStream({ compatibleWithNodeStreams: true, }) .pipe(process.stdout);Promise stream.completed は、実行と保留中のすべてのコールバックが完了すると解決されます。これ以上出力がないことを確認したい場合は、必ずこれを await してください。これには、最後のテキストトークンが到着した後に完了する、セッションの永続化や履歴圧縮フックなどの後処理も含まれます。
toTextStream() はアシスタントのテキストのみを出力します。ツール呼び出し、ハンドオフ、承認、その他のランタイムイベントは、完全なイベントストリームから取得できます。
すべてのイベントの監視
Section titled “すべてのイベントの監視”for await ループを使うと、各イベントが到着するたびにその内容を確認できます。低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などの有用な情報が含まれています。
import { Agent, run } from '@openai/agents';
const agent = new Agent({ name: 'Storyteller', instructions: 'You are a storyteller. You will be given a topic and you will tell a story about it.',});
const result = await run(agent, 'Tell me a story about a cat.', { stream: true,});
for await (const event of result) { // these are the raw events from the model if (event.type === 'raw_model_stream_event') { console.log(`${event.type} %o`, event.data); } // agent updated events if (event.type === 'agent_updated_stream_event') { console.log(`${event.type} %s`, event.agent.name); } // Agent SDK specific events if (event.type === 'run_item_stream_event') { console.log(`${event.type} %o`, event.item); }}プレーンテキストのストリームと元のイベントストリームの両方を出力する完全なスクリプトについては、ストリーミングのコード例を参照してください。
Responses WebSocket トランスポート(任意)
Section titled “Responses WebSocket トランスポート(任意)”このページのストリーミング API は、OpenAI Responses WebSocket トランスポートでも動作します。
setOpenAIResponsesTransport('websocket') でグローバルに有効にするか、useResponsesWebSocket: true を設定した独自の OpenAIProvider を使用してください。
WebSocket 経由でストリーミングするだけであれば、withResponsesWebSocketSession(...) やカスタムの OpenAIProvider は必要ありません。実行間での再接続が許容される場合は、トランスポートを有効にした後も run() / Runner.run(..., { stream: true }) をそのまま使用できます。
接続を再利用し、プロバイダーのライフサイクルをより明示的に制御したい場合は、withResponsesWebSocketSession(...) またはカスタムの OpenAIProvider / Runner を使用してください。
previousResponseId による継続は、HTTP トランスポートと同じセマンティクスを使用します。異なるのはトランスポートと接続のライフサイクルだけです。
プロバイダーを自分で構築する場合は、終了時に忘れずに await provider.close() を呼び出してください。WebSocket を使用するモデルラッパーは、デフォルトで再利用のためにキャッシュされており、プロバイダーを閉じるとそれらの接続が解放されます。withResponsesWebSocketSession(...) でも同じように再利用できますが、クリーンアップの範囲が単一のコールバック内に自動的に限定されます。
ストリーミング、ツール呼び出し、承認、previousResponseId を含む完全なコード例については、examples/basic/stream-ws.ts を参照してください。
イベントの種類
Section titled “イベントの種類”ストリームは、次の 3 種類のイベントを生成します。
raw_model_stream_event
Section titled “raw_model_stream_event”import { isOpenAIChatCompletionsRawModelStreamEvent, isOpenAIResponsesRawModelStreamEvent, type RunStreamEvent,} from '@openai/agents';
export function logOpenAIRawModelEvent(event: RunStreamEvent) { if (isOpenAIResponsesRawModelStreamEvent(event)) { console.log(event.source); console.log(event.data.event.type); return; }
if (isOpenAIChatCompletionsRawModelStreamEvent(event)) { console.log(event.source); console.log(event.data.event.object); }}例:
{ "type": "raw_model_stream_event", "data": { "type": "output_text_delta", "delta": "Hello" }}OpenAI プロバイダーを使用している場合、@openai/agents-openai と @openai/agents はどちらも、agents-core の汎用的な RunRawModelStreamEvent の契約を変更せずに、元の OpenAI ペイロードの型を絞り込むヘルパーをエクスポートしています。
import type { RunStreamEvent } from '@openai/agents';import { isOpenAIResponsesRawModelStreamEvent } from '@openai/agents';
export function isOpenAIResponsesTextDelta(event: RunStreamEvent): boolean { return ( isOpenAIResponsesRawModelStreamEvent(event) && event.data.event.type === 'response.output_text.delta' );}トランスポートに依存しないストリーミングコードだけが必要な場合は、引き続き event.type === 'raw_model_stream_event' のチェックだけで十分です。
OpenAI モデルを使用しており、手動でキャストせずにプロバイダー固有のペイロードを確認したい場合に備えて、SDK は型を絞り込むヘルパーもエクスポートしています。
isOpenAIResponsesRawModelStreamEvent(event):Responses の元のイベント用です。isOpenAIChatCompletionsRawModelStreamEvent(event):Chat Completions のチャンク用です。
これらの OpenAI モデルイベントでは、RunRawModelStreamEvent.source にも 'openai-responses' または 'openai-chat-completions' が設定されます。
これは、response.reasoning_summary_text.delta、response.output_item.done、MCP の引数の差分など、Responses 固有のイベントを確認しつつ、TypeScript が基となるイベントの構造を認識できるようにしたい場合に特に便利です。
OpenAI 固有のストリーミングパターンのより詳しいコード例については、examples/basic/stream-ws.ts、examples/tools/code-interpreter.ts、examples/connectors/index.ts を参照してください。
run_item_stream_event
Section titled “run_item_stream_event”import type { RunItemStreamEvent, RunStreamEvent } from '@openai/agents';
export function isRunItemStreamEvent( event: RunStreamEvent,): event is RunItemStreamEvent { return event.type === 'run_item_stream_event';}name は、生成されたアイテムの種類を示します。
name | 意味 |
|---|---|
message_output_created | メッセージ出力アイテムが作成されました。 |
handoff_requested | モデルがハンドオフを要求しました。 |
handoff_occurred | ランタイムが別のエージェントへのハンドオフを完了しました。 |
tool_search_called | tool_search_call アイテムが出力されました。 |
tool_search_output_created | 読み込まれたツール定義を含む tool_search_output アイテムが出力されました。 |
tool_called | ツール呼び出しアイテムが出力されました。 |
tool_output | ツールの実行結果アイテムが出力されました。 |
reasoning_item_created | 推論アイテムが出力されました。 |
tool_approval_requested | ツール呼び出しが人間の承認を待つために一時停止しました。 |
tool_search_* イベントは、toolSearchTool() を使って実行中に遅延読み込みのツールを読み込む Responses の実行でのみ発生します。
ハンドオフのペイロードの例:
{ "type": "run_item_stream_event", "name": "handoff_occurred", "item": { "type": "handoff_call", "id": "h1", "status": "completed", "name": "transfer_to_refund_agent" }}agent_updated_stream_event
Section titled “agent_updated_stream_event”import type { RunAgentUpdatedStreamEvent, RunStreamEvent,} from '@openai/agents';
export function isRunAgentUpdatedStreamEvent( event: RunStreamEvent,): event is RunAgentUpdatedStreamEvent { return event.type === 'agent_updated_stream_event';}例:
{ "type": "agent_updated_stream_event", "agent": { "name": "Refund Agent" }}ストリーミング中の Human in the loop (人間の介入)
Section titled “ストリーミング中の Human in the loop (人間の介入)”ストリーミングは、実行を一時停止するハンドオフにも対応しています(たとえば、ツールに承認が必要な場合)。ストリームオブジェクトの interruptions フィールドには保留中の承認が格納されており、それぞれに対して state.approve() または state.reject() を呼び出すことで実行を続行できます。ストリームが一時停止すると、stream.completed が解決され、stream.interruptions に処理すべき承認が格納されます。{ stream: true } を指定して再実行すると、ストリーミング出力が再開されます。
import { Agent, run } from '@openai/agents';
const agent = new Agent({ name: 'Storyteller', instructions: 'You are a storyteller. You will be given a topic and you will tell a story about it.',});
let stream = await run( agent, 'What is the weather in San Francisco and Oakland?', { stream: true },);stream.toTextStream({ compatibleWithNodeStreams: true }).pipe(process.stdout);await stream.completed;
while (stream.interruptions?.length) { console.log( 'Human-in-the-loop: approval required for the following tool calls:', ); const state = stream.state; for (const interruption of stream.interruptions) { const approved = confirm( `Agent ${interruption.agent.name} would like to use the tool ${interruption.name} with "${interruption.arguments}". Do you approve?`, ); if (approved) { state.approve(interruption); } else { state.reject(interruption); } }
// Resume execution with streaming output stream = await run(agent, state, { stream: true }); const textStream = stream.toTextStream({ compatibleWithNodeStreams: true }); textStream.pipe(process.stdout); await stream.completed;}ユーザーとやり取りする、より詳しいコード例は human-in-the-loop-stream.ts にあります。
ストリームの停止と同じターンの続行
Section titled “ストリームの停止と同じターンの続行”ストリーミング実行を途中で停止するには、run() に渡した signal を中断するか、stream.toStream() から作成したリーダーをキャンセルします。どちらの場合も、実行が終了したと見なす前に、必ず stream.completed を await してください。コードがイベントの受信を停止した後も、SDK が現在のターンの入力を永続化したり、その他のクリーンアップを完了したりしている場合があります。
ストリームをキャンセルすると、stream.cancelled が true になり、現在のターンが完了していないため、stream.finalOutput は多くの場合 undefined のままです。その未完了のターンを後で続行したい場合は、新しいユーザーメッセージを追加するのではなく、stream.state を使って同じエージェントを再実行してください。これにより、ターン数のカウントが正しく保たれ、RunState にすでに保存されている conversationId や previousResponseId が再利用されます。
セッションの永続化も使用している場合は、再開時の run() 呼び出しで同じ session を再度渡し、会話が同じ保存先に引き続き書き込まれるようにしてください。
承認による一時停止にも同じルールが適用されます。stream.interruptions を解決してから、新しいターンを開始するのではなく、stream.state から再開してください。
- すべての出力がフラッシュされたことを確認するため、終了する前に必ず
stream.completedを待ってください。 - 最初の
{ stream: true }オプションは、それを指定した呼び出しにのみ適用されます。RunStateを使って再実行する場合は、このオプションを再度指定する必要があります。 - アプリケーションがテキストの実行結果だけを必要とする場合は、個々のイベントオブジェクトを処理せずに済むよう、
toTextStream()を優先して使用してください。
ストリーミングとイベントシステムを使うと、チャットインターフェイス、ターミナルアプリケーションなど、逐次更新がユーザーにとって役立つあらゆる場所にエージェントを組み込めます。