실행 결과

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

stream: true 없이 run을 호출하면 RunResult
stream: true로 run을 호출하면 StreamedRunResult. 스트리밍에 대한 자세한 내용은 스트리밍을 확인하세요

최종 출력

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 속성에는 마지막으로 실행된 에이전트가 포함됩니다. 애플리케이션에 따라 다음 번에 user가 무언가를 입력할 때 유용한 경우가 많습니다. 예를 들어, 프런트라인 분류 에이전트가 언어별 에이전트로 핸드오프하는 경우, 마지막 에이전트를 저장해 두었다가 user가 에이전트에 메시지를 보낼 때 재사용할 수 있습니다.

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

새 항목

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

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

상태

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

인터럽션(중단 처리)

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

기타 정보

원문 응답

rawResponses 속성에는 에이전트 실행 중 모델이 생성한 원문의 LLM 응답이 포함됩니다.

마지막 응답 ID

lastResponseId 속성에는 에이전트 실행 중 모델이 생성한 마지막 응답의 ID가 포함됩니다.

가드레일 결과

inputGuardrailResults 및 outputGuardrailResults 속성에는 가드레일의 결과(있는 경우)가 포함됩니다. 가드레일 결과에는 로깅하거나 저장하고 싶은 유용한 정보가 포함되는 경우가 있어, 이를 사용할 수 있도록 제공합니다.

원래 입력

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