OpenAI Agents API란? 비개발자도 이해하는 AI 작업 앱 설계

AI에게 일을 맡기는 앱을 만들려는데, 작업을 이어가는 장치까지 직접 만들어야 할까요? OpenAI가 2026년 9월 10일 공개 베타로 내놓은 Agents API는 그 부담을 줄이는 개발 도구입니다. OpenAI가 관리하는 Codex 실행 체계에 앱을 연결하는 방식입니다. 공식 변경 기록

다만 가입하면 바로 쓰는 업무용 챗봇은 아닙니다. 내 서비스에 AI 작업 기능을 넣으려는 개발자와, 그런 서비스를 기획하는 사람에게 맞습니다. 아래는 공식 문서 기반 설명과 가상 설계 예제이며, API를 실제 호출한 성능·비용 후기는 아닙니다.

모델과 실행 체계를 나눠 이해하세요

모델이 답변을 만드는 AI라면, 실행 체계인 하네스(harness)는 모델이 도구를 사용하며 작업을 이어가도록 관리하는 부분입니다. Agents API에서는 OpenAI가 세션, 작업 조율, 길어진 맥락의 압축, 복구를 관리합니다. 앱 쪽에서는 도구와 실행 환경을 정합니다. Agents API 개요

공식 문서의 네 용어를 알아두면 개발자와 대화하기 쉬워집니다.

표의 용어 정의는 공식 개요를 풀어쓴 것이고, 마지막 열은 이 글의 기획 제안입니다. 세션을 이어갈 수 있다는 기능만으로 월요일 아침 자동 실행까지 설정되는 것은 아닙니다. 정해진 시간에 일을 시작하려면 앱의 예약 실행 방식도 별도로 정해야 합니다.

진행을 관리하는 일과 결과가 맞는지 판단하는 일은 나눠야 합니다. 세션이 정상 종료돼도 요약이 틀리거나 필요한 자료가 빠질 수 있습니다. 관리형 API를 쓴다는 이유로 검수 기준까지 없어지지는 않습니다.

Agents API와 Agents SDK 중 무엇이 다를까요?

이름이 비슷해서 같은 제품의 다른 표현으로 보기 쉽습니다. 공식 문서는 Agents SDK가 내 애플리케이션에서 실행되고, Agents API는 OpenAI 서비스에서 관리형 하네스를 실행한다고 구분합니다. SDK 방식에서는 내 서버가 배포·도구 구현·상태 저장·승인 결정을 맡습니다. Agents SDK 안내

다음은 이 차이를 바탕으로 한 선택 제안입니다.

• 혼자 자료를 정리하려는 사용자: 개발부터 시작할 필요가 있는지 살펴보세요. 이미 쓰는 AI 앱에서 작업이 되는지 먼저 확인하는 편이 간단합니다.
• 내 서비스 안에 지속적인 AI 작업을 넣으려는 팀: Agents API를 후보로 검토하되 연결할 시스템과 데이터 범위를 먼저 정합니다.
• 이미 자체 서버의 실행 흐름과 승인 로직을 운영하는 팀: Agents SDK 방식과 비교해 기존 구조를 얼마나 유지할지 따져보세요.

이 글은 API가 SDK보다 항상 빠르거나 싸다는 비교를 하지 않습니다. 운영 부담을 어느 쪽에서 맡는지부터 다르므로, 같은 시험 업무의 결과와 비용을 비교해야 합니다.

개발자가 검토를 시작할 때는 공식 Quickstart를 기준으로 API 키 권한과 SDK 설정을 확인할 수 있습니다. 공개 베타 단계라 예전 코드나 블로그 예제가 현재 문서와 다를 수 있습니다. API 키는 채팅이나 공개 코드에 붙여넣지 마세요.

예제 — 공급사 공지 검토 앱의 업무 설계서

