금요일 아침입니다. 슬랙 맨 위에 “OpenAI Agents API 공개 베타”가 있습니다. 제목만 보면 오늘부터 Assistants를 전부 지우고 세션 API로 갈아타야 할 것 같습니다. 갈아타지 않습니다. 출근 칸은 세 개입니다. OpenAI-Beta: agents=v1 헤더가 붙는지, environment.type이 무엇인지, 그리고 idle이 성공인지.
오늘은 2026년 9월 11일 금요일 아침입니다. OpenAI Developer Community 공지 Introducing the Agents API and hosted sandboxes(2026-09-10)와 공식 문서 Agents API Overview·Run and continue sessions·Architecture·OpenAI-hosted sandboxes를 기준으로 합니다. 공지 원본은 https://community.openai.com/t/introducing-the-agents-api-and-hosted-sandboxes/1396481 이고, 개요 문서는 https://developers.openai.com/api/docs/guides/agents-api/overview 입니다. 이 글은 튜토리얼 복사가 아닙니다. 책상에서 먼저 채울 칸만 적습니다.
주의합니다. Hugging Face 침해·스웜 에이전트 후일담, EU AI Act 인시던트 리포트, CISA AA26-251A, 어제 아침 ADK Kotlin 1.0, 어제 점심 DeepSeek Harness CVE, 어제 저녁 GPT Image 2.5는 이 글의 주제가 아닙니다. Assistants API 폐기 일정, 제 로컬 벤치 숫자, “프로덕션에 당장 올려도 된다”는 단정도 없습니다. 공지가 말한 범위는 public beta, 추가 API 수수료 없음, 토큰·도구·컨테이너 요금만 따른다는 쪽입니다.
헤더와 세션 좌표부터
문서 예시가 반복하는 호출은 단순합니다. POST https://api.openai.com/v1/agents/sessions 에 Authorization Bearer와 함께 OpenAI-Beta: agents=v1 를 붙입니다. SDK 경로도 같은 베타 축입니다. client.beta.agents.sessions.create(...). 예시 모델 문자열은 gpt-6-astra 입니다. 모델 이름만 보고 어제 Image 2.5 글과 섞지 마세요. 오늘은 이미지 품질 칸이 아니라 세션·환경 칸입니다.
세션이 남기는 건 configuration과 conversation과 saved work입니다. 첫 요청에 agent와 input을 넣고, stream: true면 첫 턴 이벤트를 같은 응답에서 받습니다. 이어서 쓸 때는 애플리케이션 상태에 session_id를 저장합니다. 같은 세션에 agent.session.input.message를 다시 보내면, 에이전트가 일하는 중이면 steer이고, idle이면 새 turn입니다. 스트림이 끊기면 이벤트를 다시 재생하지 않습니다. 문서는 세션과 items를 다시 조회하라고 적습니다.
아침의 질문은 “에이전트 플랫폼을 바꿀까”보다 “우리 요청에
agents=v1헤더와 저장할session_id칸이 있는가”입니다.
environment.type 세 칸 — none / openai_hosted / self_hosted
Architecture 문서가 조각을 나눕니다. OpenAI가 돌리는 harness, 코드·파일을 다루는 environment, 그리고 우리 application server. environment는 선택입니다. 질문만 받거나 원격 도구만 쓰면 environment.type: "none" 으로 충분합니다. 그 경우 내장 Bash, apply-patch, workspace 파일, executor MCP는 문서상 사용할 수 없습니다. harness는 원격 MCP를 직접 호출할 수 있고, function tool은 우리 코드가 받아 실행한 뒤 결과를 돌려줍니다.
스크립트를 돌리고 파일을 만들고 artifact를 받으려면 openai_hosted 입니다. 작업 디렉터리는 /workspace. 패키지(python/system/npm), setup_commands, inline/Files API files, env, skills/plugins를 넣습니다. 패키지와 입력 파일 준비가 끝난 뒤 setup이 돌고, setup이 nonzero로 끝나면 에이전트는 시작하지 않습니다. 네트워크는 enabled(기본)·disabled·restricted(정확한 호스트 1–100개, 와일드카드·프로토콜·경로·포트 금지)입니다. 호스티드 stdio MCP는 현재 enabled가 필요하다고 적혀 있습니다.
세션 생성 응답은 setup이 “시작됐다”는 뜻입니다. GET /v1/agents/environments/{environment_id} 로 provisioning인지 connected인지 봅니다. failed면 agent.session.environment.failed의 environment.error를 봅니다. live file 조작은 connected 이후에만. /workspace/outputs 아래 파일은 턴이 끝나면 immutable artifact로 남고, 샌드박스가 사라져도 그 복사본은 받을 수 있습니다. keep-alive가 한 시간 끊기면 샌드박스가 지워질 수 있고, 이 타임아웃은 설정할 수 없다고 문서에 있습니다.
self_hosted는 우리 인프라·사설망·커스텀 이미지가 필요할 때입니다. 세션의 environment.id와 remote_url을 executor에 넘기고, 대시보드 Agents 탭에서 권한을 거의 None으로 줄인 environment key를 CODEX_API_KEY로 넣습니다. 넓은 애플리케이션 API 키는 환경 밖에 둡니다. 공지가 나열한 1st-party 연동 이름(Blaxel, Cloudflare Dev, Daytona, DigitalOcean, E2B, Modal, Oracle Cloud, Runloop, Vercel 등)은 “연결할 수 있다”는 안내이지, 오늘 아침 우리 VPC가 이미 붙어 있다는 증거가 아닙니다.
깨지는 지점 — idle, ZDR, 요금 착각
Sessions 문서가 여러 번 같은 경고를 합니다. 턴 결과는 agent.session.turn.completed, agent.session.turn.failed, agent.session.turn.cancelled로 봅니다. 세션이 idle이라는 사실만으로 성공으로 치지 마세요. completed여도 모든 tool이 성공했다는 뜻은 아닙니다. function result나 environment connection이 필요하면 required_actions를 처리해야 하고, 핸들러가 없으면 에이전트는 결과 대기 상태로 남을 수 있습니다. 이벤트 스트림을 닫는다고 작업이 취소되지는 않습니다. 취소는 agent.session.input.cancel 입니다.
데이터 칸도 출근 때 바로 걸립니다. Overview는 Agents API가 현재 미국 데이터 레지던시만 지원하고 Zero Data Retention(ZDR)을 지원하지 않는다고 적습니다. self-hosted sandbox를 골라도 Agents API가 ZDR-eligible이 되지 않습니다. 세션과 published artifact는 필요 없으면 지우라고 되어 있고, 삭제 중 setup/execution이 겹치면 409가 날 수 있어 재시도 한도를 두라고 합니다.
요금 칸은 공지와 hosted 문서가 같이 말합니다. Agents API 자체 추가 수수료는 없고, 선택한 모델 API 요금·OpenAI 도구 요금·호스티드 샌드박스의 표준 container 요금입니다. 커뮤니티 스레드에서도 “컨테이너 요금을 먼저 계산하라”는 실무 경고가 바로 달렸습니다. 가격표 숫자를 이 글에서 다시 적지는 않습니다. 공식 Pricing의 Containers 항목을 열면 됩니다.
책상에 남기는 1인 습관
저는 새 에이전트 엔드포인트를 볼 때마다 같은 순서로 적습니다. (1) 요청에 OpenAI-Beta: agents=v1 가 있는지, (2) environment.type이 none·openai_hosted·self_hosted 중 무엇인지와 그 선택이 막는 것(Bash 없음 / 네트워크 제한 / ZDR 불가)을 한 줄로 쓰는지, (3) 성공 판정을 idle이 아니라 agent.session.turn.completed와 items 조회로 하는지. 이 세 줄이 채워지기 전에는 “베타 나왔으니 마이그레이션” 문장을 슬랙에 올리지 않습니다.
오늘 아침 할 일은 프레임워크 교체가 아닙니다. 문서 네 탭(Overview, Sessions, Architecture, OpenAI-hosted)을 열어 우리 키 권한과 세션 저장 위치와 네트워크 기본값만 확인하는 일입니다. 그다음에도 남는 불안은 대개 모델 이름보다 환경 수명과 턴 결과 이벤트 쪽에 있습니다.
