OpenAI Agents API 공개 베타: 지속형 AI 에이전트 구축과 비용·성능 검증 가이드

공식 발표일: 2026년 9월 10일 · 확인일: 2026년 9월 11일

OpenAI가 Agents API를 공개 베타로 출시했습니다. 이전에는 모델 호출, 대화 상태, 도구 실행기, 작업 재개, 로그 수집을 애플리케이션이 따로 엮어야 했다면, 이제는 관리형 Codex 하네스가 세션 오케스트레이션과 문맥 압축, 복구를 맡습니다. 개발자는 에이전트의 모델·지시문·도구를 정하고, 실행 환경을 OpenAI 호스팅 또는 자체 호스팅으로 선택할 수 있습니다.

이번 발표는 새로운 기반 모델의 점수 경쟁보다 오래 실행되는 에이전트를 서비스에 넣는 방식을 바꾸는 API 출시입니다. 공개 엔드포인트는 /v1/agents/sessions이며 현재 요청에는 OpenAI-Beta: agents=v1 헤더가 필요합니다. 이 글은 직접 API를 실행한 후기가 아닙니다. OpenAI 공식 문서에서 확인한 기능, 비용 구조, 보안 조건과 독자가 같은 조건으로 재현할 평가 방법을 구분해 정리합니다.

Agents API 핵심 요약: 누가 먼저 살펴봐야 하나

항목	공식 확인 내용	실무 의미
출시 단계	2026년 9월 10일 공개 베타	프로덕션 적용 전 변경 가능성과 장애 대응 경로를 준비해야 함
핵심 단위	Agent, Environment, Session, Events·Items	설정과 실행 공간, 대화 기록, 진행 이벤트를 분리해 운영 가능
관리 범위	세션, 오케스트레이션, 문맥 압축, 복구	장기 작업의 상태 관리 코드를 줄일 수 있음
실행 환경	환경 없음, OpenAI 호스팅, 자체 호스팅	단순 도구 호출부터 파일·코드 실행과 사설망 연결까지 선택
관측	스트리밍, 웹훅, 저장 이력, 대시보드 추적	완료 여부뿐 아니라 모델 응답과 도구 호출 과정을 점검
비용	선택 모델, 도구, 컨테이너 사용량을 각각 과금	API 이름만 보고 단가를 계산하면 실제 작업 비용을 놓침

가장 먼저 검토할 팀은 코드 수정, 문서 분석, 사고 조사, 데이터 질의처럼 한 번의 모델 응답으로 끝나지 않는 업무를 운영하는 팀입니다. 반대로 짧은 분류나 요약 한 번이면 끝나는 서비스는 Responses API를 직접 호출하는 편이 구조와 비용을 파악하기 쉬울 수 있습니다.

기존 모델 호출과 무엇이 달라졌나

Responses API는 모델이 텍스트를 만들고 도구를 요청하는 기반을 제공합니다. Agents API는 그 위에서 여러 번의 모델 호출과 도구 실행이 이어지는 작업을 지속형 세션으로 관리합니다. 세션에는 에이전트 설정, 대화, 저장된 작업이 유지되고, 유휴 상태에 새 메시지를 보내면 새 턴이 시작됩니다. 실행 중 메시지를 보내면 현재 턴을 조정하는 입력으로 처리됩니다.

관리형 하네스는 샌드박스에서 명령과 코드를 실행하고 파일을 수정하며, 관련 스킬을 적용하고 MCP 서버와 연결할 수 있습니다. 문맥이 길어지면 이전 작업을 요약해 창을 관리하고, 하위 에이전트에 일부 작업을 맡기거나 중단된 지점에서 세션을 이어 갈 수도 있습니다. 다만 환경을 none으로 만들면 내장 셸과 파일 작업 공간, 실행기 MCP를 쓸 수 없습니다. 이 경우 애플리케이션 함수 도구 또는 원격 MCP 중심으로 구성해야 합니다.

세션이 실제로 움직이는 순서

