openai-agents-python

김민범·2025년 7월 17일
AIagent
0

AI

목록 보기
10/12

https://github.com/openai/openai-agents-python README 번역

OpenAI Agents SDK

OpenAI Agents SDK는 멀티 에이전트 워크플로우를 구축하기 위한 가볍지만 강력한 프레임워크입니다. 이는 제공자에 구애받지 않으며, OpenAI Responses와 Chat Completions API는 물론 100개 이상의 다른 LLM을 지원합니다.

참고: JavaScript/TypeScript 버전을 찾고 계신가요? Agents SDK JS/TS를 확인해보세요.

핵심 개념:

  • 에이전트: 지시사항, 도구, 가이드레일, 핸드오프로 구성된 LLM
  • 핸드오프: 에이전트 간 제어권을 전송하기 위해 Agents SDK에서 사용하는 특수 도구 호출
  • 가이드레일: 입력 및 출력 검증을 위한 구성 가능한 안전 검사
  • 세션: 에이전트 실행 간 대화 기록 자동 관리
  • 트레이싱: 에이전트 실행의 내장 추적 기능으로 워크플로우를 보고, 디버그하고 최적화할 수 있음

examples 디렉토리를 살펴보면 SDK가 동작하는 모습을 볼 수 있고, 더 자세한 내용은 문서를 읽어보세요.

세션

Agents SDK는 내장된 세션 메모리를 제공하여 여러 에이전트 실행에서 대화 기록을 자동으로 유지하므로, 턴 사이에 .to_input_list()를 수동으로 처리할 필요가 없습니다.

빠른 시작

from agents import Agent, Runner, SQLiteSession

# 에이전트 생성
agent = Agent(
    name="Assistant",
    instructions="매우 간결하게 답변하세요.",
)

# 세션 인스턴스 생성
session = SQLiteSession("conversation_123")

# 첫 번째 턴
result = await Runner.run(
    agent,
    "골든게이트 브리지가 있는 도시는 어디인가요?",
    session=session
)
print(result.final_output)  # "샌프란시스코"

# 두 번째 턴 - 에이전트가 자동으로 이전 컨텍스트를 기억
result = await Runner.run(
    agent,
    "어느 주에 있나요?",
    session=session
)
print(result.final_output)  # "캘리포니아"

# 동기식 러너와도 함께 작동
result = Runner.run_sync(
    agent,
    "인구는 얼마인가요?",
    session=session
)
print(result.final_output)  # "약 3,900만 명"

세션 옵션

  • 메모리 없음 (기본값): session 매개변수가 생략되면 세션 메모리 없음
  • session: Session = DatabaseSession(...): 대화 기록을 관리하기 위해 Session 인스턴스 사용
from agents import Agent, Runner, SQLiteSession

# 커스텀 SQLite 데이터베이스 파일
session = SQLiteSession("user_123", "conversations.db")
agent = Agent(name="Assistant")

# 서로 다른 세션 ID는 별도의 대화 기록을 유지
result1 = await Runner.run(
    agent,
    "안녕하세요",
    session=session
)
result2 = await Runner.run(
    agent,
    "안녕하세요",
    session=SQLiteSession("user_456", "conversations.db")
)

커스텀 세션 구현

Session 프로토콜을 따르는 클래스를 만들어 자신만의 세션 메모리를 구현할 수 있습니다:

from agents.memory import Session
from typing import List

class MyCustomSession:
    """Session 프로토콜을 따르는 커스텀 세션 구현."""

    def __init__(self, session_id: str):
        self.session_id = session_id
        # 초기화 코드

    async def get_items(self, limit: int | None = None) -> List[dict]:
        # 세션의 대화 기록 조회
        pass

    async def add_items(self, items: List[dict]) -> None:
        # 세션의 새 항목 저장
        pass

    async def pop_item(self) -> dict | None:
        # 세션에서 가장 최근 항목 제거 및 반환
        pass

    async def clear_session(self) -> None:
        # 세션의 모든 항목 지우기
        pass

# 커스텀 세션 사용
agent = Agent(name="Assistant")
result = await Runner.run(
    agent,
    "안녕하세요",
    session=MyCustomSession("my_session")
)

시작하기

Python 환경 설정

옵션 A: venv 사용 (전통적인 방법)

python -m venv env
source env/bin/activate  # Windows: env\Scripts\activate

옵션 B: uv 사용 (권장)

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

Agents SDK 설치

pip install openai-agents

음성 지원을 위해서는 선택적 음성 그룹과 함께 설치: pip install 'openai-agents[voice]'

