OpenAI Agents API 운영법: 장시간 에이전트와 도구 호출을 제품에 넣는 기준

OpenAI Agents API는 “에이전트 API가 하나 더 생겼다” 정도로 보면 놓치는 부분이 많습니다. 공식 설명에서 중요한 문장은 장시간 실행, 컨텍스트 관리, 도구 사용, 서브에이전트 조정, 파일 작업, 코드 실행, 중간 결과 저장을 OpenAI가 호스팅하는 하네스와 인프라로 제공한다는 부분입니다. 즉 이 API의 본질은 모델 호출이 아니라 에이전트 런타임 임대입니다.

개발자가 바로 궁금해할 질문은 하나입니다. “우리 서비스에 이걸 언제 써야 하는가?” 답은 단순하지 않습니다. 짧은 질의응답이나 한 번의 요약 작업에는 과합니다. 반대로 여러 파일을 읽고, 도구를 고르고, 중간 결과를 남기며, 몇 분 이상 이어지는 업무에는 직접 하네스를 만드는 것보다 빠를 수 있습니다.

문제: 에이전트 PoC는 쉽지만 운영은 어렵습니다

대부분의 팀은 처음에 다음 구조로 시작합니다.

사용자 요청을 받는다.
모델에 프롬프트를 보낸다.
함수 호출이 오면 내부 API를 실행한다.
결과를 다시 모델에 넣는다.
최종 답변을 보여준다.

이 구조는 데모에서는 잘 작동합니다. 하지만 운영 제품이 되면 바로 문제가 생깁니다.

작업이 30초를 넘으면 HTTP 요청 타임아웃에 걸립니다.
도구가 많아질수록 프롬프트에 모든 스키마를 넣기 어렵습니다.
컨텍스트가 길어지면 토큰 비용과 오류가 같이 늘어납니다.
사용자가 중간에 나가도 작업 상태를 보존해야 합니다.
복잡한 업무는 여러 하위 작업으로 나눠 병렬 처리해야 합니다.
에이전트가 생성한 파일, 패치, 로그를 보관해야 합니다.

Agents API는 이 부분을 표준 하네스에 맡기는 방향입니다.

원인: 직접 만든 에이전트 하네스는 숨은 유지보수 비용이 큽니다

직접 에이전트 런타임을 만들면 처음에는 유연합니다. 하지만 시간이 지나면 내부 프레임워크가 됩니다. 큐, 워커, 샌드박스, 파일 시스템, 로그, 권한, 컨텍스트 압축, 도구 검색, 재시도 정책, 서브태스크 조정이 모두 필요해집니다.

특히 도구 호출은 생각보다 까다롭습니다. 도구가 5개일 때는 전체 스키마를 모델에 넣으면 됩니다. 도구가 50개가 되면 모델이 잘못된 도구를 고르거나, 토큰 비용이 늘거나, 캐시 효율이 떨어집니다. OpenAI가 언급한 tool search는 필요한 도구 정의를 그때그때 로드해 토큰 사용량을 줄이는 접근입니다.

컨텍스트도 마찬가지입니다. 대화를 계속 붙이면 길어지고, 중간 내용을 요약하면 중요한 정보가 사라질 수 있습니다. Agents API는 세션이 컨텍스트 한계에 가까워질 때 이전 내용을 자동 압축해 이어갈 수 있게 한다고 설명합니다. 물론 이 기능을 맹신하면 안 됩니다. 하지만 직접 압축 파이프라인을 구현하기 전 기본값으로 실험할 만합니다.

해결: 사용 후보를 세 가지로 나눠야 합니다

첫 번째 후보는 코드베이스 작업입니다. 여러 파일을 읽고, 테스트를 실행하고, 패치를 만들고, 실패 로그를 보고 다시 수정하는 작업은 장시간 에이전트에 적합합니다. 단, 실제 머지는 사람 승인 후 실행해야 합니다.

두 번째 후보는 리서치와 분석입니다. 경쟁사 페이지 20개를 읽고, 가격표를 비교하고, 차이점을 표로 정리하는 작업은 서브에이전트 병렬화의 이점이 큽니다. 각 서브에이전트가 하나의 사이트나 문서 묶음을 맡고, 메인 에이전트가 결과를 합치는 구조가 가능합니다.