1. 에이전트를 정합니다. 모델, 지시문, 함수 도구, MCP 서버와 추론 설정을 구성합니다. 같은 설정을 여러 세션에서 쓸 때는 에이전트를 저장하고 agent_id를 재사용할 수 있습니다.
2. 환경을 선택합니다. 실행이 필요 없으면 none, 관리형 Linux 작업 공간이 필요하면 openai_hosted, 사설망이나 전용 이미지를 써야 하면 self_hosted를 선택합니다.
3. 세션과 첫 입력을 만듭니다. stream: true를 지정하면 생성 요청에서 첫 턴의 이벤트를 바로 받을 수 있습니다.
4. 진행 상황을 확인합니다. 스트림 또는 웹훅으로 상태 변화를 받고, 저장된 아이템과 턴을 조회합니다.
5. 성공을 판정합니다. agent.session.turn.completed를 확인하되 도구별 성공 여부도 따로 검사합니다. 단순히 세션이 idle이라는 사실만으로 성공으로 처리하면 안 됩니다.
6. 후속 작업을 보냅니다. 같은 세션 ID에 추가 입력을 보내 기존 문맥과 결과를 이어 갑니다. 실행 중 방향을 바꾸려면 현재 턴을 조정합니다.
7. 산출물을 보존하고 정리합니다. 필요한 파일을 먼저 내려받은 뒤 더 쓸 필요가 없는 세션을 삭제합니다.

OpenAI 호스팅과 자체 호스팅, 선택 기준

OpenAI 호스팅 샌드박스는 Python, Node.js, 명령줄 도구가 있는 Linux 작업 공간을 제공합니다. 작업 디렉터리는 /workspace이며 필요한 Python·시스템·npm 패키지, 초기 설정 명령, 입력 파일, 환경 변수, 스킬과 플러그인을 세션 설정에 넣을 수 있습니다. 같은 구성을 반복한다면 환경 템플릿을 재사용할 수 있습니다.

선택	잘 맞는 경우	운영 책임
환경 없음	원격 MCP나 애플리케이션 함수만 호출	함수 실행과 외부 서비스 상태를 애플리케이션이 관리
OpenAI 호스팅	빠른 실험, 코드 실행, 파일 편집, 산출물 생성	OpenAI가 샌드박스를 제공하지만 패키지·네트워크·비밀정보 정책은 사용자가 설계
자체 호스팅	사설망, 커스텀 이미지, 특정 컴퓨팅 환경	프로비저닝부터 종료와 보존까지 애플리케이션이 책임

실제 성능: 공식 자료가 보여 주는 것과 보여 주지 않는 것

Agents API 자체의 성공률이나 기존 직접 구현 대비 지연시간을 비교한 공식 표준 벤치마크는 현재 문서에서 확인되지 않았고, 신뢰할 수 있는 독립 평가도 아직 확인되지 않았습니다. 따라서 “에이전트 개발이 몇 배 빨라진다”거나 “작업 성공률이 자동으로 높아진다”고 단정할 근거는 없습니다.

공식 추적 문서에는 기록된 세션 예시 하나가 공개돼 있습니다. 루트 에이전트와 하위 에이전트 2개가 참여한 한 턴에서 10회 도구 호출, 252,468토큰, 완료까지 1분 37초가 표시됩니다. 추적에는 에이전트 스팬 3개, 모델 생성 스팬 11개, 도구 스팬 10개가 포함됩니다. 이는 기능을 설명하기 위한 단일 기록 예시이며 일반적인 속도나 비용의 대표값이 아닙니다.

확인 가능한 지표	공식 문서의 설명	해석할 때 주의점
턴 완료 상태	completed, failed, cancelled 등 이벤트로 확인	턴 완료가 모든 도구의 성공을 보장하지 않음
단계별 시간	추적 화면에서 스팬의 시작·종료·기간 확인	하위 에이전트가 병렬이면 스팬 시간 합과 실제 경과 시간이 다름
토큰 사용량	루트·하위 에이전트 턴의 입력, 캐시 입력, 출력, 추론 토큰 기록	최선 노력 값이며 null일 수 있고 나중에 바뀔 수 있어 최종 청구서가 아님
도구 성공	도구 스팬의 인수, 결과, 오류, 상태 확인	애플리케이션이 업무 성공 조건을 별도로 정의해야 함
품질 점수	공통 Agents API 점수는 공개되지 않음	자체 대표 과제와 채점표로 측정해야 함

