OpenAI Agents API 관리형 harness

AI 에이전트를 제품에 넣는 일은 모델 API를 한 번 호출하는 것과 다르다. 모델이 다음 행동을 고르고, 도구 결과를 읽고, 다시 판단하며, 긴 작업의 맥락을 유지해야 한다. 실행이 중단되면 어디서부터 이어갈지 결정해야 하고, 여러 작업자를 나누어 쓴다면 결과를 다시 합쳐야 한다. 이 반복 구조를 안정적으로 운영하는 계층이 흔히 말하는 agent harness다.

OpenAI는 2026년 9월 10일 Agents API를 공개 베타로 출시했고, Codex에서 사용하던 harness를 OpenAI가 호스팅하고 유지한다고 설명했다.[1] 발표가 내세우는 변화는 모델 하나가 더 생겼다는 것이 아니다. 애플리케이션 팀이 직접 만들던 세션 관리, 도구 반복 호출, 컨텍스트 정리, 위임, 재개 같은 실행 제어를 관리형 서비스의 경계 안으로 옮긴다는 제안이다.

이 제안은 매력적이지만, “관리형”을 “운영 책임이 사라진다”로 읽으면 곤란하다. harness가 맡는 책임과 애플리케이션이 계속 맡아야 할 책임이 다르기 때문이다. 특히 도구 권한, 실행 환경, 민감 데이터, 승인 절차, 비용 한도, 감사 로그는 API가 대신 결정해 줄 수 없다. 관리형 harness 도입의 핵심 질문은 기능 목록이 아니라 어느 상태와 제어권을 공급자에게 맡기고, 어느 위험을 우리 시스템에 남길 것인가다.

먼저 harness의 경계를 정확히 보자

일반적인 에이전트 애플리케이션은 모델 호출 바깥에 많은 코드를 둔다. 응답에서 도구 호출을 찾아 실행하고, 결과를 대화에 다시 넣고, 토큰 한도에 가까워지면 과거 기록을 줄이고, 오류가 나면 재시도하며, 중단된 작업의 상태를 데이터베이스에 보관한다. 하위 에이전트를 만들면 작업 분배와 결과 취합도 직접 구현한다. 모델은 추론하지만, 실제 업무의 수명 주기는 harness가 통제한다.

OpenAI 개발 문서는 관리형 harness가 세션, 오케스트레이션, 컨텍스트 압축, 복구를 담당하고, 애플리케이션은 도구를 제공하며 실행 환경을 선택한다고 경계를 설명한다.[2] 이 문장을 운영 책임으로 번역하면 다음과 같다.

영역 관리형 harness에 기대하는 역할 애플리케이션이 계속 책임질 역할
작업 진행 모델과 도구 사이의 실행 흐름 유지 업무 목표, 완료 조건, 중단 조건 정의
상태 세션과 turn 사이의 진행 상태 관리 사용자·조직·업무 객체와 세션 연결
컨텍스트 길어진 맥락의 압축과 요약 절대 잃으면 안 되는 사실과 원본 보관
도구 호출 연결과 결과 전달 도구 구현, 인증, 권한, 검증, 멱등성
환경 선택한 환경에서 실행 흐름 연결 hosted/self-hosted 선택과 격리 정책
복구 중단된 세션의 재개 기반 제공 부작용 확인, 보상 작업, 수동 개입 기준
관찰 이벤트와 항목을 통한 진행 노출 장기 로그, 감사, 경보, SLO, 비용 귀속

이 표에서 중요한 것은 오른쪽 열이다. 관리형 harness가 루프를 실행해도 업무의 의미는 알지 못한다. “결제가 두 번 됐는가”, “배포가 절반만 반영됐는가”, “고객 데이터가 다른 tenant로 넘어갔는가” 같은 판단은 도메인 상태를 아는 애플리케이션이 해야 한다. 따라서 관리형 harness는 운영 플랫폼의 일부이지, 운영 정책 전체가 아니다.

agent, environment, session, events/items를 업무 모델로 번역하기

개발 문서가 제시하는 핵심 엔터티는 agent, environment, session, events/items다.[2] 이름만 보면 단순하지만, 이 네 개를 어떻게 매핑하느냐에 따라 권한 경계와 장애 조사가 달라진다.

Agent: 사람 이름이 아니라 실행 정책의 버전

agent는 “고객지원 봇” 같은 표시 이름보다 구체적이어야 한다. 운영에서는 지침, 사용할 수 있는 도구, 기본 행동, 모델 선택, 검토 규칙이 묶인 실행 정책으로 취급하는 편이 안전하다. 같은 고객지원 업무라도 환불을 조회만 하는 agent와 실제 환불을 승인하는 agent는 별도 정책이어야 한다.