작은 쇼핑몰이 거래하는 공급사의 제품 공지를 읽고 담당자에게 요약을 전달하는 앱을 가정해보겠습니다. 시작부터 자동 상품 수정까지 맡길 필요는 없습니다. 첫 버전은 읽기와 보고서 초안 작성으로 좁힙니다.

아래 텍스트는 개발자 또는 개발을 돕는 AI에게 전달할 설계용 프롬프트입니다. 붙여넣기만 하면 Agents API 연동이 완료되는 코드는 아니며, 실제 연결·실행은 하지 않았습니다.

공급사 공지 검토 앱의 첫 버전을 설계해줘.
Agents API의 현재 공식 문서를 먼저 확인하되,
지금은 구현·배포·API 호출 없이 설계서만 만들어줘.

입력:
담당자가 승인한 공급사 공지 URL 목록과 직전 검수 완료 보고서.
URL 목록이 비어 있으면 검색 범위를 임의로 넓히지 말고 멈춰줘.

작업:
공지별 게시일, 제품명, 변경 내용, 원문 URL을 정리해.
추가된 내용과 이전부터 있던 내용을 구분해.
읽지 못한 페이지는 오류 항목으로 남겨줘.

출력:
새 검토용 보고서와 검수가 필요한 항목 목록.
제품 가격 수정, 고객 메일, 외부 게시, 주문 처리는 제외해.

설계서에 포함할 것:
- Agent의 지시와 허용할 읽기 도구
- 실행 환경과 자료가 전달되는 범위
- 업무 번호와 Session을 연결하는 방식
- 시작·진행·입력 대기·실패·완료를 보여주는 방법
- 재시도 전에 기존 실행을 확인하는 방법
- 사람의 검수 상태와 API 실행 완료 상태의 분리
- 비용·실행 시간 상한과 중지 방법
- 구현 전에 추가로 결정해야 할 질문

이 설계서에 대해 점검할 항목은 구체적으로 설명할 수 있습니다. URL을 읽는 도구가 없다면 ‘웹에서 수집한다’는 설명만으로는 구현 계획이 완성되지 않습니다. 읽기 도구를 누가 제공하고 어떤 주소에 접근하게 할지 답이 있어야 합니다.

가상 입력으로 합격 기준 정하기

실제 고객 자료를 연결하기 전에 다음 가상 입력으로 비교 규칙을 검토할 수 있습니다.

직전 검수 완료 기록:
제품 A — 포장 수량 12개
제품 B — 변경 사항 없음

이번 시험 자료:
공지 1 — 제품 A 포장 수량을 10개로 변경
공지 2 — 페이지 접근 실패
공지 3 — 공지 1과 동일한 URL과 내용

사람이 미리 적을 기대 기준은 이렇습니다. 제품 A의 변경은 12개에서 10개로 한 번만 기록합니다. 공지 2는 확인하지 못했으므로 ‘변경 없음’으로 처리하지 않습니다. 공지 3은 같은 자료이므로 새 변화로 세지 않습니다. 이는 입력에서 정한 검수 기준이며 AI가 실제로 이 결과를 냈다는 기록이 아닙니다.

오류가 한 건 있는 보고서는 ‘일부 수집 실패’로 표시하고 다음 비교의 검수 완료 기준으로 자동 승격하지 않도록 설계하는 편을 권합니다. 이번 기록을 저장하는 일과 다음 실행의 기준으로 채택하는 일도 나누면 원인을 추적하기 쉽습니다.

예약 실행은 별도 항목으로 남겨두세요

개발 의뢰서에는 실행 요일, 시각, 시간대, 실패 알림을 받을 사람을 적습니다. 같은 예약이 두 번 전달됐을 때 같은 보고서를 두 번 발송하지 않도록 업무 번호도 필요합니다. 이런 중복 방지 규칙은 서비스가 정해야 할 운영 조건입니다.

‘복구 지원’이라는 설명을 보고 실패한 외부 작업을 무조건 다시 실행하도록 만들면 위험합니다. 응답만 끊겼는지, 상대 시스템에서 이미 작업이 끝났는지 확인하고 재시도해야 합니다. 첫 버전에서 외부 발송을 제외한 것도 이 범위를 줄이기 위한 제안입니다.

