Release process / changelog

Release process / changelog (릴리스 프로세스 / 변경 이력)

이 프로젝트는 0.Y.Z 형태의 세마버전(semantic versioning)을 살짝 변형해 사용해요. 맨 앞의 0은 SDK가 아직 빠르게 진화 중이라는 뜻이에요. 구성 요소를 이렇게 올려요.

출처: 문서

본문

Minor (Y) 버전

베타로 표시되지 않은 공개 인터페이스에 파괴적 변경(breaking change)이 있으면 minor 버전 Y를 올려요. 예를 들어 0.0.x에서 0.1.x로 가는 것에 파괴적 변경이 포함될 수 있어요. 파괴적 변경을 원하지 않는다면 프로젝트에서 0.0.x 버전으로 고정(pin)하는 걸 권장해요.

Patch (Z) 버전

비파괴 변경에는 Z를 올려요.

버그 수정
새 기능
비공개 인터페이스 변경
베타 기능 업데이트

파괴적 변경 변경 이력 (Breaking change changelog)

0.22.0

버전 0.22.0은 여러 기존 API의 실패 처리와 데이터 격리를 강화했어요. 명시적 클라이언트로 OpenAIProvider를 만들면서 organization이나 project도 프로바이더에 넘기던 애플리케이션은 그 중복 인자를 제거해야 해요.

하이라이트:

에이전트 수준 출력 guardrail이 터미널 function tool이 직접 만든 최종 출력을 막으면, SDK는 검증된 필드가 안전한 재구성을 허용할 때만 재생(rewind) 가능한 호출/출력 쌍을 유지해요. 원래 function_call_output 페이로드는 세션 기록·RunState·스트리밍된 결과 상태에서 "Output withheld by an output guardrail."이라는 고정 텍스트로 바뀌고, 페이로드를 담은 current-response guardrail 메타데이터는 지워지거나 대체돼요. 현재 응답에 reasoning이나 다른 지원되지 않는 형태가 있으면 SDK는 대신 current-response 접미사 전체를 버려요. 이전에 수용된 턴과 guardrail 결과는 그대로 남아요. 자세한 내용은 Output guardrails를 참고하세요.
비스트리밍 OpenAI Responses 호출은 이제 반환된 응답의 터미널 상태가 failed나 incomplete면 기존 스트리밍 터미널 이벤트 처리에 맞춰 ModelBehaviorError를 발생시켜요. OpenAIResponsesModel과 AnyLLMModel의 Responses 경로에 적용돼요. 자세한 내용은 Exceptions를 참고하세요.
OpenAIProvider는 이제 openai_client를 organization이나 project와 조합하면 UserError도 발생시켜요. api_key, base_url, websocket_base_url과의 기존 충돌은 그대로예요. 이런 값들은 명시적 AsyncOpenAI 클라이언트에서 구성하세요. 자세한 내용은 API keys and clients를 참고하세요.
각 RunResult.to_state() 체크포인트는 이제 독립적인 사용량 스냅샷을 소유해요. 재개된 결과는 체크포인트 합계에서 시작해 자기 모델 호출을 더하며, 원본 결과나 형제 체크포인트를 변형하지 않아요. 중첩된 Agent.as_tool() 재개는 재개 후 사용량을 활성 바깥 실행으로 계속 집계해요. 자세한 내용은 Usage in RunState checkpoints를 참고하세요.
에이전트 시각화는 이제 handoff(agent)로 등록된 대상의 도구·MCP 서버·하위 handoff를 재귀적으로 확장해, 에이전트 handoffs 목록의 직접 Agent 항목과 일치시켜요. 자세한 내용은 Generating a graph를 참고하세요.
Agent.clone()·RealtimeAgent.clone() API 안내는 이제 기존 얕은 복사(shallow-copy) 동작을 정확히 명시해요. 재정의되지 않은 리스트 속성은 같은 리스트 객체로 남아요. 클론이 컨테이너를 독립적으로 소유해야 한다면 새 리스트를 넘기세요. 자세한 내용은 Cloning/copying agents를 참고하세요.