agent 변경은 코드 배포처럼 다뤄야 한다. 지침 한 줄, 도구 하나, 권한 범위 하나가 실행 결과를 바꿀 수 있다. 운영 로그에는 단순한 agent 이름보다 배포 버전이나 설정 해시처럼 재현 가능한 식별자를 함께 남기는 것이 좋다. 그래야 사고 당시 어떤 규칙과 도구 집합이 적용됐는지 되짚을 수 있다.

Environment: 모델 바깥의 실제 위험이 놓이는 곳

environment는 명령과 코드가 실행되고 파일과 네트워크를 만나는 장소다. 발표는 OpenAI 관리 환경, self-hosted 환경, 열거된 sandbox 파트너를 선택지로 제시한다.[1] 선택의 본질은 성능보다 신뢰 경계다. 누가 이미지를 만들고, 누가 패치하며, 파일이 어디에 남고, 어떤 네트워크로 나갈 수 있고, 비밀 값을 어떤 방식으로 주입하는지가 달라진다.

환경을 선택할 때는 “실행되느냐”가 아니라 “실행 후 설명하고 폐기할 수 있느냐”를 봐야 한다. 작업별 격리, egress 제한, 읽기 전용 기본값, 자격 증명 수명, 파일 보존 기간, 강제 종료, 자원 한도, 악성 입력 대응이 필요하다. 관리 환경을 쓰더라도 저장소 토큰이나 SaaS 권한의 범위는 애플리케이션이 정한다.

Session: 대화 기록보다 큰 복구 단위

문서에 따르면 session은 turn 사이에서 상태를 유지하며 삭제할 수 있다.[2] 그러므로 session을 단순 채팅방 ID로만 보면 부족하다. 운영에서는 하나의 목표를 수행하는 작업 인스턴스로 보고, 내부 업무 객체와 연결해야 한다.

예를 들어 하나의 이슈 수정, 하나의 고객 조사, 하나의 데이터 정리 작업마다 session을 만들 수 있다. 이때 tenant_id, actor_id, case_id, risk_class, environment_id, agent_version을 애플리케이션 쪽 기록에 함께 연결해야 한다. 이 연결이 없으면 나중에 세션은 찾았지만 어느 고객의 어떤 승인으로 실행됐는지 알 수 없는 상황이 생긴다.

세션 수명도 업무 수명과 같지 않을 수 있다. 장기 업무를 한 세션에 계속 누적하면 편하지만 권한과 맥락이 오래 남는다. 반대로 turn마다 새 세션을 만들면 격리는 쉬워도 연속성과 복구가 약해진다. 실무에서는 “하나의 승인 범위와 하나의 완료 조건”을 세션 경계로 삼는 방식이 이해하기 쉽다.

Events/items: 디버깅 재료이지 자동으로 완성된 감사 체계는 아니다

events/items는 진행 중 무엇이 일어났는지 표현하는 핵심 단위다.[2] 모델 출력, 도구 요청, 도구 결과, 상태 전환을 이벤트로 관찰할 수 있다면 UI 스트리밍과 장애 분석의 기반이 된다. 그러나 이벤트가 존재한다고 해서 감사 요건이 자동으로 충족되는 것은 아니다.

운영팀은 최소한 다음 질문에 답할 수 있어야 한다.

  • 누가 어떤 업무 목적으로 세션을 시작했는가?
  • 어느 agent 버전과 environment가 사용됐는가?
  • 어떤 도구가 어떤 권한으로 호출됐는가?
  • 정책이 허용하거나 거부한 이유는 무엇인가?
  • 외부 시스템의 변경 결과를 어떤 식별자로 확인했는가?
  • 재시도와 resume이 같은 부작용을 반복하지 않았는가?
  • 어느 시점에 사람의 승인이나 개입이 있었는가?

이를 위해 공급자 이벤트를 내부 trace ID와 연결하고, 도구 gateway와 대상 시스템의 감사 로그까지 이어야 한다. 프롬프트 전문과 도구 결과를 무조건 장기 저장하는 것도 답은 아니다. 민감 정보가 섞일 수 있으므로 메타데이터, 정책 결정, 변경 식별자, 마스킹된 인자, 보존 기간을 목적에 맞게 설계해야 한다.

Hosted와 self-hosted는 제어권의 배치 문제다

OpenAI는 환경 선택지로 관리형, self-hosted, sandbox 파트너를 제시한다.[1] 여기서 흔한 오해는 hosted를 빠르고 편한 선택, self-hosted를 안전하지만 어려운 선택으로 단순화하는 것이다. 실제 판단은 데이터 위치, 네트워크 접근, 격리 책임, 운영 역량, 장애 시 통제권을 함께 봐야 한다.

Hosted environment가 맞는 경우

