SDK로 에이전트를 만들어 바로 실행하려면 이 가이드를 따라 하세요. 아래 JavaScript와 Python 예제는 같은 기본 개념을 사용합니다. 먼저 에이전트를 정의하고 실행한 뒤, 워크플로우가 확장되면 도구와 전문 에이전트를 추가합니다.
SDK 설치
프로젝트를 만들고 SDK를 설치한 뒤 API 키를 설정하세요.
API 키 만들기
# JavaScript
npm install @openai/agents zod
# Python
pip install openai-agents
export OPENAI_API_KEY=sk-...
첫 에이전트 만들고 실행하기
먼저 한 가지 작업을 담당하는 에이전트 하나를 만들고 한 턴만 실행하세요. SDK가 모델을 호출하고 최종 출력과 실행 기록이 담긴 결과 객체를 반환합니다.
import { Agent, run } from "@openai/agents";
const agent = new Agent({
name: "History tutor",
instructions: "You answer history questions clearly and concisely.",
model: "gpt-6-astra",
});
const result = await run(agent, "When did the Roman Empire fall?");
console.log(result.finalOutput);터미널에 짧은 답변이 표시됩니다. 처음부터 여러 에이전트로 구성된 큰 시스템을 설계하기보다는 이 실행 루프가 작동하는지 확인한 뒤 같은 구조에서 기능을 하나씩 추가하세요.
다음 턴으로 상태 전달하기
첫 실행 결과를 바탕으로 두 번째 턴에 어떤 상태를 전달할지 결정할 수 있습니다.
| 원하는 동작 | 사용할 항목 |
|---|---|
| 애플리케이션에서 전체 기록 보관 | result.history |
| SDK가 기록을 불러오고 저장하도록 설정 | 세션 |
| 실행을 이어가는 데 필요한 상태 관리를 OpenAI에 위임 | 서버가 관리하는 실행 재개용 ID |
| 승인 대기나 인터럽트로 일시 중지된 실행 재개 | result.stateinterruptions |
핸드오프를 받은 전문 에이전트가 다음 턴에도 대화를 이어가야 한다면 lastAgent
에이전트에 도구 추가하기
처음 추가하는 기능은 대개 함수 도구이거나 웹 검색, 파일 검색처럼 OpenAI가 호스팅하는 도구입니다.
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";
const historyFunFact = tool({
name: "history_fun_fact",
description: "Return a short history fact.",
parameters: z.object({}),
async execute() {
return "Sharks are older than trees.";
},
});
const agent = new Agent({
name: "History tutor",
instructions:
"Answer history questions clearly. Use history_fun_fact when it helps.",
tools: [historyFunFact],
});
const result = await run(
agent,
"Tell me something surprising about ancient life on Earth."
);
console.log(result.finalOutput);호스팅 도구나 도구 검색이 필요하거나 에이전트를 도구로 사용하려면 공통 가이드인 도구 사용하기를 참고하세요.
전문 에이전트 추가하기
다음 단계로는 보통 워크플로우의 작업을 전문 에이전트별로 나누고, 라우터가 핸드오프를 통해 적합한 에이전트에 작업을 위임하도록 구성합니다.
import { Agent, run } from "@openai/agents";
const historyTutor = new Agent({
name: "History tutor",
instructions: "Answer history questions clearly and concisely.",
});
const mathTutor = new Agent({
name: "Math tutor",
instructions: "Explain math step by step and include worked examples.",
});
const triageAgent = Agent.create({
name: "Homework triage",
instructions: "Route each homework question to the right specialist.",
handoffs: [historyTutor, mathTutor],
});
const result = await run(
triageAgent,
"Who was the first president of the United States?"
);
console.log(result.finalOutput);
console.log(result.lastAgent?.name);첫 실행부터 트레이스 확인하기
서버 측에서 SDK를 일반적인 방식으로 실행하면 트레이스가 기록됩니다. 첫 실행에 성공하면 프롬프트를 조정하기 전에 트레이스 대시보드를 열어 모델 호출, 도구 호출, 핸드오프, 가드레일을 확인하세요.
다음 단계
첫 실행에 성공했다면 다음으로 추가하려는 기능에 맞는 가이드를 선택하세요.