0.21.0

버전 0.21.0은 openai v3을 요구하고 Agents SDK의 OpenAI HTTP 통합을 HTTPX2로 옮겨요. 기본 OpenAI 클라이언트를 쓰는 애플리케이션은 클라이언트 설정을 바꿀 필요가 없지만, OpenAI HTTP 계층을 커스터마이즈한 애플리케이션은 transport-facing 코드를 마이그레이션해야 할 수 있어요.

하이라이트:

요구되는 OpenAI 의존성이 이제 openai>=3.0.0,<4예요. 깨끗한 코어 설치는 HTTPX2를 쓰고 레거시 httpx를 직접 의존성으로 설치하지 않아요.
기본 OpenAI 프로바이더·Voice 프로바이더·Responses WebSocket 지원·tracing exporter·프로바이더 재시도 정규화가 이제 HTTPX2를 써요. 기존 Agents SDK 공개 구성과 런타임 동작은 그대로예요.
AsyncOpenAI에 http_client=를 넘기는 애플리케이션은 커스텀 클라이언트·transport·인증·이벤트 훅·mock transport·타임아웃 값·URL·요청·응답·transport 예외 처리를 httpx에서 httpx2로 마이그레이션해야 해요. 애플리케이션이 OpenAI 클라이언트 기본값에 커스텀 HTTP 옵션을 더해 써야 한다면 OpenAI Python SDK의 DefaultAsyncHttpx2Client를 선호하세요. 자세한 내용은 Custom HTTP clients with openai v3를 참고하세요.
Agents SDK는 임의의 레거시 HTTPX 객체를 HTTPX2로 변환하지 않아요. OpenAI Python SDK의 임시 레거시 클라이언트 호환 경로는 명시적 httpx 설치가 필요하며 마이그레이션 브리지로 취급해야 해요.
로컬 MCP HTTP 커스터마이즈는 설치된 MCP 패키지를 따릅니다. MCP Python SDK v1은 레거시 httpx를 제공·사용하고, MCP Python SDK v2는 httpx2를 사용해요. 일반 MCP 연결에는 애플리케이션 변경이 필요 없어요. 자세한 내용은 MCP Python SDK v1 and v2를 참고하세요.
공개 프로바이더 중립 테스트 유틸리티가 이제 Agent 모델·Sandbox 세션·Realtime 세션·Voice pipeline 워크플로를 프로바이더·프로세스 의존성 없이 다뤄요. 레시피와 실제 프로바이더 어댑터나 통합 경계를 언제 유지할지에 대한 안내는 Testing을 참고하세요.

0.20.0

버전 0.20.0은 로컬 MCP HTTP transport를 커스터마이즈하는 애플리케이션에 잠재적으로 파괴적인 MCP 의존성 마이그레이션을 포함해요. 또한 에이전트나 실행이 명시적으로 하나를 선택하지 않을 때 쓰는 SDK 기본 모델도 업데이트해요.

하이라이트:

