OpenAI Agents API 공개: Codex 하네스를 API로 쓰는 방식

OpenAI가 Agents API 문서를 공개하면서 개발자가 Codex 하네스를 직접 제품 안에 붙일 수 있는 길이 열렸습니다. 핵심은 단순한 “에이전트 호출 API”가 아닙니다. 세션 저장, 오케스트레이션, 컨텍스트 압축, 복구, 샌드박스 실행, MCP 연결, 서브에이전트 위임 같은 운영 부담을 OpenAI가 관리하는 구조입니다.

검색 의도는 분명합니다. “OpenAI Agents API가 기존 Responses API나 Agents SDK와 뭐가 다른가”, “프로덕션에 붙이면 어떤 구조가 안전한가”, “Codex를 우리 서비스 안에 넣는다는 게 무슨 뜻인가”를 찾는 개발자를 위한 정리입니다. 공식 문서 기준으로 보면 Agents API는 장기 작업과 상태 유지가 필요한 에이전트 워크플로우에 초점이 맞춰져 있습니다.

이번 공개에서 달라진 점

기존 AI API 통합은 보통 요청 하나를 보내고 응답 하나를 받는 구조였습니다. 애플리케이션이 대화 기록을 저장하고, 도구 호출을 처리하고, 실패한 작업을 복구하고, 긴 컨텍스트를 요약해야 했습니다. 에이전트가 길게 일할수록 애플리케이션 코드가 복잡해졌습니다.

Agents API는 이 부담을 세션 단위로 옮깁니다. 개발자는 agent, environment, session, events/items라는 네 가지 개념으로 작업을 구성합니다. agent에는 모델, 지시문, 도구, MCP 서버가 들어갑니다. environment는 샌드박스나 self-hosted 작업 공간입니다. session은 에이전트가 이어서 일하는 durable instance입니다. events와 items는 작업 중 들어오고 나가는 입력·출력 기록입니다.

문서에서 강조하는 부분은 OpenAI가 managed Codex harness를 제공한다는 점입니다. 이 하네스는 명령 실행, 파일 편집, 스킬 로딩, 외부 데이터 연결, 작업 중 steer, 컨텍스트 압축, 서브에이전트 위임, 세션 재개를 처리합니다. 개발자는 “모델에게 어떻게 말할까”보다 “이 에이전트가 어떤 환경에서 무엇을 할 수 있어야 하나”를 설계해야 합니다.

기존 API와의 차이를 개발팀 언어로 정리하면

Responses API는 모델 응답을 직접 다루고 싶은 팀에 적합합니다. 도구 실행, 상태 저장, 재시도 정책을 애플리케이션이 세밀하게 통제할 수 있습니다. 대신 구현 책임이 큽니다.

Agents SDK는 애플리케이션 내부에서 agent loop를 돌리고, handoff와 tool runner를 제어하려는 경우에 맞습니다. 자체 런타임, 자체 저장소, 자체 승인 흐름이 이미 있는 팀이라면 SDK가 더 자연스럽습니다.

Agents API는 장기 작업을 빠르게 붙이고 싶을 때 유리합니다. OpenAI가 세션과 하네스를 관리하고, 개발자는 도구와 실행 환경을 구성합니다. 예를 들어 장애 알림을 조사하는 bot, GitHub issue를 재현하는 bot, 문서를 검토하는 bot, 데이터 웨어하우스를 읽는 분석 bot처럼 “작업이 여러 단계로 이어지고 중간 상태가 남아야 하는” 서비스에 맞습니다.

차이는 자유도와 운영 부담의 교환입니다. 직접 제어가 중요하면 Responses API나 SDK가 낫고, 장기 작업과 세션 관리 부담을 줄이고 싶으면 Agents API가 맞습니다.

샌드박스는 기능이 아니라 보안 경계입니다

Agents API는 OpenAI-hosted sandbox, self-hosted sandbox, no sandbox 옵션을 전제로 설명합니다. 여기서 샌드박스를 단순 실행 환경으로 보면 위험합니다. 에이전트가 코드를 실행하고 파일을 수정하고 MCP 서버에 연결할 수 있다면, 샌드박스는 제품 보안 경계의 일부입니다.

