ストリーミング
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);
stream.completed
の Promise は、実行と保留中のコールバックがすべて完了したら解決されます。もう出力がないことを確実にする場合は、必ず待機してください。
すべてのイベントの監視
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); }}
ストリーミングの code examples を参照してください。プレーンなテキストストリームと 元 のイベントストリームの両方を出力する完全なスクリプトです。
イベントタイプ
Section titled “イベントタイプ”ストリームは 3 種類のイベントタイプを生成します:
raw_model_stream_event
Section titled “raw_model_stream_event”type RunRawModelStreamEvent = { type: 'raw_model_stream_event'; data: ResponseStreamEvent;};
例:
{ "type": "raw_model_stream_event", "data": { "type": "output_text_delta", "delta": "Hello" }}
run_item_stream_event
Section titled “run_item_stream_event”type RunItemStreamEvent = { type: 'run_item_stream_event'; name: RunItemStreamEventName; item: RunItem;};
ハンドオフのペイロード例:
{ "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”type RunAgentUpdatedStreamEvent = { type: 'agent_updated_stream_event'; agent: Agent<any, any>;};
例:
{ "type": "agent_updated_stream_event", "agent": { "name": "Refund Agent" }}
ストリーミング中の Human in the loop
Section titled “ストリーミング中の Human in the loop”ストリーミングは、実行を一時停止するハンドオフ(たとえばツールに承認が必要な場合)と両立します。ストリームオブジェクトの interruption
フィールドで割り込みを取得でき、各割り込みに対して state.approve()
または state.reject()
を呼び出すことで実行を継続できます。{ 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.rawItem.name} with "${interruption.rawItem.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
です。
- すべての出力がフラッシュされることを確実にするため、終了前に
stream.completed
を待機することを忘れないでください - 最初の
{ stream: true }
オプションは、それを指定した呼び出しにのみ適用されます。RunState
で再実行する場合は、再度オプションを指定する必要があります - アプリケーションがテキストの結果のみに関心がある場合は、個々のイベントオブジェクトを扱わなくて済むように
toTextStream()
を使用することを推奨します
ストリーミングとイベントシステムを使えば、エージェント をチャットインターフェース、ターミナルアプリケーション、または段階的な更新が ユーザー の役に立つあらゆる場所に統合できます。