SDK 기본 모델이 gpt-5.4-mini에서 gpt-5.6-luna로 바뀌었어요. 기본 reasoning.effort="none"과 verbosity="low" 설정은 그대로예요.
명시적 에이전트 모델·실행 수준 모델 재정의·OPENAI_DEFAULT_MODEL 환경 변수는 SDK 기본값보다 계속 우선해요.
Realtime 입력 전사(transcription) 설정이 이제 gpt-transcribe, gpt-live-transcribe, gpt-realtime-whisper를 인식해요. 저지연 gpt-live-transcribe 세션의 경우 중첩된 audio.input.transcription 설정이 prompt, keywords, 여러 기대 언어를 제공할 수 있어요. 이 SDK가 고정한 OpenAI 클라이언트 버전은 delay 지연/정확도 수준을 gpt-realtime-whisper에서만 지원해요. 커밋된 오디오 턴 이후 전사나 감지된 언어 출력은 WebSocket 위 gpt-transcribe를 쓰세요. audio.input.turn_detection=None으로 명시적으로 설정하면 자동 턴 감지를 비활성화해요. 자세한 내용은 Input transcription settings를 참고하세요.
Agents SDK가 만든 로컬 MCP 연결은 이제 MCP Python SDK v2를 지원하면서, mcp>=1.19.0,<3을 통해 v1 호환성도 유지해요. Agents SDK는 일반 stdio·SSE·Streamable HTTP 연결을 자동으로 적응시켜요. MCP v2가 설치되면 이 연결들은 mcp.Client(mode="auto")로 최신 지원 프로토콜을 탐색하고, 더 오래된 서버에는 레거시 initialize 핸드셰이크로 폴백해요. 의존성 해석이 MCP v2를 선택하면, 커스텀 httpx.Auth 객체나 httpx.AsyncClient 팩토리를 공급하는 애플리케이션은 그 값들을 httpx2로 마이그레이션하거나 v1 HTTP 스택을 유지하려면 mcp<2로 고정해야 해요. MCPServerStreamableHttp의 params["ignore_initialized_notification_failure"] = True 옵션도 v1 전용으로 남아요. 마이그레이션 세부 사항은 MCP Python SDK v1 and v2를 참고하세요.
샌드박스 마운트 검증이 이제 샌드박스나 마운트 헬퍼 부수 효과 전에 안전하지 않은 자격 증명 배치를 거부해요. 신뢰하는 애플리케이션은 저장 기능 테이블을 바꾸지 않고도 정확한 in-container 마운트 경로에 대한 mount-scoped 또는 광범위 자격 증명 노출을 인정할 수 있어요. 이 인정(acknowledgement)은 런타임 전용이며, 직렬화된 샌드박스 상태는 그 자체로 자격 증명 권한을 부여하지 않아요. 보호된 마운트 경계에서 SDK는 새 redacted 예외를 돌려줘요. 원본 예외가 정확히 인식된 SDK 샌드박스 오류이고 승인된 구조화 필드가 검증되면, 교체 예외는 그 하위 타입과 검증된 안전 필드를 유지해요. 인식된 MountConfigError는 SDK가 생성한 안전한 검증 메시지도 유지할 수 있어요. 그렇지 않으면 SDK는 새 일반 redacted 오류를 돌려줘요. 프로바이더 제어 또는 승인되지 않은 메시지·명령 데이터·메모·컨텍스트·원인·원본 traceback 상태는 유지되지 않아요. 자세한 내용은 Mounts and remote storage와 Resume from session state를 참고하세요.
재시도 정책이 안정적인 재생 안전 사실을 검사하고, 프로바이더가 안전하지 않다고 표시한 비스트리밍 요청에 명시적으로 RetryDecision(approve_unsafe_replay=True)를 설정할 수 있어요. 이 승인은 abort·방출된 스트리밍 출력·Programmatic Tool Calling 같은 별도의 로컬 부수 효과 거부를 우회하지 않아요. 자세한 내용은 Runner-managed retries를 참고하세요.
재개 가능한 RunState 객체는 이제 다음 모델 호출 전에 add_input()으로 지속적인(durable) 사용자 입력을 스테이징할 수 있어요. 스테이징된 입력은 직렬화를 견디고, 입력 guardrail을 통과하며, 로컬 세션과 서버 관리 대화에서 하나의 지속 SDK 입력 항목을 만들어요. 명시적으로 승인된 안전하지 않은 재생은 여전히 입력을 프로바이더에 재전송해 프로바이더 측 작업을 반복할 수 있어요. 자세한 내용은 Add input before resuming을 참고하세요.
런타임 신뢰성 수정이 스트리밍·비스트리밍 출력-guardrail 세션 영속화를 정렬시키고, 복사·네임스페이스 중 FunctionTool 서브클래스를 보존하며, 지원되지 않는 Chat Completions 오디오 출력에 대해 빈 스트림을 조용히 완료하는 대신 명시적 오류를 발생시켜요. OpenAIResponsesCompactionSession 래퍼는 취소가 호출자에게 도달하기 전에 압축 전 기록 복구를 시도·대기해요. VoicePipeline 소비자는 깨끗한 실행 후 전사 세션 닫기 실패를 받고, 더 이른 턴 실패가 더 늦은 닫기 실패보다 우선해요. RunState 왕복은 로컬 셸 출력·승인된 컴퓨터 안전 검사·기본값 지정 도구 출력 필드·딕셔너리/리스트/튜플을 탐색 중 만난 Pydantic 모델이나 dataclass 출력을 보존해요. MCP 변환은 자유꼴 객체 스키마와 이미지 출력을 보존하고, 오디오·리소스 블록 같은 다른 원시 콘텐츠 블록을 유효한 JSON 텍스트로 직렬화해요. MCPServerManager는 겹치는 lifecycle 연산을 직렬화하고 연결·정리에 유한 기본 타임아웃을 적용해요. 모델 재생은 출력 항목을 입력으로 쓰기 전에 서버 소유 created_by 메타데이터를 제거해요.

