빠른 시작
프로젝트 설정
섹션 제목: “프로젝트 설정”-
프로젝트를 생성하고 npm을 초기화합니다. 이 작업은 한 번만 수행하면 됩니다.
터미널 창 mkdir my_projectcd my_projectnpm init -y -
Agents SDK와 Zod를 설치합니다. SDK는 도구 스키마와 structured outputs에 Zod v4를 사용합니다.
터미널 창 npm install @openai/agents zod -
OpenAI API 키를 설정합니다. 키가 없다면 이 안내에 따라 OpenAI API 키를 생성하세요.
터미널 창 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 대시보드의 트레이스 뷰어로 이동하세요.
다음 단계
섹션 제목: “다음 단계”더 복잡한 에이전트 기반 흐름을 구축하는 방법을 알아보세요: