Agents API는 애플리케이션에 OpenAI가 관리하는 API를 통해 Codex 하니스(harness) 접근 권한을 제공합니다.
OpenAI는 세션 관리, 오케스트레이션(orchestration), 컨텍스트 압축(context compaction), 복구(recovery) 등을 담당하며, 사용자의 애플리케이션은 도구를 제공하고 실행 환경을 선택하는 역할을 합니다.
Agents는 샌드박스에서 작동할 수 있으며, 이곳에서 코드를 실행하고, 파일을 편집하며, MCP 서버에 연결하고, 아티팩트(artifacts)를 생성할 수 있습니다.
엔드포인트, 요청 매개변수 및 응답 필드는 API 레퍼런스를 참조하십시오.
가격 책정 (Pricing)
모델 사용량은 선택된 모델의 API 요율로 청구됩니다. OpenAI 도구는 표준 요율을 사용하며, OpenAI가 호스팅하는 샌드박스는 표준 컨테이너 요율을 사용합니다.
예제 시도하기 (Try an example)
다음 전체 예제들을 시도해 보세요:
- OpenAI가 호스팅하는 샌드박스에서 디렉터리 트리 스크립트를 생성하고 실행합니다.
- 서브 에이전트(subagents)와 비교하여 릴리스 노트를 검토하고 그 결과를 하나의 답변으로 결합합니다.
완성된 애플리케이션 탐색:
- 인시던트 대응 에이전트: 경고를 조사하고 복구 조치에 대한 승인을 요청합니다.
- Slack 봇: 연결된 워크플레이스 도구를 사용하여 요청을 조사합니다.
- 데이터 분석가: 읽기 전용 SQL로 웨어하우스 질문에 답변합니다.
- GitHub 이슈 조사관을 사용하여 보고된 버그를 재현하고 그 결과를 GitHub에 공유합니다.
- 문서 검토기를 사용하여 정책 기술(policy skills) 및 전문 에이전트로 문서를 검토합니다.
핵심 개념 (Core concepts)
Agents API는 네 가지 주요 개념을 중심으로 구축되었습니다:
Agent: 모델, 지침(instructions), 도구(tools), 그리고 Agent가 사용할 수 있는 MCP 서버입니다.Environment: 에이전트가 파일에 접근하고, 기술을 로드하며, 명령을 실행할 수 있는 선택적 샌드박스 또는 컴퓨터 환경입니다.Session: 작업을 수행하고 입력에 응답하는 에이전트의 영속적인 인스턴스입니다.Events and items: 에이전트에게 전송되는 입력과 세션 중에 생성되는 출력물입니다.
시작부터 끝까지의 세션 (A session from start to finish)
빠른 시작 가이드에서 OpenAI가 호스팅하는 샌드박스로 시작하세요:
세션 생성. 에이전트를 구성하고, OpenAI가 환경을 제공합니다.작업 부여. 사용자의 입력은 환경 준비가 완료되면 작업의 한 턴(turn)을 시작합니다.진행 상황 추적. 스트리밍 출력 또는 웹훅(webhook)을 사용하여 에이전트가 완료되거나 입력이 필요할 때 알림을 받습니다.계속하거나 방향 조정. 동일한 세션에 다른 작업을 보내거나 현재 턴 동안 에이전트를 안내할 수 있습니다.
OpenAI에서 호스팅하는 세션을 사용하면, 애플리케이션은 입력을 보내고 이벤트를 받고, OpenAI가 에이전트를 실행하고 샌드박스(sandbox)를 제공 및 관리합니다. 설정 및 제한 사항에 대해서는 환경 옵션(environment options)을 참조하세요.
Your application starts sessions and receives events and output from the Agents API. OpenAI runs the managed Codex harness and provisions and manages its sandbox.
관리형 하네스(managed harness)가 제공하는 기능
관리형 Codex 하네스는 다음 기능을 지원합니다:
- 샌드박스에서 명령어 및 코드 실행.
- 관련 기술(skills) 및 지침 적용.
- 도구(tools) 또는 MCP를 통해 외부 데이터 연결.
- 에이전트 작업 중 방향 조정(steering).
- 컨텍스트 창을 관리하기 위해 이전 작업 요약.
- 작업을 하위 작업으로 분할하고 하위 에이전트에게 위임.
- 이전에 멈춘 세션 재개.
API 키 권한 및 SDK 설정에 대한 빠른 시작 전제 조건(quickstart prerequisites)을 확인하세요. 다음 코드를 사용하여 세션을 생성할 때 이러한 기능을 구성합니다:
from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
...
런타임 비교를 보려면 에이전트 개요(Agents overview)를 참조하세요.
에이전트 API를 기반으로 구축된 AWS 서비스는 Bedrock Managed Agents를 참조하세요.
에이전트 API는 세션 상태를 유지하므로 대화 컨텍스트를 재구축할 필요 없이 턴을 거쳐 작업을 계속할 수 있습니다. 더 이상 필요하지 않은 경우 세션과 게시된 아티팩트(artifacts)를 삭제할 수 있습니다. 에이전트 API는 현재 미국 내에서만 데이터 상주지(data residency)를 지원하며, 제로 데이터 보존(Zero Data Retention, ZDR)은 지원하지 않습니다. 자체 호스팅 샌드박스를 선택하더라도 에이전트 API가 ZDR 자격을 갖추게 되지는 않습니다. 데이터 상주지 및 보존에 대한 자세한 내용은 OpenAI 플랫폼의 데이터 제어(Data controls)를 참조하세요.
