OpenAI Agents API 사용법｜Codex 하네스·장기 실행·MCP·서브에이전트

OpenAI는 2026년 9월 10일 Agents API를 공개 베타로 출시했습니다. Agents API는 단순히 모델의 답변을 반환하는 API가 아니라, Codex에 사용되는 에이전트 하네스를 통해 장기 작업과 도구 호출, 파일 작업, MCP 연결, 서브에이전트 협업을 관리하는 API입니다.

OpenAI가 세션·오케스트레이션·컨텍스트 압축·복구를 관리하고, 개발자는 모델·도구·실행환경과 실제 업무 흐름을 선택하는 구조입니다. 다만 현재는 정식 출시 단계가 아닌 공개 베타이므로 API 형식과 지원 범위가 변경될 가능성을 고려해야 합니다.

먼저 결론

Agents API는 OpenAI가 관리하는 Codex 하네스로 오래 실행되는 에이전트를 만들 때 적합합니다. 애플리케이션 내부에서 에이전트 실행 루프와 승인·저장 방식을 직접 제어하려면 Agents SDK, 모델 응답과 도구 호출을 가장 낮은 수준에서 직접 구성하려면 Responses API가 더 적합합니다.

정보 기준일: 2026년 9월 11일

OpenAI Agents API 사용법｜Codex 하네스·장기 실행·MCP·서브에이전트

Agents API란 무엇인가

Agents API는 애플리케이션에서 OpenAI가 관리하는 Codex 하네스를 호출할 수 있게 만든 API입니다. 하네스는 모델에 질문을 한 번 전달하는 데서 끝나지 않고, 작업 계획을 세우고 도구를 선택하며 필요한 명령을 실행하고 결과를 확인하는 반복 과정을 관리합니다.

Agents API의 기본 구성요소는 다음 네 가지입니다.

  • Agent: 사용할 모델·지침·도구·MCP 서버를 정의합니다.
  • Environment: 명령 실행, 파일 처리, 코드 실행에 사용하는 선택적 환경입니다.
  • Session: 에이전트 설정과 대화, 저장된 작업을 이어가는 지속형 단위입니다.
  • Events and items: 에이전트에 전달한 입력과 실행 과정에서 생성된 결과를 나타냅니다.

관리형 하네스는 컨텍스트 압축, 작업 재개, 진행 중 지시 변경, MCP와 도구 연결, 서브에이전트 위임 등을 처리합니다. 장애 분석, 코드 수정, 문서 검토, 데이터 조사처럼 여러 단계가 필요한 업무에 적합합니다.

Responses API·Agents SDK와 무엇이 다른가

세 가지 기능은 서로 완전히 대체하는 관계가 아닙니다. 에이전트 실행과 상태 관리를 어디에서 담당할 것인지에 따라 선택 기준이 달라집니다.

구분 적합한 작업 상태·실행 관리 통합 부담
Agents API 장기 실행, 파일 작업, MCP, 다중 에이전트 OpenAI가 Codex 하네스와 세션을 관리 낮음
Agents SDK 맞춤 도구·핸드오프·승인 흐름 애플리케이션에서 실행 루프와 저장 방식 관리 중간
Responses API 모델 직접 호출, 단순 도구 연결, 자체 에이전트 구축 응답 연결과 실행환경을 개발자가 직접 설계 높음

Responses API는 가장 기초적인 모델·도구 통합 계층에 가깝습니다. Agents SDK는 개발자의 애플리케이션 안에서 에이전트 실행 루프와 핸드오프를 구성합니다. Agents API는 한 단계 더 나아가 OpenAI가 관리하는 Codex 하네스와 지속형 세션을 API로 제공합니다.

관리형 샌드박스·자체 인프라·협력사 환경 차이

Agents API에서 하네스와 실행환경은 분리되어 있습니다. OpenAI가 하네스를 운영하지만, 실제 명령과 파일 작업이 실행되는 환경은 개발자가 선택할 수 있습니다.

환경 적합한 경우 관리 주체 주의점
none 질문 응답이나 원격 MCP·함수 도구만 사용하는 작업 OpenAI 하네스 내장 셸·파일·실행기 MCP를 사용할 수 없음
openai_hosted 빠른 시작, 코드 실행, 파일 편집, 결과물 생성 OpenAI가 샌드박스 프로비저닝과 연결 관리 컨테이너 비용·네트워크 정책·수명 확인 필요
self_hosted 사설 네트워크, 맞춤 소프트웨어, 자체 컴퓨팅 사용 개발자가 실행기와 환경 수명 관리 프로비저닝·재연결·종료·파일 보존 책임
협력사 샌드박스 특정 VPC·CPU·GPU·스토리지 조건이 필요한 경우 선택한 공급자와 개발자 별도 API 환경 유형이 아니라 자체 관리 환경의 공급 선택지

OpenAI가 발표한 협력사에는 Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop, Vercel 등이 포함됩니다. 협력사 환경은 Agents API에서 별도의 네 번째 environment.type으로 지정하는 방식이 아니라, 자체 또는 외부 공급자의 실행환경을 연결하는 선택지로 이해하는 것이 정확합니다.

장기 세션과 작업 이어가기

Agents API의 세션은 에이전트 설정, 대화, 저장된 작업을 유지합니다. 같은 세션 ID를 사용해 후속 메시지를 보내면 이전 작업의 맥락에서 계속 진행할 수 있습니다.

  • 유휴 세션에 메시지를 보내면 새로운 작업 턴이 시작됩니다.
  • 실행 중인 세션에 메시지를 보내면 현재 턴에 추가 지시를 전달할 수 있습니다.
  • 진행 상황은 스트리밍이나 웹훅으로 확인할 수 있습니다.
  • 컨텍스트 한도에 가까워지면 이전 내용을 자동 압축해 다음 작업에 필요한 정보를 유지합니다.
  • 연결이 끊어졌을 때는 저장된 세션과 항목을 다시 조회해 결과를 복구할 수 있습니다.

세션이 유지된다는 사실과 샌드박스가 계속 실행된다는 사실은 구분해야 합니다. OpenAI 호스팅 샌드박스는 활동과 유지 신호가 한 시간 동안 중단되면 삭제될 수 있으며, 세션 상태와 실행환경의 수명은 서로 다른 개념입니다.

MCP 연결 구조

MCP 서버는 에이전트가 사용할 수 있는 도구 정의를 제공하고 실제 도구 호출을 실행합니다. Agents API는 MCP 서버의 도구를 탐색하고 호출한 뒤 결과를 에이전트에 반환합니다.

연결 방식 실행 위치 환경 필요 여부
HTTP·서비스 연결 OpenAI 서비스 필요 없음
HTTP·환경 연결 세션 실행환경 필요
stdio 환경 내부 프로세스 필요

외부에서 접근 가능한 MCP 서버는 OpenAI 서비스가 HTTP로 직접 연결할 수 있습니다. 사설 네트워크의 서버나 환경에 설치된 프로그램은 connection_origin: "environment" 또는 stdio 연결을 사용합니다.

서브에이전트 사용법

다중 에이전트 기능을 활성화하면 메인 에이전트가 독립적인 작업을 서브에이전트에 나눠 맡길 수 있습니다. 각 서브에이전트는 별도의 컨텍스트에서 작업하고, 메인 에이전트가 결과를 모아 최종 답변을 작성합니다.

문서 여러 개를 각각 검토하거나 서로 다른 장애 원인을 병렬 조사하는 작업에 적합합니다. 앞 단계의 결과가 있어야 다음 단계를 진행할 수 있는 작업이나 짧은 과업은 메인 에이전트가 직접 처리하는 편이 낫습니다.

서브에이전트 제한 확인

서브에이전트는 설정된 MCP 도구, 웹 검색, 환경의 파일과 명령줄 도구를 사용할 수 있습니다. 현재 공식 문서 기준으로 애플리케이션이 직접 처리하는 function tool은 서브에이전트에서 지원되지 않습니다.

Agents API 최소 JavaScript 예제

다음 예제는 OpenAI 호스팅 환경에서 공식 문서 MCP를 연결하고, 최대 2개의 서브에이전트를 사용하도록 세션을 생성합니다.

import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "공식 OpenAI 문서만 사용해 조사하고, 독립적인 주제는 서브에이전트에 나눠 맡기세요.",
    tools: [
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp"
        },
        connection_origin: "service",
        required: true
      }
    ],
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 2
    }
  },
  environment: {
    type: "openai_hosted"
  },
  input:
    "Agents API와 Responses API의 차이, MCP 연결 방법을 각각 조사한 뒤 하나의 보고서로 정리하세요."
});

console.log(session.id);

세션 ID를 저장한 다음 같은 세션에 후속 메시지를 보내면 이전 작업을 이어갈 수 있습니다.

await client.beta.agents.sessions.events.create(session.id, {
  events: [
    {
      type: "agent.session.input.message",
      input: [
        {
          role: "user",
          content: [
            {
              type: "input_text",
              text: "앞선 조사에서 공개 베타의 제한과 비용 부분을 추가하세요."
            }
          ]
        }
      ]
    }
  ]
});

SDK를 사용하면 베타 헤더가 자동으로 추가됩니다. cURL로 직접 요청할 때는 OpenAI-Beta: agents=v1 헤더가 필요합니다. API 키에는 세션 작업을 위한 api.agents.read·api.agents.write와 모델 추론을 위한 api.responses.write 권한이 필요합니다.

비용·권한·보안 점검

OpenAI 공식 발표 기준으로 Agents API 자체에 별도의 추가 이용료는 없습니다. 다만 실제 사용 비용은 선택한 모델의 토큰, OpenAI 도구, 호스팅 샌드박스 사용량에 따라 발생합니다.

  • 모델 사용량은 선택한 모델의 API 요금을 적용합니다.
  • 웹 검색 등 OpenAI 도구는 해당 도구의 요금을 적용합니다.
  • OpenAI 호스팅 샌드박스는 컨테이너 요금이 별도로 발생합니다.
  • 외부 MCP와 협력사 샌드박스 비용은 각 공급자의 정책도 확인해야 합니다.

API 키는 에이전트의 샌드박스에 넣지 말고 애플리케이션 서버에서 관리해야 합니다. MCP 인증정보는 세션용 헤더나 재사용 가능한 Vault를 활용하고, 에이전트 정의·플러그인 파일·로그에 비밀값을 직접 저장하지 않는 것이 중요합니다.

OpenAI 호스팅 환경은 네트워크 접근을 허용·차단하거나 지정한 도메인만 허용하도록 설정할 수 있습니다. 업무에 불필요한 외부 통신을 차단하고, 사용자 또는 작업별로 실행환경을 분리해야 합니다.

공개 베타에서 확인할 주의사항

  • 정식 GA가 아닙니다. API 형식과 기능 범위가 빠르게 변경될 수 있습니다.
  • 완료 이벤트만 믿으면 안 됩니다. 턴이 완료됐더라도 개별 도구 호출이 성공했는지 결과를 확인해야 합니다.
  • 실행환경 수명을 관리해야 합니다. 세션과 샌드박스는 서로 다른 자원입니다.
  • function tool 처리기가 필요합니다. 애플리케이션 함수 호출은 개발자 서버가 결과를 반환해야 작업이 계속됩니다.
  • 비용 제한을 설정해야 합니다. 장기 세션과 병렬 서브에이전트는 토큰·도구·컨테이너 사용량을 늘릴 수 있습니다.
  • 승인 절차를 설계해야 합니다. 외부 메시지 전송, 데이터 변경, 배포처럼 되돌리기 어려운 작업은 자동 실행 전에 승인 단계를 두는 것이 안전합니다.

자주 묻는 질문

Agents API는 누구나 사용할 수 있나요?

OpenAI 공식 발표 기준으로 모든 개발자에게 공개 베타로 제공됩니다. 실제 호출에는 OpenAI Platform 프로젝트의 API 키와 필요한 Agents·Responses 권한이 있어야 합니다.

Responses API를 Agents API로 모두 바꿔야 하나요?

아닙니다. 단순한 모델 호출이나 개발자가 전체 실행 흐름을 직접 관리하는 서비스라면 Responses API가 더 단순할 수 있습니다. 장기 세션·샌드박스·복구·서브에이전트가 필요한 경우 Agents API를 검토하는 것이 좋습니다.

OpenAI 호스팅 샌드박스가 필수인가요?

필수는 아닙니다. 실행환경 없이 원격 MCP와 함수만 사용하거나, 자체 서버·노트북·컨테이너·원격 샌드박스를 연결할 수 있습니다.

MCP 서버는 어디에서 실행되나요?

외부에서 접근 가능한 HTTP MCP는 OpenAI 서비스가 직접 연결할 수 있습니다. 사설 네트워크나 로컬 프로그램은 세션 환경에서 HTTP 또는 stdio 방식으로 실행합니다.

서브에이전트를 많이 사용하면 항상 빨라지나요?

아닙니다. 서로 독립적인 조사·검토 작업은 병렬화 효과가 있지만, 순서가 중요한 작업이나 같은 파일을 동시에 수정하는 작업은 조정 비용과 충돌 가능성이 커질 수 있습니다.

정리

Agents API의 핵심은 새로운 모델 하나가 아니라 Codex 하네스와 지속형 세션을 관리형 API로 제공한다는 점입니다. 개발자는 Responses API만으로 직접 구축해야 했던 컨텍스트 관리, 작업 재개, MCP 연결, 샌드박스 실행, 서브에이전트 조정을 하나의 세션 구조에서 사용할 수 있습니다.

처음 도입할 때는 OpenAI 호스팅 환경과 단일 MCP 서버로 작은 작업을 실행해보고, 세션 복구와 비용을 확인한 뒤 자체 인프라·협력사 환경·다중 에이전트로 확장하는 순서가 안전합니다. 공개 베타 기간에는 공식 문서의 API 형식과 지원 범위를 발행일마다 다시 확인해야 합니다.

공식 출처

이 블로그의 인기 게시물

갤럭시 S26 AI 기능 실제 활용법｜써보면 유용한 기능과 굳이 안 써도 되는 기능

이미지
갤럭시 S26 AI 기능이 궁금하다면 먼저 알아야 할 것은 “기능이 많다”가 아니라 “내 일상에서 시간을 줄여주는 기능이 무엇인가”입니다. 갤럭시 S26 시리즈는 삼성전자가 3세대 AI폰으로 강조한 모델입니다. 단순히 카메라가 좋아지고 성능이 올라간 스마트폰이 아니라, 사용자의 상황을 이해하고 필요한 기능을 더 빠르게 제안하는 방향으로 발전했습니다. 하지만 AI 기능이 많다고 해서 모든 기능을 매일 쓰는 것은 아닙니다. 어떤 기능은 실제로 자주 쓰면 편하지만, 어떤 기능은 처음에만 신기하고 금방 잊히기도 합니다. 그래서 갤럭시 S26을 구매할 때는 “AI 기능이 있다”보다 “내가 어떤 AI 기능을 실제로 쓸 수 있는지”를 기준으로 봐야 합니다. 이번 글에서는 갤럭시 S26 AI 기능, 나우 넛지, Now Brief, 서클 투 서치, 글쓰기 어시스트, 포토 어시스트, 오디오 지우개, AI 기능 추천 대상 까지 실제 사용 관점에서 정리했습니다. 작성 기준: 2026년 5월 기준 삼성전자 뉴스룸과 삼성닷컴 Galaxy AI 공식 정보를 참고했습니다. AI 기능은 지원 언어, 앱, 네트워크 연결, 삼성 계정 로그인, 기기 설정에 따라 사용 가능 여부가 달라질 수 있습니다. 📌 갤럭시 S26 가격 스펙 총정리 목차 갤럭시 S26 AI 기능, 결론부터 보면? 갤럭시 S26 AI 핵심 기능 한눈에 보기 나우 넛지: 필요한 정보를 먼저 제안하는 기능 Now Brief: 하루 일정을 요약해 주는 기능 서클 투 서치: 검색 시간을 줄여주는 기능 글쓰기 어시스트: 문자·메일·블로그 초안에 유용한 기능 포토 어시스트: 사진 편집을 쉽게 하는 기능 오디오 지우개: 영상 소리를 더 깔끔하게 만드는 기능 갤럭시 S26 AI 기능이 필요한 사람과 아닌 사람 결론: 갤럭시 S26 AI 기능은 실제로 쓸 만할까? 자주 묻는 질문 출처 갤럭시 S26 AI 기능, 결론부터 보면? 갤럭시 S26 AI 기능은 스마트...
Read more »

윈도우 10 서비스 종료, 내 컴퓨터는 어떻게 될까요?

이미지
2024년 10월 14일 , 우리가 오랫동안 사용해 온 마이크로소프트(MS)의 운영체제 '윈도우 10'에 대한 무료 보안 업데이트 지원이 공식적으로 종료됩니다. 게임 플랫폼 스팀(Steam)의 통계에 따르면, 전 세계 접속자 중 무려 40.6% 가 여전히 윈도우 10을 사용하고 있습니다. 이는 10명 중 4명이 사용하는 셈으로, 이번 변화가 수많은 사용자에게 직접적인 영향을 미칠 것임을 의미합니다. 📋 목차 '서비스 종료'의 진짜 의미는 무엇일까요? 보안 업데이트 중단의 위험성 사용자가 선택할 수 있는 3가지 대안 새로운 시대의 PC: 'AI PC'란? 지금 당장 해야 할 일 결론 1. '서비스 종료'의 진짜 의미는 무엇일까요? '서비스 종료'라는 말을 들으면 당장 컴퓨터를 못 쓰게 되는 것은 아닐까 걱정할 수 있습니다. 하지만 이는 사실과 다릅니다. 서비스 종료의 핵심적인 의미는 '무료로 제공되던 새로운 보안 업데이트(신규 보안 패치) 제공이 중단된다' 는 것입니다. 즉, 10월 14일 이후에도 윈도우 10을 계속 사용할 수는 있지만, 새로 발견되는 보안 위협으로부터 컴퓨터를 보호해 줄 방패가 더 이상 제공되지 않는다는 뜻입니다. 🚗 자동차 비유로 이해하기 자동차 회사가 특정 모델을 단종시키는 것을 넘어, "이제 이 모델에 맞는 새로운 부품은 더 이상 생산하지 않겠습니다" 라고 선언하는 것과 같습니다. 차를 계속 운전할 수는 있지만, 고장이 났을 때 수리하기가 매우 어려워지고 위험에 노출되는 상황과 유사합니다. 2. 보안 업데이트 중단의 위험성 보안 취약점 노출 보안 업데이트가 중단되면 컴퓨터는 해커들...
Read more »

DISM/SFC 명령어 완전 정리 (초보자용) — Windows 손상·업데이트 오류 복구 가이드

이미지
💻 DISM/SFC 명령어 완전 정리 (초보자용) Windows 손상·업데이트 오류 복구 가이드 Windows 업데이트가 실패하거나 재부팅 후 되돌아가나요? 시스템이 느려지거나 파일과 기능이 비정상적으로 동작하나요? 이럴 때 DISM과 SFC는 "윈도우 자체 파일을 점검하고 복구"하는 대표적인 명령어입니다. 핵심은 순서 입니다. Microsoft는 일반적으로 DISM을 먼저 실행해 복구에 필요한 구성 요소(이미지/저장소)를 정리·복구한 뒤, SFC로 실제 시스템 파일을 최종 복구 하라고 안내합니다. 이 글에서는 초보자 기준으로 "언제 무엇을 입력해야 하는지", "성공/실패 시 다음 행동", "가장 많이 묻는 오류 메시지 대응"까지 한 번에 정리해드릴게요. 📑 목차 DISM과 SFC 차이 (딱 2줄로 이해) 실행 전 필수 준비 (실수 방지) 초보자용 "표준 복구 순서" (가장 추천) 가장 흔한 결과 메시지 해석 (초보자용) Windows 업데이트 "구성요소 초기화"까지 해야 할 때 그래도 해결이 안 되면 (공식 복구 옵션) FAQ (초보자가 가장 많이 묻는 질문) 🔍 DISM과 SFC 차이 (딱 2줄로 이해) 많은 분들이 DISM과 SFC를 헷갈려 하시는데, 각각의 역할을 정확히 이해하면 복구 과정이 훨씬 명확해집니다. 🛠️ DISM (Deployment Image Servicing and ...
Read more »