OpenAI Agents API 2026 완전 해설: AI Agent는 어떻게 도구를 호출하는가? JSON Schema, Tool Calling, Workflow 데이터 구조

읽기 전 한눈

개념	한 줄	어디에 떨어지나
Agents API	OpenAI가 관리하는 Codex harness	sessions.create / agent
Tool Calling	모델이 이름과 인자를 제안한다	function_call / arguments
JSON Schema	루프에 넣을 수 있는 인자 모양	parameters / additionalProperties
Workflow	세션, 턴, 항목, 인수인계	session / turn / items

역할을 먼저 기억한다. 당신이 Agent / Tools / Environment를 선언하고, OpenAI가 루프를 돌린다. 부작용은 호스트나 샌드박스에 남는다. 가중치 안이 아니다.

도구는 호출할 수 있다. 호출하는 쪽은 모델이 아니다

공개 베타 이후 POST /v1/agents/sessions 하나로 오래 도는 Agent를 세울 수 있다. 주문 조회, 저장소 읽기, subagent 위임. 그 부작용은 진짜다.

「직접 호출」은 주어를 잘못 쓴다. 모델은 MCP 소켓을 갖지 않고, 샌드박스를 spawn하지 않으며, 업무 API도 치지 않는다. 내는 것은 검증 가능한 객체다. 실행하는 것은 관리 harness와 당신이 고른 Environment다.

• 선언: agent.tools에 function, MCP, web_search를 둔다.
• 제안: 모델이 function_call을 낸다. 이름과 인자 객체.
• 실행: harness가 서비스 도구, 당신의 handler, 또는 샌드박스 명령을 돌린다.

Agent, Tool Calling, Function Calling이 아직 한 단어라면 먼저 AI Agent 완전 가이드. 이 글은 한 가지만 다룬다. Agents API가 이 JSON 사슬을 어떻게 호스트하는가.

9월 10일 베타가 넘긴 것

OpenAI는 단정하다. Codex와 ChatGPT for Work의 같은 harness를 API로 냈다. 모델 쪽은 흔히 GPT-6 Astra 가이드. 내는 돈은 토큰과 도구 사용량. API 자체 추가 요금은 없다.

• 관리 루프: session, 오케스트레이션, 복구. 직접 짠 LangChain 접착제는 필요 없다.
• 문맥 압축: 창 상한 근처에서 자동 compact. 여러 창을 이어 달린다.
• Tool search + programmatic tool calling: 정의를 필요할 때 싣고, 병렬 호출하며, 관련 결과만 되돌린다.
• MCP / function / web_search: 한 도구 표에 섞을 수 있다.
• Subagents: multi_agent.enabled. 동시 실행 상한을 둔다. 문서 기본값은 흔히 6.

OpenAI DevDay 2026 예측는 Structured Outputs와 Function Calling을 예측했다. 나온 것은 또 하나의 chat completion 포장이 아니다. Agent, Environment, Session, Events / Items라는 session 자원이다.

골격은 여전히 JSON Tool Calling

API 이름은 바뀌었다. 네 홉은 바뀌지 않았다:

1. 선언: agent.tools[]가 function Schema, MCP, 내장 도구를 낸다.
2. 제안: 모델이 이름과 인자를 채운다. 실행하지 않는다.
3. 문: harness나 handler가 검증하고 allowlist하며, 사람을 기다릴지 정한다.
4. 되돌림: tool result가 다음 보이는 item이 된다.

session 생성은 대략 이 모양이다. 주문은 허구다. 진짜 비밀이나 사내 URL을 공개 사이트에 붙이지 마라:

{
  "agent": {
    "model": "gpt-6-astra",
    "instructions": "Look up orders. Confirm before any refund.",
    "tools": [
      { "type": "programmatic_tool_calling" },
      {
        "type": "function",
        "name": "lookup_order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      },
      {
        "type": "mcp",
        "server_label": "orders",
        "transport": {
          "type": "http",
          "server_url": "https://orders.example.com/mcp"
        }
      }
    ],
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 3
    }
  },
  "environment": {
    "type": "hosted",
    "workspace_directory": "/workspace"
  },
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Look up order A-1042." }
      ]
    }
  ]
}

