콘텐츠로 이동

빠른 시작

프로젝트 및 가상 환경 생성

이 작업은 한 번만 수행하면 됩니다.

mkdir my_project
cd my_project
python -m venv .venv

가상 환경 활성화

새 터미널 세션을 시작할 때마다 이 작업을 수행하세요.

macOS 또는 Linux:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

Agents SDK 설치

pip install openai-agents # or `uv add openai-agents`, etc

OpenAI API 키 설정

키가 없다면 이 지침에 따라 OpenAI API 키를 생성하세요.

이 명령은 현재 터미널 세션에 키를 설정합니다.

macOS 또는 Linux:

export OPENAI_API_KEY=sk-...

Windows PowerShell:

$env:OPENAI_API_KEY = "sk-..."

Windows 명령 프롬프트:

set "OPENAI_API_KEY=sk-..."

첫 에이전트 생성

에이전트는 instructions, 이름, 특정 모델 같은 선택적 구성으로 정의됩니다.

from agents import Agent

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

첫 에이전트 실행

에이전트를 실행하고 RunResult를 돌려받으려면 Runner를 사용하세요.

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

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

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

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

다음 경험칙을 사용하세요.

원하는 경우... 다음으로 시작하세요...
완전한 수동 제어와 공급자에 구애받지 않는 기록 result.to_input_list()
SDK가 기록을 로드하고 저장해 주기를 원하는 경우 session=...
OpenAI가 관리하는 서버 측 이어가기 previous_response_id 또는 conversation_id

트레이드오프와 정확한 동작은 에이전트 실행을 참조하세요.

작업이 주로 프롬프트, 도구, 대화 상태에 머문다면 일반 Agent와 Runner를 사용하세요. 에이전트가 격리된 워크스페이스에서 실제 파일을 검사하거나 수정해야 한다면 Sandbox 에이전트 빠른 시작으로 이동하세요.

에이전트에 도구 제공

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

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():
    result = await Runner.run(
        agent,
        "Tell me something surprising about ancient life on Earth.",
    )
    print(result.final_output)


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

에이전트 몇 개 추가

멀티 에이전트 패턴을 선택하기 전에 최종 답변의 소유자가 누구인지 결정하세요.

  • 핸드오프: 해당 턴의 그 부분에 대해 전문가가 대화를 이어받습니다.
  • Agents as tools: 오케스트레이터가 제어를 유지하고 전문가를 도구로 호출합니다.

이 빠른 시작에서는 첫 예제로 가장 짧기 때문에 핸드오프를 계속 사용합니다. 매니저 스타일 패턴은 에이전트 오케스트레이션 및 도구: agents as tools를 참조하세요.

추가 에이전트도 같은 방식으로 정의할 수 있습니다. handoff_description은 라우팅 에이전트에 언제 위임할지에 대한 추가 컨텍스트를 제공합니다.

from agents import Agent

history_tutor_agent = Agent(
    name="History Tutor",
    handoff_description="Specialist agent for historical questions",
    instructions="You answer history questions clearly and concisely.",
)

math_tutor_agent = Agent(
    name="Math Tutor",
    handoff_description="Specialist agent for math questions",
    instructions="You explain math step by step and include worked examples.",
)

핸드오프 정의

에이전트에서는 작업을 해결하는 동안 선택할 수 있는 나가는 핸드오프 옵션 목록을 정의할 수 있습니다.

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route each homework question to the right specialist.",
    handoffs=[history_tutor_agent, math_tutor_agent],
)

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

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

import asyncio
from agents import Runner


async def main():
    result = await Runner.run(
        triage_agent,
        "Who was the first president of the United States?",
    )
    print(result.final_output)
    print(f"Answered by: {result.last_agent.name}")


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

참조 코드 예제

저장소에는 동일한 핵심 패턴에 대한 전체 스크립트가 포함되어 있습니다.

트레이스 보기

에이전트 실행 중 발생한 일을 검토하려면 OpenAI Dashboard의 Trace viewer로 이동하여 에이전트 실행 트레이스를 확인하세요.

다음 단계

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