OpenAI-hosted sandbox는 빠른 실험에 좋습니다. 인프라를 직접 만들지 않아도 세션을 시작하고 결과를 받을 수 있습니다. 다만 내부 네트워크 접근, 데이터 위치, 감사 요구사항이 강한 조직은 self-hosted 환경을 검토해야 합니다. no sandbox는 도구 호출만으로 충분하거나 실행 환경을 아예 열지 않는 경우에 적합합니다.

운영 기준은 간단합니다. 에이전트가 파일을 쓸 수 있으면 별도 작업 디렉터리를 줘야 합니다. 명령을 실행할 수 있으면 네트워크와 파일 권한을 제한해야 합니다. MCP 서버를 연결하면 서버별 권한과 감사 로그를 남겨야 합니다. 샌드박스 없는 에이전트도 안전하다고 단정하면 안 됩니다. 외부 API를 호출하는 도구가 붙는 순간 그 도구가 실행 권한이 됩니다.

개발자가 주목할 제품 기회

Agents API의 의미는 “ChatGPT 같은 화면을 하나 더 만든다”가 아닙니다. 기존 업무 도구 안에 장기 작업자를 붙일 수 있다는 점입니다. 예를 들어 보안 콘솔에서 알림 하나를 누르면 에이전트가 로그를 읽고, 관련 커밋을 찾고, 재현 스크립트를 만든 뒤, 복구 액션은 사람 승인을 기다릴 수 있습니다.

고객지원 콘솔도 비슷합니다. 티켓 내용을 읽고, 사용자의 계정 상태를 확인하고, 관련 문서를 찾고, 답변 초안을 만들 수 있습니다. 단, 환불·계정 삭제·개인정보 변경 같은 작업은 승인 단계로 분리해야 합니다.

데이터 분석 제품에서는 read-only SQL 도구와 연결해 자연어 질문을 분석 쿼리로 바꾸고, 결과를 설명하고, 다음 질문으로 이어갈 수 있습니다. 여기서 중요한 것은 SQL 실행 권한을 읽기 전용으로 제한하고, 큰 쿼리에는 비용 제한을 두는 것입니다.

도입 전에 정해야 할 운영 원칙

첫 번째 원칙은 도구 최소화입니다. 처음부터 web search, MCP, shell, file write, external API를 모두 붙이면 문제 원인을 찾기 어렵습니다. 첫 버전은 읽기 전용 도구 1~2개와 명확한 성공 조건으로 시작하는 편이 낫습니다.

두 번째 원칙은 사람 승인입니다. 배포, 삭제, 결제, 외부 발송, 개인정보 조회는 모델 판단만으로 실행하지 않습니다. Agents API가 세션을 이어갈 수 있다는 장점은 승인 대기 상태를 자연스럽게 저장할 수 있다는 뜻이기도 합니다.

세 번째 원칙은 관측성입니다. 어떤 세션이 어떤 도구를 어떤 입력으로 호출했고, 어떤 결과를 받았는지 저장해야 합니다. 모델 출력만 로그로 남기면 사고 분석이 불가능합니다. 도구 호출, 비용, 지연시간, 실패 이유, 사용자 승인 여부를 함께 봐야 합니다.

실행 체크리스트

• Agents API, Agents SDK, Responses API 중 어떤 런타임이 맞는지 먼저 고른다.
• 첫 실험은 장기 작업이지만 위험이 낮은 문서 검토나 이슈 조사로 시작한다.
• 샌드박스 유형을 OpenAI-hosted, self-hosted, no sandbox 중 명시적으로 선택한다.
• 에이전트 도구는 읽기 전용부터 시작하고 쓰기 권한은 나중에 추가한다.
• MCP 서버별 권한, 입력 스키마, 반환값 범위를 좁힌다.
• 삭제, 배포, 결제, 외부 발송은 사람 승인 없이는 실행하지 않는다.
• 세션별 도구 호출, 비용, 지연시간, 실패 이유를 로그로 남긴다.
• 모델 응답이 아니라 실제 도구 실행 결과를 성공 기준으로 삼는다.

출처: OpenAI Developers, “Agents API”; OpenAI Developers, “Agents”