OpenAI Agents API 해설: AI 에이전트를 만들거나 내려받기 전 확인할 점

먼저 결론: Agents API가 바꾸는 것

OpenAI는 2026년 9월 10일 Agents API 공개 베타를 발표했습니다. Codex 뒤에서 사용하던 장기 작업용 하니스를 개발자가 서비스로 사용할 수 있게 한 것입니다. 팀이 에이전트 루프, 컨텍스트 관리, 도구 조정, 세션 진행을 처음부터 만들지 않고 OpenAI에 실행 계층을 맡긴 뒤 에이전트가 할 수 있는 일을 설계할 수 있습니다. OpenAI에 따르면 베타 기간에는 Agents API 추가 요금이 없지만 토큰과 도구 사용료는 계속 발생합니다.

그렇다고 관리형 API가 모든 프로젝트에 맞는 것은 아닙니다. 핵심은 통제권입니다. 자체 저장소, 애플리케이션이 관리하는 승인, 사설 실행 환경, 예측 가능한 오케스트레이션이 필요하면 Agents SDK나 Responses API가 더 적합할 수 있습니다. 반대로 파일, 코드, 도구, 하위 에이전트를 사용하는 긴 작업을 안정적으로 운영하는 것이 문제라면 관리형 하니스가 많은 인프라 작업을 줄여 줍니다.

이 발표가 소프트웨어 개발에 중요한 이유

공식 Agents API 발표는 오픈소스 Codex 하니스를 기반으로 한 클라우드 에이전트를 소개합니다. OpenAI가 하니스를 운영하고 유지하지만 개발자는 공개된 기반을 살펴보고 자신의 기능을 연결할 수 있습니다. 에이전트는 더 이상 프롬프트를 붙인 단순한 모델 호출이 아니라 진행 상태, 도구, 컨텍스트, 실행 환경, 실패 복구를 갖춘 런타임입니다.

OpenAI 문서는 세 가지 출발점을 제시합니다. Agents API 개요는 OpenAI가 하니스를 관리하고 진행 상태를 저장하는 장기 작업에 적합합니다. Agents SDK는 코드 중심 방식으로 애플리케이션이 배포, 저장, 도구, 승인을 소유하고 SDK가 루프를 실행합니다. Responses API는 모델 호출과 자체 오케스트레이션을 직접 제어하는 저수준 선택입니다.

이 비교는 OpenAI가 아닌 제품을 고를 때도 유용합니다. 실제 질문은 누가 런타임을 소유하며 어느 부분을 검사, 교체, 감사할 수 있는가입니다.

관리형 하니스가 대신 처리하는 일

프로덕션 에이전트에는 좋은 지시문만 필요한 것이 아닙니다. 도구 호출 뒤 계속 실행하고, 긴 작업의 상태를 보존하고, 컨텍스트를 압축하고, 전문 하위 에이전트를 조정하고, 파일을 다루고, 진행 상황을 보여 줘야 합니다. 짧은 데모는 이 작업을 숨기기 때문에 팀이 구현량을 과소평가하기 쉽습니다.

Agents API는 바로 이 운영 계층을 제공하도록 설계되었습니다. 발표는 장기 세션, 도구 사용, 컨텍스트 관리, 중간 결과, 파일과 코드를 다루는 환경을 강조합니다. 현재 개요에는 자동 컨텍스트 압축, 멀티 에이전트 오케스트레이션, 프로그램 방식 도구 호출, MCP, 선택형 샌드박스도 포함됩니다.

연구 도우미, 코드 유지보수, 데이터 분석, 장애 대응, 사내 업무를 빠르게 시험하려는 팀에는 매력적입니다. 그러나 토큰 및 도구 비용, 권한, 데이터 경계, 실패 복구, 지속적인 평가라는 책임은 남습니다.

세 가지 API를 어떻게 고를까

장기 실행과 도구 사용 에이전트의 운영이 가장 어렵다면 Agents API를 검토할 수 있습니다. 파일이나 코드가 필요한 작업, Codex 스타일 관리 하니스를 원하는 작업에 맞습니다. 대신 런타임에 대한 세밀한 소유권은 줄어듭니다.

애플리케이션이 루프와 제품 로직을 직접 가져야 한다면 Agents SDK가 적합합니다. 자체 데이터베이스, 사람의 승인, 전용 도구 라우터, 사설 배포, TypeScript나 Python 서비스와의 긴밀한 통합에 어울립니다. 공식 빠른 시작은 에이전트를 정의하고 실행한 뒤 도구, 핸드오프, 가드레일, 추적을 더하는 흐름입니다.

요청, 상태, 도구 호출, 오케스트레이션 그래프를 직접 제어하려면 Responses API를 선택합니다. 멀티 에이전트 가이드는 루트 에이전트가 독립 작업을 하위 에이전트에 나누고 애플리케이션이 함수를 실행해 결과를 반환하는 방식을 설명합니다.

첫 번째 실패를 생각하면 선택이 쉬워집니다. 긴 작업 뒤 컨텍스트가 사라지는 것이 문제라면 관리형 세션이 유리합니다. 민감한 도구를 잘못 호출하는 것이 문제라면 애플리케이션이 오케스트레이션을 소유해야 합니다.

샌드박스는 보안 경계다

파일을 읽고 코드를 실행하고 외부 서비스에 접근하는 에이전트는 실제 일을 할 수 있지만 보안 경계도 만듭니다. 접근 가능한 데이터, 코드 실행 위치, 허용 네트워크, 비밀 정보 노출 방식, 예상 밖 입력 처리 방식을 먼저 문서화해야 합니다.