0.19.0

이 minor 릴리스는 파괴적 변경을 도입하지 않아요. minor 버전 상승은 중요한 새 OpenAI Responses 기능 영역인 Programmatic Tool Calling을 반영해요.

하이라이트:

Programmatic Tool Calling 자격이 있는 도구를 조정하기 위해 지원되는 OpenAI Responses 모델이 JavaScript를 생성하게 하는 ProgrammaticToolCallingTool을 추가했어요. 도구별 allowed_callers, FunctionTool 인스턴스의 구조화 출력, Runner 스트리밍·guardrail·승인·세션·RunState 통합을 지원해요. 설정과 제약은 Programmatic Tool Calling을 참고하세요.
공개 agents.decorators 모듈과 기존 @function_tool 데코레이터의 짧은 별칭인 @tool을 기존 guardrail 데코레이터와 함께 추가했어요. FunctionTool 인스턴스는 이제 async callable 객체도 지원해요.
SDK 구성이 이제 에이전트·실행·모델·세션·샌드박스·voice pipeline 전반에서 타이핑된 설정 객체나 딕셔너리 어느 쪽이든 일관되게 받고, 알 수 없는 설정은 검증해요.
모델·도구·MCP·Realtime·세션·샌드박스·tracing 전반의 오류·진단 로깅을 강화해 유용한 디버깅 컨텍스트를 보존하면서 원시 민감 페이로드 노출을 피했어요.
AnyLLM·LiteLLM·Chat Completions 호환성, 모델 재시도 간 세션 기록 보존을 개선했고, 응답이 시작되기 전에 발생하는 WebSocket 과부하에 대한 프로바이더 재시도 안내를 추가해, opt-in Runner 재시도 정책이 허용될 때 실패한 시도를 재생할 수 있게 했어요.
S3 마운트를 추가했는데, Vercel 샌드박스가 VercelCloudBucketMountStrategy로 만들어질 때만 구성할 수 있어요. 마운트된 세션은 버킷 내용물을 작업 공간 영속성에서 제외하고, 의도적으로 동적 마운트 변경이나 세션 재개를 지원하지 않아요.

0.18.0

이 minor 릴리스는 파괴적 변경을 도입하지 않아요. minor 버전 상승은 Realtime 에이전트 기본 모델 업데이트만 반영해요.

하이라이트:

Realtime 에이전트가 이제 기본 모델로 gpt-realtime-2.1을 사용해, 새 Realtime 설정은 추가 구성 없이 최신 권장 모델을 사용해요.

0.17.0

이 버전에서 샌드박스 로컬 소스 구체화(materialization)는 LocalFile.src와 LocalDir.src를, 그 소스 경로가 Manifest.extra_path_grants로 커버되지 않는 한 materialization base_dir 안에 유지해요. base_dir은 매니페스트가 적용될 때의 SDK 프로세스 현재 작업 디렉터리예요. 상대 로컬 소스는 그 디렉터리에서 해석되고, 절대 로컬 소스는 이미 그 안에 있거나 명시적 grant 아래 있어야 해요. 이것은 로컬 아티팩트 경계 문제를 닫지만, 의도적으로 그 base 디렉터리 밖에서 신뢰하는 호스트 파일·디렉터리를 샌드박스 작업 공간으로 복사하던 애플리케이션에 영향을 줄 수 있어요.

