OpenAI Agents SDK

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

참고

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

핵심 개념:

Agents : 지침, 도구, 가드레일, 핸드오프로 구성된 LLM
Sandbox agents : 장기간에 걸쳐 컨테이너와 함께 작업하도록 미리 구성된 에이전트
Realtime agents : gpt-realtime-2.1과 전체 에이전트 기능으로 강력한 음성 에이전트 구축
Voice agents : 음성-텍스트 변환, 에이전트 워크플로, 텍스트-음성 변환을 결합한 음성 파이프라인 구축
Agents as tools / Handoffs : 특정 작업을 다른 에이전트에 위임
Tools : 다양한 도구를 통해 에이전트가 작업 수행 (함수, MCP, 호스팅 도구)
Guardrails : 입력 및 출력 검증을 위한 구성 가능한 안전 검사
Human in the loop : 에이전트 실행 전반에 걸쳐 사람을 참여시키는 내장 메커니즘
Sessions : 에이전트 실행 전반에 걸친 자동 대화 기록 관리
Tracing : 에이전트 실행에 대한 내장 추적 기능으로, 워크플로를 확인, 디버그, 최적화 가능

SDK가 실제로 동작하는 모습을 보려면 examples 디렉터리를 살펴보고, 자세한 내용은 문서를 참고하세요.

시작하기
시작하려면 Python 환경을 설정하고(Python 3.10 이상 필요), OpenAI Agents SDK 패키지를 설치하세요.

venv
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install openai-agents
음성 지원의 경우 선택적 voice 그룹과 함께 설치하세요: pip install 'openai-agents[voice]' . Redis 세션 지원의 경우 선택적 redis 그룹과 함께 설치하세요: pip install 'openai-agents[redis]' .

uv
uv 에 익숙하다면 패키지 설치가 훨씬 더 쉬울 것입니다:

uv init
uv add openai-agents
음성 지원의 경우 선택적 voice 그룹과 함께 설치하세요: uv add 'openai-agents[voice]' . Redis 세션 지원의 경우 선택적 redis 그룹과 함께 설치하세요: uv add 'openai-agents[redis]' .

첫 번째 에이전트 실행하기
SDK는 에이전트를 실행하는 네 가지 주요 방법을 지원합니다. 아래 예제 중 하나를 실행하기 전에 OPENAI_API_KEY 환경 변수를 설정하세요.

텍스트 에이전트 실행
지속적인 실시간 연결이나 샌드박스 워크스페이스가 필요 없는 워크플로에는 텍스트 Agent를 사용하세요.

from agents import Agent , Runner

agent = Agent ( name = "Assistant" , instructions = "You are a helpful assistant" )

result = Runner . run_sync ( agent , "Write a haiku about recursion in programming." )
print ( result . final_output )

# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.
( Jupyter 노트북 사용자는 hello_world_jupyter.ipynb 를 참고하세요 )

샌드박스 에이전트 실행
에이전트가 파일을 검사하고, 명령을 실행하고, 패치를 적용하거나, 더 긴 작업 전반에 걸쳐 워크스페이스 상태를 보존해야 할 때는 SandboxAgent를 사용하세요.

이 예제는 macOS와 Linux에서 지원되는 UnixLocalSandboxClient 를 사용합니다. Windows에서는 openai-agents[docker] 추가 기능과 함께 DockerSandboxClient 를 사용하거나 호스팅 샌드박스 클라이언트를 대신 사용하세요. 설정 세부 사항은 Sandbox clients를 참고하세요.

from agents import Runner
from agents . run import RunConfig
from agents . sandbox import Manifest , SandboxAgent , SandboxRunConfig
from agents . sandbox . entries import GitRepo
from agents . sandbox . sandboxes import UnixLocalSandboxClient

agent = SandboxAgent (
name = "Workspace Assistant" ,
instructions = "Inspect the sandbox workspace before answering." ,
default_manifest = Manifest (
entries = { "repo" : GitRepo ( repo = "openai/openai-agents-python" , ref = "main" )}
),
)

result = Runner . run_sync (
agent ,
"Inspect the repo README and summarize what this project does." ,
run_config = RunConfig ( sandbox = SandboxRunConfig ( client = UnixLocalSandboxClient ())),
)
print ( result . final_output )
실시간 에이전트 실행
WebSocket을 통한 저지연 서버 측 음성 및 멀티모달 경험에는 RealtimeAgent를 사용하세요.

import asyncio
from agents . realtime import RealtimeAgent , RealtimeRunner

async def main () -> None :
agent = RealtimeAgent (
name = "Assistant" , instructions = "You are a helpful voice assistant. Keep responses short."
)
runner = RealtimeRunner ( starting_agent = agent )
session = await runner . run ()

async with session :
await session . send_message ( "Say hello in one short sentence." )
async for event in session :
if event . type == "audio" :
# Forward or play event.audio.data.
pass
elif event . type == "history_added" :
print ( event . item )
elif event . type == "agent_end" :
break

if __name__ == "__main__" :
asyncio . run ( main ())
음성 에이전트 실행
VoicePipeline을 사용하여 오디오를 텍스트로 변환하고, 에이전트 워크플로를 실행하고, 생성된 음성을 스트리밍하세요.

import asyncio

import numpy as np

from agents import Agent
from agents . voice import AudioInput , SingleAgentVoiceWorkflow , VoicePipeline

async def main () -> None :
agent = Agent ( name = "Assistant" , instructions = "You are a helpful voice assistant." )
pipeline = VoicePipeline ( workflow = SingleAgentVoiceWorkflow ( agent ))
audio_input = AudioInput ( buffer = np . zeros ( 24000 * 3 , dtype = np . int16 ))

result = await pipeline . run ( audio_input )
async for event in result . stream ():
if event . type == "voice_stream_event_audio" :
# Forward or play event.data.
pass

if __name__ == "__main__" :
asyncio . run ( main ())
SDK가 실제로 동작하는 모습을 보려면 examples 디렉터리를 살펴보고, 자세한 내용은 문서를 참고하세요.

기여하기
버그 보고와 기능 요청은 GitHub issues를 통해 공유해 주세요.
풀 리퀘스트는 저장소 협력자로 제한됩니다. 비협력자의 풀 리퀘스트는 받지 않습니다.
기여 정책과 개발 가이드는 CONTRIBUTING.md를 참고하세요.
보안 취약점의 경우 SECURITY.md를 따르세요.

감사의 말
오픈소스 커뮤니티의 훌륭한 작업에 감사를 표합니다. 특히:

Pydantic
Requests
MCP Python SDK
Griffe

이 라이브러리에는 다음과 같은 선택적 의존성이 있습니다:

websockets
SQLAlchemy
any-llm and LiteLLM

또한 프로젝트 관리를 위해 다음 도구에 의존합니다:

uv and ruff
mypy and Pyright
pytest and Coverage.py
MkDocs

우리는 커뮤니티의 다른 사람들이 우리의 접근 방식을 확장할 수 있도록 Agents SDK를 오픈소스 프레임워크로 계속 구축해 나갈 것입니다.