가격과 비용 계산: API 이용료는 한 줄이 아니다

Agents API에는 모든 것을 포함한 단일 작업당 가격이 제시된 것이 아닙니다. 모델 호출은 선택한 모델의 API 단가, OpenAI 도구는 해당 도구 단가, OpenAI 호스팅 샌드박스는 표준 컨테이너 단가가 각각 적용됩니다. 외부 MCP나 자체 호스팅 인프라 비용도 별도입니다.

한 작업의 예상 비용은 다음처럼 계산하는 편이 안전합니다.

총비용 = 루트 모델 호출 + 하위 에이전트 호출 + 캐시 읽기·쓰기 + OpenAI 도구 + 샌드박스 시간 + 외부 서비스 + 재시도

공식 사용량 필드는 입력 토큰, 캐시 입력 토큰, 출력 토큰, 추론 토큰을 보여 주지만 최선 노력 방식입니다. 캐시 쓰기 가격이 있는 모델에서도 Agents API 사용량 필드가 별도 캐시 쓰기 수치를 노출하지 않을 수 있어, 이 값만으로 정확한 모델 비용을 계산할 수 없다는 제한도 문서에 명시돼 있습니다. 예산 경보와 실제 청구 데이터를 함께 봐야 합니다.

10분 빠른 시작: 최소 권한부터 설정하기

애플리케이션 API 키에는 세션 작업용 api.agents.read, api.agents.write와 모델 추론용 api.responses.write 권한이 필요합니다. 키는 에이전트의 샌드박스 밖에 보관합니다. 현재 공개 베타에서는 SDK가 베타 헤더를 자동으로 붙이지만 cURL 사용 시 직접 추가해야 합니다.

from openai import OpenAI

client = OpenAI()

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "작업을 수행하고 실제 실행 결과와 오류를 보고하세요.",
    },
    environment={"type": "openai_hosted"},
    input="현재 폴더의 파일 트리를 만드는 스크립트를 작성하고 실행하세요.",
    stream=True,
) as events:
    for event in events:
        print(event.type)

위 코드는 공식 빠른 시작을 한국어 작업으로 단순화한 예시입니다. 실제 배포에서는 완료 이벤트와 도구 오류, 생성 파일, 예상 출력, 사용량을 함께 검증하세요.

직접 재현하는 성능·비용 평가 절차

다음은 공개 벤치마크가 부족한 새 API를 실제 서비스 조건에서 검증하는 방법입니다. 같은 모델과 입력을 사용하는 기존 오케스트레이터를 기준군으로 두고 Agents API를 비교군으로 둡니다.

1. 실제 개인정보를 제거한 대표 과제 30~100개를 준비합니다. 코드 수정, 문서 분석, 도구 조회처럼 서비스의 핵심 유형을 비슷한 비율로 섞습니다.
2. 모델, 추론 강도, 도구 설명, 데이터 스냅샷, 동시성, 최대 실행 시간을 고정합니다.
3. 업무 성공 기준을 실행 전에 정의합니다. 예를 들어 테스트 통과, 필요한 필드 채움, 허용된 파일만 변경, 출처 일치 여부를 자동 채점합니다.
4. 기존 방식과 Agents API 방식을 각 과제마다 최소 3회 실행해 우연한 네트워크 변동을 줄입니다.
5. 작업 성공률, 완전 성공까지 걸린 p50·p95 시간, 모델 호출 수, 도구 호출 성공률, 재시도율, 전체 토큰, 샌드박스 시간을 저장합니다.
6. 하위 에이전트를 켠 경우 루트와 하위 사용량을 분리하고 병렬 실행이 경과 시간과 비용에 미친 영향을 따로 계산합니다.
7. 스트림 끊김, 도구 500 오류, 세션 재개, 시간 초과를 의도적으로 주입해 중복 실행과 복구 성공률을 확인합니다.
8. 품질이 같은 결과만 비용 비교에 포함합니다. 낮은 성공률로 싸게 끝난 실행을 비용 개선으로 계산하지 않습니다.