다음 조건이라면 hosted 환경이 초기 선택이 될 수 있다.

  • 외부 인터넷이나 제한된 개발 자원만 다룬다.
  • 빠른 실험과 표준화가 직접 환경 운영보다 중요하다.
  • 작업이 짧고 폐기 가능하며 장기 파일 상태가 필요하지 않다.
  • 사내망 전용 시스템에 직접 접근할 이유가 없다.
  • 공급자가 제공하는 지역성과 보존 조건이 조직 정책에 맞는다.
  • 환경 이미지를 세밀하게 통제할 필요가 적다.

이 경우에도 비밀 값을 장기 credential로 넣지 말아야 한다. 작업 목적에 맞는 짧은 수명과 좁은 scope를 가진 자격 증명을 발급하고, 네트워크와 도구 양쪽에서 사용 범위를 제한해야 한다. hosted라는 이유만으로 외부 입력을 신뢰하거나 광범위한 저장소 쓰기 권한을 줄 수는 없다.

Self-hosted environment가 맞는 경우

다음 조건에서는 self-hosted 환경을 검토할 이유가 크다.

  • 사내망, 전용 데이터베이스, 규제된 저장소에 접근해야 한다.
  • 실행 이미지, 커널 수준 격리, 패치 주기를 직접 통제해야 한다.
  • outbound network를 조직 정책으로 제한해야 한다.
  • 기존 비밀 관리, EDR, SIEM, 워크로드 identity를 재사용해야 한다.
  • 실행 로그와 파일을 지정한 저장소에 보관해야 한다.
  • 장애 시 환경을 동결하고 자체 조사해야 한다.

대신 self-hosted는 샌드박스 공급과 폐기, 용량, 이미지 공급망, 네트워크 정책, 노드 보안, 로그 전달, 고아 작업 정리까지 운영 대상에 넣는다. 실행 환경을 직접 호스팅한다고 해서 harness의 세션 데이터까지 모두 내부에 남는다고 가정해서도 안 된다. 환경의 위치와 API 제어면의 데이터 처리는 별개의 경계다.

혼합 모델이 현실적이다

한 조직 안에서도 모든 agent를 같은 환경에 넣을 필요는 없다. 공개 문서 조사나 일회성 변환은 hosted 환경에서, 내부 저장소 수정이나 규제 데이터 접근은 self-hosted 환경에서 실행할 수 있다. 중요한 것은 요청마다 임의로 선택하게 두지 않고 업무 위험 등급으로 라우팅하는 것이다.

환경 라우팅 정책에는 데이터 분류, 필요한 network zone, 도구의 변경 권한, 예상 실행 시간, 파일 지속성, 사람 승인 여부를 입력으로 사용할 수 있다. 정책 결과와 실제 선택된 environment를 이벤트에 함께 기록해야 우회 여부를 확인할 수 있다.

Context compaction은 기억이 아니라 손실 정책이다

OpenAI는 자동 context compaction을 제품 기능으로 제시하며, 개발 문서는 context summarization을 관리형 harness 기능에 포함한다.[1][2] 긴 작업에서 과거 내용을 계속 원문 그대로 넣을 수 없으므로 압축은 필요하다. 그러나 압축은 저장 공간 최적화가 아니라 정보 손실을 동반하는 운영 결정이다.

요약에서 사라지면 안 되는 항목을 먼저 정해야 한다.

  • 사용자가 명시한 금지 조건과 완료 조건
  • 확정된 식별자, 파일 경로, 브랜치, 리소스 이름
  • 이미 수행한 외부 변경과 그 결과 ID
  • 사람의 승인 범위와 만료 시점
  • 실패한 시도와 다시 하면 안 되는 이유
  • 검증 결과와 아직 검증하지 않은 항목
  • 민감 정보 취급 지침과 데이터 분류

이런 사실을 자연어 대화에만 두지 말고 구조화된 작업 상태로 별도 보관하는 편이 안전하다. harness의 요약은 추론에 필요한 working memory로 쓰고, 원본 이벤트와 도메인 상태는 감사 및 복구의 source of truth로 둔다. 압축된 요약이 원본을 대체하면, 에이전트가 왜 결정을 내렸는지 확인하거나 잘못된 요약을 교정하기 어려워진다.

압축 품질도 평가해야 한다. 긴 세션을 준비하고 중간에 제약 조건, 승인 범위, 이미 완료한 부작용을 배치한 뒤, compaction 이후에도 agent가 이를 지키는지 테스트한다. “대화가 이어진다”보다 “중요한 불변 조건이 보존된다”를 성공 기준으로 삼아야 한다.

Tools와 MCP: 연결보다 권한 모델이 먼저다

발표는 MCP, custom tool, built-in tool과 programmatic tool calling, tool search를 제품 기능으로 제시한다.[1] 개발 문서도 tools/MCP를 관리형 harness의 기능 범위에 포함한다.[2] 도구 연결이 쉬워질수록 agent가 수행할 수 있는 행동은 넓어진다. 동시에 잘못된 선택의 피해 범위도 넓어진다.

