OpenAI Agents API 사용법

OpenAI Agents API는 OpenAI의 오픈 소스 Codex 하네스를 실행합니다. OpenAI-Beta: agents=v1 헤더, 에이전트 정의 및 작업을 포함하여 POST https://api.openai.com/v1/agents/sessions를 전송하면 OpenAI가 모델 및 도구 루프를 실행하고 세션을 유지하며 샌드박스를 프로비저닝할 수 있습니다. Agents API 수수료는 없습니다. 토큰, 도구 및 호스팅된 컨테이너 시간에 대해 비용을 지불합니다 (1GB에서 16GB 샌드박스 크기의 경우 20분 세션당 $0.03 ~ $0.48). 2026년 9월 10일에 공개 베타에 진입했으며, OpenAI는 9월 29일 DevDay에서 컴퓨터 사용 기능을 추가했습니다.

button

아래: 첫 REST 세션, 진행 이벤트, MCP 도구, 서브에이전트 및 컴퓨터 사용 승인 흐름. OpenAI의 다른 에이전트 인터페이스와 비교하는 방법은 Agents API vs Responses API vs Agents SDK를 참조하세요. 나머지 이벤트에 대해서는 DevDay 2026 총정리를 참조하세요. 모든 호출은 일반 HTTP이므로 애플리케이션 코드를 작성하기 전에 Apidog에서 보낼 수 있습니다.

OpenAI Agents API 요약

항목	값
상태	2026년 9월 10일부터 공개 베타; 9월 29일 컴퓨터 사용 추가
세션 생성	`POST /v1/agents/sessions`
베타 헤더	`OpenAI-Beta: agents=v1` (OpenAI SDK가 추가함)
주요 권한	`api.agents.read`, `api.agents.write`, `api.responses.write`
가격	Agents API 수수료 없음; 모델 토큰은 API 요율, 도구는 표준 요율 (웹 검색 1K 호출당 $10)
호스팅된 컨테이너	20분 세션당 $0.03 (`small`, 1 GB), $0.12 (`medium`, 4 GB), $0.48 (`large`, 16 GB)
환경	`none`, `openai_hosted`, `self_hosted`
문서 예시의 모델	`gpt-6-astra`
데이터 제어	미국 데이터 상주만 가능; 제로 데이터 보존(ZDR) 없음
최대 요청 크기	4 MiB

출처: Agents API 소개, Agents API 개요, 가격 페이지.

네 가지 개념

문서는 네 가지 핵심 요소를 중심으로 API를 구성합니다:

에이전트(Agent): 모델, 지침, 도구 및 MCP 서버. 인라인으로 전달하거나 저장하고 agent_id를 재사용할 수 있습니다.
환경(Environment): 에이전트가 파일을 읽고 명령을 실행하는 선택적 샌드박스 또는 컴퓨터.
세션(Session): 구성, 대화 및 저장된 작업을 유지하는 에이전트의 영구적인 인스턴스.
이벤트 및 항목(Events and items): 이벤트는 실시간으로 진행 상황을 보고하며, 항목은 저장된 메시지 및 도구 호출입니다.

유휴 세션에 메시지를 보내면 새로운 턴이 시작되고, 턴 중간에 메시지를 보내면 조종됩니다. 하네스(아키텍처 페이지에 따르면, 모델 및 도구 루프를 실행하는 호스팅된 Codex 인스턴스)는 컨텍스트 압축도 처리하므로 별도로 구성할 필요가 없습니다.

환경 선택

environment.type은 명령이 실행될 위치를 결정합니다:

none: 컴퓨팅 없음. 원격 MCP 서버 및 함수 도구는 여전히 작동하지만, 내장 Bash, apply-patch, 작업 공간 파일 및 Executor MCP는 작동하지 않습니다.
openai_hosted: OpenAI가 /workspace에 Python 및 Node.js가 있는 Linux 샌드박스를 관리합니다. container_size를 small (1GB), medium (기본값, 4GB) 또는 large (16GB)로 설정하고, network.access를 enabled, disabled 또는 allowed_domains와 함께 restricted로 설정합니다. 턴이 완료되면 /workspace/outputs의 파일은 아티팩트가 됩니다. keep-alive가 없는 유휴 샌드박스는 한 시간 후에 삭제될 수 있습니다.
self_hosted: 자체 인프라. 노트북, 컨테이너 또는 원격 샌드박스에서 codex exec-server를 실행하고, 별도의 환경 키로 외부와 연결됩니다.

출시 게시물에는 Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop 및 Vercel과 같은 샌드박스 파트너가 나열되어 있습니다. 자체 호스팅 가이드에는 AWS Lambda MicroVMs가 추가되었습니다.

REST를 통한 첫 세션

위의 권한이 있는 키를 OPENAI_API_KEY로 내보낸 다음, 작은 컨테이너로 퀵스타트 작업을 전송합니다:

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