평가 지표	권장 계산	합격 기준 예시
작업 성공률	모든 필수 조건을 통과한 과제 ÷ 전체 과제	현재 운영 방식보다 낮지 않음
도구 성공률	정상 결과를 반환한 호출 ÷ 전체 호출	업무 중요도별 목표를 별도 설정
복구 성공률	장애 뒤 중복 부작용 없이 완료한 실행 ÷ 장애 주입 실행	결제·삭제 작업은 별도 엄격 기준
작업당 비용	모델·도구·컨테이너·외부 비용 합계	동일 품질 기준에서 비교
완료 시간	요청 시작부터 검증 가능한 산출물까지 p50·p95	사용자 대기 허용치 이내

보안과 승인 설계에서 놓치기 쉬운 부분

에이전트가 만든 코드는 환경에 노출된 파일, 자격 증명, 네트워크에 접근할 수 있습니다. 따라서 사용자나 업무별로 데이터를 공유하면 안 되는 경우 별도 격리 환경을 사용하고, 애플리케이션별 전용 OpenAI 프로젝트를 만드는 것이 기본입니다. 외부 통신은 승인된 엔드포인트만 허용하고, 실행기 MCP와 원격 MCP가 각각 어느 위치에서 연결되는지 구분해야 합니다.

애플리케이션 API 키를 샌드박스에 넣지 마세요. 자체 호스팅 실행기는 연결 전용 환경 키를 CODEX_API_KEY로 사용하며, 이 키는 다른 API 작업을 승인하지 못합니다. 제3자 자격 증명은 가능하면 환경에 직접 주입하지 말고 승인된 요청에만 비밀을 붙이는 브로커를 통하게 합니다. 장기 비밀은 비밀 저장소에 보관하고 노출이 의심되면 즉시 폐기·교체해야 합니다.

자주 생기는 실패와 해결법

세션이 idle인데 작업이 끝났다고 처리했다

idle은 현재 실행 중이 아니라는 상태일 뿐 성공을 뜻하지 않습니다. 완료·실패·취소 이벤트와 각 도구의 결과, 최종 산출물을 함께 확인합니다.

스트림이 끊긴 뒤 같은 요청을 다시 보내 중복 작업이 생겼다

세션과 저장 아이템을 먼저 조회해 턴이 계속 실행됐는지 확인합니다. 외부 쓰기 도구에는 작업 ID와 멱등성 키를 넣어 같은 결제나 게시가 두 번 일어나지 않게 합니다.

비용이 예상보다 크게 나왔다

한 작업 안에서 모델이 여러 번 호출되고 하위 에이전트와 재시도가 더해질 수 있습니다. 루트와 하위 턴 사용량, 도구·컨테이너 시간, 캐시 적중을 모두 합산하고 과제별 최대 호출·시간 예산을 둡니다.

샌드박스에서 사내 서비스가 연결되지 않는다

OpenAI 호스팅 환경의 네트워크 정책과 원격 MCP 접근 가능성을 확인합니다. 사설망이나 전용 소프트웨어가 필요하면 자체 호스팅 환경으로 옮기되 실행기 연결과 종료 책임도 함께 가져와야 합니다.

추적 화면의 토큰 값이 비어 있다

사용량은 최선 노력 값이며 늦게 도착하거나 null일 수 있습니다. 0으로 계산하지 말고 미확정 상태로 저장한 뒤 청구·예산 데이터와 대조합니다.

배포 전 체크리스트

