OpenAI Agents API란? AI 에이전트 개발 방식이 달라지는 이유

최종 수정일: 2026년 11월 4일

OpenAI 에이전트를 만드는 방법은 하나가 아닙니다. 모델을 직접 호출하는 Responses API, 애플리케이션 코드 안에서 실행을 조율하는 Agents SDK, 세션과 실행 환경을 관리형으로 제공하는 공개 베타 Agents API가 있습니다. AgentKit은 이 중 하나의 API라기보다 에이전트 구축과 UI 관련 도구 묶음입니다.

검토 기준일은 2026년 10월 24일입니다. 제품과 베타 기능은 바뀔 수 있으므로, 실제 도입 전에는 최신 공식 문서와 프로젝트별 접근 권한을 확인하세요.

대표·본문 그림은 개념을 설명하는 별도 예시입니다. 그림 속 코드는 실행 예제가 아니며, 현행 제품 화면이나 구성요소별 제공 상태를 재현한 것도 아닙니다. 실제 API 경로와 지원 범위는 아래 설명 및 공식 문서를 구분해 확인하세요.

OpenAI 에이전트 개발 경로 비교

표를 좌우로 밀어 전체 열을 확인하세요.

경로	주된 역할	실행과 상태 관리	검토할 때
Responses API	모델 호출과 도구 사용을 위한 기본 API	앱이 사용자 정의 함수를 실행하고 권한·업무 상태·오류 흐름을 관리합니다. Responses 또는 Conversations 기능을 활용할 수 있습니다.	호출과 실행 흐름을 직접 제어하고 싶을 때
Agents SDK	애플리케이션 코드 안에서 에이전트 실행 조율	SDK가 에이전트 루프, 도구, 핸드오프 등의 구현을 돕습니다. 앱은 서버와 업무 데이터, 권한 및 운영 정책을 관리합니다.	여러 단계나 에이전트를 앱 안에서 조합할 때
Agents API	OpenAI 관리형 세션과 에이전트 실행 환경	세션과 이벤트로 실행을 주고받습니다. 구성에 따라 호스팅 환경을 선택합니다. 공개 베타 상태입니다.	세션·실행 환경을 관리형으로 이용하려 할 때
AgentKit / ChatKit	에이전트 구축 도구 및 채팅 UI 구성요소	단일 런타임 API가 아닙니다. 구성요소별 상태와 지원 범위를 확인해야 합니다.	UI 또는 기존 워크플로의 이행을 검토할 때

Responses API에서 사용자 정의 함수를 등록하면 모델은 함수 호출을 요청할 수 있습니다. 실제 데이터베이스 조회나 외부 서비스 호출은 앱이 수행해야 합니다. Agents SDK는 앱 내부의 조율을 돕고, Agents API는 세션 기반의 관리형 실행 경로를 제공합니다. 따라서 어느 하나가 모든 새 프로젝트의 기본 선택이라고 단정하기보다 필요한 제어 수준과 운영 부담에 맞춰 고르는 것이 정확합니다.

Agents API는 무엇을 관리하나요?

Agents API는 2026년 9월 10일 공개 베타로 발표된 세션 기반 실행 경로입니다. 앱은 에이전트 설정과 도구를 지정하고 세션 이벤트를 주고받습니다. OpenAI 호스팅 환경에서의 코드 실행·파일 작업·MCP 연결·브라우저 computer use 등은 각 기능 문서와 환경 설정에 따라 사용할 수 있습니다. 기능 이름만 보고 모든 세션에서 기본 제공된다고 가정하면 안 됩니다.

Computer use는 브라우저 세션과 이벤트를 앱이 다루는 방식입니다. 웹사이트 접근 및 로그인 요청을 자동으로 승인하는 기능은 아니므로, 승인 요청과 사용자 동의를 별도로 처리해야 합니다.

도입 전 데이터 처리 위치와 보존 조건도 확인하세요. 검토 기준일 현재 공식 안내에는 Agents API의 미국 내 데이터 처리 및 ZDR(Zero Data Retention) 미지원 제한이 표시돼 있습니다. 민감한 데이터를 다루는 서비스라면 이 제한을 설계 단계에서 검토해야 합니다.

관리형 Agents API를 선택했다면 다음 순서로 준비하세요. 아래는 실행 절차 제안이며 이 글에서 실제로 실행한 결과가 아닙니다.

1. 프로젝트 키에 api.agents.read·api.agents.write·api.responses.write 권한을 준비하고, 키는 에이전트의 격리된 실행 환경(샌드박스) 밖에 보관합니다.
2. SDK와 실행 환경을 선택하고 세션 생성 → 작업 입력 → 진행 이벤트 수신의 순서를 공식 예제로 확인합니다. SDK는 API 연결을 돕는 개발 라이브러리입니다.
3. session_id를 저장하고 agent.session.turn.completed 이벤트와 실제 도구 결과를 함께 확인합니다. idle 상태나 Turn 완료만으로 모든 도구가 성공했다고 판단하지 않습니다.

다음 코드는 이 관리형 세션 절차가 아니라, 앱이 함수 실행을 직접 맡는 Responses API 경로를 설명합니다. (관리형 Agents API 빠른 시작)

읽기 전용 함수 호출 예제

다음 예제는 Responses API에서 송장 상태 조회 함수를 한 번 호출하는 기본 흐름만 보여줍니다. API 호출과 코드를 실행하지 않은 예시이며, 데이터베이스에 연결되지 않은 스텁 함수입니다.

import OpenAI from "openai";

const client = new OpenAI();

async function getInvoiceStatus(invoiceId) {
  // Demo stub only. Replace with an authenticated, read-only system lookup.
  return { invoice_id: invoiceId, status: "example-only" };
}

const first = await client.responses.create({
  model: "gpt-6-astra",
  input: "Check invoice INV-1048 and summarize its payment status.",
  tools: [
    {
      type: "function",
      name: "get_invoice_status",
      description: "Look up a read-only invoice status.",
      strict: true,
      parameters: {
        type: "object",
        properties: {
          invoice_id: { type: "string" }
        },
        required: ["invoice_id"],
        additionalProperties: false
      }
    }
  ]
});

const call = first.output.find(
  (item) =>
    item.type === "function_call" &&
    item.name === "get_invoice_status"
);

if (!call) {
  console.log(first.output_text);
} else {
  const { invoice_id } = JSON.parse(call.arguments);
  const result = await getInvoiceStatus(invoice_id);

  const final = await client.responses.create({
    model: "gpt-6-astra",
    previous_response_id: first.id,
    input: [
      {
        type: "function_call_output",
        call_id: call.call_id,
        output: JSON.stringify(result)
      }
    ]
  });

  console.log(final.output_text);
}

이 예제의 결과는 실제 송장 상태가 아닙니다. getInvoiceStatus는 실제 데이터베이스를 조회하지 않고 status가 example-only인 값을 돌려줍니다. 따라서 그 값을 바탕으로 모델이 작성하는 후속 답변도 실제 송장이나 결제 상태를 확인한 결과가 아니라 데모 응답입니다.

이 코드는 단일 함수 호출만 처리합니다. 모델은 한 응답에서 여러 함수 호출을 요청하거나, 함수 결과를 받은 뒤 추가 호출을 요청할 수 있습니다. 운영 코드에서는 모든 function_call 항목을 반복 처리하고 최종 응답이 나올 때까지 실행 흐름을 이어가야 합니다. 각 함수의 권한 검사, 실패·시간 초과·재시도 정책, 중복 실행 방지, 로그와 사용자 승인도 별도로 설계해야 합니다. 이 예제에는 그런 반복 처리와 오류 대응이 포함돼 있지 않습니다.

Assistants API에서 무엇이 달라졌나요?

Assistants API는 2026년 8월 26일 종료됐습니다. OpenAI 공식 이행 가이드는 기존 객체를 다음 방향으로 매핑합니다.

기존 Assistants API	이행 방향
Assistant	Prompt
Thread	Conversation
Run	Response
Run Step	Item

기존 객체 이름만 바꾸는 것으로 이행이 끝나지는 않습니다. 함수 호출 요청과 실제 실행을 구분하고, 대화 기록과 권한을 새 구조에서 어떻게 관리할지 확인하세요. 기존 Thread나 Run 데이터가 새 시스템에서 자동으로 계속 작동한다고 가정하지 말고 필요한 데이터를 보존·매핑해야 합니다.

Agent Builder와 ChatKit 상태는 다릅니다

OpenAI는 2026년 6월 3일 Agent Builder 폐기를 공지했고, 공식 문서상 Agent Builder는 2026년 11월 30일 종료 예정입니다. 기존 사용자는 전환 기간 동안 계속 사용할 수 있다고 안내돼 있습니다. 반면 ChatKit은 계속 이용 가능하다고 안내돼 있으므로 두 제품의 상태를 혼동하지 마세요. 새 ChatKit 작업이나 마이그레이션은 현재 안내된 고급 통합 경로를 검토할 수 있습니다.

API 비용은 ChatGPT 구독과 별도입니다

ChatGPT 유료 구독과 OpenAI API 사용은 별도 청구 체계입니다. ChatGPT 구독이 API 사용료를 자동으로 포함하지 않습니다. API 예산은 사용할 모델과 토큰, 선택한 도구 및 실행 환경의 요금을 공식 가격표에서 확인하세요. Agents API라는 이름만 보고 모든 도구나 호스팅 실행 환경이 무료라고 판단하면 안 됩니다.

선택할 때 확인할 질문

• 모델 호출과 함수 실행을 직접 관리하고 싶다면 Responses API를 검토합니다.
• 앱 안에서 다단계 실행과 에이전트 간 핸드오프를 조율하려면 Agents SDK를 검토합니다.
• 관리형 세션과 실행 환경이 필요하면 Agents API의 베타 범위, 데이터 처리 조건, 접근 권한을 확인합니다.
• 사용자용 채팅 UI가 필요하면 ChatKit과 직접 구축 옵션을 비교합니다. Agent Builder의 종료 예정 일정은 별도로 고려합니다.
• 민감한 데이터가 있다면 데이터 위치, 보존, 권한 검사, trace 및 로그 기록 정책을 먼저 확인합니다.

관련 글

• AI 에이전트 운영 비용은 얼마나 들까?
• AI 에이전트의 Computer Use란?
• AI 에이전트의 Tracing이란?
• AI 에이전트 권한 체크리스트

공식 참고 자료

• OpenAI Agents API 발표
• Agents 개발 경로 개요
• Responses API 이행 가이드 · Function calling · Conversation state
• Agents API 개요 · 빠른 시작 · Computer use
• Assistants API 이행 · API 종료 및 폐기 안내
• AgentKit 발표 · ChatKit · Agent Builder 이행
• GPT-6 Astra 모델 문서 · API 가격표 · ChatGPT와 API 청구 안내
• Agents SDK Tracing