Rihpig

Posted on Oct 2 Originally published at apidog.com

OpenAI Agents API 사용법

#openai #ai #api #agents

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입니다. 이 API는 2026년 9월 10일 공개 베타에 진입했고, OpenAI는 9월 29일 DevDay에서 컴퓨터 사용 기능을 추가했습니다.

Apidog를 지금 사용해 보세요

이 글에서는 첫 REST 세션 생성, 진행 이벤트 처리, MCP 도구, 서브에이전트, 컴퓨터 사용 승인 흐름을 구현합니다. 다른 OpenAI 에이전트 인터페이스와의 차이는 Agents API vs Responses API vs Agents SDK를 참고하세요. DevDay의 나머지 발표 내용은 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`, 1GB), `$0.12` (`medium`, 4GB), `$0.48` (`large`, 16GB)
환경	`none`, `openai_hosted`, `self_hosted`
문서 예시 모델	`gpt-6-astra`
데이터 제어	미국 데이터 상주만 가능, 제로 데이터 보존(ZDR) 미지원
최대 요청 크기	4MiB

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

먼저 이해할 네 가지 개념

Agents API 구현은 다음 네 가지 리소스를 기준으로 설계하면 됩니다.

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

유휴 세션에 메시지를 보내면 새 턴이 시작됩니다. 실행 중인 턴에 메시지를 보내면 에이전트를 조종할 수 있습니다. 아키텍처 문서에 따르면 호스팅된 Codex 인스턴스인 하네스가 모델·도구 루프와 컨텍스트 압축을 처리하므로, 별도의 컨텍스트 압축 설정은 필요하지 않습니다.

환경 선택하기

environment.type은 명령과 파일 작업이 실행될 위치를 결정합니다.

none: 컴퓨팅 환경을 만들지 않습니다. 원격 MCP 서버와 함수 도구는 사용할 수 있지만, 내장 Bash, apply-patch, 작업 공간 파일, Executor MCP는 사용할 수 없습니다.
openai_hosted: OpenAI가 Linux 샌드박스를 관리합니다. /workspace에서 Python과 Node.js를 사용할 수 있습니다.
- 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로 첫 세션 만들기

먼저 필요한 권한이 포함된 API 키를 환경 변수로 설정합니다.

export 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);

운영 환경에서는 session.id를 사용자 요청, 작업 ID, 만료 시각과 함께 저장해 두는 것이 좋습니다. 그래야 스트림이 끊겨도 항목 조회 API로 상태를 복구할 수 있습니다.

진행 상태 추적: SSE 또는 웹훅

SSE 스트리밍

입력을 보내기 전에 이벤트 스트림을 열어야 초기 이벤트를 놓치지 않습니다.

curl --no-buffer \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Accept: text/event-stream" \
  "https://api.openai.com/v1/agents/sessions/$SESSION_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은 턴이 성공했다는 의미가 아닙니다.
완료된 턴에도 실패한 도구 호출이 포함될 수 있습니다.
SSE 연결을 닫아도 에이전트 작업은 중지되지 않습니다.

스트림은 놓친 이벤트를 재생하지 않습니다. 연결이 끊기면 새 스트림을 열고, 세션 및 items API를 조회해 현재 상태를 복구하세요.

웹훅

장기 실행 작업은 웹훅으로 처리할 수 있습니다. 다음 이벤트를 구독하세요.

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에 MCP 서버를 추가합니다.

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

기본값은 connection_origin: "service"이며 OpenAI 서비스가 MCP 서버에 연결합니다. 따라서 서버는 OpenAI에서 접근 가능해야 합니다.

사설 네트워크의 MCP 서버에는 다음 중 하나를 사용하세요.

connection_origin: "environment": 에이전트 환경에서 서버에 연결
stdio: 샌드박스에서 MCP 서버 프로세스 시작

자격 증명은 세션 단위로 transport.authorization에 전달할 수 있습니다. 재사용 가능한 자격 증명이 필요하면 vault_ids와 함께 볼트 자격 증명인 static_bearer 또는 mcp_oauth를 연결합니다.

많은 도구를 사용할 때: 도구 검색

MCP 도구는 모델이 도구 검색을 지원할 경우 자동으로 발견됩니다. 함수 도구가 많다면 tool_search를 추가하고, 지연 로드할 함수에는 defer_loading: true를 지정합니다.

{
  "agent": {
    "tools": [
      { "type": "tool_search" },
      {
        "type": "function",
        "name": "get_deployment_logs",
        "defer_loading": true
      }
    ]
  }
}

프로그래밍 방식 도구 호출

프로그래밍 방식 도구 호출은 기본적으로 활성화됩니다. 에이전트는 격리된 V8 런타임에서 JavaScript를 실행하는 exec 도구를 사용합니다. 이를 통해 여러 도구 호출을 반복하고, 큰 결과를 컨텍스트에 넣기 전에 잘라낼 수 있습니다.

필요하지 않다면 명시적으로 비활성화하세요.

{
  "type": "programmatic_tool_calling",
  "enabled": false
}

서브에이전트 활성화

병렬 조사나 독립적인 하위 작업이 필요하면 multi_agent를 설정합니다.

{
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 3
  }
}

기본 동시 실행 제한은 6입니다. 서브에이전트는 환경 파일 시스템을 공유하고 MCP 도구 및 웹 검색을 상속합니다. 다만 함수 도구는 사용할 수 없습니다. 메인 에이전트 턴의 subagent_id는 null입니다.

컴퓨터 사용 기능 구현하기

컴퓨터 사용은 에이전트에 호스팅된 브라우저를 제공합니다. computer_use 도구와 데스크톱 환경을 함께 활성화해야 합니다.

{
  "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을 확인합니다.
사용자에게 승인 UI를 표시합니다.
이벤트 엔드포인트로 결과를 제출합니다.

요청 유형은 두 가지입니다.

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"
        }
      }
    ]
  }'

브라우저 동작은 computer_use_call 항목으로 저장됩니다. 이 항목에는 id, turn_id, title, status, output이 포함됩니다. include_screenshots를 활성화했고 스크린샷을 사용할 수 있다면 output에 base64 JPEG 스크린샷이 포함됩니다.

스크린샷에는 계정 데이터가 포함될 수 있으므로 애플리케이션 로그, 분석 이벤트, 오류 추적 도구에 원문을 기록하지 마세요.

컴퓨터 사용 가이드의 주요 운영 주의사항은 다음과 같습니다.

원본 승인과 작업 승인은 다릅니다. 사이트 접근을 허용해도 구매나 삭제 같은 개별 작업마다 확인을 요구하지는 않습니다. 작업 단위 승인이 필요하다면 해당 작업을 수행할 수 없는 리소스로 브라우저 권한을 제한하거나 제어 가능한 브라우저 런타임을 사용하세요.
로그인에는 이메일, 비밀번호, 인증 코드가 포함될 수 있습니다. 패스키와 QR 코드 로그인은 지원되지 않습니다.
인증 요청은 메인 에이전트만 할 수 있습니다. 서브에이전트는 인증을 요청할 수 없습니다.
자격 증명 제출 요청에서는 자동 재시도를 끕니다. SDK는 maxRetries: 0, curl은 --retry 0을 사용합니다.
HTTP 202는 요청 수락만 의미합니다. 탐색이나 로그인이 성공했다는 의미는 아닙니다.
인증 요청은 5분 후 만료됩니다.
원본 승인은 네트워크 정책을 재정의하지 않습니다. network 설정에서도 대상 사이트와 리디렉션 도메인을 허용해야 합니다.

요약에 따르면 컴퓨터 사용 기능은 “API를 통해, 그리고 Pro 500 및 Enterprise 버전의 Codex 및 ChatGPT Work에서 제공됩니다.” 동일한 모델로 UI 기반 테스트를 수행하려면 API 테스트를 위한 GPT-6 Astra 컴퓨터 사용을 참고하세요.

에이전트에는 UI보다 API를 제공하세요

브라우저 자동화는 API가 없는 소프트웨어를 다루는 대체 수단입니다. 제어 가능한 시스템이라면 브라우저 조작보다 MCP 서버로 감싸는 편이 낫습니다.

MCP 서버를 제공하면 다음을 얻을 수 있습니다.

유형화된 도구 입력과 출력
웹페이지 원본 접근 승인 감소
검증 가능한 결과
더 단순한 오류 처리와 감사 로그

컴퓨터 사용 대 구조화된 API에서 두 접근 방식의 트레이드오프를 확인할 수 있습니다. Apidog MCP 서버는 래퍼를 작성하는 코딩 도우미에 API 사양을 제공하는 방법을 다룹니다.

코드 작성 전에 Apidog에서 Agents API 테스트하기

Agents API는 베타이므로 애플리케이션 코드에 연결하기 전 Apidog에서 각 요청의 구조와 상태 전이를 수동으로 검증하세요.

OPENAI_API_KEY, VAULT_ID, SESSION_ID를 포함하는 Apidog 환경을 만듭니다.
모든 요청에 다음 헤더를 설정합니다.

   Authorization: Bearer {{OPENAI_API_KEY}}
   OpenAI-Beta: agents=v1

먼저 stream 없이 세션 생성 요청을 보냅니다. 2xx 상태 코드와 비어 있지 않은 id를 검증한 뒤, 응답의 id를 SESSION_ID 환경 변수에 저장합니다.
SSE 요청으로 이벤트 스트림을 열고, 두 번째 요청에서 입력 이벤트를 전송합니다. 텍스트 델타, 완료, 승인 필요 이벤트가 도착하는지 확인합니다.
승인 및 취소 페이로드를 저장해 각 required_actions 케이스를 재현합니다.
이 요청들을 테스트 시나리오로 연결하고 Apidog CLI로 CI에서 실행합니다.

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

자주 묻는 질문

OpenAI Agents API는 무료인가요?

플랫폼 수수료는 없지만 모델 토큰, 도구 호출, 호스팅된 컨테이너 시간 비용을 지불합니다.

Agents API와 호환되는 모델은 무엇인가요?

문서의 컴퓨터 사용 예시를 포함한 모든 예시는 gpt-6-astra를 사용합니다. 페이지에는 다른 지원 모델이 나열되어 있지 않으므로, 사용할 모델은 먼저 테스트하세요.

Agents API는 제로 데이터 보존을 지원하나요?

아니요. 미국 데이터 상주만 지원하며, 자체 호스팅 샌드박스를 사용하더라도 ZDR 대상이 아닙니다.

Agents SDK 또는 Responses API와 어떻게 다른가요?

Agents SDK는 애플리케이션 내부에서 루프를 실행합니다. Responses API는 직접 루프를 구축하기 위한 모델 호출 인터페이스입니다. 자세한 비교는 Agents API vs Responses API vs Agents SDK를 참고하세요.

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

처음에는 읽기 전용 작업과 단일 MCP 서버로 시작하세요. 이후 기본값이 거부인 승인 핸들러를 구현한 뒤에 컴퓨터 사용 기능을 추가하는 편이 안전합니다.

ChatGPT가 자체 서버의 이벤트에 반응해야 하는 경우에는 MCP 이벤트가 해당 기능을 제공합니다.

DEV Community