한 줄 답: OpenAI Agents API는 Codex의 에이전트 실행 구조를 관리형 API로 제공하는 공개 베타다. 앱 개발자는 모델·도구·실행 환경을 고르고, OpenAI가 세션·오케스트레이션·컨텍스트 압축·복구를 맡는다.[1][2]
OpenAI는 2026년 9월 10일 Agents API 공개 베타를 발표했다.[1] 이름이 비슷한 Responses API, Agents SDK, ChatGPT의 에이전트 기능과 혼동하기 쉽다. 이 글은 개발자가 무엇을 새로 쓸 수 있는지, 어떤 경우에는 기존 방식을 유지하는 편이 나은지, 비용과 회사 데이터 주의사항을 공식 문서와 실제 HTTP 확인 결과로 정리한다.
- 확인일: 2026년 9월 12일(KST)
- 검증 범위: 공식 변경 기록·개요·빠른 시작·아키텍처·가격 문서의 현재 응답과 필수 설정
- 확인하지 않은 범위: 유료 API 키를 사용한 실제 에이전트 실행, 처리 속도, 한국 리전 제공 여부
이 글이 필요한 사람
- Responses API와 Agents SDK를 이미 쓰고 있지만 Agents API로 바꿔야 할지 판단하려는 개발자
- 파일·코드·여러 도구를 사용하는 장시간 AI 업무를 제품에 넣으려는 팀
- 회사 문서와 API 키를 에이전트에 연결하기 전에 비용·권한·데이터 보존 조건을 확인하려는 담당자
OpenAI Agents API에서 달라진 점
기존에는 모델 호출, 도구 실행, 대화 상태 저장, 실패 복구, 긴 작업의 컨텍스트 정리를 개발팀이 조합해야 했다. Agents API에서는 OpenAI가 Codex 기반 하네스를 운영하고 세션·오케스트레이션·컨텍스트 압축·복구를 관리한다. 개발자는 모델, 지침, 도구와 실행 환경을 지정한다.[2]
에이전트는 한 번의 답변 객체가 아니라 지속되는 세션에서 일한다. 같은 세션에 후속 요청을 보내거나 작업 중 방향을 수정할 수 있고, 진행 상황은 스트림이나 웹훅으로 받는다. 코드 실행과 파일 작업이 필요하면 샌드박스를 연결할 수 있다.[2]
공개 베타이므로 모든 개발자가 시작할 수 있지만, 정식 출시가 아니다.[1] API 모양, 제한 또는 운영 조건이 바뀔 수 있다는 전제로 작은 업무부터 시험하는 편이 안전하다.
Responses API·Agents SDK·Agents API 차이
| 선택지 | 누가 실행 루프를 관리하나 | 상태와 실행 환경 | 적합한 경우 |
|---|---|---|---|
| Responses API | 개발자 애플리케이션 | 개발자가 대화 연결과 분기 로직을 설계 | 짧고 통제 범위가 분명한 모델 호출, 기존 서버 로직에 세밀하게 결합할 때 |
| Agents SDK | SDK가 애플리케이션 안에서 루프를 실행 | 배포·도구·저장·승인 정책은 개발자 측에서 관리 | 코드 중심 설계와 자체 인프라 통제가 필요할 때 |
| Agents API | OpenAI의 관리형 Codex 하네스 | 지속 세션과 복구는 OpenAI가 관리하고 실행 환경은 선택 | 며칠 이어지는 작업, 파일·코드·여러 도구·하위 에이전트를 묶을 때 |
OpenAI 문서도 Responses API는 개발자가 루프를 소유하고, Agents SDK는 SDK가 루프를 실행하는 선택으로 구분한다.[7] Agents API는 여기서 한 단계 더 나아가 하네스 자체를 OpenAI가 운영한다.[2]
단순 질의응답이나 한두 번의 도구 호출에 Agents API를 붙이면 운영 복잡도와 비용 추적만 늘 수 있다. 반대로 작업 중단 뒤 이어서 실행해야 하거나, 여러 파일과 도구를 다루며 결과물을 남겨야 한다면 지속 세션과 복구 기능이 실제 이점이 된다.
도입 과정 1: 실행 환경은 세 가지 중에서 고른다
공식 아키텍처 문서는 작업에 따라 none, openai_hosted, self_hosted를 선택하도록 안내한다.[4]
| 환경 | 의미 | 먼저 확인할 점 |
|---|---|---|
none |
별도 셸·파일 공간 없이 모델과 원격 도구를 사용 | 코드 실행이나 로컬 파일 편집이 필요 없는가 |
openai_hosted |
OpenAI가 Linux 샌드박스를 준비 | 파일 반출, 네트워크 허용 범위, 컨테이너 비용 |
self_hosted |
회사 또는 개발자 인프라를 연결 | 실행기 수명주기, 재연결, 로그, 권한을 직접 운영할 수 있는가 |
OpenAI 호스팅 샌드박스에는 Python, Node.js, 명령줄 도구가 있으며 파일과 패키지를 넣을 수 있다.[5] 네트워크는 허용, 차단 또는 지정 도메인만 허용하도록 설정할 수 있다. 업무 문서처럼 외부 전송이 불필요한 작업은 network.access를 disabled로 시작하고, 필요한 도메인만 추가하는 방식이 안전하다.[5]
도입 과정 2: 빠른 시작 전에 필요한 권한
공식 빠른 시작은 프로젝트 API 키에 세션용 api.agents.read, api.agents.write와 모델 추론용 api.responses.write 권한을 요구한다. cURL로 호출할 때는 OpenAI-Beta: agents=v1 헤더도 넣어야 한다.[3]
API 키는 샌드박스 안에 넣지 말아야 한다는 안내도 명시돼 있다.[3] 키를 코드나 채팅에 붙여 넣는 대신 운영체제 환경 변수나 비밀 저장소에서 주입해야 한다. 구체적인 저장 원칙은 API 키를 소스코드와 채팅에 넣으면 안 되는 이유에서 확인할 수 있다.
아래는 실제 실행 코드가 아니라, 시작 전에 확인할 설정 예시다.
{
"agent": {
"model": "gpt-6-astra",
"instructions": "입력 파일만 근거로 요약하고 결과 파일을 다시 읽어 검증한다."
},
"environment": {
"type": "openai_hosted",
"network": { "access": "disabled" }
},
"input": "문서를 요약해 outputs/summary.md에 저장하고 다시 읽어 확인해줘."
}
회사 시스템을 수정하거나 메시지를 보내는 도구를 붙인다면 승인 지점을 따로 둬야 한다. 삭제·발송·공개 같은 작업은 모델이 바로 실행하지 못하게 하고 사람이 확인한 뒤 진행하도록 설계한다. AI 자동화에서 사람이 반드시 승인해야 하는 작업의 구분표를 함께 적용할 수 있다.
비용은 ‘API 사용료 0원’이 아니다
Agents API 자체에 별도 이용료가 붙는 구조는 아니지만, 선택한 모델의 입력·출력 토큰, 도구 호출, OpenAI 호스팅 샌드박스의 컨테이너 비용은 각각 청구된다.[2][6]
따라서 비용은 호출 횟수보다 완료된 업무 1건당 비용으로 기록하는 편이 낫다. 에이전트가 같은 파일을 여러 번 읽거나 하위 에이전트를 반복 호출하면 한 번의 사용자 요청 안에서도 토큰과 도구 사용량이 늘어난다.
도입 시험에서는 다음 항목을 함께 기록한다.
- 세션 하나가 끝날 때까지 사용한 모델과 토큰
- 웹 검색·파일 검색 등 유료 도구 호출 수
- 샌드박스 실행 시간과 재시도 횟수
- 사람이 결과를 검수하고 수정한 시간
- 완성된 결과물 수와 실패한 결과물 수
회사 문서 보안: 넣기 전에 확인할 제한
현재 Agents API 개요는 데이터 레지던시를 미국에서만 지원하고 Zero Data Retention(ZDR)은 지원하지 않는다고 설명한다. 자체 샌드박스를 선택해도 Agents API 자체가 ZDR 대상이 되는 것은 아니다.[2]
따라서 고객 정보, 계약서, 미공개 재무자료를 바로 넣어 시험하면 안 된다. 먼저 익명화한 샘플로 기능을 확인하고, 조직의 보존 정책·처리 지역·접근 권한 요구와 맞는지 검토해야 한다. self_hosted는 실행 파일과 사설 네트워크를 회사 쪽에 둘 수 있지만, 하네스와 세션 데이터 조건까지 자동으로 사내 보관으로 바꾸지는 않는다.[2][4]
직접 확인한 결과
2026년 9월 12일 KST에 공식 Agents API 개요와 빠른 시작 문서를 HTTP로 요청해 모두 200 OK를 확인했다. 두 문서에서 관리형 Codex 하네스, beta.agents 네임스페이스, OpenAI-Beta: agents=v1 헤더, 세 가지 실행 환경 설명을 대조했다.
OpenAI 발표 페이지는 같은 자동 요청에서 403을 반환했다. 이는 자동 접근 차단 결과이며 제품 중단을 뜻하지 않는다. 발표 날짜와 공개 베타 상태는 HTTP 200으로 열린 공식 API 변경 기록과 개발자 문서를 기준으로 확인했다.[1][2]
유료 API 키를 사용한 세션 생성은 실행하지 않았다. 따라서 속도, 실제 토큰 비용, 샌드박스 준비 시간은 검증 결과로 쓰지 않았다.
도입 판단표
| 질문 | 예 | 아니요 |
|---|---|---|
| 작업이 여러 단계이고 중단 뒤 이어서 실행해야 하나 | Agents API 시험 후보 | Responses API부터 검토 |
| 파일 생성·코드 실행·도구 연결이 필요한가 | 샌드박스 환경 검토 | environment.type: none 검토 |
| 데이터 처리 지역이나 ZDR가 필수인가 | 현재 제한 때문에 도입 보류 또는 별도 검토 | 다음 질문으로 |
| 자체 인프라와 사설 네트워크가 필요한가 | self_hosted 검토 |
openai_hosted로 작은 시험 가능 |
| 삭제·발송·결제·공개 작업이 있는가 | 사람 승인 단계부터 설계 | 읽기 전용 시험부터 시작 |
출시 전 검증 체크리스트
- 공개 베타 변경을 견딜 수 있는 실험 업무를 골랐는가
- API 키 권한을 필요한 범위로만 제한했는가
- API 키를 샌드박스·소스코드·프롬프트에 넣지 않았는가
- 네트워크를 기본 차단하거나 허용 도메인으로 제한했는가
- 세션 실패·취소·연결 끊김 뒤 상태를 다시 읽는 절차가 있는가
- 외부 전송과 데이터 삭제 전에 사람 승인을 요구하는가
- 모델·도구·컨테이너 비용을 업무 1건 단위로 기록하는가
- 테스트 데이터에 개인정보와 회사 기밀이 없는가
- 결과 파일을 다시 열어 내용과 출처를 검증하는가
자주 묻는 질문
OpenAI Agents API는 ChatGPT 유료 구독에 포함되나?
아니다. ChatGPT 구독과 OpenAI API 과금은 별도다. Agents API 자체의 추가 요금보다 모델 토큰, 도구, 호스팅 샌드박스 비용을 확인해야 한다.[2][6]
코딩을 모르면 바로 사용할 수 있나?
현재 빠른 시작은 API 키와 Python·JavaScript·Go·Java 또는 cURL 사용을 전제로 한다.[3] ChatGPT 화면에서 에이전트를 만드는 기능과 개발자용 Agents API는 같은 제품 화면이 아니다.
Responses API를 당장 바꿔야 하나?
그럴 필요는 없다. 짧고 예측 가능한 흐름을 이미 안정적으로 운영한다면 Responses API가 더 단순할 수 있다. 지속 세션, 복구, 파일·코드 실행, 여러 에이전트 조정이 필요할 때 전환 시험의 이유가 생긴다.[2][7]
한국 회사 문서를 넣어도 되나?
현재 문서상 미국 데이터 레지던시와 ZDR 미지원 조건을 먼저 검토해야 한다.[2] 회사 승인 없이 실제 고객·직원·계약 데이터를 넣지 말고, 익명화한 테스트 자료로 시작해야 한다.