OpenAI Agents API는 추론, 도구 사용, 코드 실행, 다단계 작업을 수행하는 AI 에이전트를 구축하기 위한 관리형 플랫폼입니다. 턴을 거쳐 작업을 이어가고, 도구를 실행하며, 중단에서 복구해야 하는 애플리케이션을 위해 설계되었으며, 전체 에이전트 루프를 직접 구현하지 않아도 됩니다. 이 가이드는 개발자가 기능, 통합 옵션, 비용을 평가하는 데 도움을 줍니다.
일반적인 LLM API와 달리 OpenAI Agents API는 지속 세션, 관리형 실행 환경, 멀티 에이전트 조정, 스트리밍 이벤트, 아티팩트를 지원합니다. 개발자는 관리형 실행을 위해 네이티브 OpenAI Agents API 엔드포인트를 사용하거나, CometAPI를 통해 지원되는 OpenAI 모델을 통합하여 커스텀 에이전트 워크플로를 구축할 수 있습니다. 이는 서로 구분되는 통합 경로입니다.
네이티브 관리형 실행과 CometAPI를 활용한 커스텀 에이전트는 인프라 책임이 다른 독립적인 통합 선택지입니다.
What Is the OpenAI Agents API?
OpenAI Agents API는 추론 모델과 외부 도구를 사용하여 다단계 작업을 수행하는 애플리케이션을 위한 관리형 실행 서비스입니다. Codex 에이전트 하네스를 서비스로 제공합니다. 모델 호출, 도구 실행, 세션 상태, 작업 복구를 수동으로 관리하는 대신, 런타임에 많은 조정을 위임할 수 있습니다.
일반 챗봇이 답변만 생성하는 것과 달리, 에이전트는 단계를 계획하고, 권한 있는 환경에서 코드를 실행하고, 오류를 검사하고, 재시도하며, 생성된 파일을 제공할 수 있습니다. 따라서 이 API는 단순 채팅이 아닌 운영 워크플로에 적합합니다.
OpenAI Agents API Workflow
에이전트 워크플로는 네 가지 요소를 결합합니다. 에이전트는 모델, 지침, 사용 가능한 도구를 정의하고; 환경은 컴퓨트와 파일 접근을 제공하며; 세션은 컨텍스트와 저장된 작업을 유지하고; 이벤트와 아이템은 진행 상황과 결과를 노출합니다. 이들 구성 요소는 애플리케이션이 작업을 제출하고, 실행을 추적하며, 이후 턴에서 작업을 이어갈 수 있게 합니다. 기본 개념은 Agents API 개요를 참조하세요.
일반적인 흐름: 세션을 생성하고; 목표를 제출하며; 모델이 추론하여 허용된 도구를 선택하게 하고; 도구를 실행하고; 중간 결과를 검사하며; 진행 상황과 최종 아티팩트를 스트리밍합니다. 세션은 필요에 따라 이어갈 수 있습니다.
공식 다이어그램은 애플리케이션이 관리형 하네스 및 샌드박스와 입출력 및 이벤트를 교환하는 모습을 보여줍니다. 아키텍처 다이어그램 출처: OpenAI Agents API 아키텍처 문서; 원작: OpenAI.
What Are the Main OpenAI Agents API Features?
관리형 하네스 기능은 코드 실행, 컨텍스트 관리, 도구 연결, 스티어링, 위임을 다룹니다. 가용성은 설정된 환경과 도구에도 좌우됩니다.
Feature
Specification
Practical benefit
Managed runtime
Codex 기반 하네스
오케스트레이션 코드 감소
Session persistence
다중 턴 상태
후속 작업 지원
Context management
관리형 압축
확장 워크플로
Hosted execution
Linux 샌드박스; Python 및 Node.js
실제 코드 실행
Self-hosted environment
개발자 관리 컴퓨트
인프라 통제
Multi-agent execution
구성 가능한 하위 에이전트
병렬 하위 작업
Tool connections
Functions 및 MCP
서비스 통합
Computer use
제어된 UI 상호작용
인터페이스 자동화
Streaming and webhooks
진행 이벤트
반응형 애플리케이션
Artifacts
저장 파일
전달 가능한 보고서
Persistent Sessions and Context Management
세션은 구성, 대화 컨텍스트, 저장된 작업을 턴 간에 유지합니다. 개발자는 기존 세션에 새 지시를 제출할 수 있으며, 컨텍스트 관리는 맞춤 대화 압축 로직 없이도 장기 작업을 유지하는 데 도움을 줍니다.
Sandboxed Code Execution
Environment
Infrastructure
Best use
none
로컬 실행 없음
원격 도구 중심 워크플로
openai_hosted
OpenAI 관리 샌드박스
코드, 분석 및 파일 처리
self_hosted
개발자 제어 컴퓨트
맞춤 인프라
호스팅 환경은 격리된 워크스페이스에서 Python, Node.js, 커맨드라인 프로그램을 실행할 수 있습니다. 자가 호스팅 환경을 사용하면 관리형 에이전트가 개발자 제어 컴퓨트를 사용할 수 있습니다. 이 경우 환경 운영과 보안은 개발자 책임이며, 에이전트 하네스와 세션 상태 관리는 계속해서 Agents API가 담당합니다.
Multi-Agent Collaboration
조정 에이전트는 전문 하위 에이전트에게 독립 작업을 위임할 수 있습니다. 예를 들어 리서치 에이전트가 서로 다른 소스를 조사하고, 주 에이전트가 증거를 조정할 수 있습니다. 병렬성은 처리량을 높일 수 있지만, 추가 모델 호출과 조정으로 비용이 증가할 수 있습니다. API는 동시성 및 하위 에이전트 설정을 구성할 수 있도록 지원합니다.
OpenAI Agents API vs Agents SDK vs Responses API vs AgentKit
Dimension
Agents API
Agents SDK
Responses API
AgentKit
Purpose
관리형 실행
코드 우선 오케스트레이션
추론 및 도구
에이전트 구성 요소
Agent loop
관리형
앱/SDK
개발자 관리
구성 요소에 따라 다름
Infrastructure
호스팅 또는 외부
개발자 제어
앱 + 호스팅 도구
다양함
Multi-agent
내장형 조정
핸드오프
커스텀
구성 요소별
Best for
내구성 자동화 작업
맞춤형 에이전트
세밀한 제어
내장형 에이전트 도구
Agents API는 관리형 실행을 제공합니다. Agents SDK는 오케스트레이션 스택을 자체 보유하는 애플리케이션에 적합합니다. Responses API는 추론과 경량 도구 워크플로에 적합합니다. AgentKit은 또 다른 동급의 호스팅 런타임이 아니라 상호보완적인 개발 구성 요소를 제공합니다.
How to Get Started With the OpenAI Agents API
Step 1: Configure API Access
빠른 시작 사전 준비가 요구하는 에이전트 및 추론 권한이 포함된 OpenAI 플랫폼 프로젝트 키를 사용하세요. curl 예시는 curl이 설치된 Bash 호환 셸을 대상으로 하며, PowerShell 예시는 환경 변수만 설정합니다. 키는 소스 제어에 포함하지 마세요.
Bash 코드 예시: Bash 호환 터미널에서 다음 명령을 실행합니다.
export OPENAI_API_KEY="your-openai-api-key"
PowerShell 코드 예시: 현재 PowerShell 프로세스에 API 키를 설정합니다.
$env:OPENAI_API_KEY="your-openai-api-key"
Step 2: Create Your First Agent
Bash 코드 예시: Bash 호환 터미널에서 다음 명령을 실행합니다.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write reliable Python code, execute it, and report observed results."
},
"environment": {"type": "openai_hosted", "container_size": "small"},
"input": "Calculate the mean and standard deviation of [12,15,19,20,24] in Python.",
"stream": true
}'
세션은 첫 번째 턴을 시작하고, 에이전트가 도구를 실행하고 응답을 준비하는 동안 상태 이벤트를 스트리밍합니다.
Step 3: Enable Multi-Agent Execution
Bash 코드 예시: Bash 호환 터미널에서 다음 명령을 실행합니다.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Delegate independent analyses and reconcile the results.",
"multi_agent": {"enabled": true, "max_concurrent_subagents": 2}
},
"environment": {"type": "none"},
"input": "Compare two release changes: date filtering in search and export URL behavior.",
"stream": true
}'
Step 4: Continue an Existing Session
Bash 코드 예시: Bash 호환 터미널에서 다음 명령을 실행합니다.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Summarize the findings in an executive report."}]}]}]}'
세션 식별자를 저장하고, 재시도 보호 장치를 적용하며, 활성 작업을 조정하는 메시지와 새로운 지시를 구분하세요.
추론 강도는 대기 시간, 토큰 소모, 계획 심도에 영향을 줍니다. 선택한 모델과 인터페이스가 지원하는 강도를 공식 GPT-6 가이드에 따라 선택하세요. 모델 수준 설정이 모든 엔드포인트에 동일하게 적용된다고 가정해서는 안 됩니다.
How to Build an AI Agent With CometAPI?
CometAPI는 커스텀 에이전트 애플리케이션을 위한 모델 추론을 제공할 수 있습니다. 애플리케이션은 에이전트 루프, 도구 실행, 세션 상태, 복구, 지원 모델 간 라우팅의 책임을 계속 집니다. 이를 통해 오케스트레이션을 통제할 수 있지만, 해당 인프라도 직접 운영해야 합니다.
에이전트 실행과 세션 상태를 OpenAI가 관리하길 원하면 네이티브 Agents API 통합을 선택하세요. 지원 모델 API를 중심으로 자체 오케스트레이션을 구축하고 운영하길 원하면 CometAPI 기반 애플리케이션을 선택하세요. CometAPI를 통해 모델에 접근하는 것만으로는 네이티브 Agents API 세션 엔드포인트 지원이 자동으로 제공되지 않습니다. 사용하려는 인터페이스를 확인하세요. 비용 경로도 다릅니다. 네이티브 사용은 OpenAI에서 과금되고, 커스텀 애플리케이션은 CometAPI 요금과 자체 인프라 비용을 합산합니다.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.responses.create(
model="gpt-6-astra",
input=(
"Analyze an API latency spike after a database migration. "
"Identify possible causes and prioritize diagnostic steps."
),
)
print(response.output_text)
커스텀 컨트롤러는 모델을 프롬프트하고, 도구 호출 요청을 검사하고, 작업을 승인 및 실행하고, 결과를 반환하며, 완료 또는 사전 정의된 한계에 도달할 때까지 반복할 수 있습니다. 턴 수, 도구 호출, 실행 시간 및 지출에 대한 제한을 설정하고, 파괴적 작업에는 독립적 확인을 요구하세요.
What Are the Best OpenAI Agents API Applications?
소프트웨어 엔지니어링: 이슈 분석, 코드 변경 생성, 테스트 실행, 리뷰 작성(병합 또는 배포 전 승인 포함).
데이터 분석 및 보고: 업로드된 데이터셋 처리, Python 계산 실행, 차트 생성, 의사결정을 지원하는 보고서로 결과 전환.
IT 인시던트 대응: 알림 검사, 로그 상관관계 분석, 런북 참조, 위험 작업은 사람 승인 하에 완화책 권고.
고객 지원 자동화: 관련 기록 조회, 티켓 요약, 응답 초안 작성, 미해결 사례를 허용된 CRM 접근으로 라우팅.
리서치 및 문서 처리: 문서 비교, 주장 검증, 사실 추출, 근거 인용과 함께 결과 정리.
Evaluate Your Workflow
자신의 워크로드에서 대표 작업을 선택하고, 성공적 완료 기준을 정의하세요. 동일한 입력과 승인 기준으로 현재 프로세스와 에이전트를 비교하세요. 후속 요청과 도구 실패를 포함해, 이상 경로뿐만 아니라 복구도 평가되도록 하세요.
Metric
Measures
Reason
Task completion
성공적으로 달성한 목표
엔드 투 엔드 유용성
Tool success
올바른 통합
실패 감지
Recovery rate
실패 후 완료율
내구성
Time to completion
총 소요 시간
대기 시간
Cost per completed task
성공 작업당 비용
효율성
Human intervention
수동 개입
자율성
Safety compliance
정책 준수
위험 통제
이 지표들을 함께 읽으세요. 더 많은 작업을 완료하더라도, 잦은 수동 수정이 필요하거나 시간·비용 한도를 초과하면 적합하지 않을 수 있습니다. 결과를 바탕으로 어디를 자동화하고, 어디에 인간 검토를 유지하며, 확장 전에 어떤 실패를 해결할지 결정하세요.
How Much Does the OpenAI Agents API Cost?
별도의 관리형 하네스 플랫폼 요금은 없습니다. 모델 토큰, 해당 도구 호출, 선택적 호스팅 컴퓨트가 총 사용 비용을 결정합니다. 아래 모델 요금은 짧은 컨텍스트 프롬프트(최대 272K 입력 토큰)에 대한 Standard 처리 기준으로 백만 토큰당 USD이며, 2026년 10월 21일 기준입니다. 더 긴 프롬프트, 다른 처리 등급, 캐시 쓰기, 지역 처리 여부에 따라 적용 요금이 달라질 수 있습니다.
OpenAI model pricing
Input / 1M
Cached input / 1M
Output / 1M
GPT-6 Astra
$10.00
$1.00
$50.00
GPT-6.1 Sol
$2.00
$0.10
$10.00
GPT-6 Luna
$0.10
$0.01
$0.50
CometAPI를 통한 모델 접근의 경우, 개발자는 GPT-6.1 Sol과 GPT-6 Luna를 사용할 수 있습니다. 위 표는 OpenAI 요금이며, CometAPI 과금은 자체 적용 요금을 따릅니다.
Resource or tool
Configuration / billing basis
Rate
Hosted container — Small
1 GB 메모리; 20분 기간
20분당 $0.03
Hosted container — Medium
4 GB 메모리; 20분 기간
20분당 $0.12
Hosted container — Large
16 GB 메모리; 20분 기간
20분당 $0.48
Web search
1,000회 호출당; 콘텐츠 토큰은 별도 과금
1,000회당 $10, 콘텐츠 토큰 별도
File search storage
무료 할당량 이후, GB/일 기준
GB/일당 $0.10
Example: Estimating a Task Cost
Component
Illustrative calculation
Cost
Input tokens
50,000 × $10 / 1M
$0.50
Output tokens
10,000 × $50 / 1M
$0.50
Web searches
2 × $0.01
$0.02
Small container
한 번의 20분 기간
$0.03
Total
부대 비용 제외
$1.05
이 예시 $1.05 총액은 표시된 토큰 볼륨, 두 번의 검색, 한 차례 스몰 컨테이너 20분 기간, 추가 과금되는 검색 콘텐츠 토큰이나 캐시 쓰기가 없음을 가정합니다. 실제 비용은 재시도, 하위 에이전트 사용, 캐시 동작, 세션에 적용되는 샌드박스 과금 규칙에도 좌우됩니다. 대표 워크로드 전반에서 성공적으로 완료된 작업당 비용을 추적하세요.
What Are the Limitations of the OpenAI Agents API?
데이터 제한. Agents API는 현재 미국 내 데이터 레지던시만 지원하며 Zero Data Retention(ZDR)을 지원하지 않습니다. 자가 호스팅 샌드박스를 사용해도 ZDR 적격성은 변하지 않습니다. 민감한 자료를 보내기 전에 보존 및 레지던시 조건이 요구사항을 충족하는지 확인하세요.
API 및 모델 호환성. 공개 베타 인터페이스는 변경될 수 있으며, 지원 기능은 모델에 따라 다를 수 있습니다. 애플리케이션에서 사용하는 정확한 모델, 엔드포인트, 추론 설정, 도구를 테스트하세요. 모델을 변경하거나 API 업데이트를 채택할 때마다 통합 점검을 반복하세요.
실행 제어. 다단계 작업은 토큰이 누적되고, 소요 시간이 가변적이며, 도구 실패가 발생할 수 있습니다. 턴 수와 런타임에 대한 예산과 한도를 설정하고, 작업에 필요한 권한만 부여하며, 장기 실행 작업을 비동기적으로 모니터링하세요. 중단된 도구 호출에서 복구하는 방법을 계획하고, 중대한 결과를 초래할 수 있는 작업에는 사람 승인을 요구하세요.
FAQ
How should OpenAI Agents API clients retry follow-up messages?
세션 입력 및 재시도 패턴에 따라 동일한 논리 메시지를 재시도할 때는 동일한 제출 키를 재사용하세요. 애플리케이션 상태에서 세션 ID와 제출 키를 함께 유지하세요. 별도의 사용자 지시는 자체 키를 사용해야 하며, HTTP 응답 손실이 자동으로 새로운 지시로 간주되어서는 안 됩니다.
Can an OpenAI Agents API session change models?
세션 설정 엔드포인트는 모델, 추론 강도, 서비스 계층 업데이트를 지원합니다. 업데이트는 이후 턴에 영향을 주며, 활성 턴은 기존 설정을 유지합니다. 결과 구성에 선택한 모델이 지원하는지 확인하고, 이 엔드포인트가 허용하지 않는 설정 변경이 필요하면 새 세션을 생성하세요.
How does OpenAI Agents API restrict sandbox network access?
OpenAI 호스팅 환경은 아웃바운드 접근을 활성화, 비활성화, 제한 모드로 지원합니다. 제한 모드는 명시적 호스트 허용 목록을 사용하며, 리디렉션이나 서브도메인도 별도 항목이 필요할 수 있습니다. 작업에 필요한 서비스를 위해 샌드박스 네트워크 정책을 구성하세요. 네트워크 접근과 애플리케이션 자격 증명은 별개의 제어입니다.
Conclusion
여러 도구 호출과 최소 한 번의 후속 턴이 필요한 대표 작업으로 Agents API를 평가하세요. 완료율, 복구 동작, 대기 시간, 성공 작업당 비용을 측정하세요. 이러한 결과는 관리형 실행이 애플리케이션 요구사항을 충족하는지 보여줄 것입니다.