비용과 보안의 한계

공식 개요는 선택 모델의 API 사용료, 도구 사용료, OpenAI 호스팅 샌드박스의 컨테이너 요금을 구분합니다. ‘요약 보고서 한 장’이라는 출력만 보고 원가를 계산하기 어렵습니다. 자료를 읽고 재시도한 과정까지 살펴봐야 합니다. 요금 구성

이 글에서는 실제 요청을 실행하지 않았으므로 건당 비용이나 절감률을 제시하지 않습니다. 도입을 결정할 때는 정상 입력, 읽기 실패, 긴 자료를 각각 시험하고 발생한 사용량을 기록하는 방식을 권합니다. 할인이나 무료 한도는 계정의 최신 조건을 확인하세요.

OpenAI의 보안 문서는 에이전트가 만든 코드가 실행 환경에 놓인 파일·인증정보·네트워크에 접근할 수 있다고 경고합니다. 작업 환경을 분리하고 외부 연결 대상을 제한하며, 애플리케이션 API 키를 에이전트 환경 밖에 두라고 안내합니다. 샌드박스 보안

따라서 ‘샌드박스’라는 이름만 보고 민감자료나 관리자 키를 모두 넣는 방식은 피하세요. 프롬프트의 금지 문장과 별개로 접근 권한을 실제 설정에서 제한해야 합니다. 자체 서버를 연결하더라도 어떤 입력과 도구 결과가 모델 서비스에 전달되는지 확인해야 합니다.

개발 의뢰 전 체크리스트

• 완성된 AI 앱으로 해결되지 않아 별도 개발이 필요한 이유가 있나요?
• 연결할 자료·도구·실행 환경의 담당자가 정해졌나요?
• Session과 실제 업무 번호를 어떻게 연결할지 설명할 수 있나요?
• 실행 완료와 사람의 검수 완료가 화면에서 구별되나요?
• 읽기 실패를 ‘변경 없음’으로 숨기지 않나요?
• 중복 실행·비용 초과·권한 오류 때 멈추는 기준이 있나요?
• API 키와 고객 자료를 로그나 결과 보고서에 노출하지 않나요?

일반적인 API 도입 준비는 OpenAI API 시작 전 점검에서 이어서 볼 수 있습니다. 이번 글의 초점은 관리형 실행 체계와 내 앱 사이에서 어떤 일을 나눠 맡길지 정하는 데 있습니다.

자주 묻는 질문

Agents API는 비개발자도 바로 쓸 수 있는 앱인가요?

앱에 에이전트 기능을 연결하는 개발용 API입니다. 비개발자는 위 설계서처럼 업무 범위와 합격 기준을 정하는 것부터 시작할 수 있습니다.

Agents SDK와 같은 것인가요?

아닙니다. 공식 문서는 SDK는 내 애플리케이션에서, API의 관리형 하네스는 OpenAI 서비스에서 실행된다고 구분합니다.

세션을 만들면 매일 자동 실행되나요?

세션을 이어가는 기능과 예약 실행은 별개로 설계해야 합니다. 원하는 주기와 시간대, 중복 실행 방지까지 개발 범위에 적으세요.

OpenAI가 복구를 관리하면 사람의 검수는 없어도 되나요?

실행을 이어가는 일과 내용이 맞는지 확인하는 일은 다릅니다. 원문 확인, 업무별 합격 기준, 외부 변경 전 승인을 따로 두는 편을 권합니다.

출처

공식 자료 확인일: 2026년 9월 17일. 대표 이미지는 자체 제작 개념 일러스트이며 실제 제품 화면이 아닙니다.

• OpenAI API — 9월 10일 공개 베타 변경 기록
• OpenAI — Agents API 개요
• OpenAI — Agents SDK와 실행 방식
• OpenAI — Agents API Quickstart
• OpenAI — Sandbox security