stream: true를 사용하면 응답은 첫 번째 턴의 이벤트 스트림입니다. 여기서 세션 ID를 저장합니다. 나머지 라이프사이클은 동일한 리소스를 사용합니다:

작업	요청
후속 조치 또는 조종	`agent.session.input.message` 이벤트를 포함한 `POST /v1/agents/sessions/{id}/events`
활성 턴 취소	동일한 엔드포인트, 이벤트 유형 `agent.session.input.cancel`
저장된 작업 읽기	`GET /v1/agents/sessions/{id}/items?order=asc&limit=100`
정리	`DELETE /v1/agents/sessions/{id}`

JavaScript SDK도 동일한 형태를 가집니다. 출시 게시물에서 발췌한 다음 버전은 도구, 서브에이전트 및 볼트를 추가합니다:

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

진행 상황 추적: 스트림 또는 웹훅

스트리밍. 입력을 보내기 전에 Accept: text/event-stream 헤더와 함께 GET /v1/agents/sessions/{id}/events?stream=true를 열어 초기 이벤트를 놓치지 않도록 합니다. 다음 이벤트를 주시하세요:

텍스트의 경우 agent.session.turn.output_text.delta 및 agent.session.turn.output_text.done
결과의 경우 agent.session.turn.completed, agent.session.turn.failed 또는 agent.session.turn.cancelled
에이전트가 함수 결과, 환경 연결 또는 컴퓨터 사용 승인이 필요할 때 agent.session.requires_action

세 가지 주의사항: agent.session.idle은 턴이 성공했음을 의미하지 않으며, 완료된 턴에 실패한 도구 호출이 포함될 수 있고, 스트림을 닫는다고 작업이 중지되지는 않습니다. 스트림은 놓친 이벤트를 재생하지 않으므로, 연결이 끊긴 후 새 스트림을 열고 세션과 해당 항목을 검색하세요.

웹훅. agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle, agent.session.failed를 구독하세요. 명명법에 유의하세요: 스트림에서는 requires_action이라고 하고, 웹훅에서는 action_required라고 합니다. 페이로드는 호출 세부 정보를 생략하므로, 핸들러가 세션을 검색하고 required_actions를 읽습니다. 각 서명을 확인하세요(웹훅 서명 확인). 장기 실행 API 작업은 웹훅이 수 분이 소요되는 작업에 적합한 이유를 설명합니다.

MCP 도구, 도구 검색, 프로그래밍 방식 도구 호출 및 서브에이전트

MCP. agent.tools에 서버를 추가합니다:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

기본적으로 OpenAI가 연결하므로(connection_origin: "service"), 서버는 OpenAI에서 접근 가능해야 합니다. 사설 네트워크 서버의 경우 connection_origin: "environment"를 사용하거나, 샌드박스에서 시작하려면 stdio를 사용합니다. 자격 증명의 경우, 한 세션에 대해 transport.authorization을 전달하거나, vault_ids와 함께 볼트 자격 증명(static_bearer 또는 mcp_oauth)을 첨부합니다.

도구 검색. MCP 도구는 모델이 도구 검색을 지원할 때 자동으로 발견됩니다. 많은 함수 도구의 경우 {"type": "tool_search"}를 추가하고 함수를 defer_loading: true로 표시하세요.

프로그래밍 방식 도구 호출. 기본적으로 활성화되어 있습니다. 에이전트는 격리된 V8 런타임에서 JavaScript를 실행하는 exec 도구를 얻습니다. 따라서 도구 호출을 반복하고 큰 결과를 컨텍스트에 도달하기 전에 잘라낼 수 있습니다. {"type": "programmatic_tool_calling", "enabled": false}로 비활성화합니다.

서브에이전트. multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (기본 제한은 6입니다)로 설정합니다. 서브에이전트는 환경의 파일 시스템을 공유하고 MCP 도구 및 웹 검색을 상속받지만, 함수 도구를 사용할 수는 없습니다. 메인 에이전트의 턴 subagent_id는 null입니다.

컴퓨터 사용: DevDay 추가 기능

컴퓨터 사용은 에이전트에게 호스팅된 브라우저를 제공합니다. 호스팅된 환경에 도구와 데스크톱을 추가합니다:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

브라우저는 각 새 웹사이트 원본(공개 사이트 포함)을 방문하기 전에 사용자 승인이 필요합니다. agent.session.requires_action 시 세션을 검색하고 computer_use_approval_request 항목을 찾습니다. 중첩된 request.type은 두 가지 유형 중 하나입니다:

browser_origin_access: origin과 reason을 표시한 다음, approve, deny 또는 cancel을 제출합니다.
browser_authentication: fields, 선택적 로그인 options 및 credential_origin이 있는 로그인 양식. 사용자 값과 함께 action: "submit"을 제출하거나 action: "cancel"을 제출합니다.

두 답변 모두 이벤트 엔드포인트를 통해 다시 전달됩니다:

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