마이그레이션하려면 SandboxPathGrant로 매니페스트 수준에서 신뢰하는 호스트 루트를 grant하세요. 샌드박스가 그 파일을 읽기만 하면 될 때는 가능하면 read-only로요.

from pathlib import Path

from agents.sandbox import Manifest, SandboxPathGrant
from agents.sandbox.entries import Dir, LocalDir

# This is an absolute host path outside the SDK process base_dir.
TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")

manifest = Manifest(
    extra_path_grants=(
        # This host root is outside the SDK process base_dir, so the manifest must grant it.
        SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
    ),
    entries={
        # No grant is needed for local sources that stay under the SDK process base_dir.
        "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
        # This entry reads from the granted host root and copies it into the sandbox workspace.
        "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
        # Dir creates a sandbox workspace directory; it does not read from the host filesystem.
        "output": Dir(description="Generated artifacts."),
    },
)

extra_path_grants를 신뢰하는 애플리케이션 구성으로 취급하세요. 애플리케이션이 이미 그 호스트 경로를 승인하지 않았다면 grant를 모델 출력이나 다른 신뢰할 수 없는 매니페스트 입력으로 채우지 마세요.

0.16.0

이 버전에서 SDK 기본 모델이 gpt-4.1에서 gpt-5.4-mini로 바뀌었어요. 모델을 명시적으로 설정하지 않은 에이전트와 실행에 영향을 줘요. 새 기본값이 GPT-5 모델이므로, 암시적 기본 모델 설정에 이제 reasoning.effort="none", verbosity="low" 같은 GPT-5 기본값이 포함돼요.

이전 기본 모델 동작을 유지해야 한다면 에이전트나 실행 구성에 모델을 명시적으로 설정하거나 OPENAI_DEFAULT_MODEL 환경 변수를 설정하세요.

agent = Agent(name="Assistant", model="gpt-4.1")

하이라이트:

Runner.run, Runner.run_sync, Runner.run_streamed가 이제 턴 제한을 끄는 max_turns=None을 받아요.
샌드박스 작업 공간 하이드레이션이 이제 로컬·Docker·프로바이더 지원 샌드박스 구현 전반에서 절대 심볼릭 링크 대상 등 아카이브 루트 밖을 가리키는 symlink가 든 tar 아카이브를 거부해요.

0.15.0

이 버전에서 모델 거부(refusal)가 이제 빈 텍스트 출력 취급이나(구조화 출력의 경우) MaxTurnsExceeded까지 재시도하는 대신 ModelRefusalError로 명시적으로 표면화돼요.

이전에 거부 전용 모델 응답이 final_output == ""로 완료되길 기대하던 코드에 영향을 줘요. 발생시키지 않고 거부를 처리하려면 model_refusal 실행 오류 핸들러를 제공하세요.

result = Runner.run_sync(
    agent,
    input,
    error_handlers={"model_refusal": lambda data: data.error.refusal},
)

구조화 출력 에이전트의 경우 핸들러는 에이전트의 출력 스키마와 일치하는 값을 반환할 수 있고, SDK는 그걸 다른 실행 오류 핸들러 최종 출력처럼 검증해요.

0.14.0

이 minor 릴리스는 파괴적 변경을 도입하지 않지만, 주요 새 베타 기능 영역인 Sandbox Agents와, 로컬·컨테이너·호스팅 환경에서 쓰기 위한 런타임·백엔드·문서 지원을 추가해요.

하이라이트:

