OpenAI Agents API 빠른 시작: 호스팅 샌드박스와 Agents SDK 차이

OpenAI가 2026년 9월 10일 Agents API를 공개 베타로 내놓았다. 핵심은 새 모델이 아니라 Codex를 움직이는 에이전트 하네스를 API로 제공한다는 데 있다. 세션 유지, 도구 실행, 컨텍스트 압축, 복구, 서브에이전트 조율은 OpenAI가 맡는다. 개발자는 모델과 도구, 실행 환경을 고른다.

이 API는 파일을 고치고 명령을 실행하며 결과물을 남기는 장기 작업에 맞는다. 짧은 질의응답이나 단발성 도구 호출이라면 Responses API가 더 단순하다. 애플리케이션 안에서 실행 루프와 핸드오프를 직접 제어하고 싶다면 오픈소스 Agents SDK가 더 알맞다.

한눈에 보는 공개 베타

출시일: 2026년 9월 10일
상태와 대상: 모든 개발자가 쓸 수 있는 공개 베타
하네스: OpenAI가 Codex 하네스와 세션, 오케스트레이션, 컨텍스트 압축, 복구를 관리
실행 환경: 환경 없음, OpenAI 호스팅 샌드박스, 자체 호스팅 환경
파트너 환경: Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, Vercel
비용: Agents API 자체 추가 요금은 없지만 모델 token, 도구, OpenAI 호스팅 컨테이너 사용료는 별도

공개 베타라는 말은 운영 환경에서 곧바로 안정성을 가정해도 된다는 뜻이 아니다. OpenAI는 정식 출시 전까지 API 세부 사항과 기본값, 지원 기능을 빠르게 바꿀 수 있다고 안내한다.

Agents API가 맡는 범위

Agents API의 기본 단위는 agent, environment, session, event다. Agent에는 모델, instructions, 도구와 MCP 서버가 들어간다. Environment는 명령 실행과 파일 작업이 일어나는 곳이며 선택 사항이다. Session은 대화와 작업 상태를 이어 가는 내구성 있는 실행 단위다. Event와 item으로 진행 상황과 저장된 출력을 확인한다.

OpenAI 관리 하네스는 명령 실행, skill 적용, MCP와 외부 도구 연결, 실행 중 steering, 오래된 컨텍스트 압축, 서브에이전트 위임, 세션 재개를 처리한다. 애플리케이션은 task를 보내고 event를 받으며 function tool 요청을 처리한다.

Python 빠른 시작

먼저 OpenAI Platform 프로젝트에서 application API key를 만든다. 세션에는 api.agents.read, api.agents.write, 모델 추론에는 api.responses.write 권한이 필요하다. 키는 샌드박스 안이 아니라 애플리케이션 쪽에 둔다.

python -m venv .venv
. .venv/bin/activate
pip install --upgrade openai
export OPENAI_API_KEY="your-api-key"

아래 예제는 OpenAI 공식 quickstart의 최소 흐름을 따른다. 한 번의 요청으로 세션을 만든다. 호스팅 샌드박스를 준비한 다음 tree.py 작성과 실행을 맡기고 event를 스트리밍한다.

from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input=(
            "Create tree.py, a Python script that prints a readable tree of "
            "the files in the current directory. Run it and show me the output."
        ),
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

python quickstart.py

성공 여부는 agent.session.turn.completed event와 agent가 보고한 실제 실행 결과를 함께 확인해야 한다. agent.session.idle만으로 성공을 판단하면 안 된다. 완료 event가 와도 개별 tool이 실패했을 수 있다. 연결이 일찍 끊겼다면 같은 task를 바로 다시 보내기보다 저장된 session과 item을 먼저 조회한다.

SDK는 베타 header를 자동으로 붙인다. cURL을 쓸 때는 OpenAI-Beta: agents=v1을 직접 넣어야 한다.

호스팅 샌드박스에서 할 수 있는 일

environment.type을 openai_hosted로 지정하면 Python, Node.js와 command-line tool이 들어 있는 Linux workspace가 생긴다. 작업 디렉터리는 /workspace다. Python, system, global npm package를 설치할 수 있다. 입력 파일은 Files API 또는 base64로 넣으며 setup command와 환경 변수, skill, plugin도 구성할 수 있다.

네트워크 정책은 세 가지다. enabled는 외부 통신을 허용하고 기본값이다. disabled는 outbound access를 막는다. restricted는 allowed_domains에 적은 1~100개의 정확한 hostname만 허용한다. wildcard, protocol, path, port는 넣을 수 없으며 redirect destination과 subdomain도 따로 허용해야 한다. 가능하면 처음부터 disabled나 좁은 allowlist를 택하는 편이 낫다.

세션마다 workspace가 분리된다. sandbox가 살아 있는 동안에는 turn 사이에서도 파일이 유지된다. /workspace/outputs 아래 파일은 turn 완료 시 immutable artifact로 게시된다. 이 복사본은 sandbox가 만료된 뒤에도 내려받을 수 있다. 활동과 keep-alive가 한 시간 동안 멈추면 sandbox가 삭제될 수 있으며 이 timeout은 바꿀 수 없다. 필요한 artifact를 보관한 뒤 session을 지워 정리를 요청해야 한다.