브라우저 작업은 id, turn_id, title, status 및 output을 포함하는 computer_use_call 항목으로 나타납니다. include_screenshots가 켜져 있고 사용 가능한 경우 output에는 base64 JPEG 스크린샷이 포함됩니다. 스크린샷은 계정 데이터를 보여줄 수 있으므로 로그에 포함하지 마세요.

컴퓨터 사용 가이드는 다음과 같은 주의사항을 강조합니다:

원본 승인은 작업 확인이 아닙니다. 사이트를 승인한다고 해서 에이전트가 각 구매 또는 삭제 전에 묻는 것은 아닙니다. 그것이 필요한 경우, 해당 작업을 수행할 수 없는 리소스로 브라우저를 제한하거나 제어하는 브라우저 런타임을 사용하세요.
로그인은 이메일, 비밀번호, 인증 코드를 포함합니다. 패스키 및 QR 코드 로그인은 지원되지 않습니다.
메인 에이전트만 인증을 요청할 수 있습니다. 서브에이전트는 할 수 없습니다.
자격 증명 제출 시 자동 재시도를 비활성화합니다 (SDK에서는 maxRetries: 0, curl에서는 --retry 0).
202는 수락되었음을 의미하며, 탐색 또는 로그인이 성공했음을 의미하지 않습니다. 인증 요청은 5분 후에 만료됩니다.
원본 승인은 네트워크 정책을 재정의하지 않습니다. network에서도 사이트 및 해당 리디렉션 도메인을 허용하세요.

요약에 따르면 컴퓨터 사용 기능은 "API를 통해, 그리고 Pro 500 및 Enterprise 버전의 Codex 및 ChatGPT Work에서 제공됩니다." 라고 명시되어 있습니다. 동일한 모델을 사용한 UI 기반 테스트의 경우 API 테스트를 위한 GPT-6 Astra 컴퓨터 사용을 참조하세요.

에이전트에게 UI가 아닌 API를 제공하세요

브라우저는 API가 없는 소프트웨어의 대체 수단입니다. 시스템이 사용자 소유라면 MCP 서버로 감싸세요: 유형화된 도구, 원본 프롬프트 없음, 확인 가능한 결과. 컴퓨터 사용 대 구조화된 API는 트레이드오프를 다루며, Apidog MCP 서버는 래퍼를 작성하는 코딩 도우미에게 API 사양을 제공합니다.

코드 작성 전에 Apidog에서 Agents API를 테스트하세요

API는 베타 버전이므로, 먼저 Apidog에서 각 호출의 형태를 수동으로 확인하세요:

OPENAI_API_KEY, VAULT_ID, SESSION_ID를 사용하여 Apidog 환경을 생성합니다. 모든 요청에 Bearer {{OPENAI_API_KEY}} 및 OpenAI-Beta: agents=v1를 보냅니다.
stream 없이 세션 생성 요청을 보내고, 2xx 상태와 비어 있지 않은 id를 단언하며, id를 SESSION_ID로 추출합니다.
SSE 요청으로 이벤트 스트림을 열고, 두 번째 요청에서 입력을 보낸 다음, 이벤트가 도착하는 것을 확인합니다.
승인 및 취소 페이로드를 각 required_actions 케이스를 재현하기 위한 요청으로 저장합니다.
이를 테스트 시나리오로 연결하고 Apidog CLI를 사용하여 CI에서 실행합니다.

AI 에이전트 API 테스트 가이드는 비결정적 출력에 대한 단언 패턴을 포함합니다. 따라하려면 Apidog를 다운로드하세요.

자주 묻는 질문 (FAQ)

OpenAI Agents API는 무료인가요? 플랫폼 수수료는 없지만, 모델 토큰, 도구 호출, 호스팅된 컨테이너 시간에 대한 비용을 지불합니다.

Agents API와 호환되는 모델은 무엇인가요? 모든 컴퓨터 사용 예시를 포함한 문서의 예시는 gpt-6-astra를 사용합니다. 페이지에는 다른 지원 모델이 나열되어 있지 않으므로, 먼저 사용하려는 모델을 테스트하세요.

Agents API는 제로 데이터 보존을 지원하나요? 아니요. 미국 데이터 상주만 지원하며, 자체 호스팅 샌드박스를 사용하더라도 ZDR 대상이 아닙니다.

Agents SDK 또는 Responses API와 어떻게 다른가요? SDK는 앱 내부에서 루프를 실행하며, Responses API는 루프를 구축하는 모델 호출입니다. 전체 비교를 참조하세요.

읽기 전용 세션 하나로 시작하기

읽기만 하는 세션으로 시작하고, 하나의 MCP 서버를 추가한 다음, 기본적으로 거부하는 승인 핸들러 뒤에 컴퓨터 사용 기능을 추가합니다. ChatGPT가 대신 자체 서버의 이벤트에 반응해야 할 때, MCP 이벤트가 그에 해당하는 기능입니다.