SandboxAgent, Manifest, SandboxRunConfig를 중심으로 새 베타 샌드박스 런타임 표면을 추가해, 에이전트가 파일·디렉터리·Git 저장소·마운트·스냅샷·재개를 지원하는 영속 격리 작업 공간 안에서 동작하도록 했어요.
UnixLocalSandboxClient, DockerSandboxClient를 통한 로컬·컨테이너 개발용 샌드박스 실행 백엔드와, Python 패키지의 선택적 의존성 extras를 통한 Blaxel·Cloudflare·Daytona·E2B·Modal·Runloop·Vercel 호스팅 프로바이더 통합을 추가했어요.
이후 실행이 이전 실행의 교훈을 재사용할 수 있는 샌드박스 메모리 지원을 추가했어요. 점진적 공개(progressive disclosure), 다중 턴 그룹화, 구성 가능한 격리 경계, S3 지원 워크플로를 포함한 영속 메모리 예제를 지원해요.
로컬·합성 작업 공간 항목, S3/R2/GCS/Azure Blob Storage/S3 Files용 원격 저장소 마운트, 휴대용 스냅샷, RunState·SandboxSessionState·저장된 스냅샷을 통한 재개 흐름을 포함한 더 넓은 작업 공간·재개 모델을 추가했어요.
examples/sandbox/ 아래에 상당한 샌드박스 예제와 튜토리얼을 추가했어요. skills를 사용한 코딩 작업, handoff, 메모리, 프로바이더별 설정, 코드 리뷰·데이터룸 QA·웹사이트 클로닝 같은 end-to-end 워크플로를 다뤄요.
샌드박스 인지 세션 준비·기능 바인딩·상태 직렬화·통합 tracing·프롬프트 캐시 키 기본값·더 안전한 민감 MCP 출력 편집으로 코어 런타임·tracing 스택을 확장했어요.

0.13.0

이 minor 릴리스는 파괴적 변경을 도입하지 않지만, 주목할 Realtime 기본값 업데이트와 새 MCP 기능·런타임 안정성 수정을 포함해요.

하이라이트:

기본 websocket Realtime 모델이 이제 gpt-realtime-1.5라서, 새 Realtime 에이전트 설정은 추가 구성 없이 더 새로운 모델을 사용해요.
MCPServer가 이제 list_resources(), list_resource_templates(), read_resource()를 노출하고, MCPServerStreamableHttp는 session_id를 노출해서 MCP Streamable HTTP transport를 쓰는 세션을 재연결이나 상태 없는 워커 간에 재개할 수 있게 됐어요.
Chat Completions 통합이 이제 should_replay_reasoning_content로 기존 reasoning 콘텐츠 재전송을 선택할 수 있어, LiteLLM/DeepSeek 같은 어댑터의 프로바이더별 reasoning/도구 호출 연속성을 개선해요.
SQLAlchemySession의 동시 첫 쓰기, reasoning 제거 후 고아 어시스턴트 메시지 ID가 있는압축 요청, remove_all_tools()가 MCP/reasoning 항목을 남기던 문제, FunctionTool 인스턴스의 batch executor 경쟁 등 여러 런타임·세션 엣지 케이스를 수정했어요.

0.12.0

이 minor 릴리스는 파괴적 변경을 도입하지 않아요. 주요 기능 추가는 릴리스 노트를 확인하세요.

0.11.0

이 minor 릴리스는 파괴적 변경을 도입하지 않아요. 주요 기능 추가는 릴리스 노트를 확인하세요.

0.10.0

이 minor 릴리스는 파괴적 변경을 도입하지 않지만, OpenAI Responses 사용자에게 중요한 새 기능 영역인 Responses API의 websocket transport 지원을 포함해요.

하이라이트:

OpenAI Responses 모델용 websocket transport 지원을 추가했어요(opt-in이고 HTTP가 기본 transport로 남아요).
다중 턴 실행에 걸쳐 공유 websocket 지원 프로바이더와 RunConfig를 재사용하기 위한 responses_websocket_session() 헬퍼 / ResponsesWebSocketSession을 추가했어요.
스트리밍·도구·승인·후속 턴을 다루는 새 websocket 스트리밍 예제(examples/basic/stream_ws.py)를 추가했어요.

0.9.0

이 버전에서 Python 3.9는 더 이상 지원되지 않아요. 이 메이저 버전이 3개월 전에 EOL에 도달했거든요. 더 새로운 런타임 버전으로 업그레이드하세요.

