콘텐츠로 이동

빠른 시작

  1. 프로젝트를 생성하고 npm을 초기화합니다. 이 작업은 한 번만 하면 됩니다.

    Terminal window
    mkdir my_project
    cd my_project
    npm init -y
  2. Agents SDK를 설치합니다.

    Terminal window
    npm install @openai/agents zod@3
  3. OpenAI API 키를 설정합니다. 아직 없다면 OpenAI API 키를 만들기 위해 이 안내를 따르세요.

    Terminal window
    export OPENAI_API_KEY=sk-...

    또는 setDefaultOpenAIKey('<api key>')를 호출해 프로그램적으로 키를 설정하고, 트레이싱을 위해 setTracingExportApiKey('<api key>')를 사용할 수 있습니다. 자세한 내용은 설정 가이드를 참고하세요.

에이전트는 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);

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

import { Agent, tool } from '@openai/agents';
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.',
// Adding the tool to the agent
tools: [historyFunFact],
});

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

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를 정의할 수 있습니다. 이렇게 하면 에이전트가 대화를 다음 에이전트로 넘길 수 있으며, 이는 실행 과정에서 자동으로 이뤄집니다.

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

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

Runner는 개별 에이전트 실행, 잠재적인 핸드오프, 도구 실행을 처리합니다.

import { run } from '@openai/agents';
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 파일에 넣고 실행하세요.

Quickstart
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 = new Agent({
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 대시보드의 Trace viewer로 이동하세요.

더 복잡한 에이전트 플로우를 만드는 방법을 알아보세요: