콘텐츠로 이동

빠른 시작

프로젝트 및 가상 환경 생성

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

mkdir my_project
cd my_project
python -m venv .venv

가상 환경 활성화

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

source .venv/bin/activate

Agents SDK 설치

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

OpenAI API 키 설정

아직 없다면 이 안내를 따라 OpenAI API 키를 생성하세요

export OPENAI_API_KEY=sk-...

첫 에이전트 생성

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

from agents import Agent

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

첫 에이전트 실행

Runner를 사용해 에이전트를 실행하고 RunResult를 반환받으세요

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(...)에 다시 전달하거나, session을 연결하거나, conversation_id / previous_response_id로 OpenAI 서버 관리 상태를 재사용할 수 있습니다. 에이전트 실행 가이드에서 이러한 접근 방식을 비교합니다

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

원한다면... 먼저 시작할 것...
완전한 수동 제어 및 provider-agnostic 히스토리 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 대시보드의 Trace viewer로 이동해 에이전트 실행의 트레이스를 확인하세요

다음 단계

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