세 번째 후보는 운영 백오피스입니다. 고객 문의 분류, 환불 검토, 내부 지표 점검, 장애 초동 분석처럼 도구 호출과 정책 판단이 섞인 업무입니다. 다만 이 영역은 보안과 감사 로그가 중요하므로 처음부터 쓰기 작업을 허용하면 안 됩니다.

아키텍처 기준: 샌드박스 선택부터 정해야 합니다

OpenAI Agents API는 OpenAI 관리 샌드박스, 자체 인프라, 파트너 샌드박스 같은 선택지를 언급합니다. 실무에서는 다음 기준으로 나누면 됩니다.

개인정보와 내부 소스코드가 적고 빠른 실험이 목적이면 관리형 샌드박스가 편합니다. 초기 PoC, 공개 데이터 리서치, 샘플 파일 처리에 적합합니다.

회사 내부망, 민감 데이터, 특정 보안 정책이 필요하면 자체 인프라나 VPC 연동형 환경을 검토해야 합니다. 이때는 네트워크 접근 범위, 시크릿 주입 방식, 파일 보존 정책을 먼저 문서화해야 합니다.

컴퓨팅 요구가 특수하면 파트너 샌드박스를 검토할 수 있습니다. 예를 들어 GPU, 대용량 메모리, 특정 패키지 캐시, 빠른 콜드스타트가 중요할 수 있습니다.

운영 지표: 모델 점수보다 먼저 볼 숫자

Agents API를 붙였다면 다음 지표를 봐야 합니다.

작업 성공률: 사용자가 기대한 완료 상태까지 도달한 비율
평균 도구 호출 수: 작업 하나에 몇 번의 외부 호출이 필요한지
재시도율: 모델 재호출, 도구 재호출, 샌드박스 재시작 비율
컨텍스트 압축 이후 오류율: 긴 세션에서 중요한 조건이 사라지는지
사람 승인 대기 시간: 승인 UX가 병목인지
비용/작업: 토큰 비용뿐 아니라 도구 실행 비용과 샌드박스 비용 포함
감사 가능성: 누가 어떤 입력으로 어떤 도구를 실행했는지 추적 가능한지

이 숫자를 보지 않으면 “에이전트가 똑똑해 보인다”는 인상만 남습니다. 운영 제품에서는 인상이 아니라 완료율과 재현성이 필요합니다.

피해야 할 설계

첫째, 모든 도구를 처음부터 에이전트에 열어두지 마세요. 읽기 도구, 초안 도구, 실행 도구를 분리해야 합니다. 실행 도구에는 승인, 권한, 한도, 로그를 붙입니다.

둘째, 컨텍스트 압축을 영구 기억처럼 쓰지 마세요. 압축은 비용과 길이 문제를 줄이는 기술이지, 법적 기록이나 정확한 상태 저장소가 아닙니다. 중요한 상태는 DB에 구조화해 저장해야 합니다.

셋째, 서브에이전트 병렬화를 무조건 쓰지 마세요. 병렬화는 독립적인 하위 작업에서 효과가 큽니다. 서로의 결과에 계속 의존하는 작업은 오히려 조정 비용이 늘어납니다.

실행 체크리스트

후보 업무를 10개 적고, 그중 5분 이상 걸리며 도구 호출이 3개 이상 필요한 업무만 남깁니다.
각 업무를 읽기, 초안, 실행 단계로 분리합니다.
실행 단계에는 사람 승인과 롤백 가능 여부를 표시합니다.
샌드박스 선택 기준을 개인정보, 내부망 접근, 패키지 요구, 비용으로 나눕니다.
작업 성공률, 도구 호출 수, 재시도율, 비용/작업을 대시보드에 넣습니다.
컨텍스트 압축 이후에도 반드시 보존해야 하는 값은 별도 DB 필드로 저장합니다.
첫 배포는 내부 사용자 5~10명에게만 열고 실패 로그를 수집합니다.

OpenAI Agents API는 에이전트 제품을 빠르게 시작하게 해주는 강한 도구입니다. 하지만 모든 AI 기능을 여기에 올릴 필요는 없습니다. 장시간 실행, 다중 도구, 파일 작업, 서브태스크 조정이 필요한 곳에 제한적으로 쓰고, 실행 권한과 감사 로그를 먼저 설계하는 팀이 가장 빨리 안정화할 수 있습니다.