Agents API 퀵스타트 정리 — beta.agents.sessions, 샌드박스 선택, 이벤트 판정

mini_knows·2026년 9월 11일

AI트렌드 Agents API Codex harness LLM API MCP OpenAI Agents API

AI 트렌드·이슈

목록 보기

98/120

안녕하세요, 미니지식공간입니다.

OpenAI Agents API가 2026년 9월 10일 공개 베타로 열렸다. Codex를 돌리는 하네스(harness, 모델·툴·컨텍스트를 조율하는 실행 골격)와 샌드박스를 OpenAI가 관리해 주고, 개발자는 beta.agents.sessions.create() 한 번으로 클라우드 에이전트를 띄운다. 이 글은 공식 블로그와 API 문서를 기준으로 요청 규약, 환경 선택, 이벤트 판정까지 실제로 붙일 때 걸리는 지점을 정리한다.

1. 최소 예제

공식 퀵스타트는 tree.py를 만들고 실행해 결과를 보여 주는 코딩 에이전트를 예제로 쓴다. SDK는 beta.agents 네임스페이스를 쓰고, 요청 한 번이 세션 생성과 작업 제출, 진행 스트리밍을 모두 처리한다.

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)

출처: OpenAI Developers — Agents API quickstart

2. 요청 규약: 키 스코프와 베타 헤더

붙이기 전에 확인할 항목이 세 가지다.

항목	값
엔드포인트	`POST https://api.openai.com/v1/agents/sessions`
필수 헤더	`OpenAI-Beta: agents=v1` (SDK는 자동 추가, cURL은 직접 명시)
키 스코프	세션 조작에 `api.agents.read`, `api.agents.write` / 모델 추론에 `api.responses.write`

문서는 애플리케이션 API 키를 플랫폼 프로젝트에서 발급하고, 그 키를 에이전트 샌드박스 바깥에 두라고 명시한다. 에이전트가 임의로 코드를 실행하는 환경이라는 점을 생각하면 당연한 주의사항이지만, 샌드박스에 환경변수를 통째로 밀어 넣는 습관이 있다면 여기서 걸린다.

3. 환경은 세 갈래

environment.type으로 에이전트가 코드를 돌릴 공간을 정한다.

openai_hosted — OpenAI가 프로비저닝·관리한다. Codex와 ChatGPT를 떠받치는 것과 같은 샌드박스 인프라이며, 파일·패키지·스킬·플러그인을 붙여 구성할 수 있다.
자체 호스팅 — 직접 준비한 컴퓨트를 애플리케이션이 제어한다.
파트너 샌드박스 — Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, Vercel 9곳과 통합을 제공한다.

공식 블로그는 파트너 선택 기준으로 완전관리형이냐 VPC 내 배포냐, 파일·시크릿 저장 방식, 그리고 CPU·GPU·메모리 구성과 콜드스타트·비용 프로파일을 든다. 요구 조건이 뚜렷하지 않다면 openai_hosted로 시작하고 필요할 때 옮기는 쪽이 간단하다.

4. 하네스가 기본으로 주는 네 가지

직접 만들면 시간이 꽤 드는 기능들이다. OpenAI는 모델이 새로 나올 때마다 버전이 매겨진 형태로 이 기능들을 하네스에 반영한다고 밝혔다.

기능	동작	직접 만들 때 드는 것
자동 컴팩션	세션이 컨텍스트 한계에 가까워지면 앞선 컨텍스트를 압축하고 필요한 정보를 보존	요약 전략, 보존 규칙, 경계 판정
툴 검색	필요한 툴 정의만 그때그때 로드해 토큰 사용량을 줄이고 모델 캐시를 보존	툴 레지스트리, 검색 인덱스
프로그래매틱 툴 호출	호출을 병렬화·체이닝하고 결과를 코드로 필터·결합해 관련 있는 것만 컨텍스트로 반환	병렬 실행기, 결과 축약 로직
서브에이전트	작업을 독립 조각으로 쪼개 병렬 처리, 각 서브에이전트가 자기 컨텍스트 유지	오케스트레이터, 컨텍스트 격리