루프가 돌기 시작해도 모델이 내는 것은 객체다. 「주문을 조회해 주세요」라는 산문이 아니다:

{
  "type": "function_call",
  "id": "call_3c91",
  "name": "lookup_order",
  "arguments": "{\"order_id\":\"A-1042\"}"
}

MCP 행은 같은 도구 표의 다른 표기. 경계는 MCP Tool Schema vs Function Calling. 샌드박스에서 명령을 도는 Coding Agent도 JSON. AI Coding Agent와 JSON 호출 사슬.

문은 JSON Schema다. 「JSON을 반환해」가 아니다

루프를 호스트해도 넓은 object는 안전해지지 않는다. 계약은 왜 AI에 JSON Schema가 필요한가. prompt는 무엇을 채울지에 닿는다. 실행 가능 여부는 Schema가 정한다.

{
  "name": "lookup_order",
  "description": "Look up an order by ID",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "pattern": "^[A-Z]-\\d{4}$"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

나쁜 홉을 막을 수 있는 function Schema에는 적어도 넷이 필요하다:

• 타입을 조인다: order_id에 pattern. 맨 string은 쓰지 않는다.
• 금액과 동작을 enum으로: 환불과 상태 변경은 enum.
• 여분 키를 닫는다: additionalProperties: false. 넓은 객체는 또 하나의 문.
• 확인은 호스트가 쓴다: 모델은 create_refund를 제안할 수 있다. allowed: true를 상태에 쓰면 안 된다.

도구와 워크플로는 저장소의 Schema로 둔다. 채팅 약속으로 두지 않는다. 문을 잇는 법은 JSON Schema와 AI Agent 워크플로.

Workflow는 네 객체다. prompt 사슬이 아니다

공식은 Agents API를 네 개념으로 접는다. 공학에서는 모두 JSON:

• Agent: 모델, instructions, tools, MCP. 능력 표.
• Environment: hosted / self_hosted 샌드박스. 파일, 명령, skills가 여기 산다.
• Session: 이어 달릴 수 있는 인스턴스. 상태는 서버. history를 직접 짜지 않는다.
• Events / Items: 입력, tool call, 결과, subagent 조정.

감사 가능한 워크플로는 객체처럼 보여야 한다. 「끝냈다」는 마지막 문장처럼 보이면 안 된다:

{
  "session_id": "sess_9f2a",
  "turn": 2,
  "items": [
    { "type": "function_call", "name": "lookup_order", "id": "call_3c91" },
    { "type": "function_call_result", "call_id": "call_3c91", "status": "paid" }
  ],
  "state": {
    "order_id": "A-1042",
    "status": "paid"
  },
  "next": {
    "tool": "create_refund",
    "allowed": false,
    "reason": "missing_confirmation"
  }
}

subagent는 자신의 문맥을 가진다. 주 Agent는 create / message / wait / interrupt item으로 조정한다. 동시 실행에 상한을 둔다. 상한이 없으면 토큰과 부작용이 부채처럼 퍼진다.

차이는 누가 루프를 도느냐

누가 더 똑똑한지가 아니다. 오케스트레이션이 어디에 사느냐:

API를 고르기 전에 주어를 고른다. 루프를 직접 쥘 것인가. 자세한 비교는 다음 글. 이 글은 한 가지만 본다. 입구를 바꿔도 JSON 호출 사슬은 남는다.

볼 것은 객체다. 「끝났다」는 문장이 아니다

session이 끝난 뒤 마지막 자연어를 심사하지 않는다. 궤적을 심사한다.

• agent.tools, function_call, function_call_result를 포맷. 이름과 인자가 생각한 홉인지 본다.
• JSONPath 추출로 name, arguments, server_url을 뽑는다. 산문을 눈으로 훑지 않는다.
• 지난주 통과한 session 궤적과 JSON Diff. 루프가 흘렀으면 먼저 도구 표와 인자 모양을 본다. 모델을 탓하는 것은 그다음.
• compact 뒤 요약에도 핵심 필드가 남아야 한다. order_id를 잃으면 다음 홉이 틀린다.
• 주문, 세션, 사내 MCP URL을 공개 포맷터에 붙이지 마라. JSONSort는 브라우저 로컬. 이런 객체를 읽을 자리다.

궤적을 다시 만들 수 있으면 session을 복기할 수 있다. 그것이 프로덕션 입장권이다. 장식이 아니다.

함정

• Agents API가 모델에게 실행을 넘겼다고 생각한다. 실행권은 harness와 Environment.
• 넓은 object를 관리 루프에 넘긴다. 호스트된다는 것은 문이 아니다.
• multi_agent를 켜고 동시 실행 상한을 두지 않는다. subagent는 토큰과 부작용을 부채처럼 퍼뜨린다.
• Session을 또 한 번의 chat completion으로 본다. 상태, 복구, compact는 일급 객체다.
• prompt로 Schema를 바꾼다. 계약은 검증 가능해야 한다.
• hosted sandbox를 Zero Data Retention으로 읽는다. 공식은 분명하다. 자체 샌드박스도 Agents API를 ZDR로 만들지 않는다.

FAQ

Agents API는 모델이 도구를 직접 호출하게 하는가?

직접 내게 하는 것은 도구 JSON이다. 실행은 관리 harness, function handler, 또는 샌드박스. tools[]가 없으면 아무것도 호출하지 못한다.

Agents API와 Responses API, 어디서 시작하나?

긴 루프, 문맥 압축, subagent를 OpenAI에 맡기려면 Agents API. 매 단계 모델 호출을 직접 쥐려면 Responses API. 루프를 자기 프로세스에 두려면 Agents SDK.

Agents API에서도 JSON Schema가 필요한가?

필요하다. 관리 루프는 편성만 한다. function 인자, MCP inputSchema, 상태 객체는 여전히 조여야 한다. 넓은 Schema에 자동 루프를 더하면 문은 더 열린다.

Session, Turn, Item의 차이는?

Session은 이어 달릴 수 있는 인스턴스. Turn은 한 사용자 입력으로 시작하는 일. Item은 그 구간의 입력, tool call, 결과, subagent 조정. 감사는 item. 마지막 문장이 아니다.

Agent가 프로덕션 DB나 프로덕션 환불을 건드려도 되나?

프로덕션 부작용을 첫 홉에 두지 마라. 격리 환경과 조인 Schema에서 초안을 쓰게 하고, 확인은 호스트가 쓴다. 비밀과 배포는 사람의 전략 문.

결론

Agents API가 「도구를 직접 호출한다」——그 문장은 절반만 맞다. 맞는 절반: 더 이상 루프를 손으로 쓰지 않는다. 틀린 절반은 주어. 주어는 harness, 술어는 실행, 목적어는 모델이 채운 JSON.

오늘부터 「스스로 하는가」를 덜 다툰다. 먼저 Agent, Tools, Session items, Schema를 저장소에 넣는다. 모델은 바뀐다. 이 JSON Tool Calling 사슬을 먼저 안정시킨다.

더 읽기

• AI Agent란 무엇인가: 완전 가이드 런타임, Tool Calling, JSON 계약
• JSON Schema와 AI Agent 워크플로 도구와 상태를 Schema로
• MCP Tool Schema vs Function Calling 도구 JSON의 프로토콜 경계
• 왜 AI에 JSON Schema가 필요한가 Schema / Function Calling / Structured Output
• OpenAI DevDay 2026 예측 Structured Outputs와 Agent의 이전 프레임
• JSONSort 로컬 도구함 포맷, 검증, Diff
• 모든 글 JSON과 AI 개발 메모

변경 기록: 2026-09-20 최초 게시