OpenAI Agents API: Codex 하네스를 관리형으로 제공

TL;DR Highlight

OpenAI가 세션·컨텍스트 압축·복구를 맡는 관리형 에이전트 API를 공개했다

Who Should Read

에이전트 하네스를 직접 만들고 운영하는 게 부담스러운 백엔드 개발자

Core Mechanics

Codex 하네스를 API로 제공
- Agents API는 OpenAI가 관리하는 Codex 하네스(에이전트 실행 틀)를 API로 열어 준다.
- 세션, 오케스트레이션, 컨텍스트 압축, 복구는 OpenAI가 맡는다.
- 앱은 도구를 제공하고 실행 환경을 고른다.
핵심 개념은 네 가지
- Agent는 모델, 지시문, 도구, MCP 서버 묶음이다.
- Environment는 파일·스킬·명령 실행이 가능한 선택형 샌드박스나 컴퓨터다.
- Session은 작업을 이어 가는 지속형 에이전트 인스턴스다.
- Events and items는 입력과 출력 단위다.
하네스가 기본 제공하는 기능
- 샌드박스에서 명령과 코드를 실행한다.
- 스킬 적용, MCP 등 외부 데이터 연결, 작업 중 방향 조정(steering)을 지원한다.
- 이전 작업 요약으로 컨텍스트를 관리하고, 서브에이전트에 작업을 나누며, 세션을 이어서 재개한다.
세션 흐름은 생성-작업-관찰-이어가기
- 세션을 만들면 OpenAI가 환경을 준비한다.
- 스트리밍이나 웹훅으로 진행 상황과 입력 요청을 받는다.
- 같은 세션에 작업을 추가하거나 진행 중인 턴에 지시를 보낼 수 있다.

Community Reactions

자체 호스팅 샌드박스 선택이 매력이라는 의견
- 문서 깊은 곳에 샌드박스를 직접 호스팅할 수 있다는 점이 있어 벤더 전환이 쉬워질 수 있다는 의견이 있었다.
- 반대로 락인(종속) 우려가 크다는 댓글도 여럿 있었다.
에이전트를 원격에 두는 건 거꾸로라는 반론
- 로컬 데이터 접근이 핵심 마찰인데 원격 에이전트가 내부 인프라에 접근하면 문제가 더 커진다는 의견이 있었다.
- 에이전트는 로컬에 두고 샌드박스만 원격 호스팅하길 원한다는 의견이었다.
데이터 보존 정책이 불투명하다는 지적
- 발표 하단에 Zero Data Retention 비적용 표시가 있다는 지적이 있었다.
- '대화 학습 금지' 설정에서 '대화'가 사용자 가시 입출력만 뜻해 추론 흔적이 빠질 수 있다는 우려가 있었다.
직접 만든 경험담도 갈렸다
- OpenAI agents SDK로 샌드박스·Slack 연동을 직접 만들어 노출 범위를 엄격히 통제해 봤더니 잘 됐다는 경험이 있었다.
- 하네스를 직접 만들면 API 변화를 따라가기 어려워 결국 호스팅 추상화로 돌아간다는 의견도 있었다.
- 예제 GitHub 링크가 처음엔 404였다가 openai-cookbook으로 고쳐졌다는 댓글이 있었다.

How to Apply

문서 MCP 붙인 세션 예제 돌려보기
- 오늘 API 키로 아래 예제의 세션 생성 코드를 그대로 실행해 session.id를 출력해 본다.
- instructions와 input 텍스트를 우리 서비스 질문으로 바꾼다.
자체 하네스와 책임 범위 표로 비교하기
- 세션 보관, 컨텍스트 압축, 복구 중 우리가 직접 짠 부분을 목록으로 적는다.
- 그 항목이 Agents API 기본 기능과 겹치는지 표시한다.
데이터 보존 조건을 먼저 확인하기
- 고객 데이터가 들어가는 에이전트라면 도입 전에 Zero Data Retention 비적용 표시를 확인한다.
- 샌드박스는 자체 호스팅 옵션으로 두고 접근 범위를 최소로 정한다.
서브에이전트 병렬 작업 하나 실험하기
- 독립적인 조사 작업 하나를 골라 multi_agent를 켠다.
- max_concurrent_subagents를 4로 두고 결과를 한 답변으로 합치는지 본다.

Try It

복사해서 바로 해보기

# 터미널에서 실행 (pip install openai 후, OpenAI API 키와 Agents API 베타 접근 권한 필요)

from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
        "tools": [
            {"type": "programmatic_tool_calling"},
            {
                "type": "mcp",
                "server_label": "openai_docs",
                "transport": {"type": "http", "server_url": "https://developers.openai.com/mcp"},
            },
            {"type": "web_search"},
        ],
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/capabilities/skills"],
    },
    input=[{"role": "user", "content": [{"type": "input_text", "text": "{{질문}}"}]}],
)
print(session.id)

# 이어서 해 볼 것: 질문을 바꿔 돌리고 multi_agent를 꺼서 결과를 비교해 본다.

Terminology

하네스(harness)모델 둘레에서 도구 호출, 컨텍스트 관리, 재시도를 맡는 실행 틀이다. 자동차의 엔진 말고 변속기와 계기판에 가깝다.

샌드박스에이전트가 코드를 실행하고 파일을 고치는 격리된 실행 공간이다. 실수해도 본 서버에 영향이 없는 연습장이다.

컨텍스트 압축(compaction)긴 작업 기록을 요약해 모델이 보는 창에 맞게 줄이는 일이다. 회의록을 한 장 요약본으로 줄이는 것과 비슷하다.

서브에이전트메인 에이전트가 일을 쪼개 맡기는 하위 에이전트다. 팀장이 팀원에게 조사를 나눠 주는 것과 같다.

MCP에이전트가 외부 도구와 데이터에 붙는 표준 규격이다. 기기를 꽂는 USB 포트 같은 역할이다.