툴은 MCP(Model Context Protocol), 커스텀 함수, 웹 검색 같은 내장 툴을 지원한다. MCP 서버와 서브에이전트를 함께 켜는 구성은 공식 블로그 예제가 그대로 보여 준다.

import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "observability",
        transport: {
          type: "http",
          server_url: "https://observability.example.com/mcp",
        },
      },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: ["vault_YOUR_VAULT_ID"],
  environment: {
    type: "openai_hosted",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input:
    "Investigate service-api's elevated 5xx rate over the last 30 minutes. " +
    "Delegate deployment, error, and dependency analysis to subagents. " +
    "Save findings, evidence, and recommended mitigation in /workspace/outputs.",
});

출처: OpenAI — Introducing the Agents API

max_concurrent_subagents로 동시 서브에이전트 수를 제한하고, capability_directories로 샌드박스 안의 스킬 디렉터리를 지정하는 구조다. MCP 서버를 붙일 때는 그 서버의 인증 경로를 함께 점검해 두는 편이 안전하다. 관련해서는 LiteLLM MCP 인증 우회 CVE-2026-59822 정리 글을 참고할 만하다.

5. 이벤트 판정: turn.completed는 성공이 아니다

가장 걸리기 쉬운 지점이다. 문서가 직접 경고한다.

agent.session.turn.completed를 찾은 뒤 에이전트가 보고한 실행 결과를 따로 확인해야 한다. 턴이 완료됐다고 해서 모든 툴 호출이 성공한 것은 아니다.
turn.failed, turn.cancelled, session.failed로 끝나는 이벤트는 실패 또는 취소를 뜻한다.
agent.session.idle 하나만으로는 성공을 의미하지 않는다.
스트림이 일찍 끊기면 재시도하기 전에 세션과 저장된 아이템을 먼저 조회해야 한다.

즉 "완료 이벤트 오면 성공" 식의 단순 분기는 위험하다. 후속 입력을 보낼 때도 순서가 있는데, 이벤트 스트림을 먼저 열고 그다음에 입력을 보내야 초반 이벤트를 놓치지 않는다.

6. 세션 정리

세션은 다음 작업에 계속 쓰거나 끝나면 삭제한다. 삭제 전에 필요한 파일은 먼저 저장해야 한다.

import os

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), os.environ["OPENAI_SESSION_ID"])
    print(result.to_json())

출처: OpenAI Developers — Agents API quickstart

7. 비용과 라이선스

OpenAI는 "Agents API 사용에 따른 추가 요금은 없으며, 에이전트가 쓰는 토큰과 툴에 대해서만 지불한다"고 밝혔다. 샌드박스를 파트너나 자체 인프라에 두면 그쪽 비용은 별도다.

하네스는 오픈소스 Codex 하네스이고 코드베이스는 github.com/openai/codex에 공개돼 있다. OpenAI가 운영·유지관리하되 개발자는 모델 호출·툴·컨텍스트 조율의 핵심 로직을 직접 열어 볼 수 있다는 구성이다.

자주 묻는 질문

Q. Agents API를 쓰려면 별도 요금을 내야 하나?
공식 블로그 기준 추가 요금은 없다. 에이전트가 소비한 토큰과 툴 사용분만 기존 요금표대로 과금된다. 다만 파트너 샌드박스나 자체 인프라를 쓰면 해당 컴퓨트 비용은 따로 발생한다.

Q. cURL로도 호출할 수 있나?
가능하다. 엔드포인트는 https://api.openai.com/v1/agents/sessions이고, SDK가 자동으로 붙여 주는 OpenAI-Beta: agents=v1 헤더를 직접 넣어야 한다. 세션 삭제는 같은 경로에 세션 ID를 붙여 DELETE를 보낸다.

Q. 프로덕션에 바로 써도 되나?
공개 베타 단계다. OpenAI는 정식 출시(GA)까지 피드백을 받아 빠르게 반복하겠다고 밝혔고 GA 일정은 공개하지 않았다(확인 필요). SDK 경로가 beta.agents인 만큼 인터페이스 변경 가능성을 감안하는 것이 좋다.