직접 에이전트 루프를 작성하는 것을 멈추세요: OpenAI Agents API 실습 튜토리얼

Originally published at AI Frontier Post

지난 1년 동안, AI 에이전트를 배포한다는 것은 모두가 똑같은 루프를 작성하는 것을 의미했습니다: 모델 호출 → 도구 호출 파싱 → 실행 → 결과 추가 → 반복 — 그리고 데모가 제품이 되어야 할 때 컨텍스트 관리, 재시도, 복구 기능을 덧붙이는 것이었습니다. DevDay 2026에서 OpenAI는 이 루프 자체를 제품화했습니다. 현재 public beta로 공개된 Agents API는 회사 자체 에이전트 뒤에 숨겨진 관리형 Codex 하네스를 API 형태로 노출합니다: OpenAI가 세션 실행, 오케스트레이션(orchestration), 컨텍스트 압축(context compaction), 그리고 복구를 처리하고, 사용자의 애플리케이션은 도구만 제공하고 실행 환경을 선택하면 됩니다.

이것은 OpenAI가 DevDay 무대에서 발표한 항상 작동하는 에이전트인 Dots를 구동하는 엔진과 동일합니다. 그리고 Assistants API가 8월에 종료됨에 따라, Agents API는 OpenAI 플랫폼에서 상태 유지(stateful) 방식으로 나아갈 수 있는 경로입니다. 이 튜토리얼에서는 이를 사용하여 처음부터 끝까지 작동하는 에이전트를 구축할 것입니다: 첫 번째 세션, 세 가지 환경 옵션, MCP를 포함한 도구, 다중 턴 세션, 서브에이전트(subagents), 그리고 정리 작업까지 모두 다룹니다. 아래의 모든 호출은 OpenAI의 공식 문서와 Python SDK 자체를 통해 검증되었습니다.

필요한 것

필요 사항

• OpenAI 플랫폼 계정 및 세 가지 스코프를 가진 애플리케이션 API 키: 세션 작업을 위한 api.agents.read와 api.agents.write, 그리고 모델 추론을 위한 api.responses.write가 필요합니다. OpenAI 플랫폼 프로젝트에서 키를 생성하고 OPENAI_API_KEY로 내보내세요.

• Python 3.10 이상: 버전 3.13.0 이상인 OpenAI Python SDK가 필요합니다. pip install --upgrade openai로 설치하거나 업그레이드하세요. 아래 스니펫은 beta.agents 네임스페이스를 포함하여 SDK 3.22.0을 기준으로 검증되었습니다.

• 예산: 베타 기간 동안 별도의 Agents API 비용은 없습니다. 선택한 모델의 API 요금, OpenAI 도구에 대한 표준 요금, 그리고 OpenAI 호스팅 샌드박스에 대한 표준 컨테이너 요금을 지불하게 됩니다.

• 주의사항을 명심하세요: Public beta라는 것은 표면이 여전히 변경될 수 있다는 의미입니다. SDK 버전을 고정하고 변경 로그를 확인하세요. 데이터 거주지는 미국 전용이며, 자체 샌드박스를 가져와도 Zero Data Retention은 지원되지 않습니다.

Step 1 — 스코프가 지정된 API 키 생성

OpenAI 플랫폼 프로젝트에서 애플리케이션 API 키를 생성하고 정확히 세 가지 스코프(api.agents.read, api.agents.write, api.responses.write)를 부여하세요. 그런 다음 내보냅니다:

export OPENAI_API_KEY="your-api-key-here"

두 가지 사항을 문서에서 강조하며 실수하기 쉬운 부분이 있습니다. 첫째, 이 키는 에이전트의 샌드박스 외부에 보관하세요 — 에이전트는 코드를 실행하므로, 그 환경 내부에 있는 모든 것을 접근 가능하다고 간주해야 합니다. 둘째, 모든 Agents API 요청에는 OpenAI-Beta: agents=v1 헤더가 필요합니다. 공식 SDK는 이를 자동으로 추가하지만, cURL이나 다른 HTTP 클라이언트를 사용하여 API를 호출하는 경우 명시적으로 포함해야 하며 그렇지 않으면 요청이 실패할 것입니다.

Step 2 — 첫 번째 세션 실행

API는 네 가지 개념을 중심으로 구성되어 있습니다: 에이전트(agent) (모델, 지침, 도구, MCP 서버), 환경(environment) (작동하는 샌드박스 또는 컴퓨터), 세션(session) (에이전트의 영속적인 인스턴스), 그리고 이벤트 및 아이템(events and items) (무슨 일이 일어났는지에 대한 실시간 기록과 저장된 기록)입니다. 이 구조를 가장 빠르게 이해하는 방법은 공식 퀵스타트(quickstart)입니다. 에이전트가 tree.py 스크립트를 작성하고, 실행하며, 디렉터리 트리를 보고하는 예제입니다.

from openai import OpenAI

