OpenAI Agents API란? 관리형 에이전트 실행 환경 이해하기
모델에 질문을 한 번 보내는 것과, 파일을 읽고 도구를 호출하며 여러 단계의 작업을 끝내는 에이전트를 운영하는 것은 다른 문제입니다. 후자에서는 작업 기록, 실행 권한, 중간 실패, 결과물 보관까지 설계해야 합니다. OpenAI Agents API는 Codex의 에이전트 하네스를 OpenAI가 관리하는 API로 사용할 수 있게 하는 선택지입니다.
OpenAI는 2026년 9월 10일 Agents API 공개 베타를 발표했습니다. 이 글에서는 설치 명령을 나열하기보다 무엇을 맡길 수 있는지, Agents SDK·Responses API와 어떻게 다른지, 어떤 작은 업무로 도입 여부를 판단하면 좋을지 살펴봅니다.
자료 확인: 2026년 9월 16일 · 공식 발표와 개발자 문서 기준
- 관리형 하네스는 모델 자체가 아니라 작업을 이어 가고 도구를 쓰도록 조율하는 실행 기반입니다.
- 실행 환경을 선택할 수 있어도 도구 권한, 외부 시스템 접근, 승인 기준은 개발자가 정해야 합니다.
- 긴 작업에 유용한 선택지이지만, 단발성 호출까지 모두 옮길 필요는 없습니다.
1. 관리형 하네스는 무엇을 관리할까?
하네스는 에이전트가 입력을 받고, 필요한 도구를 사용하고, 중간 결과를 다음 단계에 반영하도록 돕는 실행 틀입니다. 공식 개요는 세션, 작업 조율, 컨텍스트 압축, 복구를 OpenAI가 관리하고 애플리케이션은 도구와 실행 환경을 제공하거나 선택한다고 설명합니다. 따라서 “더 강한 모델을 호출하는 API”보다는 에이전트 운영 책임을 나누는 방식으로 이해하는 편이 정확합니다.
- Agent: 사용할 모델, 지시문, 도구와 MCP 서버를 정하는 구성입니다.
- Environment: 파일을 다루고 명령을 실행하는 선택적 샌드박스나 컴퓨터 환경입니다.
- Session: 여러 차례 입력을 받으며 작업을 이어 갈 수 있는 지속적인 에이전트 인스턴스입니다.
- Events와 items: 세션에 전달된 입력과 생성된 출력을 추적하는 자료입니다.
예를 들어 첫 요청에서 조사 범위를 정하고, 중간 결과를 본 뒤 같은 세션에 추가 조건을 줄 수 있습니다. 긴 문맥을 요약하는 자동 압축과 독립적인 하위 작업을 나누는 기능도 제공합니다. 다만 이를 모든 정보가 그대로 보존되거나 결과가 자동으로 정확해진다는 뜻으로 받아들이지는 마세요. 중요한 제약과 판단 근거는 결과 기록에 남겨 검토해야 합니다.
그림에서 self_hosted는 작업 환경의 수명주기를 앱이 관리한다는 뜻이지, OpenAI의 관리형 하네스까지 자체 호스팅한다는 뜻은 아닙니다. none에는 로컬 명령·파일 작업 환경이 없지만 원격 MCP와 앱의 함수 도구는 사용할 수 있습니다. 공식 아키텍처 문서의 경계를 기준으로 설계하세요.
2. Agents API·Agents SDK·Responses API의 차이
세 가지는 같은 기능의 상위·하위 요금제가 아닙니다. 공식 개발자 가이드가 구분하는 핵심은 에이전트 실행 흐름을 어디에서 운영하고, 상태와 도구 연결을 누가 관리하는가입니다.
| 선택지 | 주된 역할 | 판단할 질문 |
|---|---|---|
| Agents API | OpenAI가 관리하는 Codex 하네스와 저장된 세션을 사용 | 긴 작업의 실행 기반을 직접 운영하는 부담을 줄이고 싶은가? |
| Agents SDK | 애플리케이션 안에서 에이전트 루프, 도구, 핸드오프를 구성 | 배포·저장소·승인·런타임 통합을 내 앱에서 제어해야 하는가? |
| Responses API | 모델 응답과 도구 사용을 바탕으로 통합을 직접 구성 | 모델 호출을 기존 서비스 흐름에 직접 조합하는 편이 단순한가? |
문장 하나를 분류하거나 짧은 문서를 요약하는 기능이라면 기존 모델 호출 구조부터 검토할 수 있습니다. 반대로 파일과 도구를 오가며 조사하고 후속 요청까지 처리하는 작업이라면 세션과 실행 기반을 묶어 제공하는 방식의 이점을 비교해 볼 만합니다. 이미 자체 승인 체계와 배포 환경이 잘 갖춰진 팀은 관리형이라는 이유만으로 이전할 필요가 없습니다.
3. 샌드박스 선택과 데이터 경계부터 정하기
공식 가이드는 OpenAI 호스팅 샌드박스, 자체 호스팅 샌드박스, 샌드박스 없는 실행을 구분합니다. 파일이나 명령 실행이 필요한지부터 판단하세요. 질문에 답하거나 외부 도구를 호출하는 데 로컬 파일 작업이 필요 없다면 샌드박스 없이 구성하는 선택지도 있습니다.
자체 호스팅 샌드박스를 선택했다고 Agents API 전체가 내 서버에서만 실행되는 것은 아닙니다. 관리형 하네스와 작업 환경을 구분해야 합니다. 네트워크 접근, 필요한 패키지, 전달할 파일, 보존할 결과물을 정하고 외부 MCP 서버가 어떤 데이터와 작업에 접근하는지도 따로 살펴보세요.
데이터 요건은 도입 초기에 확인할 사항입니다. 확인일 기준 공식 개요는 Agents API의 데이터 레지던시가 미국 지역만 지원되며, Zero Data Retention(ZDR)은 지원하지 않는다고 안내합니다. 자체 호스팅 샌드박스를 써도 ZDR 적용 대상으로 바뀌지 않습니다. 특정 지역 내 보관이나 무보관 조건이 필요한 조직이라면 기능 시험보다 이 조건 검토가 먼저입니다.
4. 업무에 적용한다면: 구체적인 사례 세 가지
다음은 도입 범위를 정하기 위한 설계 예시입니다. 도구 연결과 권한 설정이 필요하며, API를 선택하는 것만으로 해당 업무가 완성되지는 않습니다. 각 예시에서 결과물과 사람의 검토 지점을 먼저 정해 두는 것이 핵심입니다.
사례 1. 장애 조사 자료를 하나의 보고서로 모으기
목적과 입력: 장애 알림이 발생했을 때 담당자가 살펴볼 첫 조사 자료를 정리합니다. 민감정보를 제거한 로그, 최근 배포 시각, 변경 목록, 읽기 전용 상태 조회 도구를 준비합니다. 처음부터 운영 서버의 재시작·설정 변경 권한까지 주지는 않습니다.
진행 흐름: 로그에서 이상 시점을 찾는 작업과 배포 변경을 확인하는 작업처럼 독립적인 조사를 나누고, 결과를 시간순으로 합칩니다. 각 조사에는 확인한 자료와 시각을 남기도록 요청합니다. 서로 다른 시간대나 오래된 기록을 같은 사건으로 잘못 묶지 않았는지 점검해야 합니다.
산출물과 검토: 사건 타임라인, 관찰된 사실, 원인 후보, 추가 확인 항목을 구분한 보고서를 받습니다. “원인 확정”과 “가능성 있는 가설”을 섞지 않았는지 담당자가 확인하고, 복구 조치가 필요하면 별도 승인을 거칩니다. 자료 수집 시간을 줄이는 것과 자동 복구를 허용하는 것은 별개의 결정입니다.
사례 2. 저장소의 테스트 실패 원인 조사하기
목적과 입력: 실패한 테스트 출력, 관련 변경사항, 재현에 필요한 샘플 파일을 모읍니다. 실행이 필요하다면 격리된 환경에서 테스트할 수 있도록 준비하고, 운영용 키나 실제 고객 데이터는 제외합니다. 조사 대상 브랜치와 커밋도 명확히 지정하세요.
진행 흐름: 실패 지점, 최근 코드 변화, 문서와 실제 설정의 차이를 확인한 뒤 수정 후보를 제안하게 합니다. 확인하지 않은 의존성이나 환경 차이가 있다면 남은 조건으로 기록하도록 합니다. 단순히 오류 메시지를 설명하는 데서 끝내지 않고 어떤 증거가 수정 제안을 뒷받침하는지 연결하는 방식입니다.
산출물과 검토: 재현 절차, 원인 후보, 패치 제안, 확인한 테스트와 확인하지 못한 테스트 목록을 받습니다. 담당자는 차이를 검토하고 필요한 테스트를 실행한 뒤 병합 여부를 결정합니다. 세션이 완료됐다는 사실만으로 코드가 안전하거나 모든 테스트가 통과했다고 판단하면 안 됩니다.
사례 3. 제품 업데이트 비교 자료를 반복해서 만들기
목적과 입력: 비교할 제품, 이전 기준 버전, 공식 릴리스 노트 URL, 확인 기간을 정합니다. “최근 소식 전부”보다 “이번 변경이 팀의 현재 작업에 미치는 영향”처럼 질문을 좁히는 편이 결과를 평가하기 쉽습니다.
진행 흐름: 제품별 자료 확인을 나누고 변경 기능, 지원 조건, 이전 방식과의 차이를 모읍니다. 이후 하나의 비교표로 합치면서 최초 발표와 나중에 갱신된 문서를 구분합니다. 자료가 없는 항목은 추측으로 채우지 않고 미확인으로 남깁니다.
산출물과 검토: 변경점, 영향받는 작업, 확인 출처·시각, 팀이 해볼 작은 검증 작업을 정리합니다. 담당자는 실제로 필요한 변화인지와 도입 비용을 판단합니다. 여러 조사를 병렬로 실행하면 호출과 도구 사용량도 늘 수 있으므로, 같은 자료를 중복 조사하지 않게 범위를 나누세요.
5. 처음 검증할 때의 작은 실행 순서
- 성공 기준을 한 문장으로 정합니다. 예를 들어 “샘플 장애 로그에서 시간순 사실과 추가 질문을 정리한다”처럼 결과물과 범위를 한정합니다.
- 프로젝트와 권한을 준비합니다. 공식 Quickstart는 애플리케이션 API 키에
api.agents.read,api.agents.write,api.responses.write권한을 안내합니다. 키는 에이전트 샌드박스 밖에서 관리합니다. - 작업에 맞는 환경과 도구를 고릅니다. 파일 실행이 필요한지, 조회만 필요한지 구분하고 최소 권한으로 시작합니다. 실제 지원 모델과 SDK 사용법은 최신 Quickstart에서 확인하세요.
- 세션을 만들고 한 작업을 보냅니다. 세션 ID와 진행 이벤트를 기록해 후속 입력이나 연결 중단 시 상태 확인에 사용합니다.
- 완료 신호와 실제 결과를 함께 봅니다. 공식 문서는
agent.session.turn.completed를 확인하되 모든 도구의 성공을 보장하는 것은 아니라고 설명합니다.agent.session.idle만 보고 성공으로 처리하지 않습니다. - 결과를 보관하고 정리합니다. 필요한 파일을 저장한 뒤 세션을 계속 사용할지 삭제할지 결정합니다. 스트림이 끊겼다면 재실행 전에 저장된 세션과 항목을 조회해 중복 작업을 피하세요.
agent.session.turn.completed는 턴의 종료 결과 중 하나입니다. 모든 도구의 성공이나 보고서의 정확성을 보장하는 신호로 사용하지 마세요. 유휴 상태나 스트림 연결 종료만 보고 성공으로 처리하지 말고, 출력·도구 결과·저장된 항목을 확인해야 합니다. 자세한 구분은 공식 세션 문서에서 확인할 수 있습니다.
6. 비용·권한·운영에서 놓치기 쉬운 점
비용은 한 가지 항목만 보면 안 됩니다. 공식 개요는 선택한 모델의 API 사용료, OpenAI 도구의 표준 요금, OpenAI 호스팅 샌드박스의 컨테이너 요금을 구분합니다. 긴 세션, 반복 조사, 하위 에이전트가 실제로 어떤 사용량을 만드는지 작은 시험에서 기록하세요. 관리형이라는 말이 무료나 정액 무제한을 뜻하지는 않습니다.
도구를 연결하는 것과 행동을 승인하는 것도 다릅니다. 조회 도구부터 검증하고 파일 수정, 외부 게시, 배포, 결제처럼 영향을 주는 동작은 애플리케이션의 승인 흐름으로 분리하는 편이 좋습니다. MCP 서버 역시 이름만 믿지 말고 운영 주체, 전달되는 데이터, 허용 동작을 확인해야 합니다.
세션과 샌드박스는 같은 자원이 아닙니다. 공식 가이드는 각 런타임의 상태·정리 규칙을 따르도록 안내합니다. 세션을 재사용할 범위, 보관할 산출물, 더 이상 필요 없는 자료의 삭제 담당을 미리 정하세요. 복구 기능이 있더라도 재시도가 외부 작업을 두 번 수행하지 않는지 확인하는 책임은 남습니다.
정리: 무엇을 맡길지보다 어디까지 맡길지
Agents API는 긴 작업의 실행 기반과 상태 관리를 맡기고 싶은 팀이 검토할 만한 선택지입니다. 단발성 모델 호출은 Responses API, 애플리케이션 내부의 세밀한 제어는 Agents SDK와 함께 비교하세요. 데이터 조건을 통과하는 작은 작업 하나에서 결과 품질·검토 부담·비용을 확인한 뒤 넓히는 접근이 좋습니다. 처음의 목표는 완전 자동화가 아니라, 사람이 검증할 수 있는 유용한 결과를 반복해서 얻는 것입니다.
공식 참고 자료
영어판으로 읽기: Read the guide in English
댓글
댓글 쓰기