호스팅 환경이 맞지 않으면 self_hosted를 고를 수 있다. 노트북, container, remote sandbox에서 codex exec-server를 실행하고 Agents API와 outbound WebSocket으로 연결하는 방식이다. custom image, 자체 compute, private network가 필요할 때 유용하지만 provisioning, reconnect, shutdown, 파일 보존은 애플리케이션이 책임진다. 파트너 sandbox도 이 경계에서 선택할 수 있다.

파일이나 shell이 필요 없는 agent라면 environment.type을 none으로 두면 된다.

가격 계산

Agents API 자체에는 별도 platform fee가 없다. 실제 청구는 선택한 모델 token, built-in tool, hosted container에서 발생한다. 2026년 9월 16일 공식 가격표의 standard short-context 기준으로 gpt-6-astra는 100만 token당 input $10, cached input $1, cache write $12.50, output $50다.

호스팅 컨테이너는 20분 session 기준으로 1 GB $0.03, 4 GB $0.12, 16 GB $0.48, 64 GB $1.92다. 공식 가격표는 eligible container session을 분 단위로 청구하며 session당 최소 5분이 적용된다고 덧붙인다. Web search는 모든 모델에서 1,000회당 $10이며 search content token은 모델 요율로 별도 계산된다. 모델과 도구 가격은 바뀔 수 있으므로 배포 전에 가격표를 다시 확인해야 한다.

Agents SDK와 Responses API 중 무엇을 고를까

Agents API는 하네스를 OpenAI가 운영한다. 애플리케이션은 세션 중심 API로 task를 보낸다. OpenAI가 orchestration과 recovery를 관리하며 실행 위치는 OpenAI hosted, self-hosted, partner 중에서 고를 수 있다.

Agents SDK의 sandbox agent는 반대쪽에 가깝다. 애플리케이션 프로세스가 harness를 실행하고 Runner, SandboxAgent, Manifest, sandbox client로 lifecycle과 provider를 조립한다. 로컬 Unix와 Docker부터 hosted provider까지 바꿔 끼우기 쉽고, handoff, guardrail, hook을 코드에서 세밀하게 제어할 수 있다.

Responses API는 모델 응답과 built-in tool을 직접 호출하는 더 낮은 수준의 출발점이다. persistent workspace나 장시간 session이 필요 없고 짧은 결과만 받으면 된다면 Agents API를 얹을 이유가 적다.

정리하면 운영 주체가 선택 기준이다. Codex harness 운영을 넘기고 durable session을 빠르게 붙이려면 Agents API, 앱 안에서 agent loop를 소유하려면 Agents SDK, 짧고 직접적인 모델 호출이면 Responses API가 자연스럽다.

보안 경계와 베타 제한

Agent가 만든 코드는 environment에 놓인 파일, credential, network에 접근할 수 있다. sandbox를 신뢰 경계로 보고 사용자나 workload별로 격리해야 한다. application API key는 environment 밖에 둔다. self-hosted executor에는 environment 연결만 허용하는 제한된 CODEX_API_KEY를 쓴다. 장기 credential을 source, image, log에 넣어서는 안 된다. 가능하면 credential broker가 승인된 outbound request에만 secret을 주입하도록 구성한다.

MCP server와 tool도 권한을 좁혀야 한다. 읽기 전용으로 충분한 작업에는 쓰기 권한을 주지 않는다. 외부 side effect에는 승인 단계를 둔다. prompt injection은 sandbox가 자동으로 해결해 주는 문제가 아니다. untrusted file과 web content가 agent 지시처럼 작동할 수 있다는 전제로 tool permission과 network policy를 설계해야 한다.

현재 Agents API의 data residency는 미국만 지원한다. Zero Data Retention은 지원하지 않으며 self-hosted sandbox를 골라도 ZDR 대상이 되지 않는다. OpenAI hosted sandbox는 자체 image나 private network가 필요한 작업에도 맞지 않는다. 이 경우 self-hosted 환경을 써야 한다.

로컬 검증에서는 Python SDK 3.14.1 설치, OpenAI import, client.beta.agents.sessions.create surface와 예제 문법을 확인했다. 유료 API 호출과 hosted sandbox end-to-end 실행은 API key와 비용 승인이 없어 수행하지 않았다.

누가 쓰고, 누가 미뤄야 하나

코딩 assistant, document reviewer, incident investigator처럼 파일과 명령, 중간 산출물, 여러 turn의 상태가 필요한 팀은 살펴볼 가치가 있다. 특히 harness의 context compaction과 recovery를 직접 운영하고 싶지 않을 때 이점이 크다.

반대로 ZDR이 필수이거나 미국 외 data residency가 필요한 서비스는 현재 조건에 맞지 않는다. API surface 변경을 감당하기 어려운 production system도 general availability까지 기다리는 편이 안전하다. 단순 챗봇이나 한 번의 tool call에는 Responses API가 비용과 구조 모두 가볍다.

출처

검증일: 2026년 9월 16일