• 공개 베타 변경 가능성을 감안해 SDK 버전과 베타 헤더를 기록했는가?
• 애플리케이션 키에 agents 읽기·쓰기와 responses 쓰기 최소 권한만 부여했는가?
• 애플리케이션 API 키와 제3자 비밀을 샌드박스 밖에 보관하는가?
• 환경 없음, OpenAI 호스팅, 자체 호스팅 중 요구 사항에 맞는 방식을 골랐는가?
• 완료 이벤트와 실제 도구 결과를 모두 검증하는가?
• 외부 쓰기 도구에 멱등성 키와 승인 절차가 있는가?
• 스트림 단절 뒤 조회 우선, 재시도 후순서 원칙을 구현했는가?
• 루트·하위 에이전트·재시도·도구·컨테이너를 포함한 작업당 비용을 계산하는가?
• 추적 로그의 입력·출력에 개인정보나 비밀정보가 남지 않는지 점검했는가?
• 대표 과제로 성공률, p95 완료 시간, 복구 성공률을 배포 전 측정했는가?

자주 묻는 질문

Agents API는 기존 Agents SDK와 같은 것인가요?

같지 않습니다. Agents API는 OpenAI가 관리하는 Codex 하네스와 지속형 세션을 제공하는 API이고, Agents SDK는 애플리케이션 코드에서 에이전트 흐름을 구성하는 개발 도구입니다. 요구하는 실행 위치와 운영 책임을 비교해 선택해야 합니다.

모든 작업에 OpenAI 호스팅 샌드박스가 필요한가요?

아닙니다. 함수 도구나 원격 MCP만 필요하면 환경을 none으로 둘 수 있습니다. 코드 실행과 파일 작업이 필요하면 호스팅 환경을 고르고, 사설망·전용 이미지가 필요하면 자체 호스팅을 검토합니다.

세션을 유지하면 비용이 자동으로 줄어드나요?

보장되지 않습니다. 동일한 앞부분이 반복되면 프롬프트 캐시가 도움이 될 수 있지만, 긴 이력이 여러 모델 호출에서 계속 처리되면 총 토큰은 커질 수 있습니다. 같은 품질의 작업당 총비용으로 비교해야 합니다.

공개 베타인데 바로 프로덕션에 써도 되나요?

작은 읽기 전용 업무부터 제한적으로 검증하는 것이 안전합니다. 변경 가능성, 사용량 집계 지연, 장애 복구, 승인과 멱등성을 먼저 확인하고 중요한 쓰기 작업은 사람 승인을 유지하세요.

공식 성능 수치만으로 기존 오케스트레이터보다 낫다고 판단할 수 있나요?

아닙니다. 공개 문서의 1분 37초·252,468토큰 예시는 하나의 기록된 추적 사례이지 비교 벤치마크가 아닙니다. 동일 모델·도구·과제로 직접 A/B 평가해야 합니다.

공식 확인 자료

• OpenAI API 변경 로그 — Agents API 공개 베타 발표
• Agents API 개요 — 관리 범위, 핵심 개념, 가격 구조
• Agents API 빠른 시작 — 권한, 베타 헤더, 세션 실행 예시
• Agents API 아키텍처 — 환경 없음·호스팅·자체 호스팅 비교
• 세션 실행과 이어가기 — 턴, 스트리밍, 후속 입력
• OpenAI 호스팅 샌드박스 — 패키지, 파일, 환경 설정과 비용
• 샌드박스 보안 — 격리, 네트워크, 자격 증명 원칙
• 관측과 사용량 — 토큰 집계와 비용 해석 한계
• 추적 — 모델 응답, 도구 호출, 하위 에이전트 분석

Agents API의 가치는 모델 한 번의 점수보다 오래 실행되는 작업의 상태, 복구, 도구, 추적을 하나의 운영 단위로 묶는 데 있습니다. 공개 베타 단계에서는 읽기 전용 과제부터 시작해 작업 성공률과 p95 시간, 전체 비용, 장애 뒤 복구 성공률을 먼저 측정하세요. 그 결과가 기존 방식보다 낫고 보안 경계가 명확할 때 쓰기 권한을 단계적으로 넓히는 것이 안전합니다.