도구 catalog는 기능 목록이 아니라 권한 표면이다. 각 도구에 최소한 다음 메타데이터를 붙이는 것이 좋다.

  • 소유 팀과 업무 목적
  • read-only인지 상태를 변경하는지
  • 접근하는 데이터 등급과 tenant 범위
  • 필요한 identity와 scope
  • 네트워크 목적지
  • 멱등성 지원 여부와 idempotency key
  • dry-run 지원 여부
  • 사람 승인이 필요한 조건
  • timeout, rate limit, 최대 반복 횟수
  • 성공을 확인할 read-back 방법
  • 실패 시 가능한 보상 작업

특히 변경 도구는 “호출 성공”과 “업무 성공”을 구분해야 한다. 도구가 200 응답을 돌려줘도 대상 시스템에 원하는 상태가 반영됐는지 다시 읽어 확인해야 한다. timeout이 발생하면 실패로 단정하고 즉시 재호출할 것이 아니라, idempotency key나 대상 조회로 첫 호출의 반영 여부를 확인해야 한다.

MCP를 사용하더라도 정책을 protocol에 맡길 수는 없다. tool name이나 자연어 설명만으로 위험을 판단하지 말고, gateway나 실행 계층에서 identity, scope, 인자, 대상 리소스, 승인 토큰을 검증해야 한다. tool search가 필요한 도구를 동적으로 찾는 편의를 주더라도, 검색 결과에 나타났다는 이유로 호출 권한까지 자동 부여해서는 안 된다.

Subagents는 병렬성보다 책임 분리가 먼저다

OpenAI는 multi-agent delegation을 제품 기능으로 제시하고, 개발 문서는 subagents를 지원 범위에 포함한다.[1][2] 하위 에이전트는 조사, 구현, 검토처럼 독립적인 작업을 나누는 데 유용할 수 있다. 그러나 agent 수가 늘면 호출량만 늘어나는 것이 아니라 권한 전파, 상태 합의, 실패 전파가 복잡해진다.

위임할 때는 부모 agent가 다음을 명시해야 한다.

  1. 하위 작업의 입력과 기대 출력
  2. 사용할 수 있는 도구와 environment
  3. 읽을 수 있는 데이터와 쓸 수 있는 범위
  4. 시간, 호출, 비용의 상한
  5. 중단 조건과 에스컬레이션 조건
  6. 결과를 검증할 방법
  7. 부모에게 반환할 근거와 미해결 항목

하위 agent에게 부모와 같은 credential을 그대로 넘기는 방식은 편하지만 최소 권한 원칙을 무너뜨린다. 조사 agent는 읽기 전용이어야 하고, 검토 agent는 구현 agent가 만든 환경과 분리할 수 있어야 하며, 실제 변경은 승인된 단일 경로를 통과시키는 편이 좋다.

결과 합치기도 명시적인 단계여야 한다. 여러 subagent가 같은 파일이나 외부 객체를 동시에 바꾸게 두면 마지막 쓰기 우선, 중복 생성, 서로 다른 가정이 충돌할 수 있다. 병렬 작업은 읽기와 분석에서 넓게 쓰고, 상태 변경은 잠금, 버전 조건, 단일 writer, 검토 gate로 좁히는 방식이 운영하기 쉽다.

Recovery와 resume: 이어서 실행하는 것만으로는 복구가 아니다

OpenAI 개발 문서는 관리형 harness가 recovery와 session resume을 지원한다고 설명한다.[2] 이는 네트워크 단절이나 장시간 작업에서 중요한 기반이다. 다만 resume은 저장된 추론 상태에서 계속 진행하는 기능이고, 외부 시스템의 원자적 rollback을 의미하지 않는다.

에이전트 작업은 여러 시스템을 건드릴 수 있다. 브랜치를 만들고, 파일을 수정하고, CI를 시작하고, 이슈에 댓글을 남긴 뒤 중단될 수 있다. 재개 시 같은 단계를 반복하면 중복 댓글, 중복 배포, 중복 결제가 발생할 수 있다. 따라서 각 단계는 다음 상태 중 하나로 기록할 필요가 있다.

  • 시작 전
  • 요청 전송됨, 결과 미확인
  • 외부 반영 확인됨
  • 검증 완료
  • 보상 필요
  • 사람 확인 필요

“결과 미확인”을 일반 실패와 구분하는 것이 중요하다. 이 상태에서는 재시도보다 read-back이 먼저다. 외부 시스템이 idempotency key를 지원하면 세션과 step에서 안정적인 키를 만들고, 지원하지 않으면 업무 객체에 고유 표식을 남기거나 사전 조회로 중복을 방지해야 한다.