Hello World 예제

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="당신은 도움이 되는 어시스턴트입니다")

result = Runner.run_sync(agent, "프로그래밍에서 재귀에 대한 하이쿠를 써주세요.")
print(result.final_output)

# 코드 안의 코드,
# 자기 자신을 호출하는 함수,
# 무한 루프의 춤.

(이것을 실행할 때는 OPENAI_API_KEY 환경 변수를 설정했는지 확인하세요)

핸드오프 예제

from agents import Agent, Runner
import asyncio

spanish_agent = Agent(
    name="Spanish agent",
    instructions="당신은 스페인어만 합니다.",
)

english_agent = Agent(
    name="English agent",
    instructions="당신은 영어만 합니다",
)

triage_agent = Agent(
    name="Triage agent",
    instructions="요청 언어에 따라 적절한 에이전트로 핸드오프하세요.",
    handoffs=[spanish_agent, english_agent],
)

async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)
    # ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?

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

함수 예제

import asyncio
from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    return f"{city}의 날씨는 맑습니다."

agent = Agent(
    name="Hello world",
    instructions="당신은 도움이 되는 에이전트입니다.",
    tools=[get_weather],
)

async def main():
    result = await Runner.run(agent, input="도쿄의 날씨는 어때요?")
    print(result.final_output)
    # 도쿄의 날씨는 맑습니다.

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

에이전트 루프

Runner.run()을 호출하면 최종 출력을 얻을 때까지 루프를 실행합니다.

  1. 에이전트의 모델과 설정, 메시지 기록을 사용하여 LLM을 호출합니다.
  2. LLM이 도구 호출을 포함할 수 있는 응답을 반환합니다.
  3. 응답에 최종 출력이 있으면 반환하고 루프를 종료합니다.
  4. 응답에 핸드오프가 있으면 에이전트를 새 에이전트로 설정하고 1단계로 돌아갑니다.
  5. 도구 호출이 있으면 처리하고 도구 응답 메시지를 추가합니다. 그 다음 1단계로 갑니다.

루프가 실행되는 횟수를 제한하기 위해 max_turns 매개변수를 사용할 수 있습니다.

최종 출력

최종 출력은 에이전트가 루프에서 생성하는 마지막 것입니다.

  • 에이전트에 output_type을 설정하면, 최종 출력은 LLM이 해당 유형의 것을 반환할 때입니다. 이를 위해 구조화된 출력을 사용합니다.
  • output_type이 없으면 (즉, 일반 텍스트 응답), 도구 호출이나 핸드오프가 없는 첫 번째 LLM 응답이 최종 출력으로 간주됩니다.

따라서 에이전트 루프의 멘탈 모델은:

  • 현재 에이전트에 output_type이 있으면, 해당 유형과 일치하는 구조화된 출력을 생성할 때까지 루프가 실행됩니다.
  • 현재 에이전트에 output_type이 없으면, 도구 호출/핸드오프가 없는 메시지를 생성할 때까지 루프가 실행됩니다.

일반적인 에이전트 패턴

Agents SDK는 결정론적 플로우, 반복 루프 등을 포함한 다양한 LLM 워크플로우를 모델링할 수 있도록 매우 유연하게 설계되었습니다. examples/agent_patterns에서 예제를 확인하세요.

트레이싱

Agents SDK는 에이전트 실행을 자동으로 추적하여 에이전트의 행동을 쉽게 추적하고 디버그할 수 있게 합니다. 트레이싱은 설계상 확장 가능하며, 커스텀 스팬과 Logfire, AgentOps, Braintrust, Scorecard, Keywords AI를 포함한 다양한 외부 대상을 지원합니다. 트레이싱을 사용자 정의하거나 비활성화하는 방법에 대한 자세한 내용은 트레이싱 문서를 참조하세요. 외부 트레이싱 프로세서의 더 큰 목록도 포함되어 있습니다.

개발 (SDK/예제를 편집해야 하는 경우에만 필요)

  1. uv가 설치되어 있는지 확인하세요.

    uv --version

  2. 종속성 설치

    make sync

  3. (변경 후) 린트/테스트

    make check # 테스트 린터와 타입체커 실행

    또는 개별 실행:

    make tests  # 테스트 실행
make mypy   # 타입체커 실행
make lint   # 린터 실행
make format-check # 스타일 체커 실행
profile
김민범
.
이전 포스트

🤖 Claude Desktop + MCP로 자동화된 개발 환경 구축하기

다음 포스트

Pinecone 벡터 데이터베이스

0개의 댓글