실행 결과

에이전트를 실행하면 다음 중 하나를 받게 됩니다.

• stream: true 없이 run을 호출하면 RunResult
• stream: true와 함께 run을 호출하면 StreamedRunResult. 스트리밍에 대한 자세한 내용은 스트리밍 가이드도 확인하세요.

두 결과 타입 모두 finalOutput, newItems, interruptions, state 같은 동일한 핵심 결과 인터페이스를 제공합니다. StreamedRunResult는 여기에 completed, toStream(), toTextStream(), currentAgent 같은 스트리밍 제어 기능을 추가합니다.

적절한 결과 인터페이스 선택

대부분의 애플리케이션에는 몇 가지 속성만 있으면 충분합니다.

다음이 필요하다면…	사용
사용자에게 보여줄 최종 답변	finalOutput
전체 로컬 transcript가 포함된 재생 가능한 다음 턴 입력	history
이번 실행에서 새로 생성된 모델 형태의 항목만	output
에이전트/도구/핸드오프 메타데이터가 포함된 풍부한 실행 항목	newItems
일반적으로 다음 사용자 턴을 처리해야 하는 에이전트	lastAgent 또는 activeAgent
OpenAI Responses API chaining에서의 previousResponseId	lastResponseId
대기 중인 승인과 재개 가능한 스냅샷	interruptions 및 state
앱 컨텍스트, 승인, 사용량, 중첩된 agent-tool 입력	runContext
현재 중첩된 Agent.asTool() 호출에 대한 메타데이터(예: customOutputExtractor 내부)	agentToolInvocation
원문 모델 호출 또는 가드레일 진단 정보	rawResponses 및 가드레일 결과 배열

최종 출력

finalOutput 속성에는 마지막으로 실행된 에이전트의 최종 출력이 들어 있습니다. 이 결과는 다음 중 하나입니다.

• string — outputType이 정의되지 않은 모든 에이전트의 기본값
• unknown — 에이전트의 출력 타입으로 JSON schema가 정의된 경우. 이 경우 JSON은 파싱되지만 타입은 여전히 직접 검증해야 합니다.
• z.infer<outputType> — 에이전트의 출력 타입으로 Zod schema가 정의된 경우. 출력은 이 schema에 따라 자동으로 파싱됩니다.
• undefined — 에이전트가 출력을 생성하지 않은 경우(예: 출력을 생성하기 전에 중단된 경우)

스트리밍 실행이 아직 진행 중이거나, 최종 출력에 도달하기 전에 실행이 승인 인터럽션(중단 처리)에서 일시 중지된 경우에도 finalOutput은 undefined입니다.

서로 다른 출력 타입을 가진 핸드오프를 사용 중이라면, 에이전트를 만들 때 new Agent() 생성자 대신 Agent.create() 메서드를 사용해야 합니다.

이렇게 하면 SDK가 가능한 모든 핸드오프 전반에서 출력 타입을 추론하고, finalOutput 속성에 대해 union type을 제공할 수 있습니다.

예를 들면 다음과 같습니다.

핸드오프 최종 출력 타입

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	이번 실행의 기본 입력입니다. 핸드오프 입력 필터가 history를 다시 썼다면, 이는 실행이 이어서 사용한 필터링된 입력을 반영합니다.	이번 실행이 실제로 입력으로 사용한 내용을 감사할 때
output	에이전트 메타데이터 없이, 이번 실행에서 생성된 모델 형태의 항목만	새로 생성된 모델 delta만 저장하거나 재생할 때
newItems	에이전트/도구/핸드오프 메타데이터가 포함된 풍부한 RunItem 래퍼	로그, UI, 감사, 디버깅
history	input + newItems로 구성된 재생 가능한 다음 턴 입력	수동 채팅 루프 및 클라이언트 관리 대화 상태

실제로는 다음과 같습니다.

• 애플리케이션에서 전체 대화를 수동으로 유지하고 있다면 history를 사용하세요.
• 이전 history를 이미 다른 곳에 저장하고 있고, 이번 실행에서 새로 생성된 항목만 원한다면 output을 사용하세요.
• 에이전트 연결, 도구 출력, 핸드오프 경계, 승인 항목이 필요하다면 newItems를 사용하세요.
• conversationId 또는 previousResponseId를 사용 중이라면, 일반적으로 history를 다시 run()에 전달하지 않습니다. 대신 새 사용자 입력만 전달하고 서버가 관리하는 ID를 재사용합니다. 전체 비교는 에이전트 실행을 참고하세요.

history는 채팅과 유사한 사용 사례에서 전체 history를 유지하는 편리한 방법입니다.

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는 실행 중 어떤 일이 일어났는지 가장 풍부하게 보여줍니다. 일반적인 항목 타입은 다음과 같습니다.