복구 정책은 오류 종류에 따라 달라야 한다. 일시적 네트워크 오류는 제한된 backoff 재시도가 가능하지만, 권한 거부는 자격 증명이나 승인 범위를 바꾸지 않는 한 반복할 이유가 없다. 입력 검증 실패는 계획을 수정해야 하고, 외부 상태 충돌은 최신 상태를 다시 읽어야 한다. 위험한 상태 변경 이후의 불확실성은 자동 재개보다 사람 검토로 보내는 편이 안전하다.

데이터 보존과 ZDR은 초기 아키텍처 조건이다

개발 문서에는 확인 시점 기준으로 데이터 거주 지역이 미국만 지원되고 Zero Data Retention은 지원되지 않으며, self-hosted sandbox를 선택해도 API가 ZDR 대상이 되지는 않는다고 명시돼 있다.[2] 이 제약은 나중에 보안 설문에서 처리할 세부 항목이 아니라 도입 가능성을 가르는 선행 조건이다.

self-hosted environment를 사용하면 코드 실행과 파일 처리를 내부 경계에 둘 수는 있다. 그러나 agent 요청, session 상태, event/item, context compaction에 필요한 데이터가 API 제어면에서 어떻게 처리되는지는 별도로 검토해야 한다. “코드가 우리 클러스터에서 실행된다”와 “서비스 전체가 데이터 무보존 조건을 충족한다”는 같은 말이 아니다.[2]

도입 전에 다음 데이터 흐름을 그려야 한다.

  1. 사용자의 원문 입력이 어디로 전달되는가?
  2. 도구 결과 중 어떤 부분이 다시 모델과 session에 들어가는가?
  3. 파일 내용, 로그, 비밀 값이 이벤트에 포함될 수 있는가?
  4. compaction으로 만들어진 요약은 어떤 민감 정보를 보존하는가?
  5. session 삭제와 내부 업무 기록 삭제를 어떻게 연결하는가?
  6. 법적 보존 요청과 사용자 삭제 요청이 충돌하면 누가 결정하는가?
  7. 미국 외 거주 요건이나 ZDR이 필수인 workload를 어떻게 차단하는가?

현재 제약이 조직 정책과 맞지 않으면 민감 데이터를 마스킹해 제한된 업무만 시도하거나, 해당 workload를 관리형 API 범위 밖에 두어야 한다. self-hosted sandbox만 추가하고 규정 준수가 해결됐다고 선언해서는 안 된다.

권한 설계: 모델의 판단과 정책의 집행을 분리하라

에이전트는 어떤 도구가 필요할지 제안할 수 있지만 최종 권한 집행자가 되어서는 안 된다. “이 작업에 관리자 권한이 필요하다”는 모델의 문장은 권한 부여 근거가 아니다. 정책 계층은 사용자 identity, tenant, 업무 객체, risk class, 승인 상태, 도구 인자, 시간 제한을 기계적으로 검사해야 한다.

실무에서는 세 단계로 나누는 방식이 유용하다.

1. 발견 권한

agent가 도구의 존재와 스키마를 볼 수 있는 권한이다. 불필요한 도구를 숨기면 잘못된 선택과 prompt injection의 행동 표면을 줄일 수 있다. 모든 도구를 보여준 뒤 “사용하지 말라”고 지시하는 것보다 catalog 자체를 좁히는 편이 낫다.

2. 호출 권한

도구를 실제로 요청할 수 있는 권한이다. 읽기와 쓰기를 분리하고, 리소스 범위와 인자를 검증한다. 같은 update 도구라도 staging과 production, 자기 팀과 다른 팀, 소액과 고위험 변경은 정책이 달라야 한다.

3. 반영 권한

고위험 변경은 호출 즉시 반영하지 않고 승인 가능한 계획이나 dry-run으로 만들 수 있다. 사람이 대상, 차이, 예상 영향, rollback 경로를 본 뒤 짧은 승인 토큰을 발급하면 실제 반영 단계가 이를 검증한다. 승인 토큰은 특정 세션 전체가 아니라 특정 작업과 특정 입력에 묶는 편이 안전하다.

이 구조에서 harness는 실행을 조율하고, 정책 엔진과 도구 gateway는 허용 여부를 결정한다. 모델이 잘못 판단하더라도 마지막 경계가 막을 수 있어야 한다.

관찰 가능성: 답변 품질보다 작업 상태를 추적하라

에이전트 관찰 가능성은 완성된 자연어 답변을 저장하는 것으로 끝나지 않는다. 운영자가 보고 싶은 것은 작업 그래프다. 어떤 계획이 세워졌고, 어느 단계가 실행됐으며, 어디서 대기하고, 무엇이 실패했고, 어떤 외부 상태가 바뀌었는지 알아야 한다.

