OpenAI Agents API 공개 베타: Codex 하네스가 API로 온 의미

OpenAI가 Agents API를 공개 베타로 내놓으면서 개발자가 직접 만들어야 했던 에이전트 실행 하네스의 일부가 관리형 API 영역으로 들어왔습니다. 핵심은 모델 호출 하나가 아니라 세션, 컨텍스트 압축, 샌드박스, 도구 호출, 서브에이전트 오케스트레이션을 한 묶음으로 제공한다는 점입니다. 실무 개발자 입장에서는 “챗봇 API를 붙일까”가 아니라 “장시간 작업을 수행하는 작업자 프로세스를 어디까지 직접 운영할까”의 문제로 봐야 합니다.

무엇이 새로워졌나

Agents API는 OpenAI가 Codex에서 쓰는 하네스를 개발자용 API로 제공하는 형태입니다. 공식 설명 기준으로 애플리케이션은 에이전트의 모델, 지시문, 도구, MCP 서버, 실행 환경을 지정하고 세션을 만들 수 있습니다. 세션은 한 번 답하고 끝나는 요청이 아니라 작업을 이어받고, 중간 진행 상황을 이벤트로 내보내며, 필요하면 같은 세션에 추가 지시를 받을 수 있는 단위입니다.

중요한 구성요소는 네 가지입니다.

Agent: 모델, 지시문, 사용 가능한 도구, MCP 서버 정의
Environment: 파일을 읽고 명령을 실행할 수 있는 샌드박스 또는 자체 인프라
Session: 작업을 수행하고 이어갈 수 있는 지속 실행 단위
Events and items: 입력, 출력, 진행 이벤트, 산출물

기존 Responses API나 일반 채팅 API로도 간단한 도구 호출은 만들 수 있습니다. 하지만 장시간 실행, 작업 복구, 컨텍스트 정리, 서브태스크 분배까지 직접 구현하려면 상태 저장소, 큐, 로그, 재시도, 권한 제어, 샌드박스 격리가 필요합니다. Agents API는 이 운영 부담을 API 레이어로 일부 끌어올린 셈입니다.

개발자가 봐야 할 변화

가장 큰 변화는 에이전트 제품의 기본 단위가 “프롬프트”에서 “세션”으로 이동한다는 점입니다. 지금까지 많은 팀은 사용자의 한 요청을 받아 모델을 호출하고, 필요한 도구를 몇 번 실행한 뒤 결과를 반환하는 구조로 시작했습니다. 이 구조는 짧은 질의응답에는 충분하지만 코드베이스 분석, 릴리즈 노트 비교, 문서 리뷰, 장애 조사처럼 시간이 길어지는 작업에서는 금방 한계를 보입니다.

Agents API는 세션 안에서 다음 기능을 제공합니다.

긴 작업 중 이전 맥락을 요약해 컨텍스트 한도에 대응
도구 정의를 필요한 시점에 불러와 토큰 사용량을 줄이는 tool search
여러 도구 호출을 병렬 또는 절차적으로 실행하는 programmatic tool calling
독립 작업을 서브에이전트로 나눠 병렬 처리하는 multi-agent support
샌드박스에서 코드 실행, 파일 편집, 산출물 생성

이 변화는 특히 내부 운영 도구를 만드는 팀에 큽니다. 예를 들어 GitHub 이슈 조사 봇을 만든다면, 과거에는 이슈 본문 읽기, 재현 스크립트 실행, 로그 요약, 원인 후보 정리, 코멘트 초안 생성을 각각 애플리케이션 코드로 엮어야 했습니다. 이제는 에이전트 세션에 도구와 환경을 연결하고, 작업이 끝났을 때 사람이 승인할 수 있는 흐름을 설계하는 쪽에 더 집중할 수 있습니다.

비용과 운영 리스크는 사라지지 않는다

다만 관리형 하네스가 나온다고 해서 운영 리스크가 없어지는 것은 아닙니다. OpenAI 설명에 따르면 Agents API 자체의 별도 요금은 없고, 선택한 모델의 토큰 요금, 도구 요금, OpenAI 호스팅 샌드박스의 컨테이너 요금이 적용됩니다. 즉, 실패한 긴 작업도 비용이 됩니다. 서브에이전트를 많이 띄우면 처리 속도는 빨라질 수 있지만 토큰과 샌드박스 비용이 같이 늘어납니다.

또 하나는 권한 문제입니다. 에이전트가 파일을 읽고, 명령을 실행하고, MCP 서버에 연결한다면 일반 API 키보다 훨씬 넓은 공격면이 생깁니다. 특히 사내 문서, 고객 데이터, 배포 권한, 결제 관련 액션을 다루는 에이전트는 처음부터 권한 경계를 좁혀야 합니다. “에이전트가 할 수 있는 일”보다 “절대 못 하게 할 일”을 먼저 정의해야 합니다.

실무에서는 다음 세 가지를 분리하는 편이 안전합니다.

읽기 전용 조사 에이전트
로컬 또는 샌드박스에서만 수정 가능한 구현 에이전트
배포, 결제, 고객 연락처럼 인간 승인이 필요한 액션 에이전트