• assistant 메시지용 RunMessageOutputItem
• reasoning 항목용 RunReasoningItem
• Responses 도구 검색 요청 및 그 결과로 반환된 로드된 도구 정의용 RunToolSearchCallItem 및 RunToolSearchOutputItem
• 도구 호출 및 그 결과용 RunToolCallItem 및 RunToolCallOutputItem
• 승인을 위해 일시 중지된 도구 호출용 RunToolApprovalItem
• 핸드오프 요청 및 완료된 전송용 RunHandoffCallItem 및 RunHandoffOutputItem

어떤 에이전트가 항목을 생성했는지, 또는 그것이 도구, 도구 검색, 핸드오프, 승인 경계를 표시하는지 알아야 한다면 output보다 newItems를 선택하세요. toolSearchTool()을 사용할 때는, 일반적인 도구 호출이 일어나기 전에 어떤 지연된 도구나 namespace가 로드되었는지 확인하는 가장 쉬운 방법이 이 도구 검색 항목들입니다.

대화 계속 또는 재개

활성 에이전트

lastAgent 속성에는 마지막으로 실행된 에이전트가 들어 있습니다. 이는 핸드오프 이후 다음 사용자 턴에 재사용할 최적의 에이전트인 경우가 많습니다. activeAgent는 같은 값을 가리키는 별칭입니다.

스트리밍 모드에서는 실행이 아직 진행 중일 때 currentAgent가 현재 활성화된 에이전트를 알려줍니다.

인터럽션(중단 처리) 및 재개 가능한 상태

도구에 승인이 필요하면 실행이 일시 중지되고, interruptions에는 대기 중인 RunToolApprovalItem들이 들어 있습니다. 여기에는 직접 도구에서 발생한 승인, 핸드오프 이후 도달한 도구에서 발생한 승인, 또는 중첩된 agent.asTool() 실행에서 발생한 승인이 포함될 수 있습니다.

result.state.approve(...) / result.state.reject(...)를 통해 승인을 처리한 다음, 같은 state를 다시 run()에 전달해 재개하세요. 모든 인터럽션(중단 처리)을 한 번에 해결할 필요는 없습니다. 일부 항목만 처리한 뒤 다시 실행하면, 해결된 호출은 계속 진행되고 해결되지 않은 호출은 대기 상태로 남아 실행을 다시 일시 중지합니다.

state 속성은 결과 뒤에 있는 직렬화 가능한 스냅샷입니다. 나중에 일시 중지된 실행을 재개해야 하는 휴먼 인 더 루프 (HITL), 재시도 흐름, 또는 기타 모든 경우에 사용하세요.

서버 관리 continuation

OpenAI Responses API chaining을 사용할 때 lastResponseId는 다음 턴에서 previousResponseId로 전달할 값입니다.

이미 history, session, 또는 conversationId로 대화를 계속하고 있다면, 일반적으로 lastResponseId는 필요하지 않습니다. 다단계 실행의 모든 원문 모델 응답이 필요하다면 대신 rawResponses를 확인하세요.

중첩 agent-tool 메타데이터

agentToolInvocation은 중첩된 Agent.asTool() 결과를 위한 것으로, 특히 customOutputExtractor 내부에서 현재 도구 호출에 대한 메타데이터가 필요할 때 사용합니다. 이는 일반적인 “전체 실행이 완료되었다”는 요약 필드가 아닙니다.

이 중첩 컨텍스트에서 agentToolInvocation은 다음을 제공합니다.

• toolName
• toolCallId
• toolArguments

중첩된 agent-tool 실행에 전달된 구조화된 입력도 필요하다면 result.runContext.toolInput과 함께 사용하세요.

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

스트리밍 결과

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

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

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

스트리밍 실행이 취소된 경우에도 정리가 끝나면 completed는 여전히 resolve되고 cancelled는 true가 되지만, 현재 턴이 끝나지 않았기 때문에 finalOutput 같은 턴 종료 필드는 설정되지 않을 수 있습니다. 이 완료되지 않은 턴은 새 사용자 메시지를 추가하는 대신 result.state(그리고 사용 중이라면 동일한 session)로 재개하세요.

진단 및 고급 필드

실행 컨텍스트

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

원문 응답

rawResponses에는 실행 중 수집된 원문 모델 응답이 들어 있습니다. 다단계 실행은 예를 들어 핸드오프나 반복적인 도구/모델 사이클에 걸쳐 둘 이상의 응답을 생성할 수 있습니다.

가드레일 결과

inputGuardrailResults 및 outputGuardrailResults 속성에는 에이전트 수준의 가드레일 결과가 들어 있습니다. 도구 가드레일 결과는 별도로 toolInputGuardrailResults 및 toolOutputGuardrailResults를 통해 노출됩니다.

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

사용량

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

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