권장하는 상관관계 키는 다음과 같다.

  • 내부 request ID와 trace ID
  • agent와 설정 버전
  • session ID와 parent/subagent 관계
  • environment ID와 이미지 버전
  • tool call ID와 idempotency key
  • 외부 시스템의 transaction, job, commit, deployment ID
  • 사용자 승인 ID와 정책 결정 ID

대시보드에는 단순 성공률 외에도 도구별 거부율, 재시도 횟수, resume 이후 중복 행동, 사람 개입률, compaction 이후 제약 위반, environment 시작 실패, 오래 멈춘 session을 볼 수 있어야 한다. 비용은 사용자, 업무 유형, agent 버전, environment, tool 단위로 귀속할 수 있어야 개선 지점을 찾기 쉽다.

로그에는 비밀 값과 고객 원문을 가능한 한 넣지 않고, 필요한 경우 필드 단위 마스킹과 접근 통제를 적용한다. 디버깅 편의를 위해 모든 내용을 영구 저장하면 관찰 시스템 자체가 민감 데이터 저장소가 된다. 조사에 필요한 최소 메타데이터와 짧은 원문 보존, 별도 승인된 장기 감사 기록을 구분하는 편이 낫다.

OpenAI의 주장과 독립 검증을 섞지 말자

이번 글의 두 출처는 OpenAI의 발표와 OpenAI 개발 문서다. 따라서 출시 상태, 제공 엔터티, 지원 기능, 데이터 거주와 ZDR 제약을 설명하는 공식 1차 자료로는 유용하지만, 효과와 품질을 독립적으로 검증하는 자료는 아니다. 독자는 발표에 담긴 효과 주장과 고객 인용을 OpenAI의 공급자 주장으로 취급해야 한다.[1]

특히 자동 compaction이 중요한 제약을 얼마나 잘 보존하는지, tool search가 잘못된 도구 선택을 얼마나 줄이는지, subagent가 실제 업무 시간을 얼마나 단축하는지, recovery가 긴 작업에서 얼마나 안정적인지는 조직의 workload로 확인해야 한다. 이번에 허용된 출처 안에는 이를 독립적으로 재현한 비교 평가가 없다. 그러므로 “지원한다”와 “우리 환경에서 충분히 잘 동작한다”를 구분해야 한다.

검증 보고서는 다음 세 층을 분리해 작성하는 것이 좋다.

  • 공급자 문서 사실: 어떤 기능과 제약이 문서에 적혀 있는가
  • 내부 재현 결과: 어떤 입력, agent 버전, environment, 도구에서 무엇이 관찰됐는가
  • 운영 판단: 그 결과가 우리 위험 기준과 SLO를 충족하는가

이 구분이 없으면 제품 소개 문구가 곧바로 아키텍처 근거가 된다. 반대로 공급자 주장이라는 이유만으로 기능을 무시할 필요도 없다. 작은 pilot에서 실패 조건을 포함해 직접 검증하면 된다.

Build vs Buy: 무엇을 사는지부터 정의하라

관리형 harness의 build-vs-buy는 “API를 쓸까, 전부 직접 만들까”라는 이분법이 아니다. 실제로는 오케스트레이션, session store, compaction, 도구 gateway, sandbox, 정책, 관찰, 평가 가운데 어느 층을 구매하고 어느 층을 소유할지 결정하는 문제다.

OpenAI는 session, orchestration, compaction, recovery를 관리하는 경계를 제시한다.[2] 이를 구매하면 팀은 반복 루프와 상태 기계의 기본 구현 부담을 줄일 수 있다. 반면 공급자 데이터 모델, 이벤트 표현, 기능 변화, 지역성과 보존 제약에 의존하게 된다. 공개 베타라는 출시 상태도 변경 관리와 되돌리기 계획에 반영해야 한다.[1]

관리형 harness가 유리한 신호

  • 자체 harness가 아직 없고 제품 검증 속도가 중요하다.
  • 일반적인 도구 반복, session resume, subagent 패턴이 주된 요구다.
  • 관리형 데이터 처리 조건이 조직 정책과 맞는다.
  • 공급자 이벤트를 내부 관찰 체계에 연결할 수 있다.
  • 도구와 정책 계층은 별도로 소유할 준비가 돼 있다.
  • 특정 harness 동작을 세밀하게 수정할 필요가 적다.

직접 구축 또는 더 강한 추상화가 필요한 신호

  • 여러 모델 공급자를 실시간으로 교체해야 한다.
  • 오케스트레이션 상태 기계가 핵심 제품 차별점이다.
  • session과 이벤트를 지정 지역이나 자체 저장소에만 둬야 한다.
  • 독자적인 승인, replay, deterministic workflow 요구가 강하다.
  • 극단적으로 세밀한 스케줄링과 비용 통제가 필요하다.
  • 공급자 장애 시 진행 중 작업을 다른 harness에서 이어야 한다.

