퀵스타트

퀵스타트 (Quickstart)

작동하는 SDK 기반 에이전트로 가는 가장 짧은 경로를 제공하는 페이지예요. JavaScript와 Python 모두에서 동일한 고수준 개념을 사용해요: 에이전트 정의, 실행, 그리고 워크플로우가 성장함에 따라 도구와 전문가 에이전트 추가.

출처: 문서

본문

작동하는 SDK 기반 에이전트로 가는 가장 짧은 경로를 원할 때 이 페이지를 사용하세요. 아래 예시들은 JavaScript와 Python 모두에서 동일한 고수준 개념을 사용해요: 에이전트를 정의하고, 실행하고, 워크플로우가 성장함에 따라 도구와 전문가 에이전트를 추가해요.

SDK 설치하기

프로젝트를 만들고, SDK를 설치하고, API 키를 설정하세요.

Create an API Key

# 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);

import asyncio

from agents import Agent, Runner

agent = Agent(
    name="History tutor",
    instructions="You answer history questions clearly and concisely.",
    model="gpt-6-astra",
)


async def main() -> None:
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

터미널에서 간결한 답변을 보게 될 거예요. 그 루프가 작동하면, 큰 다중 에이전트 설계로 시작하는 대신 동일한 형태를 유지하며 능력을 점진적으로 추가하세요.

다음 턴으로 상태 이어가기

첫 번째 실행 결과는 또한 두 번째 턴이 상태로 무엇을 사용해야 할지 결정하는 방법이에요.

핸드오프 후 그 전문가가 제어를 유지해야 할 때 다음 턴에 TypeScript의 lastAgent 또는 Python의 last_agent를 재사용하세요.

에이전트에 도구 주기

첫 번째로 추가하는 능력은 종종 함수 도구 또는 웹 검색, 파일 검색 같은 호스팅 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 asyncio

from agents import Agent, Runner, function_tool


@function_tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."


agent = Agent(
    name="History tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Tell me something surprising about ancient life on Earth.",
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

호스팅 도구, 도구 검색, 또는 도구로서의 에이전트가 필요할 때는 공유 Using tools 가이드를 사용하세요.

전문가 에이전트 추가하기

흔한 다음 단계는 워크플로우를 전문가들로 나누고 라우터가 핸드오프로 그들에게 위임하게 하는 것이에요.

전문가 에이전트로 라우팅하기

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);

import asyncio

from agents import Agent, Runner

history_tutor = Agent(
    name="History tutor",
    handoff_description="Specialist for history questions.",
    instructions="Answer history questions clearly and concisely.",
)

math_tutor = Agent(
    name="Math tutor",
    handoff_description="Specialist for math questions.",
    instructions="Explain math step by step and include worked examples.",
)

triage_agent = Agent(
    name="Homework triage",
    instructions="Route each homework question to the right specialist.",
    handoffs=[history_tutor, math_tutor],
)


async def main() -> None:
    result = await Runner.run(
        triage_agent,
        "Who was the first president of the United States?",
    )
    print(result.final_output)
    print(result.last_agent.name)


if __name__ == "__main__":
    asyncio.run(main())

트레이스를 일찍 검사하기

일반적인 서버 측 SDK 경로에는 트레이싱이 포함돼요. 첫 실행이 작동하는 즉시 Traces dashboard를 열어 프롬프트를 튜닝하기 전에 모델 호출, 도구 호출, 핸드오프, 가드레일을 검사하세요.

다음 단계

첫 실행이 작동하면, 다음으로 추가하고 싶은 능력과 일치하는 가이드로 계속 진행하세요.

[Agent definitions

    Shape one specialist cleanly before you scale the workflow.](https://developers.openai.com/api/docs/guides/agents/define-agents)

[Using tools

    Add hosted tools, function tools, and agents-as-tools.](https://developers.openai.com/api/docs/guides/tools#usage-in-the-agents-sdk)

[Running agents

    Learn the agent loop, streaming, and continuation strategies.](https://developers.openai.com/api/docs/guides/agents/running-agents)

[Orchestration and handoffs

    Decide when specialists should take over the conversation.](https://developers.openai.com/api/docs/guides/agents/orchestration)

더 알아보기 (Learn more)

관련 문서: 에이전트 정의와 도구 사용하기를 참고하세요.