오픈AI가 코덱스의 뼈대를 API로 열었습니다 — 에이전트 API 공개 베타와 컨테이너 최소 5분
오픈AI가 9월 10일 에이전트 API를 공개 베타로 열었습니다. 그동안 코덱스를 움직이던 실행 뼈대를 API 호출 하나로 쓸 수 있게 한 것입니다.
개발자가 직접 만들어야 했던 세션 관리, 순서 조율, 문맥 압축, 중단 복구를 오픈AI가 대신 맡습니다. 개발자에게 남는 몫은 도구를 붙이고 실행 환경을 고르는 일뿐입니다.
API 자체에 붙는 별도 수수료는 없습니다. 다만 컨테이너는 분 단위로 과금되고 최소 5분이 붙습니다. 무엇이 달라졌고 무엇이 아직 남았는지 하나씩 보겠습니다.
코덱스를 돌리던 그 뼈대가 API 한 줄이 됐습니다
오픈AI의 코딩 에이전트 코덱스는 그동안 오픈AI 안에서만 돌던 물건이었습니다. 모델만 API로 열려 있었고, 그 모델을 실제로 오래 굴리는 장치는 바깥에 없었습니다.
이번 발표의 핵심은 그 장치를 통째로 외부에 열었다는 점입니다. 오픈AI는 이것을 코덱스 하네스라고 부릅니다.
같은 모델을 쓰더라도 하네스가 있느냐 없느냐에 따라 결과가 크게 갈립니다. 오래 걸리는 일을 끝까지 끌고 가는 능력이 거기서 나오기 때문입니다.
9월 10일, 오픈AI가 공개 베타로 연 것
에이전트 API는 9월 10일부터 모든 개발자에게 공개 베타로 열렸습니다. 신청 대기나 초대 코드가 필요하지 않습니다.
함께 공개된 것이 호스티드 샌드박스입니다. 에이전트가 코드를 실제로 실행해 볼 수 있는 격리된 공간을 오픈AI가 직접 제공합니다.
공개 베타이므로 규격이 아직 굳지 않았습니다. 프로덕션에 바로 올리기 전에 변경 기록을 따라가는 편이 안전합니다.
하네스라는 말부터 풀어봅니다
하네스는 원래 말이나 장비를 몸에 묶어 고정하는 끈을 뜻합니다. 소프트웨어에서는 어떤 부품을 실제로 돌게 붙잡아 주는 주변 장치를 가리킵니다.
언어 모델 하나만 놓고 보면 입력을 받아 출력을 내놓는 함수에 가깝습니다. 혼자서는 여러 단계를 이어가지도, 도구를 부르지도, 실패를 복구하지도 못합니다.
그 빈자리를 채우는 코드 덩어리가 하네스입니다. 에이전트를 만들어 본 팀이라면 이미 자기 손으로 한 번씩 짜 본 부분입니다.
지금까지 개발자가 직접 만들던 것들
에이전트를 제품에 넣으려면 모델 호출 바깥에 붙일 코드가 상당히 많습니다. 대화가 어디까지 진행됐는지 저장하고, 다음에 누가 움직일지 정하고, 기억이 넘치면 접고, 중간에 끊기면 이어 붙여야 합니다.
이 코드는 재미없고 잘 깨집니다. 그런데도 제품마다 거의 똑같이 다시 짭니다. 개발자들이 오케스트레이션 계층을 싫어하면서도 매번 만드는 이유입니다.
이번 발표는 그 계층을 오픈AI가 관리형으로 떠맡겠다는 선언에 가깝습니다.
세션 관리 — 대화가 며칠 이어져도 끊기지 않게
에이전트가 하는 일은 한 번의 질의응답으로 끝나지 않습니다. 자료를 찾고, 코드를 고치고, 결과를 확인하는 과정이 몇 시간에서 며칠까지 이어질 수 있습니다.
에이전트 API는 이 긴 흐름을 세션이라는 단위로 오픈AI가 보관합니다. 클라이언트가 꺼져도 세션은 남습니다.
직접 만들 때는 이 부분에 데이터베이스와 재시작 로직이 필요했습니다. 그 부담이 사라집니다.
오케스트레이션 — 누가 다음 차례인지 정하는 일
여러 에이전트와 여러 도구가 얽히면 다음에 무엇을 실행할지 정하는 규칙이 필요합니다. 이것이 오케스트레이션입니다.
잘못 짜면 같은 도구를 반복해서 부르거나, 끝난 일을 다시 시작하거나, 아무 일도 하지 않고 멈춥니다.
에이전트 API는 이 판정을 코덱스가 쓰던 방식 그대로 가져갑니다. 오픈AI 내부에서 다듬은 규칙을 그대로 빌려 쓰는 셈입니다.
컨텍스트 압축 — 기억이 넘칠 때 접는 기술
모델이 한 번에 볼 수 있는 분량에는 상한이 있습니다. 긴 작업은 반드시 그 상한에 부딪힙니다.
이때 지난 기록을 요약해 접고 중요한 것만 남기는 처리가 필요합니다. 오픈AI는 이것을 컨텍스트 컴팩션이라고 부릅니다.
무엇을 버리고 무엇을 남길지는 품질에 직접 영향을 줍니다. 직접 만든 압축이 엉성하면 에이전트가 앞에서 정한 것을 잊고 되돌아갑니다.
복구 — 중간에 끊겨도 이어서 하는 장치
긴 작업은 반드시 중간에 끊깁니다. 네트워크가 흔들리거나, 도구가 실패하거나, 실행 환경이 재시작됩니다.
처음부터 다시 하면 시간과 비용이 두 배로 듭니다. 그래서 어디까지 됐는지 알고 그 지점부터 이어 가는 장치가 필요합니다.
에이전트 API는 이 복구를 기본으로 제공합니다. 개발자가 체크포인트를 손으로 설계하지 않아도 됩니다.
개발자가 남기는 몫은 도구와 실행 환경뿐
오픈AI의 설명을 그대로 옮기면, 오픈AI가 세션과 조율과 압축과 복구를 맡고 애플리케이션은 도구를 제공하고 실행 환경을 고릅니다.
즉 개발자가 신경 쓸 것이 두 가지로 줄어듭니다. 우리 서비스의 기능을 도구로 어떻게 노출할 것인가, 그리고 코드를 어디서 돌릴 것인가입니다.
이 두 가지는 여전히 각 서비스의 고유한 영역이라 남겨 둔 것으로 보입니다.
샌드박스 — 코드를 실제로 돌려보는 방
에이전트가 유용해지는 순간은 글을 쓰는 것을 넘어 실제로 무언가를 실행할 때입니다. 코드를 돌리고 결과를 보고 고치는 과정입니다.
그런데 모델이 만든 코드를 그냥 서버에서 돌리면 위험합니다. 격리된 공간이 필요하고, 그 공간이 샌드박스입니다.
에이전트 API는 오픈AI가 직접 운영하는 샌드박스를 붙여 줍니다. 컨테이너 환경을 따로 구축하지 않아도 됩니다.
호스티드 샌드박스와 직접 준비한 환경의 차이
샌드박스는 고를 수 있습니다. 오픈AI가 제공하는 것을 쓸 수도 있고, 우리 쪽 환경을 붙일 수도 있습니다.
사내 데이터베이스나 내부망 도구에 닿아야 하는 작업이라면 직접 준비한 환경이 맞습니다. 반대로 계산과 변환 위주라면 호스티드가 편합니다.
문서에는 샌드박스를 쓰지 않는 접수용 에이전트가 작업 중 무거운 부분만 샌드박스 에이전트에 넘기는 구성도 나옵니다. 전부를 격리할 필요는 없다는 뜻입니다.
멀티 에이전트 위임 — 일을 나눠 맡기는 구조
하나의 에이전트가 모든 것을 처리하면 문맥이 금방 넘치고 판단도 흐려집니다. 그래서 독립적인 조각을 서브에이전트에게 넘기는 방식이 쓰입니다.
에이전트 API는 이 위임을 설정으로 켭니다. 서로 관계없는 조사 과제 여러 개를 동시에 돌리는 구성이 대표적입니다.
각 서브에이전트는 자기 몫만 보므로 문맥이 가볍습니다. 상위 에이전트는 결과만 받아 정리합니다.
동시 서브에이전트 기본값 3, 설정으로 4 이상
동시에 움직일 수 있는 서브에이전트 수는 설정값으로 정합니다. 기본값은 3입니다.
문서 예시에는 이 값을 4로 올린 구성이 나옵니다. 이 숫자는 전체 트리에서 동시에 진행 중인 차례의 개수를 제한합니다.
값을 올리면 빨라지지만 동시에 토큰이 더 빨리 소모됩니다. 병렬도는 속도와 비용을 맞바꾸는 손잡이입니다.
트리 깊이에 정해진 상한이 없다는 뜻
서브에이전트의 총 개수나 트리 깊이에는 고정된 상한이 없습니다. 제한되는 것은 동시에 활성인 차례의 수뿐입니다.
이론상 서브에이전트가 다시 서브에이전트를 부르는 구조를 깊게 쌓을 수 있습니다. 복잡한 조사 과제를 잘게 쪼갤 여지가 큽니다.
동시에 비용이 예상 밖으로 불어날 여지도 커집니다. 상한이 없다는 말은 스스로 상한을 정해야 한다는 말이기도 합니다.
요금 — API 자체 수수료는 없습니다
에이전트 API를 쓴다고 해서 추가 요금이 붙지는 않습니다. 쓴 토큰과 쓴 도구에 대해서만 냅니다.
모델 사용은 선택한 모델의 평소 API 단가로 청구됩니다. 오픈AI가 제공하는 도구에 대해서는 기존 도구 요금이 그대로 적용됩니다.
관리형 인프라를 공짜로 얹어 주는 구조라 진입 장벽이 낮습니다.
컨테이너는 분 단위 과금, 최소 5분
다만 컨테이너에는 별도 요금이 붙습니다. 해당하는 컨테이너 세션은 분 단위로 청구되고, 세션당 최소 5분이 적용됩니다.
즉 20초 만에 끝나는 작업도 5분치를 냅니다. 짧은 작업을 잘게 여러 번 돌리면 최소 과금이 반복해서 붙습니다.
이 조건은 요금표의 한 줄로 보이지만 실제로는 설계를 바꾸는 조건입니다.
이 최소 5분이 실제 비용에서 갖는 의미
짧은 작업 열 개를 각각 별도 세션으로 돌리면 최소 과금이 열 번 붙습니다. 같은 일을 한 세션 안에서 이어 처리하면 한 번으로 끝납니다.
그래서 세션을 잘게 쪼개지 않고 묶는 쪽이 유리합니다. 사용자 요청마다 새 컨테이너를 띄우는 구조는 비용이 빠르게 샙니다.
반대로 세션을 오래 열어 두면 유휴 시간에도 분이 쌓입니다. 언제 닫을지에 대한 규칙이 필요합니다.
에이전트 SDK와 무엇이 다른가
오픈AI에는 이미 에이전트 SDK가 있습니다. 파이썬과 자바스크립트용으로 공개된 가벼운 멀티 에이전트 프레임워크입니다.
SDK는 내 서버에서 도는 라이브러리입니다. 조율 코드가 내 프로세스 안에 있고, 세션 보관도 내 책임입니다.
에이전트 API는 그 조율을 오픈AI 쪽으로 옮긴 것입니다. 같은 목적을 다른 위치에서 해결합니다.
오픈소스 프레임워크를 쓰던 팀의 선택지
이미 다른 프레임워크로 에이전트를 굴리는 팀이라면 당장 갈아탈 이유는 크지 않습니다. 잘 도는 것을 바꾸는 비용이 큽니다.
다만 오래 도는 작업에서 세션과 복구 때문에 고생하고 있다면 비교해 볼 값이 있습니다. 그 부분이 이번 API의 강점입니다.
반대로 여러 모델 제공자를 섞어 쓰는 구조라면 특정 제공자의 관리형 계층에 묶이는 점을 감안해야 합니다.
기억은 여전히 밖에서 붙여야 합니다
이번 API가 다루는 것은 한 작업 안에서의 단기 문맥입니다. 사용자가 지난달에 무엇을 좋아했는지 같은 장기 기억은 범위 밖입니다.
개발자 사이의 평가도 같습니다. 단기 문맥은 깔끔하게 처리하지만 지속 기억과 검색, 개인화 계층은 바깥에서 붙이는 것을 전제로 합니다.
제품이 성숙할수록 이 바깥 계층의 비중이 커집니다. 관리형이라고 해서 전부 사라지지는 않습니다.
응답 페이로드를 바로 못 돌려받는 제약
개발자 포럼에는 실행을 시작시킬 수는 있지만 호출한 쪽으로 응답 본문을 곧장 돌려받지 못한다는 지적이 올라와 있습니다.
동기 응답이 필요한 화면에서는 이 점이 불편합니다. 결과를 따로 조회하거나 알림을 받는 구조를 추가로 짜야 합니다.
공개 베타 단계라 이런 부분은 바뀔 여지가 있습니다. 지금 설계한다면 우회 경로를 염두에 두는 편이 안전합니다.
실제 사례 — 리서치 에이전트를 짠다면
여러 자료를 찾아 비교하고 한 편의 정리본을 내는 작업을 생각해 봅니다. 주제를 몇 갈래로 나누고 각 갈래를 서브에이전트에게 맡깁니다.
동시 서브에이전트를 3에서 4로 올리면 네 갈래가 함께 돕니다. 상위 에이전트는 네 결과를 받아 합칩니다.
이 구조에서 컨텍스트 압축이 특히 값을 합니다. 갈래마다 자료가 많아도 상위로 올라오는 것은 요약된 결과뿐이기 때문입니다.
실제 사례 — 코드 작업을 맡긴다면
저장소를 읽고 고치고 테스트를 돌리는 작업은 샌드박스가 필요합니다. 오픈AI 호스티드 샌드박스를 쓰면 준비 없이 시작할 수 있습니다.
테스트가 실패하면 고치고 다시 돌리는 반복이 이어집니다. 여기서 복구 장치가 없으면 중간에 끊길 때마다 처음부터 다시 해야 합니다.
단 컨테이너 최소 5분 과금이 붙으므로 한 세션 안에서 여러 수정을 이어 처리하는 쪽이 낫습니다.
저시력 사용자 관점에서 보는 변화
에이전트가 오래 도는 작업을 스스로 끌고 가면 화면을 계속 지켜볼 필요가 줄어듭니다. 작은 글씨의 진행 상황을 눈으로 좇는 부담이 덜어집니다.
중요한 것은 결과를 어떻게 알려 주느냐입니다. 끝났다는 사실과 요약을 큰 글씨나 음성으로 전달하면 접근성이 크게 좋아집니다.
반대로 진행 상황이 작은 회색 글씨로만 흘러가면 관리형의 이점이 사라집니다. 이 부분은 여전히 만드는 쪽의 몫입니다.
핵심 정리
오픈AI가 9월 10일 에이전트 API를 공개 베타로 열었습니다. 코덱스를 굴리던 실행 뼈대를 외부 개발자에게 그대로 개방한 것입니다.
세션, 조율, 컨텍스트 압축, 복구를 오픈AI가 맡고 개발자는 도구와 실행 환경을 고릅니다. 동시 서브에이전트 기본값은 3이고 트리 깊이에는 상한이 없습니다.
API 자체 수수료는 없지만 컨테이너는 분 단위에 최소 5분입니다. 장기 기억과 동기 응답은 여전히 바깥에서 해결해야 합니다.
참고하실 만한 것
에이전트를 이미 만들고 계시다면 오픈AI 문서의 에이전트 API 개요와 샌드박스 가이드를 먼저 보시면 좋습니다. 설정값 이름과 기본값이 그대로 적혀 있습니다.
SVIL 블로그에서는 AI 도구와 개발 워크플로우를 저시력 사용자도 읽기 쉬운 큰 글씨로 정리하고 있습니다. 관련 글을 이어서 보시면 흐름이 잡힙니다.
이 글의 근거가 된 원문은 아래 출처 목록에 모아 두었습니다.
출처
- OpenAI — Introducing the Agents API
- OpenAI API Docs — Agents API overview
- OpenAI API Docs — Sandbox Agents
- OpenAI API Docs — Pricing
- OpenAI Developer Community — Introducing the Agents API and hosted sandboxes
- MarkTechPost — OpenAI Launches the Agents API in Public Beta
- AlphaSignal — Agents API and the orchestration layer
- OpenAI API Docs — Changelog
협업문의 : kuroicode@gmail.com
블로그 : https://blog.svil.dev/
홈페이지 : https://svil.dev/