실행 결과

에이전트 실행을 수행하면 다음 중 하나를 받습니다.

stream: true 없이 run을 호출한 경우 RunResult
stream: true로 run을 호출한 경우 StreamedRunResult. 스트리밍에 관한 자세한 내용은 스트리밍도 참조하세요.

두 결과 타입 모두 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 스키마가 정의된 경우. 출력은 이 스키마에 따라 자동으로 파싱됩니다.
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
추론 항목을 위한 RunReasoningItem
Responses 도구 검색 요청과 이 요청이 반환하는 로드된 도구 정의를 위한 RunToolSearchCallItem 및 RunToolSearchOutputItem
도구 호출과 그 결과를 위한 RunToolCallItem 및 RunToolCallOutputItem
승인을 기다리며 일시 중지된 도구 호출을 위한 RunToolApprovalItem
핸드오프 요청과 완료된 전환을 위한 RunHandoffCallItem 및 RunHandoffOutputItem

어떤 에이전트가 항목을 생성했는지 또는 항목이 도구, 도구 검색, 핸드오프, 승인 경계 중 하나를 나타내는지 알아야 할 때는 항상 output보다 newItems를 선택하세요. toolSearchTool()을 사용하는 경우 이러한 도구 검색 항목을 통해 일반 도구 호출이 발생하기 전에 어떤 지연된 도구나 네임스페이스가 로드되었는지 가장 쉽게 확인할 수 있습니다.

로컬 도구 또는 MCP 서버가 customDataExtractor를 정의하는 경우 해당 RunToolCallOutputItem.customData에는 반환된 SDK 전용 메타데이터가 포함됩니다. 이 데이터는 렌더러 힌트나 내부 ID와 같은 애플리케이션 UI 상태에 유용합니다. 이 데이터는 RunState 직렬화 후에도 유지되지만 history에서는 제외되며 모델로 다시 전송되지 않습니다.

대화의 계속 또는 재개

활성 에이전트

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은 다음을 제공합니다.

toolName
toolCallId
toolArguments

중첩 에이전트 도구 실행에 전달된 구조화된 입력도 필요한 경우 result.runContext.toolInput과 함께 사용하세요.

일반적인 최상위 run() 결과에서는 대개 undefined입니다. 이 메타데이터는 런타임 전용이며 RunState로 직렬화되지 않습니다. 관련 패턴은 Agents as tools를 참조하세요.

스트리밍 결과

StreamedRunResult는 위와 동일한 결과 인터페이스를 상속하지만 스트리밍 전용 제어 기능을 추가합니다.

어시스턴트 텍스트만 가져오는 toTextStream()
전체 이벤트 스트림을 가져오는 toStream() 또는 for await ... of stream
실행과 모든 후처리 콜백이 끝날 때까지 기다리는 completed
최종 스트리밍 상태를 확인하는 error 및 cancelled
실행 도중 활성 에이전트를 추적하는 currentAgent

스트리밍 실행의 확정된 최종 상태가 필요하다면 finalOutput, history, interruptions 또는 기타 요약 속성을 읽기 전에 completed를 기다리세요. 이벤트별 처리 방법은 스트리밍을 참조하세요.

스트리밍 실행이 취소되면 정리 작업 후에도 completed는 정상적으로 완료되고 cancelled는 true가 되지만, 현재 턴이 완료되지 않았으므로 finalOutput과 같은 턴 종료 필드는 설정되지 않은 상태로 남을 수 있습니다. 새 사용자 메시지를 추가하는 대신 result.state와 동일한 session을 사용 중이라면 해당 세션을 함께 사용하여 완료되지 않은 턴을 재개하세요.

진단 및 고급 필드

실행 컨텍스트

runContext 속성은 결과에서 실행 컨텍스트를 확인할 수 있도록 공식적으로 지원되는 공개 뷰입니다. result.runContext.context는 앱 컨텍스트이며, 같은 객체에는 승인, 사용량, 중첩된 toolInput과 같이 SDK가 관리하는 런타임 메타데이터도 포함됩니다. 전체 구조는 컨텍스트 관리를 참조하세요.

원문 응답

rawResponses에는 실행 중 수집된 원문 모델 응답이 포함됩니다. 핸드오프 또는 반복되는 도구/모델 주기 등으로 인해 여러 단계로 이루어진 실행에서 둘 이상의 응답이 생성될 수 있습니다.

가드레일 결과

inputGuardrailResults 및 outputGuardrailResults 속성에는 에이전트 수준의 가드레일 결과가 포함됩니다. 도구 가드레일 결과는 toolInputGuardrailResults 및 toolOutputGuardrailResults를 통해 별도로 제공됩니다.

가드레일 결정을 기록하거나, 가드레일 함수가 반환한 추가 메타데이터를 확인하거나, 실행이 차단된 이유를 디버깅하려면 이러한 배열을 사용하세요.

가드레일 하나가 실행에 실패하더라도 성공적으로 완료된 다른 가드레일의 결과는 실행 상태에 유지됩니다. 스트리밍 실행에서는 completed가 거부된 후 결과 배열을 확인하세요. 비스트리밍 실행에서는 GuardrailExecutionError에 동일하게 확정된 state가 포함됩니다.

사용량

토큰 사용량은 result.state.usage에 집계되며, 실행의 요청 수와 전체 토큰 수를 추적합니다. 동일한 사용량 객체는 result.runContext.usage에서도 확인할 수 있습니다. 스트리밍 실행에서는 응답이 도착할 때마다 이 데이터가 업데이트됩니다.

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