콘텐츠로 이동

스트리밍

Agents SDK는 모델과 기타 실행 단계의 출력을 점진적으로 전달할 수 있습니다. 스트리밍은 UI를 반응적으로 유지하고, 전체 최종 결과를 기다리지 않고 사용자 업데이트를 가능하게 합니다.

Runner.run(){ stream: true } 옵션을 전달하면 전체 결과 대신 스트리밍 객체를 얻습니다:

Enabling streaming
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,
});

스트리밍이 활성화되면 반환된 streamAsyncIterable 인터페이스를 구현합니다. 각 전달된 이벤트는 실행 내에서 발생한 일을 설명하는 객체입니다. 스트림은 에이전트 실행의 서로 다른 부분을 설명하는 세 가지 이벤트 타입 중 하나를 전달합니다. 대부분의 애플리케이션은 모델의 텍스트만 원하므로, 스트림은 이를 위한 도우미를 제공합니다.

발생한 텍스트의 스트림을 얻으려면 stream.toTextStream()을 호출하세요. compatibleWithNodeStreamstrue이면 반환값은 일반 Node.js Readable입니다. process.stdout 또는 다른 대상을 향해 직접 파이프할 수 있습니다.

Logging out the text as it arrives
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 프라미스는 실행과 보류 중인 모든 콜백이 완료되면 resolve됩니다. 더 이상 출력이 없음을 보장하려면 항상 이를 기다리세요.

for await 루프를 사용해 도착하는 각 이벤트를 검사할 수 있습니다. 유용한 정보에는 로우 레벨 모델 이벤트, 에이전트 전환, 그리고 SDK 고유의 실행 정보가 포함됩니다:

Listening to all events
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);
}
}

스트리밍 예제를 참고하면 일반 텍스트 스트림과 원문 이벤트 스트림을 모두 출력하는 완성된 스크립트를 볼 수 있습니다.

스트림은 세 가지 서로 다른 이벤트 타입을 전달합니다:

type RunRawModelStreamEvent = {
type: 'raw_model_stream_event';
data: ResponseStreamEvent;
};

예시:

{
"type": "raw_model_stream_event",
"data": {
"type": "output_text_delta",
"delta": "Hello"
}
}
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"
}
}
type RunAgentUpdatedStreamEvent = {
type: 'agent_updated_stream_event';
agent: Agent<any, any>;
};

예시:

{
"type": "agent_updated_stream_event",
"agent": {
"name": "Refund Agent"
}
}

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

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

스트리밍은 실행을 일시 중지하는 핸드오프(예: 도구 승인 필요)와 호환됩니다. 스트림 객체의 interruption 필드는 인터럽션(중단 처리)을 노출하며, 각 인터럽션에 대해 state.approve() 또는 state.reject()를 호출하여 실행을 계속할 수 있습니다. { stream: true }로 다시 실행하면 스트리밍 출력이 재개됩니다.

Handling human approval while streaming
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()을 사용하는 것이 좋습니다

스트리밍과 이벤트 시스템을 통해 에이전트를 채팅 인터페이스, 터미널 애플리케이션, 또는 점진적 업데이트가 유용한 모든 곳에 통합할 수 있습니다.