실행 결과

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

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

최종 출력

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

• string — outputType이 정의되지 않은 모든 에이전트의 기본값
• unknown — 에이전트가 출력 타입으로 JSON 스키마를 정의한 경우. 이때 JSON은 파싱되지만 타입 검증은 수동으로 해야 합니다.
• z.infer<outputType> — 에이전트가 출력 타입으로 Zod 스키마를 정의한 경우. 출력은 자동으로 해당 스키마에 맞게 파싱됩니다.
• 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

다음 턴 입력

다음 턴의 입력에 접근하는 방법은 두 가지가 있습니다:

• result.history — 입력과 에이전트 출력의 사본을 모두 포함
• result.output — 전체 에이전트 실행의 출력을 포함

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?'));
}

마지막 에이전트

lastAgent 속성에는 마지막으로 실행된 에이전트가 들어 있습니다. 애플리케이션에 따라, 이는 사용자가 다음 입력을 제공할 때 자주 유용합니다. 예를 들어, 언어별 에이전트로 핸드오프하는 프런트라인 분류 에이전트가 있는 경우, 마지막 에이전트를 저장해 두었다가 사용자가 다음에 메시지를 보낼 때 재사용할 수 있습니다.

스트리밍 모드에서는 현재 실행 중인 에이전트를 가리키는 currentAgent 속성에 접근하는 것도 유용할 수 있습니다.

새 항목

newItems 속성에는 실행 중에 생성된 새 항목이 들어 있습니다. 항목은 RunItem입니다. 실행 항목은 LLM이 생성한 원문 항목을 래핑합니다. 이를 통해 LLM의 출력 외에도 이러한 이벤트가 어떤 에이전트와 연관되었는지 접근할 수 있습니다.

• RunMessageOutputItem은 LLM의 메시지를 나타냅니다. 원문 항목은 생성된 메시지입니다.
• RunHandoffCallItem은 LLM이 핸드오프 도구를 호출했음을 나타냅니다. 원문 항목은 LLM의 도구 호출 항목입니다.
• RunHandoffOutputItem은 핸드오프가 발생했음을 나타냅니다. 원문 항목은 핸드오프 도구 호출에 대한 도구 응답입니다. 항목에서 소스/타깃 에이전트에도 접근할 수 있습니다.
• RunToolCallItem은 LLM이 도구를 호출했음을 나타냅니다.
• RunToolCallOutputItem은 도구가 호출되었음을 나타냅니다. 원문 항목은 도구 응답입니다. 항목에서 도구 출력에도 접근할 수 있습니다.
• RunReasoningItem은 LLM의 추론 항목을 나타냅니다. 원문 항목은 생성된 추론입니다.
• RunToolApprovalItem은 LLM이 도구 호출에 대한 승인을 요청했음을 나타냅니다. 원문 항목은 LLM의 도구 호출 항목입니다.

상태

state 속성에는 실행의 상태가 들어 있습니다. result에 첨부된 대부분은 state에서 파생되지만, state는 직렬화/역직렬화가 가능하며, 오류에서 복구하거나 interruption을 처리해야 하는 경우 이후 run 호출의 입력으로도 사용할 수 있습니다.

인터럽션(중단 처리)

에이전트에서 needsApproval을 사용하는 경우, 계속 진행하기 전에 처리해야 하는 interruptions가 트리거될 수 있습니다. 이 경우 interruptions는 인터럽션을 유발한 ToolApprovalItem의 배열이 됩니다. 인터럽션을 다루는 방법에 대한 자세한 내용은 휴먼 인 더 루프 (HITL) 가이드를 확인하세요.

기타 정보

원문 응답

rawResponses 속성에는 에이전트 실행 중 모델이 생성한 원문의 LLM 응답이 들어 있습니다.

마지막 응답 ID

lastResponseId 속성에는 에이전트 실행 중 모델이 생성한 마지막 응답의 ID가 들어 있습니다.

가드레일 결과

inputGuardrailResults 및 outputGuardrailResults 속성에는 가드레일의 결과(있는 경우)가 들어 있습니다. 가드레일 결과에는 로깅하거나 저장하고 싶은 유용한 정보가 포함될 수 있으므로 이를 제공해 드립니다.

도구 가드레일 결과는 toolInputGuardrailResults 및 toolOutputGuardrailResults를 통해 별도로 제공됩니다.

사용량

토큰 사용량은 result.state.usage에 집계되며, 실행에 대한 요청 수와 토큰 합계를 추적합니다. 스트리밍 실행의 경우 응답이 도착함에 따라 이 데이터가 업데이트됩니다.

RunState에서 사용량 읽기

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

원본 입력

input 속성에는 run 메서드에 제공한 원본 입력이 들어 있습니다. 대부분의 경우 필요하지 않지만, 필요한 경우를 대비해 제공됩니다.