OpenAI Agents API 완전 정복: 실전 구축 가이드

TL;DR

OpenAI Agents API가 2026년 9월 10일 퍼블릭 베타로 공개됐다.
Codex 하네스 기반으로 멀티 에이전트 오케스트레이션, MCP 서버 연동, 컨텍스트 자동 압축을 지원한다.
별도 추가 요금 없이 토큰·도구 사용량만 과금되며, 2026년 10월 5일부터 청구가 시작된다.
DevDay 2026에서 컴퓨터 사용(computer use) 기능이 추가됐다.
정식 GA 일정, 한국 리전 지원 여부는 아직 공식 확인되지 않았다.

Agents API란 무엇인가

OpenAI가 공식 발표한 Agents API는 개발자가 OpenAI 관리형 Codex 에이전트를 활용해 여러 단계에 걸친 작업을 수행하는 애플리케이션을 만들 수 있도록 설계된 API다. 기존 Chat Completions API가 단일 요청-응답 구조였다면, Agents API는 세션(session) 개념을 도입해 동일 세션 안에서 작업을 이어가거나 추가 지시를 전달할 수 있다.

핵심 설계 철학은 역할 분리다. 개발자는 작업(task)·도구(tools)·설정(configuration) 을 정의하고, 에이전트 세션 관리와 모델-도구 간 조율은 OpenAI 인프라가 전담한다. 즉, 개발자는 "에이전트가 무엇을 할 것인가"에만 집중할 수 있다.

핵심 기능 4가지

공식 가이드 문서에 명시된 주요 기능은 다음과 같다.

1. 자동 컨텍스트 압축(Context Compaction)
긴 작업 흐름에서 컨텍스트 윈도우가 초과되기 전에 자동으로 압축한다. 개발자가 별도로 컨텍스트를 관리하지 않아도 된다.

2. 멀티 에이전트 오케스트레이션
단일 에이전트가 아니라 여러 서브에이전트가 협력해 복잡한 작업을 분담 처리할 수 있다. Codex의 멀티 에이전트 기능이 API 레벨에서 그대로 활용 가능하다.

3. MCP 서버 지원
Model Context Protocol(MCP) 서버를 연결해 외부 데이터 소스나 도구를 에이전트에 통합할 수 있다. GitHub, Notion 등 MCP를 지원하는 서비스라면 직접 연동이 가능하다.

4. 컴퓨터 사용(Computer Use)
DevDay 2026에서 추가된 기능으로, OpenAI가 호스팅하는 브라우저를 통해 에이전트가 웹사이트와 직접 상호작용할 수 있다. 예컨대 에이전트가 특정 웹 UI를 클릭하고 폼을 작성하는 작업을 자동화할 수 있다.

빠르게 시작하기: 세 단계

공식 퀵스타트를 기반으로 정리했다.

1단계: API 키 발급 및 권한 설정

OpenAI Platform 프로젝트에서 API 키를 생성할 때 다음 세 가지 권한을 반드시 포함해야 한다.

api.agents.read
api.agents.write (세션 작업용)
api.responses.write (모델 추론용)

발급 후 환경 변수로 내보낸다.

export OPENAI_API_KEY="your-api-key"

2단계: SDK 설치 및 베타 헤더 확인

pip install --upgrade openai

모든 Agents API 요청에는 OpenAI-Beta: agents=v1 헤더가 필요하다. Python SDK를 사용하면 이 헤더가 자동으로 추가되므로 별도 설정이 필요 없다. cURL로 직접 요청할 때는 명시적으로 포함해야 한다.

3단계: 작업 제출 예시

Python SDK에서는 beta.agents 네임스페이스를 통해 세션을 생성하고 작업을 제출한다. 공식 문서가 제시하는 예시 태스크는 다음과 같다.

"Create tree.py, a Python script that prints a readable tree of the files
in the current directory. Run it and show me the output."

이처럼 자연어로 작업을 정의하면 에이전트가 코드를 작성하고, 실행하고, 결과를 반환하는 전 과정을 처리한다. 실행 환경에 따라 파일 편집, 코드 실행, 파일 생성도 가능하다.

세션 모니터링: 대시보드 활용

공식 FAQ에 따르면 Platform 대시보드에서 Logs → Agents 메뉴를 열면 세션 ID 기준으로 검색할 수 있다. 각 세션의 턴(turn), 도구 호출 내역, 서브에이전트 활동을 상세히 확인할 수 있어 디버깅과 비용 모니터링에 유용하다.

요금 구조: 지금 알아야 할 것

공식 Changelog에 따르면 Agents API는 퍼블릭 베타 기간 동안 별도 추가 요금이 없으며, 에이전트가 소비하는 토큰과 도구 사용량에 대해서만 과금된다. 단, 2026년 10월 5일부터 청구가 시작됐음을 유의해야 한다.

DevDay에서 함께 소개된 GPT‑6.1 Sol은 에이전트 코딩·컴퓨터 사용·전문 업무에서 높은 성능을 보이며, 기존 Astra 표준 입출력 토큰 가격의 5분의 1 수준으로 제공될 예정이다. 다만 Sol은 현재 출시 예정(coming soon) 상태로, 즉시 사용 가능한 것은 Astra 모델이다.

아직 확인되지 않은 것들

독자가 프로덕션 도입을 검토한다면 아래 항목은 반드시 공식 채널을 통해 직접 확인해야 한다.

항목	현재 상태
정식 GA(General Availability) 출시일	미정, 퍼블릭 베타 진행 중
한국 리전 지원 여부	공식 문서에서 별도 언급 없음
베타 종료 후 최종 요금 체계	미확정
GPT-6.1 Sol 정식 출시 시점	Coming soon 상태
Decisions API 일반 공개 시점	제한적 미리보기(limited preview) 중

정리

Agents API는 "에이전트 인프라를 직접 구축하지 않고 에이전트 앱을 만들고 싶은" 개발자에게 실질적인 선택지를 제공한다. Codex 하네스가 세션 관리와 모델-도구 조율을 처리하므로, 개발팀은 비즈니스 로직과 도구 설계에 집중할 수 있다. 현재 퍼블릭 베타 단계이므로 프로덕션 투입 전에 공식 커뮤니티 공지와 Changelog를 주기적으로 확인하는 것을 권장한다.

참고 자료

커버 이미지: Google DeepMind / Rose Pilkington · Unsplash License. 본문 이해를 돕기 위한 자료 이미지이며 제품 화면은 아닙니다.