또한 Agent#as_tool() 메서드가 반환하는 값의 타입 힌트가 Tool에서 FunctionTool로 좁혀졌어요. 이 변경은 보통 파괴적 문제를 일으키지 않지만, 코드가 더 넓은 union 타입에 의존한다면 약간의 조정이 필요할 수 있어요.

0.8.0

이 버전에서 두 가지 런타임 동작 변경이 마이그레이션 작업을 요구할 수 있어요.

동기 Python callable을 감싸는 FunctionTool 인스턴스가 이제 이벤트 루프 스레드 대신 asyncio.to_thread(...)로 워커 스레드에서 실행돼요. 도구 로직이 thread-local 상태나 thread-affine 리소스에 의존한다면 async 도구 구현으로 마이그레이션하거나 도구 코드에서 스레드 선호도를 명시적으로 만드세요.
로컬 MCP 도구 실패 처리가 이제 구성 가능하고, 기본 동작이 전체 실행을 실패시키는 대신 모델이 볼 수 있는 오류 출력을 반환할 수 있어요. fail-fast 의미론에 의존한다면 mcp_config={"failure_error_function": None}으로 설정하세요. 서버 수준 failure_error_function 값이 에이전트 수준 설정보다 우선하므로, 명시적 핸들러가 있는 각 로컬 MCP 서버에 failure_error_function=None을 설정하세요.

0.7.0

이 버전에서 기존 애플리케이션에 영향을 줄 수 있는 몇 가지 동작 변경이 있었어요.

중첩 handoff 기록이 이제 opt-in이에요(기본적으로 꺼짐). v0.6.x 기본 중첩 동작에 의존했다면 RunConfig(nest_handoff_history=True)를 명시적으로 설정하세요.
gpt-5.1 / gpt-5.2의 기본 reasoning.effort가 "low"(이전 SDK 기본값이 구성한 값)에서 "none"으로 바뀌었어요. 프롬프트나 품질/비용 프로필이 "low"에 의존했다면 model_settings에서 명시적으로 설정하세요.

0.6.0

이 버전에서 기본 handoff 기록이 이제 사용자 턴과 어시스턴트 턴을 별도 메시지로 넘기는 대신 단일 어시스턴스 메시지로 패키징돼, 하위 에이전트에게 간결하고 예측 가능한 요약을 줘요.

기존 단일 메시지 handoff 대본은 이제 <CONVERSATION HISTORY> 블록 앞에 "For context, here is the conversation so far between the user and the previous agent:"라는 정확한 리터럴 텍스트로 기본 시작돼, 하위 에이전트가 명확히 표시된 요약을 받아요.

0.5.0

이 버전은 보이는 파괴적 변경을 도입하지 않지만, 새 기능과 몇 가지 중요한 내부 업데이트를 포함해요.

RealtimeRunner에서 SIP 프로토콜 연결 처리 지원을 추가했어요.
Python 3.14 호환성을 위해 Runner#run_sync의 내부 로직을 대폭 수정했어요.

0.4.0

이 버전에서 openai 패키지 v1.x 버전은 더 이상 지원되지 않아요. 이 SDK와 함께 openai v2.x를 사용하세요.

0.3.0

이 버전에서 Realtime API 지원이 gpt-realtime 모델과 그 API 인터페이스(GA 버전)로 마이그레이션돼요.

0.2.0

이 버전에서 예전에 Agent를 인자로 받던 몇몇 위치가 이제 AgentBase를 인자로 받아요. 예를 들어 MCP 서버의 list_tools() 메서드 시그니처에 적용돼요. 이것은 순수 타이핑 변경이라 여전히 Agent 객체를 받아요. 업데이트하려면 Agent를 AgentBase로 바꿔 타입 오류만 수정하면 돼요.

0.1.0

이 버전에서 MCPServer.list_tools()에 run_context와 agent라는 두 개의 새 파라미터가 추가됐어요. MCPServer의 서브클래스에서 재정의한 모든 MCPServer.list_tools() 메서드에 이 파라미터를 추가해야 해요.

더 알아보기 (Learn more)

OpenAI Agents SDK 문서에서 더 많은 가이드를 확인하세요.