콘텐츠로 이동

스트리밍

Agents SDK는 모델과 다른 실행 단계의 출력을 점진적으로 전달할 수 있습니다. 스트리밍을 사용하면 UI의 응답성을 유지하고, 전체 최종 결과가 나올 때까지 기다리지 않고도 사용자에게 업데이트를 제공할 수 있습니다.

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 인터페이스를 구현합니다. 각 이벤트는 실행 중 발생한 일을 설명하는 객체입니다. 스트림은 세 가지 이벤트 유형 중 하나를 내보내며, 각 유형은 에이전트 실행의 서로 다른 부분을 설명합니다. 다만 대부분의 애플리케이션은 모델의 텍스트만 필요하므로, 스트림은 이를 위한 헬퍼를 제공합니다.

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 프로미스는 실행과 대기 중인 모든 콜백이 완료되면 이행됩니다. 더 이상 출력이 없음을 확인하려면 항상 이를 기다리세요. 여기에는 마지막 텍스트 토큰이 도착한 후 완료되는 세션 영속화나 히스토리 압축 훅 같은 후처리 작업도 포함됩니다.

toTextStream()은 어시스턴트 텍스트만 내보냅니다. 도구 호출, 핸드오프, 승인 및 기타 런타임 이벤트는 전체 이벤트 스트림에서 확인할 수 있습니다.

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 전송 방식(선택 사항)

섹션 제목: “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를 참고하세요.

스트림은 세 가지 유형의 이벤트를 내보냅니다:

RunRawModelStreamEvent
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 페이로드의 타입을 좁힐 수 있는 헬퍼를 내보냅니다.

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는 타입을 좁히는 헬퍼도 내보냅니다:

  • Responses 원문 이벤트용 isOpenAIResponsesRawModelStreamEvent(event)
  • Chat Completions 청크용 isOpenAIChatCompletionsRawModelStreamEvent(event)

이러한 OpenAI 모델 이벤트에서는 RunRawModelStreamEvent.source도 'openai-responses' 또는 'openai-chat-completions'로 설정됩니다.

이는 TypeScript가 기반 이벤트 구조를 인식하도록 유지하면서 response.reasoning_summary_text.delta, response.output_item.done 또는 MCP 인수 델타와 같은 Responses 전용 이벤트를 확인하려는 경우에 특히 유용합니다.

더 상세한 OpenAI 전용 스트리밍 패턴은 examples/basic/stream-ws.ts, examples/tools/code-interpreter.ts, examples/connectors/index.ts를 참고하세요.

RunItemStreamEvent
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_calledtool_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"
}
}
RunAgentUpdatedStreamEvent
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"
}
}

스트리밍 중 휴먼 인 더 루프 (HITL)

섹션 제목: “스트리밍 중 휴먼 인 더 루프 (HITL)”

스트리밍은 실행을 일시 중지하는 핸드오프와도 호환됩니다(예: 도구에 승인이 필요한 경우). 스트림 객체의 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입니다.

스트림 중지 및 동일 턴 계속 실행

섹션 제목: “스트림 중지 및 동일 턴 계속 실행”

스트리밍 실행을 조기에 중지하려면 run()에 전달한 signal을 중단하거나 stream.toStream()으로 생성한 리더를 취소하세요. 어느 방법을 사용하든 실행이 완전히 정리된 것으로 간주하기 전에 stream.completed를 기다려야 합니다. 코드에서 이벤트 소비를 중지한 후에도 SDK는 현재 턴의 입력을 영속화하거나 다른 정리 작업을 마무리하고 있을 수 있습니다.

스트림이 취소되면 stream.cancelled가 true가 되며, 현재 턴이 완료되지 않았기 때문에 stream.finalOutput은 undefined로 남는 경우가 많습니다. 나중에 완료되지 않은 턴을 계속 실행하려면 새 사용자 메시지를 추가하는 대신 stream.state로 동일한 에이전트를 다시 실행하세요. 이렇게 하면 턴 수를 올바르게 유지하고 RunState에 이미 저장된 conversationId 또는 previousResponseId를 재사용할 수 있습니다.

세션 영속화도 사용 중이라면, 재개하는 run() 호출에 동일한 session을 다시 전달하여 대화가 동일한 저장소에 계속 기록되도록 하세요.

승인을 위한 일시 중지에도 같은 규칙이 적용됩니다. stream.interruptions를 처리한 다음 새 턴을 시작하는 대신 stream.state에서 재개하세요.

  • 모든 출력이 완전히 전달되도록 종료 전에 반드시 stream.completed를 기다리세요.
  • 최초의 { stream: true } 옵션은 해당 옵션을 전달한 호출에만 적용됩니다. RunState로 다시 실행하는 경우에는 이 옵션을 다시 지정해야 합니다.
  • 애플리케이션에 텍스트 결과만 필요하다면 개별 이벤트 객체를 처리하지 않아도 되는 toTextStream()을 사용하는 것이 좋습니다.

스트리밍과 이벤트 시스템을 사용하면 채팅 인터페이스, 터미널 애플리케이션 등 점진적 업데이트가 사용자에게 유용한 모든 환경에 에이전트를 통합할 수 있습니다.