관리형 에이전트 세션, 실행 환경, 사용량, 데이터 제어에 대해 알아보세요.

개요

Agents API는 베타 버전으로 제공됩니다. 개발자는 OpenAI가 관리하는 Codex 에이전트로 애플리케이션을 구축할 수 있습니다. 이 에이전트는 여러 단계에 걸쳐 작업하고 같은 세션에서 작업을 이어갈 수 있습니다.

애플리케이션은 작업, 도구, 구성을 제공합니다. OpenAI는 에이전트의 세션과 모델 및 도구 간의 연동을 관리합니다.

에이전트는 어떤 작업을 할 수 있나요?

에이전트는 도구와 실행 환경에 따라 코드를 실행하고, 파일을 편집하고, MCP 연결을 사용하고, 애플리케이션에 필요한 파일을 생성할 수 있습니다. 같은 세션에서 추가 지침을 보내거나 다른 작업을 이어서 수행할 수 있습니다.

지원되는 기능과 예시는 Agents API 개요를 참조하세요.

OpenAI Platform 프로젝트에서 애플리케이션 API 키를 생성하세요. 세션용으로 api.agents.read 및 api.agents.write 권한을, 모델 요청용으로 api.responses.write 권한을 부여하세요.
빠른 시작 가이드에 따라 에이전트를 구성하고, 세션을 생성하고, 작업을 제출하세요.
세션의 이벤트를 추적하여 진행 상황과 결과를 확인하세요. 작업을 이어가려면 세션 ID를 저장하세요.

API 키는 에이전트의 샌드박스 외부에 보관하세요. 요청에는 OpenAI-Beta: agents=v1 헤더가 필요합니다. OpenAI SDK는 이 헤더를 자동으로 추가합니다.

작업에 맞는 환경을 선택하세요.

환경 없음: 에이전트가 내장 셸 명령이나 워크스페이스 파일 없이 질문에 답하거나 외부 도구를 사용하는 경우입니다.
OpenAI 호스팅 샌드박스: 에이전트가 스크립트를 실행하거나 파일 작업을 해야 하며, 샌드박스 관리를 OpenAI에 맡기려는 경우입니다.
자체 호스팅 샌드박스: 자체 인프라, 소프트웨어 또는 사설 네트워크가 필요한 경우입니다. 환경의 수명 주기는 애플리케이션에서 관리합니다.

구성에 대한 자세한 내용은 Agents API 아키텍처를 참조하세요.

Platform 대시보드의 로그를 열고 에이전트를 선택한 다음 세션 ID를 검색하세요. 턴, 도구 호출, 하위 에이전트 활동을 살펴볼 수 있습니다.

기록된 토큰 사용량을 확인하는 방법도 관측 가능성 가이드에서 안내합니다.

다시 시도하기 전에 기존 세션과 저장된 항목을 조회하세요. 이렇게 하면 추가 작업을 제출하기 전에 이전에 어떤 일이 있었는지 확인할 수 있습니다.

턴이 완료되었다고 해서 모든 도구가 성공적으로 실행되었다는 뜻은 아닙니다. 보고된 결과를 확인하세요. 세션이 유휴 상태라는 사실만으로는 작업이 성공적으로 완료되었다고 판단할 수 없습니다.

모델 요청에는 선택한 모델의 API 요금이 적용됩니다. OpenAI 도구와 OpenAI 호스팅 샌드박스에는 각각 해당 도구 및 컨테이너 요금이 적용됩니다.

현재 요금은 API 요금을 참조하세요.

Agents API는 여러 턴에 걸쳐 작업을 이어갈 수 있도록 세션 상태를 유지합니다. 세션과 게시된 결과물이 더 이상 필요하지 않으면 삭제할 수 있습니다. 세션을 삭제하기 전에 필요한 파일을 저장하세요.

Agents API는 현재 미국 내 데이터 레지던시만 지원합니다. 자체 호스팅 샌드박스를 사용하는 경우에도 데이터 비보관은 지원하지 않습니다. 데이터 제어에 대한 자세한 내용은 Agents API 문서를 참조하세요.