현실적인 접근은 얇은 애플리케이션 추상화를 두는 것이다. 내부 WorkItem, AgentPolicy, ToolInvocation, ExecutionEnvironment, Approval, Checkpoint 모델을 유지하고, Agents API의 식별자는 매핑 정보로 저장한다. 모든 공급자 기능을 최소 공통분모로 감추라는 뜻은 아니다. 핵심 업무 상태와 권한 정책을 공급자 객체에만 가두지 말라는 뜻이다.

가격 판단에서도 발표 문구를 정확히 읽어야 한다. OpenAI는 베타 기간에 별도 Agents API 요금은 없지만 모델, 도구, sandbox 사용에는 각각의 비용이 발생한다고 설명한다.[1] 이 정보만으로 총비용을 계산할 수는 없다. 호출 패턴, session 길이, compaction 전후 사용량, tool 반복, subagent fan-out, environment 실행 시간을 실제 pilot에서 계측해야 한다. 이 글은 지원되지 않은 단가나 절감률을 가정하지 않는다.

권장 도입 단계

처음부터 production 변경 권한을 주기보다 다음 순서로 경계를 넓히는 것이 안전하다.

1단계: 적합성 확인

  • 미국 데이터 거주와 ZDR 미지원 조건을 보안·법무·개인정보 담당자가 검토한다.[2]
  • 사용할 데이터 등급과 금지 데이터를 문서화한다.
  • hosted와 self-hosted environment의 책임 분담을 그린다.
  • session 삭제, 내부 로그 보존, 사용자 삭제 요청의 연결 방식을 정한다.
  • 공개 베타 기능 변경에 대비한 owner와 rollback 기준을 정한다.[1]

이 단계에서 정책과 맞지 않으면 기술 데모를 production 도입으로 밀어붙이지 않는다. 허용 가능한 비민감 workload만 별도로 정의할 수 있다.

2단계: 읽기 전용 pilot

문서 검색, 코드 탐색, 티켓 요약처럼 외부 상태를 바꾸지 않는 업무로 시작한다. 하나의 agent, 제한된 tool catalog, 짧은 session, 낮은 병렬성으로 구성한다. 이벤트와 내부 trace를 연결하고, 사람이 같은 결과를 재현할 수 있는지 확인한다.

평가 항목은 정답률만이 아니다. 잘못된 도구 선택, 권한 거부 후 행동, timeout 처리, compaction 이후 제약 보존, session resume의 연속성, 로그의 조사 가능성을 함께 본다.

3단계: 격리된 쓰기 작업

테스트 저장소나 staging 환경에서 상태 변경을 허용한다. 모든 변경 도구에 idempotency와 read-back 검증을 적용하고, dry-run과 승인 gate를 둔다. 실패 주입으로 네트워크 단절, 도구 timeout, 부분 성공, environment 종료, 중복 resume을 시험한다.

성공 기준은 에이전트가 정상 경로를 끝내는 것뿐 아니라, 비정상 경로에서 피해를 제한하고 조사 가능한 상태를 남기는 것이다.

4단계: 제한된 production

업무 유형과 사용자 그룹을 제한하고, 작은 권한 scope와 짧은 credential을 사용한다. 고위험 변경은 사람 승인을 유지한다. 세션별 시간, 호출, 도구, environment 자원 한도를 두고 초과 시 자동 중단한다. on-call이 session을 일시 정지하고, 권한을 회수하고, 외부 상태를 확인할 runbook을 준비한다.

5단계: 확대와 정기 재검증

agent 지침, 도구, 모델, harness 동작, environment 이미지가 바뀔 때 회귀 평가를 실행한다. subagent는 독립성이 높은 읽기 작업부터 추가한다. 업무별 성공률과 실패 비용을 비교해 관리형 harness에 남길 흐름과 별도 workflow로 옮길 흐름을 구분한다.

운영 도입 체크리스트

아키텍처와 경계

  • agent, environment, session, events/items를 내부 업무 객체와 매핑했다.
  • harness와 애플리케이션의 책임을 문서로 나눴다.
  • hosted/self-hosted 선택 기준과 라우팅 정책이 있다.
  • 핵심 업무 상태는 공급자 session에만 저장하지 않는다.
  • 공개 베타 변경에 대한 pinning, 회귀 테스트, rollback 계획이 있다.

데이터와 규정 준수

  • 미국 데이터 거주 조건을 허용할 수 있는지 확인했다.[2]
  • ZDR 미지원 조건을 확인했고 금지 workload를 차단했다.[2]
  • self-hosted sandbox가 API 전체를 ZDR로 만들지 않는다는 점을 반영했다.[2]
  • prompt, tool result, event, compaction summary의 데이터 흐름을 그렸다.
  • session 삭제와 내부 저장소 삭제 절차를 연결했다.
  • 로그의 마스킹, 접근 권한, 보존 기간을 정했다.