OpenAI는 관리형 샌드박스, 자체 인프라, 파트너 샌드박스, 샌드박스 없음이라는 선택지를 설명합니다. 이는 단순한 설정이 아닙니다. 프로토타입은 넓은 권한을 허용할 수 있지만 프로덕션에서는 최소 권한, 명시적 승인, 감사 로그, 위험한 행동을 반복하지 않는 복구가 필요합니다.

MCP와 프로그램 방식 도구 호출은 통합을 쉽게 하지만 권한 범위도 넓힙니다. 읽기 전용 도구부터 시작하고 엄격한 스키마로 모호한 인자를 거부하며 쓰기 작업은 승인 뒤에 실행하고 조사에 필요한 입출력을 기록하세요.

도입 전 평가 목록

1. 장기 지속성: 타임아웃, 도구 실패, 컨텍스트 압축 뒤에 재개되는가?
2. 도구 규율: 필요한 도구만 올바른 인자로 호출하고 중지 조건을 지키는가?
3. 사람의 통제: 중요한 작업을 승인, 거부, 수정, 중단할 수 있는가?
4. 데이터 처리: 보존, 학습 사용, 암호화, 삭제, 지역 처리가 문서화되어 있는가?
5. 관찰 가능성: 추적, 하위 에이전트, 도구 호출, 비용, 결과를 볼 수 있는가?
6. 비용 한도: 예산과 동시성을 제한하고 폭주 루프를 발견할 수 있는가?
7. 이식성: 베타가 바뀌어도 지시문, 도구, 상태, 평가 사례를 옮길 수 있는가?
8. 품질 근거: 인상적인 데모가 아니라 실제 작업과 회귀 세트가 있는가?

개발 및 생산성 도구를 더 찾아보려면 BTTC 소프트웨어 디렉터리에서 후보를 모은 뒤 실제 업무와 비슷한 데이터와 권한으로 시험하세요. 디렉터리는 발견을 돕지만 보안 검토를 대신하지 않습니다.

지금 Agents API에 맞는 작업

여러 출처를 조사하는 작업, 작업 공간이 필요한 코드 작업, 운영 분석, 긴 내부 절차를 빠르게 검증하는 데 적합합니다. 짧고 결정적이거나 규제가 강하거나 일반 API 호출로 해결되는 작업에는 이점이 작을 수 있습니다.

초기 구조는 작게 시작하는 편이 안전합니다. 분명한 한 가지 업무, 적은 도구, 보이는 예산, 사람의 검토 지점을 두세요. 독립된 업무를 병렬로 처리할 때만 하위 에이전트를 추가합니다. OpenAI 문서도 병렬 위임은 집중도와 속도를 높일 수 있지만 토큰을 늘리고 서로 의존하는 단계에는 적합하지 않다고 설명합니다.

도입을 작게 시작하는 설계

첫 번째 실험에서는 에이전트에 주는 권한을 업무 목적에 맞게 제한하세요. 조사만 한다면 검색과 읽기만 허용하고, 파일 업데이트나 외부 서비스 전송은 별도의 승인 단계로 분리합니다. 도구 설명도 자연어에만 의존하지 말고 입력 형식, 실패의 의미, 재시도 조건, 절대로 실행하면 안 되는 조건을 명시해야 합니다. 그래야 모델의 능력뿐 아니라 제품의 경계도 시험할 수 있습니다.

로그에는 성공한 최종 답변뿐 아니라 중간 판단과 도구의 입력·출력도 남겨야 합니다. 긴 작업에서는 어떤 정보가 요약되고 삭제되었는지 확인할 수 없으면 재현하기 어려운 실패가 늘어납니다. 사람의 개입 지점, 거부된 작업, 비용, 실행 시간을 같은 평가 사례에 저장하면 베타 업데이트 전후를 비교하기도 쉽습니다.

사내 도입에서는 자율성이 높을수록 좋다고 생각하지 않는 것도 중요합니다. 오류를 사람이 쉽게 확인할 수 있는 문의 분류나 문서 초안부터 시작하세요. 송금, 삭제, 계약 변경, 고객에게 확정 메시지를 보내는 작업은 에이전트가 제안하고 사람이 최종 승인하는 흐름을 유지해야 합니다. 속도가 조금 느려져도 복구 비용을 크게 줄일 수 있습니다.

자주 묻는 질문

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

아닙니다. Agents API는 OpenAI 서비스 안에서 관리형 하니스를 실행하고, Agents SDK는 애플리케이션 안에서 실행되어 배포, 저장, 도구, 승인을 더 많이 통제합니다.

관리형 하니스를 쓰면 평가가 필요 없나요?

아닙니다. 실제 작업, 안전 테스트, 비용 모니터링, 회귀 검사가 계속 필요합니다.

처음부터 여러 하위 에이전트를 써야 하나요?

대부분은 하나의 제한된 에이전트로 시작하세요. 병렬화의 가치가 추가 비용을 정당화할 때만 늘립니다.

공개 베타는 무료인가요?

9월 10일 발표에 따르면 베타 기간의 Agents API 추가 요금은 없습니다. 토큰과 도구 비용은 정상적으로 발생합니다.

결론

Agents API는 에이전트 인프라를 소프트웨어 선택으로 바꿉니다. 상태, 도구, 승인, 실행, 관찰, 복구를 누가 소유하는지 기준으로 관리형 하니스와 SDK, Responses API를 비교하세요. 중요한 시스템에 연결하기 전에 좁은 업무, 엄격한 권한, 실제 평가, 이전 계획으로 검증하는 것이 안전합니다.