세 단계를 같은 세션으로 뭉치면 빠르게 보일 수 있지만, 감사 로그와 권한 회수가 어려워집니다.

어떤 팀이 먼저 써볼 만한가

Agents API는 모든 챗봇에 필요한 기능은 아닙니다. FAQ 답변, 간단한 문서 검색, 짧은 텍스트 생성이라면 기존 API 호출과 RAG 구조가 더 단순합니다. 반대로 다음 조건에 해당하면 검토할 만합니다.

작업 시간이 수 분 이상 걸린다
파일, 코드, 로그, 문서 등 여러 자료를 오가야 한다
도구 호출이 많고 순서가 동적으로 바뀐다
결과를 만들기 전에 중간 산출물이 필요하다
사람이 작업 중간에 방향을 바꾸거나 승인해야 한다
동일한 작업을 여러 하위 작업으로 쪼갤 수 있다

예를 들어 “지난 2주간 릴리즈 노트 12개를 비교해 breaking change만 추려줘” 같은 작업은 서브에이전트 병렬화와 컨텍스트 압축의 이점이 분명합니다. 반면 “이 문장 요약해줘”에는 과한 구조입니다.

도입 전에 정해야 할 설계 원칙

첫 번째 원칙은 환경 선택입니다. OpenAI 호스팅 샌드박스는 시작이 빠르지만, 사내 네트워크 접근이나 특정 보안 정책이 필요하면 자체 인프라 또는 파트너 샌드박스가 맞을 수 있습니다. 공식 자료에는 Cloudflare, Daytona, E2B, Modal, Vercel 등 여러 환경 파트너가 언급됩니다. 선택 기준은 성능보다 데이터 경계, 패키지 설치 방식, 비밀값 저장 방식, 콜드스타트, 비용 예측 가능성입니다.

두 번째 원칙은 도구 정의 안정성입니다. 에이전트가 사용할 도구가 자주 바뀌면 디버깅이 어려워집니다. 도구 이름, 스키마, 반환 형식을 버전 관리하고, 실패 응답도 표준화해야 합니다. “모델이 알아서 처리하겠지”라고 두면 장애가 났을 때 원인이 프롬프트인지, 도구인지, 권한인지 구분하기 어렵습니다.

세 번째 원칙은 인간 승인 지점입니다. 장애 복구, PR 생성, 고객 메시지 발송, 비용이 발생하는 클라우드 작업은 에이전트가 초안을 만들고 사람이 승인하는 구조로 시작하는 편이 낫습니다. 완전 자동화는 로그와 회수 절차가 쌓인 뒤에 단계적으로 열어야 합니다.

기존 에이전트 구현과 비교

직접 구현 방식의 장점은 완전한 통제권입니다. 큐, 워커, 샌드박스, 컨텍스트 압축, 도구 라우팅을 모두 원하는 방식으로 만들 수 있습니다. 단점은 유지보수 비용입니다. 모델이 바뀔 때마다 프롬프트와 도구 호출 흐름을 다시 튜닝해야 하고, 장시간 작업 복구나 병렬 처리에서 예외 케이스가 계속 생깁니다.

Agents API 방식의 장점은 빠른 시작과 관리형 하네스입니다. OpenAI가 모델 업그레이드에 맞춰 하네스를 개선하면 개발자는 업무 도구와 도메인 지식에 집중할 수 있습니다. 단점은 벤더 종속과 비용 구조입니다. 세션, 샌드박스, 도구 호출 로그가 특정 플랫폼에 묶이면 다른 모델로 옮길 때 다시 추상화 계층이 필요합니다.

따라서 초기 제품은 Agents API로 빠르게 검증하고, 장기적으로는 도구 스키마와 업무 상태 저장소를 벤더 중립적으로 두는 전략이 현실적입니다.

실행 체크리스트

짧은 Q&A가 아니라 장시간 작업인지 먼저 판별합니다.
세션 단위로 저장해야 할 상태와 버려도 되는 로그를 구분합니다.
에이전트 권한을 읽기, 쓰기, 승인 필요 액션으로 나눕니다.
샌드박스 선택 기준에 데이터 경계와 비밀값 저장 방식을 포함합니다.
도구 이름, 입력 스키마, 오류 형식을 버전 관리합니다.
서브에이전트 병렬화는 비용 상한과 동시 실행 수를 먼저 정한 뒤 켭니다.
첫 도입 과제는 GitHub 이슈 조사, 문서 리뷰, 릴리즈 노트 비교처럼 실패해도 되돌리기 쉬운 업무로 잡습니다.

Agents API는 에이전트 개발을 끝내주는 만능 버튼이 아닙니다. 하지만 “모델 호출을 잘 엮는 문제”에서 “실제 업무를 안전하게 위임하는 문제”로 관심을 옮기게 만드는 신호입니다. 지금 필요한 것은 더 큰 프롬프트가 아니라, 세션·권한·검증·비용을 한 번에 보는 운영 설계입니다.