빠른 시작

프로젝트 설정

프로젝트를 만들고 npm 을 초기화합니다. 이 작업은 한 번만 하면 됩니다.
Terminal window
```
mkdir my_project
cd my_project
npm init -y
```
Agents SDK 와 Zod 를 설치합니다. SDK 는 도구 스키마와 structured outputs 에 Zod v4 를 사용합니다.
Terminal window
```
npm install @openai/agents zod
```
OpenAI API 키를 설정합니다. 아직 키가 없다면 다음 안내를 따라 OpenAI API 키를 만드세요.
Terminal window
```
export OPENAI_API_KEY=sk-...
```
또는 setDefaultOpenAIKey('<api key>') 를 호출해 프로그래밍 방식으로 키를 설정하고, 트레이싱에는 setTracingExportApiKey('<api key>') 를 사용할 수 있습니다. 자세한 내용은 SDK 설정 가이드를 참고하세요.

첫 에이전트 생성

에이전트는 instructions 와 이름으로 정의합니다.

import { Agent } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

첫 에이전트 실행

run 메서드를 사용해 에이전트를 실행할 수 있습니다. 시작할 에이전트와 전달할 입력을 함께 넘기면 실행이 시작됩니다.

그러면 최종 출력과 해당 실행 중 수행된 모든 작업이 포함된 결과가 반환됩니다.

import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const result = await run(agent, 'When did sharks first appear?');

console.log(result.finalOutput);

두 번째 턴에서는 result.history 를 다시 run() 에 전달하거나, 세션을 연결하거나, conversationId / previousResponseId 로 OpenAI 서버가 관리하는 상태를 재사용할 수 있습니다. 에이전트 실행 가이드에서 이러한 접근 방식을 비교합니다.

에이전트에 도구 제공

에이전트가 정보를 조회하거나 작업을 수행할 수 있도록 도구를 제공할 수 있습니다.

import { Agent, tool } from '@openai/agents';
import { z } from 'zod';

const historyFunFact = tool({
  // The name of the tool will be used by the agent to tell what tool to use.
  name: 'history_fun_fact',
  // The description is used to describe when to use the tool by telling it what it does.
  description: 'Give a fun fact about a historical event',
  // This tool takes no parameters, so we provide an empty Zod object.
  parameters: z.object({}),
  execute: async () => {
    // The output will be returned back to the agent to use.
    return 'Sharks are older than trees.';
  },
});

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
  // Add the tool to the agent.
  tools: [historyFunFact],
});

추가 에이전트 정의

추가 에이전트도 비슷한 방식으로 정의하여 문제를 더 작은 부분으로 나누고, 각 에이전트가 현재 작업에 더 집중하도록 만들 수 있습니다. 또한 에이전트에 모델을 정의해 문제별로 서로 다른 모델을 사용할 수도 있습니다.

import { Agent } from '@openai/agents';

const historyTutorAgent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const mathTutorAgent = new Agent({
  name: 'Math Tutor',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});

핸드오프 정의

여러 에이전트 사이를 오케스트레이션하려면 에이전트에 handoffs 를 정의할 수 있습니다. 이렇게 하면 에이전트가 대화를 다음 에이전트로 넘길 수 있습니다. 이는 실행 과정 중 자동으로 이루어집니다.

import { Agent } from '@openai/agents';

const historyTutorAgent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const mathTutorAgent = new Agent({
  name: 'Math Tutor',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});

// Use Agent.create() to keep handoff output types aligned.
const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions:
    "You determine which agent to use based on the user's homework question",
  handoffs: [historyTutorAgent, mathTutorAgent],
});

실행 후에는 결과의 lastAgent 속성을 확인해 어떤 에이전트가 최종 응답을 생성했는지 볼 수 있습니다.

에이전트 오케스트레이션 실행

러너는 개별 에이전트 실행, 모든 핸드오프, 그리고 모든 도구 호출 처리를 담당합니다.

import { Agent, run } from '@openai/agents';

const historyTutorAgent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const mathTutorAgent = new Agent({
  name: 'Math Tutor',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});

const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions:
    "You determine which agent to use based on the user's homework question",
  handoffs: [historyTutorAgent, mathTutorAgent],
});

async function main() {
  const result = await run(triageAgent, 'What is the capital of France?');
  console.log(result.finalOutput);
}

main().catch((err) => console.error(err));

전체 예제 통합

이제 전체를 하나의 완전한 예제로 합쳐보겠습니다. 이를 index.js 파일에 넣고 실행하세요. 앱이 이미 TypeScript 용으로 설정되어 있다면 대신 index.ts 를 사용할 수 있습니다.

import { Agent, run } from '@openai/agents';

const historyTutorAgent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const mathTutorAgent = new Agent({
  name: 'Math Tutor',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});

const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions:
    "You determine which agent to use based on the user's homework question",
  handoffs: [historyTutorAgent, mathTutorAgent],
});

async function main() {
  const result = await run(triageAgent, 'What is the capital of France?');
  console.log(result.finalOutput);
}

main().catch((err) => console.error(err));

트레이스 확인

Agents SDK 는 자동으로 트레이스를 생성합니다. 이를 통해 에이전트가 어떻게 동작하는지, 어떤 도구를 호출했는지, 또는 어떤 에이전트로 핸드오프했는지 검토할 수 있습니다.

에이전트 실행 중 어떤 일이 있었는지 확인하려면 OpenAI Dashboard 의 Trace viewer로 이동하세요.

다음 단계

더 복잡한 에이전트형 흐름을 구축하는 방법을 알아보세요.

에이전트 구성 방법 알아보기
에이전트 실행과 세션 알아보기
도구, 가드레일, 모델 알아보기