OpenAI Agents SDK

핸드오프와 가드레일을 갖춘 공식 에이전트 SDK

uv add openai-agents

OpenAI 가 만든 멀티 에이전트 워크플로 SDK 입니다. 에이전트 사이 핸드오프와 입출력 가드레일, 실행 추적을 기본으로 제공합니다. Responses API 와 Chat Completions 를 모두 지원해 다른 프로바이더에도 붙습니다.

판단

이럴 때 씁니다

  • 역할이 다른 에이전트 사이에 작업을 넘기는 구조를 만들 때
  • 입력과 출력에 가드레일을 걸어 원치 않는 응답을 막아야 할 때
  • 실행 과정을 추적해 어디서 어긋났는지 확인해야 할 때
  • Responses API 와 Chat Completions 를 함께 지원해야 할 때

이럴 땐 쓰지 마세요

  • 단일 에이전트로 끝나는 단순한 작업일 때
  • 프레임워크 없이 API 를 직접 호출하는 편이 명확할 때
  • 파이썬이 아닌 스택일 때. 이 경우 JS 판을 확인합니다

차별점

  • 에이전트 사이 핸드오프를 1급 개념으로 다룹니다.
  • 입출력 가드레일과 실행 추적을 기본 제공합니다.
  • 프로바이더에 묶이지 않아 다른 모델에도 붙습니다.
  • OpenAI 가 직접 관리하는 공식 SDK 입니다.

워크플로

  1. 01uv add openai-agents 로 설치합니다.
  2. 02역할별 에이전트를 정의하고 핸드오프 관계를 지정합니다.
  3. 03입출력 가드레일을 붙여 허용 범위를 좁힙니다.
  4. 04실행 추적을 켜고 실패 지점을 확인하며 조정합니다.

주요 명령

명령설명
uv add openai-agents프로젝트에 설치합니다.
pip install openai-agentsuv 를 쓰지 않을 때의 설치 경로입니다.

함정

설치 전에 확인하세요

  • clone 메서드는 얕은 복사입니다. 공유되는 객체를 바꾸면 원본에도 영향을 줍니다.
  • 프로바이더 옵션과 명시적 클라이언트를 동시에 넘기면 최근 버전에서 거부됩니다.
  • 스트리밍이 아닌 응답이 실패나 미완료 상태로 끝나면 예외가 발생하도록 바뀌었습니다. 기존 코드의 오류 처리를 확인해야 합니다.

비교

smolagents 가 최소 뼈대라면 이쪽은 운영에서 필요한 장치를 먼저 갖춘 쪽입니다. 가드레일과 추적이 필요 없다면 무게가 느껴질 수 있습니다. 반대로 여러 에이전트가 작업을 주고받는 구조라면 직접 만들 때 걸리는 시간을 크게 줄여 줍니다.

최근 변경

v0.22.2에서는 최신 이미지 생성 도구 옵션 지원을 추가하고 UnixLocal 파일 API의 심볼릭 링크 경쟁 조건을 차단했으며, 세션 pop 이후 compaction response chain을 초기화하는 수정이 반영됐습니다.

공식 변경 내역