실행 결과
에이전트 실행 시 다음 중 하나를 받습니다:
RunResult:stream: true없이run을 호출한 경우StreamedRunResult:stream: true로run을 호출한 경우. 스트리밍에 관한 자세한 내용은 스트리밍 가이드도 참고하세요.
두 결과 타입은 모두 finalOutput, newItems, interruptions, state와 같은 동일한 핵심 결과 속성을 제공합니다. StreamedRunResult는 completed, toStream(), toTextStream(), currentAgent와 같은 스트리밍 제어 기능을 추가로 제공합니다.
적절한 결과 속성 선택
섹션 제목: “적절한 결과 속성 선택”대부분의 애플리케이션에는 몇 가지 속성만 필요합니다:
| 필요한 항목 | 사용할 속성 |
|---|---|
| 사용자에게 보여줄 최종 답변 | finalOutput |
| 전체 로컬 대화 기록을 포함하며 재생에 바로 사용할 수 있는 다음 턴 입력 | history |
| 이번 실행에서 새로 생성된 모델 형식의 항목만 | output |
| 에이전트/도구/핸드오프 메타데이터가 포함된 상세 실행 항목 | newItems |
| 일반적으로 다음 사용자 턴을 처리할 에이전트 | lastAgent 또는 activeAgent |
previousResponseId를 사용한 OpenAI Responses API 연결 | lastResponseId |
| 대기 중인 승인과 재개 가능한 스냅샷 | interruptions 및 state |
| 앱 컨텍스트, 승인, 사용량, 중첩된 에이전트 도구 입력 | runContext |
현재 중첩된 Agent.asTool() 호출에 관한 메타데이터(예: customOutputExtractor 내부에서 사용) | agentToolInvocation |
| 모델 호출 원문 또는 가드레일 진단 정보 | rawResponses 및 가드레일 결과 배열 |
최종 출력
섹션 제목: “최종 출력”finalOutput 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 이 결과는 다음 중 하나입니다:
string—outputType이 정의되지 않은 모든 에이전트의 기본값unknown— 에이전트의 출력 타입이 JSON 스키마로 정의된 경우입니다. 이 경우 JSON은 파싱되지만 타입은 여전히 직접 검증해야 합니다.z.infer<outputType>— 에이전트의 출력 타입이 Zod 스키마로 정의된 경우입니다. 출력은 이 스키마에 따라 자동으로 파싱됩니다.- 추론된 검증 출력 타입 — 에이전트의 출력 타입으로 지원되는 Standard Schema 값이 정의된 경우입니다. 출력은 이 스키마에 따라 동기적으로 파싱되고 검증됩니다.
undefined— 에이전트가 출력을 생성하지 않은 경우(예: 출력을 생성하기 전에 중지된 경우)
스트리밍 실행이 아직 진행 중이거나 최종 출력에 도달하기 전에 승인 인터럽션(중단 처리)으로 실행이 일시 중지된 경우에도 finalOutput은 undefined입니다.
출력 타입이 서로 다른 핸드오프를 사용하는 경우, 에이전트를 생성할 때 new Agent() 생성자 대신 Agent.create() 메서드를 사용해야 합니다.
이렇게 하면 SDK가 가능한 모든 핸드오프의 출력 타입을 추론하고 finalOutput 속성에 대한 유니온 타입을 제공할 수 있습니다.
예를 들면 다음과 같습니다:
import { Agent, run } from '@openai/agents';import { z } from 'zod';
const refundAgent = new Agent({ name: 'Refund Agent', instructions: 'You are a refund agent. You are responsible for refunding customers.', outputType: z.object({ refundApproved: z.boolean(), }),});
const orderAgent = new Agent({ name: 'Order Agent', instructions: 'You are an order agent. You are responsible for processing orders.', outputType: z.object({ orderId: z.string(), }),});
const triageAgent = Agent.create({ name: 'Triage Agent', instructions: 'You are a triage agent. You are responsible for triaging customer issues.', handoffs: [refundAgent, orderAgent],});
const result = await run(triageAgent, 'I need to a refund for my order');
const output = result.finalOutput;// ^? { refundApproved: boolean } | { orderId: string } | string | undefined입력 및 출력 속성
섹션 제목: “입력 및 출력 속성”각 속성은 서로 다른 정보를 제공합니다:
| 속성 | 포함된 내용 | 적합한 용도 |
|---|---|---|
input | 이번 실행의 기본 입력입니다. 핸드오프 입력 필터가 기록을 다시 작성했다면, 실행을 이어갈 때 사용한 필터링된 입력이 반영됩니다. | 이번 실행에서 실제로 사용한 입력 감사 |
output | 에이전트 메타데이터 없이 이번 실행에서 생성된 모델 형식의 항목만 포함합니다. | 모델의 새 출력분만 저장하거나 재생 |
newItems | 에이전트/도구/핸드오프 메타데이터가 포함된 상세 RunItem 래퍼입니다. | 로그, UI, 감사, 디버깅 |
history | input + newItems로 구성되며 재생에 바로 사용할 수 있는 다음 턴 입력입니다. | 수동 채팅 루프 및 클라이언트에서 관리하는 대화 상태 |
실제로는 다음과 같이 사용합니다:
- 애플리케이션에서 전체 대화를 직접 유지하는 경우
history를 사용합니다. - 이전 기록을 이미 다른 곳에 저장하고 있으며 이번 실행에서 새로 생성된 항목만 필요한 경우
output을 사용합니다. - 에이전트 연결 정보, 도구 출력, 핸드오프 경계 또는 승인 항목이 필요한 경우
newItems를 사용합니다. conversationId또는previousResponseId를 사용하는 경우, 일반적으로history를run()에 다시 전달하지 않습니다. 대신 새 사용자 입력만 전달하고 서버에서 관리하는 ID를 재사용합니다. 전체 비교 내용은 에이전트 실행을 참고하세요.
history는 채팅과 같은 사용 사례에서 전체 기록을 유지하는 편리한 방법입니다:
import { Agent, user, run } from '@openai/agents';import type { AgentInputItem } from '@openai/agents';
const agent = new Agent({ name: 'Assistant', instructions: 'You are a helpful assistant knowledgeable about recent AGI research.',});
let history: AgentInputItem[] = [ // initial message user('Are we there yet?'),];
for (let i = 0; i < 10; i++) { // run 10 times const result = await run(agent, history);
// update the history to the new output history = result.history;
history.push(user('How about now?'));}새 항목
섹션 제목: “새 항목”newItems는 실행 중에 일어난 일을 가장 상세하게 보여줍니다. 일반적인 항목 타입은 다음과 같습니다:
- 어시스턴트 메시지를 위한
RunMessageOutputItem - 실행을 재개하는 동안
RunState.pendingInput에서 받아들인 입력을 위한RunInputItem - 추론 항목을 위한
RunReasoningItem - Responses 도구 검색 요청과 해당 요청이 반환하는 로드된 도구 정의를 위한
RunToolSearchCallItem및RunToolSearchOutputItem - 도구 호출과 그 결과를 위한
RunToolCallItem및RunToolCallOutputItem - 승인을 기다리며 일시 중지된 도구 호출을 위한
RunToolApprovalItem - 핸드오프 요청과 완료된 제어 이전을 위한
RunHandoffCallItem및RunHandoffOutputItem
어떤 에이전트가 항목을 생성했는지, 또는 해당 항목이 도구, 도구 검색, 핸드오프, 승인의 경계를 나타내는지 알아야 하는 경우에는 output 대신 newItems를 선택하세요. toolSearchTool()을 사용할 때 이러한 도구 검색 항목을 살펴보면 일반 도구 호출 전에 어떤 지연 로딩 도구나 네임스페이스가 로드되었는지 가장 쉽게 확인할 수 있습니다.
로컬 도구 또는 MCP 서버가 customDataExtractor를 정의한 경우, 해당 RunToolCallOutputItem.customData에는 반환된 SDK 전용 메타데이터가 포함됩니다. 이 데이터는 렌더러 힌트나 내부 ID와 같은 애플리케이션 UI 상태에 유용합니다. RunState 직렬화 후에도 유지되지만, history에서는 제외되며 모델로 다시 전송되지 않습니다.
RunToolCallOutputItem.output은 SDK 측 도구 반환값입니다. JSON과 호환되는 원시 값, 배열, 일반 객체는 RunState 직렬화 후에도 구조가 유지됩니다. 그 밖의 런타임 값에는 기존 문자열 폴백이 유지됩니다. 이 래퍼 값은 history와 재생에 사용되는 모델 공개용 도구 출력인 rawItem.output과 별도로 유지됩니다.
대화 지속 또는 재개
섹션 제목: “대화 지속 또는 재개”활성 에이전트
섹션 제목: “활성 에이전트”lastAgent 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 핸드오프 이후 다음 사용자 턴에 재사용하기에 가장 적합한 에이전트인 경우가 많습니다. activeAgent는 같은 값의 별칭입니다.
스트리밍 모드에서 currentAgent는 실행이 진행 중일 때 현재 활성 상태인 에이전트를 알려줍니다.
인터럽션(중단 처리) 및 재개 가능한 상태
섹션 제목: “인터럽션(중단 처리) 및 재개 가능한 상태”도구에 승인이 필요한 경우 실행이 일시 중지되며, interruptions에는 대기 중인 RunToolApprovalItem 항목이 포함됩니다. 여기에는 직접 호출한 도구, 핸드오프 후 도달한 도구, 중첩된 agent.asTool() 실행에서 발생한 승인 요청이 포함될 수 있습니다.
result.state.approve(...) / result.state.reject(...)로 승인 요청을 처리한 다음, 동일한 state를 run()에 다시 전달하여 실행을 재개합니다. 모든 인터럽션(중단 처리)을 한 번에 처리할 필요는 없습니다. 일부 항목만 처리한 후 다시 실행하면 처리된 호출은 계속 진행할 수 있지만, 처리되지 않은 호출은 대기 상태로 남아 실행을 다시 일시 중지합니다.
state 속성은 결과의 기반이 되는 직렬화 가능한 스냅샷입니다. 휴먼 인 더 루프 (HITL), 재시도 흐름 또는 일시 중지된 실행을 나중에 재개해야 하는 모든 경우에 사용하세요.
서버에서 관리하는 대화 지속
섹션 제목: “서버에서 관리하는 대화 지속”lastResponseId는 OpenAI Responses API 연결을 사용할 때 다음 턴의 previousResponseId로 전달할 값입니다.
이미 history, session 또는 conversationId로 대화를 이어가고 있다면 일반적으로 lastResponseId는 필요하지 않습니다. 여러 단계로 이루어진 실행의 모든 모델 응답 원문이 필요하다면 대신 rawResponses를 확인하세요.
중첩된 에이전트 도구 메타데이터
섹션 제목: “중첩된 에이전트 도구 메타데이터”agentToolInvocation은 중첩된 Agent.asTool() 결과를 위한 속성으로, 특히 customOutputExtractor 내부에서 현재 도구 호출의 메타데이터가 필요할 때 사용합니다. 일반적인 “전체 실행 완료” 요약 필드는 아닙니다.
이러한 중첩 컨텍스트에서 agentToolInvocation은 다음을 제공합니다:
toolNametoolCallIdtoolArguments
중첩된 에이전트 도구 실행에 전달된 구조화된 입력도 필요하다면 result.runContext.toolInput과 함께 사용하세요.
일반적인 최상위 run() 결과에서 이 값은 대개 undefined입니다. 이 메타데이터는 런타임 전용이며 RunState에 직렬화되지 않습니다. 관련 패턴은 Agents as tools를 참고하세요.
스트리밍 실행 결과
섹션 제목: “스트리밍 실행 결과”StreamedRunResult는 위와 동일한 결과 속성을 상속하며, 스트리밍 전용 제어 기능을 추가로 제공합니다:
- 어시스턴트 텍스트만 제공하는
toTextStream() - 전체 이벤트 스트림을 제공하는
toStream()또는for await ... of stream - 실행과 모든 후처리 콜백이 끝날 때까지 기다리는
completed - 스트리밍의 종료 상태를 확인하는
error및cancelled - 실행 중 활성 에이전트를 추적하는
currentAgent - 실제로 요청 경계에 도달한 모델 턴 수를 확인하는
currentTurn - 이번 스트리밍 실행에 적용된 제한을 확인하는
maxTurns(null은 제한 없음을 의미)
currentTurn은 모델 요청이 허용될 때만 증가합니다. 최대 턴 수 검사나 차단 입력 가드레일이 요청을 막으면 증가하지 않으며, 재개된 실행은 RunState에 보존된 횟수에서 시작합니다.
스트리밍 실행의 확정된 최종 상태가 필요하다면 completed를 기다린 후 finalOutput, history, interruptions 또는 기타 요약 속성을 읽으세요. 이벤트별 처리에 대해서는 스트리밍 가이드를 참고하세요.
스트리밍 실행이 취소되어도 정리 작업 후 completed는 정상적으로 이행되고 cancelled는 true가 됩니다. 다만 현재 턴이 끝나지 않았으므로 finalOutput과 같은 턴 종료 필드는 설정되지 않은 상태로 남을 수 있습니다. 새 사용자 메시지를 추가하는 대신 result.state(세션을 사용한다면 동일한 session도 함께)로 완료되지 않은 턴을 재개하세요.
진단 및 고급 필드
섹션 제목: “진단 및 고급 필드”실행 컨텍스트
섹션 제목: “실행 컨텍스트”runContext 속성은 결과에서 실행 컨텍스트에 접근할 수 있도록 지원되는 공개 인터페이스입니다. result.runContext.context는 앱 컨텍스트이며, 같은 객체에 승인, 사용량, 중첩된 toolInput과 같이 SDK가 관리하는 런타임 메타데이터도 포함됩니다. 전체 구조는 컨텍스트 관리를 참고하세요.
응답 원문
섹션 제목: “응답 원문”rawResponses에는 실행 중 수집된 모델 응답 원문이 포함됩니다. 여러 단계로 이루어진 실행에서는 핸드오프나 반복되는 도구/모델 사이클 등을 거치며 둘 이상의 응답이 생성될 수 있습니다.
출력 가드레일이 실행을 종료하는 함수 도구 결과를 거부하면, SDK는 SDK가 관리하는 다른 재생용 데이터와 함께 rawResponses의 현재 응답을 정제합니다. 거부된 종료 도구 출력을 이 속성에서 계속 확인할 수 있다고 가정하지 마세요. 삭제 범위와 제한 사항은 거부된 종료 도구 출력을 참고하세요.
각 응답에는 제공자가 요청 식별자를 제공하는 경우 해당 식별자인 requestId도 포함될 수 있습니다. OpenAI Responses 및 Chat Completions 모델은 스트리밍 및 비스트리밍 HTTP 요청에 이 값을 채웁니다. 일부 제공자와 전송 방식은 이를 노출하지 않으므로 선택적 값으로 취급하세요.
Chat Completions 텍스트 출력의 URL 인용을 읽으려면 정규화된 output_text 파트의 providerData.annotations를 확인하세요. 비스트리밍 응답은 제공자의 메시지 어노테이션을 보존합니다. 스트리밍 응답은 텍스트와 함께 수신한 유효한 url_citation 어노테이션을 유지하고, 반복되는 인용의 중복을 제거하며, 형식이 잘못되었거나 지원되지 않는 어노테이션 구조는 무시합니다.
Chat Completions 오디오의 경우, 정규화된 모델 응답은 오디오 전용 어시스턴트 메시지를 audio 콘텐츠 파트로 표현합니다. 해당 메시지가 실행 항목이 되면 RunMessageOutputItem.rawItem에서 같은 파트를 확인하세요. 비스트리밍 응답에 오디오와 함께 텍스트나 거부 응답이 포함되어 있으면, 정규화된 어시스턴트 메시지는 텍스트나 거부 응답을 유지하고 제공자의 전체 응답은 rawResponses[].providerData에서 확인할 수 있습니다. 스트리밍 혼합 출력에서 제공자의 오디오 청크를 도착하는 대로 확인해야 한다면 모델 스트림 이벤트 원문을 살펴보세요. 완료된 rawResponses 항목에는 정규화된 텍스트나 거부 응답이 포함되지만 재구성된 오디오는 포함되지 않습니다. 스트리밍 toTextStream() 헬퍼는 텍스트만 내보냅니다.
modelSettings.preserveRawUsage가 true이면, 각 완료된 응답에 SDK 정규화 전에 캡처한 독립적인 JSON 호환 스냅샷인 rawUsage도 노출될 수 있습니다. 정규화된 Usage는 계속 response.usage로 사용할 수 있습니다. rawUsage는 제공자별 필드 이름을 보존하며, 제공된 데이터에서 값이 생략되었는지 명시되었는지도 구분하여 유지합니다. 제공자가 사용량을 생략하거나 페이로드를 안전하게 복사할 수 없는 경우에는 undefined일 수 있습니다. rawUsage는 런타임 전용이며 직렬화된 RunState에서는 의도적으로 제외되므로, 실행을 저장하고 재개하기 전에 필요한 필드를 복사하세요.
가드레일 결과
섹션 제목: “가드레일 결과”inputGuardrailResults 및 outputGuardrailResults 속성에는 에이전트 수준의 가드레일 결과가 포함됩니다. 도구 가드레일 결과는 toolInputGuardrailResults 및 toolOutputGuardrailResults를 통해 별도로 제공됩니다.
가드레일의 결정을 기록하거나, 가드레일 함수가 반환한 추가 메타데이터를 확인하거나, 실행이 차단된 이유를 디버깅할 때 이 배열을 사용하세요.
실행을 종료하는 함수 도구 결과가 거부되면, SDK는 현재 응답의 가드레일 메타데이터를 의도적으로 정제합니다. outputGuardrailResults에서 agentOutput은 Output withheld by an output guardrail.로 바뀌고 outputInfo는 제거됩니다. 현재 toolOutputGuardrailResults는 판정 결과를 유지하지만 outputInfo는 생략하며, rejectContent 결과는 메시지로 같은 자리표시자를 사용합니다. 이전에 허용된 과거 결과는 변경되지 않습니다.
가드레일 하나가 실행에 실패하더라도 성공적으로 완료된 다른 가드레일의 결과는 실행 상태에 남습니다. 스트리밍 실행에서는 completed가 거부된 후 결과 배열을 확인하세요. 비스트리밍 실행에서는 GuardrailExecutionError에 동일하게 확정된 state가 포함됩니다.
사용량
섹션 제목: “사용량”토큰 사용량은 실행의 요청 수와 토큰 총량을 추적하는 result.state.usage에 집계됩니다. 같은 사용량 객체를 result.runContext.usage로도 사용할 수 있습니다. 스트리밍 실행에서는 응답이 도착할 때마다 이 데이터가 갱신됩니다.
완료된 스트리밍 또는 비스트리밍 Chat Completions 호출은 제공자가 사용량 객체를 생략하더라도 요청 한 건으로 계산됩니다. 이 경우 제공자가 토큰 수를 보고하지 않았으므로 토큰 총량은 0으로 유지됩니다.
import { Agent, run } from '@openai/agents';
const agent = new Agent({ name: 'Usage Tracker', instructions: 'Summarize the latest project update in one sentence.',});
const result = await run( agent, 'Summarize this: key customer feedback themes and the next product iteration.',);
const usage = result.state.usage;console.log({ requests: usage.requests, inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, totalTokens: usage.totalTokens,});
if (usage.requestUsageEntries) { for (const entry of usage.requestUsageEntries) { console.log('request', { endpoint: entry.endpoint, inputTokens: entry.inputTokens, outputTokens: entry.outputTokens, totalTokens: entry.totalTokens, }); }}