with OpenAI() as client:
...

이를 quickstart.py로 저장하고 python quickstart.py로 실행하세요. 이 단일 호출은 세션을 생성하고, OpenAI가 호스팅하는 샌드박스를 프로비저닝하며, 작업의 한 차례(turn)를 시작하고, JSON 이벤트 형태로 진행 상황을 스트리밍합니다. 성공적으로 실행되면 에이전트는 샌드박스 내부에 tree.py를 생성하고, 이를 실행한 다음, 해당 파일을 포함하는 디렉터리 트리를 보고합니다.

스트림 읽는 법을 배우세요. 이것이 여러분의 주요 디버깅 표면입니다:

• agent.session.turn.completed는 차례(turn)가 완료되었음을 의미합니다. 문서의 경고에 유의하세요: 완료된 차례가 모든 도구 호출이 성공했음을 보장하지 않습니다 — 항상 에이전트가 보고한 결과를 확인해야 합니다.

• turn.failed, turn.cancelled, 또는 session.failed로 끝나는 이벤트는 실패 또는 취소를 의미합니다.

• agent.session.idle만으로는 성공을 의미하지 않습니다.

• 스트림이 일찍 연결이 끊어지면, 재시도하기 전에 세션과 저장된 아이템들을 검색하세요 — 작업은 서버 측에서 영속적입니다.

지금 만들 습관 중 하나: 이벤트에서 session_id를 저장하는 것입니다. 이 ID는 5단계의 모든 과정에 필요할 것입니다.

AI Frontier Post를 위해 생성된 다이어그램.

Step 3 — 적절한 환경 선택하기

환경은 에이전트의 명령이 어디에서 실행되고 파일이 어디에 존재하는지를 결정합니다. 세 가지 옵션이 있으며, 이것이 튜토리얼에서 가장 큰 아키텍처적 결정 사항입니다:

– openai_hosted — OpenAI가 세션용 Linux 샌드박스를 제공하고 관리합니다. 코드를 실행하거나 파일에 접근하는 모든 경우의 기본값입니다. 패키지, 입력 파일 및 네트워크 정책으로 구성할 수 있으며, 에이전트가 생성한 아티팩트를 다운로드할 수 있습니다.

– none — 샌드박스가 전혀 없습니다. 명령을 실행하거나 로컬 파일과 작업하지 않고 질문에 답변하거나 외부 도구를 호출하는 에이전트에 사용합니다: environment={"type": "none"}.

– self_hosted — 에이전트가 사용자 인프라에서 실행됩니다. 사용자의 애플리케이션은 자체 컴퓨팅 환경 내에서 codex exec-server를 실행하고, 반환된 session.environment.id와 session.environment.remote_url을 전달합니다. 실행기는 별도의 제한된 OPENAI_EXECUTOR_API_KEY로 인증하며, 이 키는 api.agents.environments.connect 범위를 가지고 있어야 하고, 해당 IP 제한은 샌드박스의 아웃바운드 네트워크에서 요청이 가능하도록 허용해야 합니다.

session = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
...

AI Frontier Post를 위해 생성된 다이어그램.

환경을 단순한 구성 플래그가 아니라 보안, 비용, 네트워크, 아티팩트 및 데이터 거버넌스 결정 사항으로 취급해야 합니다. 호스팅 샌드박스는 시작하는 가장 빠른 방법이며, 에이전트가 VPC, 데이터 또는 도구 체인에 접근해야 할 때 self_hosted 방식이 해답입니다.

Step 4 — 에이전트에 도구를 제공하기

도구는 모델과 지침과 함께 에이전트에 선언됩니다. API는 사용자 정의 함수, web_search 및 programmatic_tool_calling 같은 내장 도구, 그리고 MCP 서버를 지원합니다. 공식 문서를 기반으로 각색된 이 예제는 OpenAI 자체 문서 MCP 서버와 웹 검색에 연결된 리서치 어시스턴트를 구축합니다:

몇 가지 주목할 점이 있습니다. MCP 도구는 server_label과 서버 URL을 가진 HTTP 전송 계층이 필요합니다. 이것이 전체 연결 구조입니다. environment에 "type": "none"으로 설정한 것은 의도적입니다. 이 에이전트는 웹에서 읽기 때문에 샌드박스가 필요하지 않습니다. 그리고 multi_agent는 서브 에이전트를 사용하도록 옵트인하며, 이는 Step 6에서 다룹니다.

Step 5 — 요청(requests)이 아닌 세션(sessions)으로 생각하기

세션은 지속적인 단위입니다. 에이전트 구성, 대화 내용, 저장된 작업물이 턴(turns)을 거쳐도 유지되므로, 사용자가 직접 대화 컨텍스트를 재구축할 필요가 없습니다. 작업을 계속하려면 기존 세션 ID로 새로운 입력을 스트리밍합니다:

with client.beta.agents.sessions.stream(
    session_id,  # Step 2에서 저장됨
    input="Add a maximum-depth option to tree.py, run it, and show me the output.",
...

후속 입력을 보내기 전에 이벤트 스트림을 여는 것을 잊지 마세요. 하네스(harness)가 컨텍스트 압축(context compaction)—세션이 컨텍스트 한계에 가까워질수록 이전 작업을 요약하는 것—을 관리하기 때문에, 긴 세션은 컨텍스트 경계에서 중단되는 대신 계속 작동하며, 세션은 중단된 지점부터 재개될 수 있습니다.

세션이 수행한 모든 작업은 나중에 검사할 수 있습니다:

turns = client.beta.agents.sessions.turns.list(session_id)
items = client.beta.agents.sessions.items.list(session_id)
subs  = client.beta.agents.sessions.subagents.list(session_id)
...

턴은 턴별 상태와 사용량을 포함하며, 아이템은 저장된 결과물(메시지, 추론 과정, 함수 호출, 도구 출력)이고, 아티팩트(artifacts)는 에이전트가 생성한 파일입니다. 작업이 완료되면 필요한 모든 것을 먼저 다운로드하고—그 후에 세션을 삭제하세요. 왜냐하면 세션은 사용자가 직접 지우기 전까지 지속되기 때문입니다:

client.beta.agents.sessions.delete(session_id)

Step 6 — 서브 에이전트로 확장하기 (Fan out with subagents)

Step 6 — 서브 에이전트로 확장하기 (Fan out with subagents)

작업이 독립적인 청크들로 분할될 때—세 가지 API를 조사하거나 세 가지 경고(alert)를 분류하는 경우—하나의 에이전트가 순차적으로 처리하면 harness가 제공하는 병렬성(parallelism)을 낭비하게 됩니다. multi_agent.enabled를 설정하면 메인 에이전트가 작업을 서브태스크로 분해하여 각자 고유한 컨텍스트를 가진 서브에이전트에게 위임할 수 있습니다:

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
...

공식 '서브에이전트를 사용한 릴리스 노트 비교' 예제가 표준 패턴(canonical pattern)입니다: 각 서브에이전트가 독립적으로 조사하고, 그 후 메인 에이전트가 발견된 내용들을 하나의 답변으로 조합합니다. 두 가지 경험칙(rules of thumb)이 있습니다: 정말로 독립적인 작업만 위임해야 하며, 공유 상태(shared state)를 신중하게 조정해야 합니다—각 서브에이전트에게 고유한 작업 디렉터리나 출력 파일을 제공하여 쓰기 충돌(write collision)을 방지하세요. 네 개의 동시 서브에이전트는 합리적인 상한선이며, 이는 문서의 예제에서도 그 값으로 사용됩니다. Step 5에서 sessions.subagents.list(session_id)를 사용하여 언제든지 서브에이전트 활동을 검사할 수 있습니다.

어떤 접근 방식을 사용해야 할까요?

OpenAI 플랫폼에서 에이전트를 배포하는 네 가지 방법과 각각의 장점은 다음과 같습니다:

작업이 장시간 진행되고 도구 사용량이 많은 경우(예: 인시던트 대응, 리서치, 데이터 분석, 레포지토리 작업)에는 Agents API를 기본으로 설정하세요. 시스템의 의견이 거슬릴 때는 Responses API로 전환하면 됩니다. SDK는 단일 프로세스 에이전트를 위해 이 두 가지 사이에 위치합니다.

비용, 제한 사항 및 가드레일

• 모델 선택이 가장 큰 비용 통제 수단입니다. 퀵스타트는 gpt-6-astra를 사용합니다. 가격에 민감한 워크로드를 위해서는 DevDay에서 발표된 GPT-6.1 Sol을 고려해 보세요. 이 모델은 입력 토큰 백만 개당 $2, 캐시된 입력 토큰 백만 개당 $0.10, 출력 토큰 백만 개당 $10으로 책정되어 Astra와 유사한 지능을 약 5분의 1 가격에 제공합니다. model 필드를 교체하고 다시 실행하면 다른 것은 아무것도 변경되지 않습니다.

• 측정되는 추가 비용에 유의하세요. 모델 토큰만이 청구서의 일부입니다. OpenAI 도구는 표준 요율로, 호스팅된 샌드박스는 표준 컨테이너 요율로 청구됩니다. 장시간 세션에서 도구를 많이 사용하면 누적되므로, 세션별 usage를 통해 감사해야 합니다.

• 베타 버전을 염두에 두고 설계하세요. 요구 사항에 openai를 고정하고 업그레이드하기 전에 변경 로그를 다시 읽어보세요. 비밀 키는 샌드박스 밖에 보관하고, Step 1의 세 가지 권한으로 키 범위를 제한하며, 규제 데이터를 처리하는 경우 미국 내 거주지 및 ZDR(Zero-Day Risk) 미적용 제약 조건을 기억하세요.