도구와 권한

  • tool catalog에 owner, 위험 등급, read/write 구분이 있다.
  • agent가 보는 도구와 실제 호출 가능한 도구를 분리했다.
  • tenant와 리소스 범위를 gateway에서 검증한다.
  • 변경 호출에 idempotency key와 read-back 검증이 있다.
  • 고위험 작업에 dry-run과 특정 입력에 묶인 승인이 있다.
  • credential은 짧은 수명과 최소 scope를 가진다.
  • MCP 연결도 동일한 정책과 감사 경계를 통과한다.

컨텍스트와 상태

  • compaction 이후에도 보존해야 할 불변 조건을 정의했다.
  • 승인, 외부 변경 ID, 완료 조건을 구조화해 별도 저장한다.
  • 원본 이벤트와 요약을 구분하고 source of truth를 정했다.
  • 긴 세션과 반복 compaction에 대한 회귀 평가가 있다.
  • session 경계가 하나의 승인 범위와 완료 조건에 맞는다.

Subagents

  • 부모와 하위 agent의 권한을 분리했다.
  • 하위 작업마다 시간, 호출, 비용, 도구 상한이 있다.
  • 읽기 병렬성과 쓰기 직렬화 원칙이 있다.
  • 결과에 근거, 미해결 항목, 검증 상태가 포함된다.
  • 동일 리소스 동시 수정에 잠금이나 버전 조건이 있다.

실패와 복구

  • 일시 오류, 권한 오류, 검증 오류, 충돌을 구분한다.
  • 요청 전송 후 결과 미확인 상태를 별도로 기록한다.
  • resume 전에 외부 부작용을 read-back한다.
  • 재시도 횟수와 backoff에 상한이 있다.
  • 보상 작업과 사람 개입 기준을 문서화했다.
  • 중단된 session과 고아 environment를 정리한다.
  • 장애 시 권한 회수와 강제 종료 runbook이 있다.

관찰과 평가

  • 내부 trace, session, tool call, 외부 transaction을 연결한다.
  • agent와 environment 버전을 기록한다.
  • 정책 허용·거부 이유와 사용자 승인을 기록한다.
  • 성공률뿐 아니라 중복 행동, 재시도, 사람 개입을 본다.
  • 정상 경로와 실패 주입 평가를 모두 실행한다.
  • 공급자 주장, 내부 재현 결과, 운영 판단을 보고서에서 구분한다.
  • 모델·도구·sandbox 사용 비용을 업무 단위로 귀속한다.

결론

OpenAI Agents API의 의미는 에이전트 애플리케이션에서 반복적으로 만들던 harness를 관리형 경계로 옮긴 데 있다. OpenAI는 session, orchestration, context compaction, recovery를 관리하고 애플리케이션이 tools와 environment를 선택하는 구조를 설명한다.[2] 이 경계가 잘 맞는 팀은 기본 실행 루프를 직접 유지하는 대신 업무 도구와 정책, 사용자 경험에 집중할 수 있다.

그러나 관리형 harness는 책임을 제거하지 않고 재배치한다. session은 업무 객체와 연결해야 하고, environment는 데이터와 네트워크 경계에 맞게 골라야 한다. compaction은 손실 정책으로 검증해야 하며, tools와 MCP는 최소 권한 gateway 뒤에 둬야 한다. subagents는 권한과 쓰기 충돌을 통제해야 하고, resume은 외부 부작용 확인과 함께 설계해야 한다. 미국 데이터 거주와 ZDR 미지원 제약은 self-hosted sandbox만으로 사라지지 않는다.[2]

도입 판단은 발표의 기능 목록보다 운영 질문에서 시작해야 한다. 중단된 작업을 안전하게 이어갈 수 있는가, 누가 어떤 권한으로 무엇을 바꿨는지 설명할 수 있는가, 요약이 중요한 조건을 잃지 않는가, 민감 데이터가 허용된 경계 안에 머무는가, 공급자를 바꿔도 핵심 업무 상태를 복구할 수 있는가를 물어야 한다.

Agents API가 이런 문제의 일부를 제품으로 제공한다는 것은 분명한 변화다. 다만 이번 출처는 모두 OpenAI 자료이므로 효과에 대한 독립 검증으로 읽어서는 안 된다. 작은 읽기 전용 pilot에서 시작해 실패를 주입하고, 권한과 데이터 경계를 확인하고, 내부 측정 결과로 확대 여부를 결정하는 것이 관리형 harness를 가장 현실적으로 평가하는 방법이다.

Sources

[1] https://openai.com/index/introducing-the-agents-api — Introducing the Agents API [2] https://developers.openai.com/api/docs/guides/agents-api/overview — Agents API overview