OpenAI Agents SDK 업데이트 핵심: 장기 실행 AI 에이전트는 어떻게 복구하고 확장할까

 

OpenAI Agents SDK 업데이트 핵심: 하네스와 샌드박스 분리로 보는 장기 실행 에이전트

파일 작업, 명령 실행, 상태 복구가 필요한 에이전트를 만들 때 무엇을 확인해야 하는지 정리했습니다.

 

OpenAI Agents SDK 업데이트에서 먼저 볼 것은 복구 구조입니다

 

이번 OpenAI Agents SDK 업데이트의 실질적 의미는 에이전트가 오래 걸리는 파일 작업과 명령 실행을 하다가 멈춰도, 상태를 분리해 다시 이어갈 구조를 제시했다는 점입니다. 2026년 5월 28일 OpenAI Build Hour 안내도 같은 Agents SDK와 model-native harness 흐름을 다시 전면에 둡니다.

AI 에이전트를 직접 만들어본 사람이라면 모델 호출보다 먼저 막히는 지점이 있습니다. 파일을 어디에 둘지, 명령 실행을 어디까지 허용할지, 작업이 중간에 끊기면 어디서 다시 시작할지가 생각보다 어렵습니다.

OpenAI가 2026년 4월 15일 공개한 Agents SDK 관련 글은 이 운영 문제를 정면으로 다룹니다. 발표의 중심은 단순히 SDK 함수가 늘었다는 이야기가 아니라, 하네스와 샌드박스 컴퓨트를 나눠 장기 실행 에이전트를 운영하는 방식입니다.

한국 사용자 입장에서는 이 업데이트를 “내 자동화 봇에 당장 넣을 기능”으로만 보면 놓치는 부분이 있습니다. 더 중요한 질문은 이것입니다. 내 에이전트가 저장소를 읽고, 테스트를 실행하고, 결과 파일을 만들고, 승인 대기 뒤 다시 이어가야 한다면 어떤 런타임 구조가 필요한가입니다.

그래서 OpenAI Agents SDK 업데이트는 뉴스 요약보다 도입 판단 기준으로 읽는 편이 낫습니다. model-native harness, sandbox, RunState, session state, snapshot, rehydration이 각각 무엇을 맡는지 구분해야 Python 첫 테스트와 Responses API 직접 사용 여부도 덜 헷갈립니다.

 

 

4월 발표와 5월 문서 상태를 나눠 봐야 합니다

 

2026년 4월 15일 발표는 updated Agents SDK, model-native harness, native sandbox execution, Python-first 출시 흐름을 설명했습니다. 2026년 5월 28일 현재 문서는 Python과 TypeScript SDK 문서, 그리고 sandbox agents의 beta 표현을 별도로 확인해야 합니다.

날짜를 먼저 나누는 편이 안전합니다. 4월 발표문은 새로운 Agents SDK 기능이 API를 통해 일반 제공된다고 설명하면서도, 새 하네스와 샌드박스 기능은 Python에서 먼저 시작하고 TypeScript 지원은 이후 계획으로 언급했습니다.

반면 2026년 5월 28일 기준으로 확인된 OpenAI 문서에는 sandbox agents 관련 Python/TypeScript 문서가 함께 존재합니다. 동시에 현재 sandbox 문서는 beta 표기를 포함합니다. 그래서 “TypeScript가 4월 발표 당시에 이미 같은 상태로 출시됐다”거나 “모든 샌드박스 기능이 완전히 성숙한 프로덕션 기능이다”라고 쓰면 정확하지 않습니다.

제가 보기에는 이 차이를 나눠 보는 일이 실무적으로 중요합니다. 발표문은 방향과 아키텍처를 설명하는 자료이고, 현재 문서는 실제 설치, SDK 언어, 베타 여부, provider 설정을 확인하는 자료입니다. 블로그나 내부 검토 문서에서 둘을 섞으면 도입 범위가 부풀려집니다.

구분	확인할 내용	실무 의미
2026-04-15 발표	model-native harness, native sandbox execution, Python-first, snapshot/rehydration	OpenAI가 제시한 아키텍처 방향
2026-05-28 현재 문서	sandbox agents 문서, Python/TypeScript SDK 문서, beta 표기	실제 구현 전에 다시 확인할 현재 상태
Build Hour	updated Agents SDK와 long-running agents 주제 강조	지금 다시 살펴볼 만한 시의성

 

model-native harness란 무엇인가

 

model-native harness는 모델 호출, 도구 라우팅, 승인, 추적, 실행 상태를 다루는 제어 계층입니다. 샌드박스가 실제 파일과 명령이 실행되는 공간이라면, 하네스는 그 실행을 어떻게 시키고 어디서 이어갈지 조율하는 쪽입니다.

하네스라는 말이 낯설 수 있지만, 에이전트 개발에서는 매우 현실적인 개념입니다. 모델에게 “이 저장소를 고쳐라”라고 지시하는 순간, 모델 호출만으로는 부족합니다. 어떤 파일을 읽게 할지, 어떤 명령을 실행하게 할지, 실패한 명령을 어떻게 기록할지, 사람이 승인해야 하는 단계는 어디인지가 필요합니다.

OpenAI의 설명에서 model-native harness는 이런 작업을 프런티어 모델의 작업 방식에 맞춘 제어 계층으로 다룹니다. 파일 시스템 도구, shell 실행, apply-patch 방식의 파일 편집, MCP 도구 사용, skills, AGENTS.md 스타일의 지시문 같은 구성요소가 함께 언급되는 이유도 여기에 있습니다.

개인 블로그 독자에게 더 쉽게 말하면, 하네스는 “에이전트에게 컴퓨터를 쥐여주는 방식”을 관리합니다. 단, 무제한으로 쥐여주는 것이 아니라 도구, 상태, 승인, 추적을 제어하면서 실행 공간과 분리합니다.

> 중요한 변화는 모델이 더 똑똑해졌다는 말보다, 모델이 오래 일할 수 있도록 작업대와 관제석을 분리했다는 점입니다.

 

 

하네스와 샌드박스를 분리하는 이유

 

분리의 목적은 보안, 복구성, 확장성입니다. credentials, billing, audit, human review, RunState는 신뢰할 수 있는 하네스 쪽에 두고, 모델이 지시하는 파일 읽기와 명령 실행은 제한된 샌드박스에서 처리합니다.

AI 에이전트가 코드를 실행하고 파일을 수정한다면, 가장 피해야 할 구조는 모든 권한과 모든 상태를 같은 실행 공간에 넣는 방식입니다. 모델이 잘못된 명령을 실행하거나 프롬프트 인젝션성 입력을 만났을 때, 자격 증명과 감사 로그까지 같은 공간에 있으면 피해 범위가 커집니다.

OpenAI 문서는 하네스와 컴퓨트를 나눠 보는 접근을 제시합니다. 하네스는 모델 호출, 도구 실행 제어, 상태, 승인, 추적을 맡고, 샌드박스는 파일, 명령, 패키지, 포트, 작업 산출물이 놓이는 실행 공간이 됩니다.

실제로 확인할 부분은 “샌드박스를 쓰면 안전하다”가 아닙니다. 더 정확한 문장은 “샌드박스를 쓰면 위험한 실행을 별도 경계 안에 둘 수 있고, 자격 증명과 복구 상태를 하네스 쪽에서 관리할 설계 여지가 생긴다”입니다.

또 하나의 장점은 provider 교체 가능성입니다. OpenAI 발표는 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel 같은 sandbox provider와 BYO sandbox 가능성을 언급합니다. 다만 각 provider의 격리, 저장소, preview, persistence, 비용 정책은 provider별 문서로 다시 확인해야 합니다.

 

장기 실행 에이전트가 실패 후 이어서 작업하려면

 

장기 실행 에이전트는 컨테이너를 오래 켜두는 것만으로 충분하지 않습니다. RunState, sandbox session state, snapshot을 구분해 저장해야 만료, 장애, 승인 대기 뒤에도 작업을 이어갈 수 있습니다.

OpenAI Agents SDK 업데이트에서 가장 실용적인 부분은 복구 상태를 나눠 설명한다는 점입니다. 에이전트가 저장소를 분석하다가 테스트를 실행하고, 중간 결과 파일을 만들고, 사용자의 승인까지 기다린다면 한 번의 API 호출 안에서 끝나지 않습니다.

여기서 세 가지 상태를 구분해야 합니다.

상태	어디에 가까운가	복구할 때의 역할
`RunState`	하네스 측 진행 상태	모델/도구 호출 흐름과 에이전트 실행 진행을 이어가는 데 필요
sandbox session state	provider 세션 연결 정보	같은 sandbox 세션에 다시 붙을 때 필요
`snapshot`	저장된 workspace 내용	새 sandbox를 이전 작업 파일 상태로 시작할 때 필요

이 구분은 작지만 중요합니다. 예를 들어 snapshot은 작업 디렉터리의 파일 상태를 살리는 데 도움을 주지만, mounted remote storage까지 그대로 복사한다는 뜻은 아닙니다. current docs 기준으로 remote storage mount는 snapshot과 persistence 흐름에서 별도 주의가 필요합니다.

제가 보기에는 이 구조가 장기 실행 에이전트의 최소 운영 언어가 될 가능성이 큽니다. “에이전트가 중간에 죽었나요?”보다 더 좋은 질문은 “어떤 상태가 사라졌고, 어느 상태로 이어갈 수 있나요?”입니다.

 

 

 

Python 설치와 첫 테스트는 작게 시작하는 편이 낫습니다

 

가장 작은 검증은 Python 3.10 이상 환경에서 `pip install openai-agents`로 시작하고, 로컬 개발에서는 `UnixLocalSandboxClient`로 작은 파일 요약 또는 비교 작업을 실행하는 것입니다. Docker 격리가 필요하면 `pip install "openai-agents[docker]"` 경로를 따로 확인합니다.

처음부터 hosted sandbox provider, 장기 실행 복구, 외부 저장소 mount까지 한 번에 붙이면 어디서 실패했는지 알기 어렵습니다. OpenAI Agents SDK 업데이트를 실험할 때는 “파일을 넣고, 에이전트가 읽고, 결과를 파일명과 함께 설명한다” 정도의 작은 proof-of-work가 좋습니다.

Python 기준 설치 경로는 비교적 명확합니다. `OPENAI_API_KEY`를 설정한 뒤, Python 3.10 이상에서 `pip install openai-agents`를 설치합니다. sandbox quickstart에서는 로컬 개발 출발점으로 `UnixLocalSandboxClient`를 확인할 수 있고, Docker 기반 격리가 필요할 때는 `pip install "openai-agents[docker]"`를 별도 경로로 봅니다.

추천하는 첫 테스트는 이렇습니다.

• 임시 workspace에 `note-a.md`, `note-b.md` 같은 작은 파일 2개를 둡니다.
• `Manifest`에 로컬 파일 또는 디렉터리와 출력 디렉터리를 정의합니다.
• `SandboxAgent`가 두 파일의 차이를 요약하고 `summary.md`를 만들게 합니다.
• 실행 뒤 결과 파일이 생겼는지, 출처 파일명을 섞지 않았는지, 실패 시 로그가 남는지 확인합니다.

이 정도가 통과하면 그다음에 Docker, provider sandbox, MCP 도구, AGENTS.md 스타일 지시, tracing/evals를 붙일 차례입니다. 순서를 작게 가져가야 오류가 모델 문제인지, sandbox 문제인지, Manifest 문제인지 구분됩니다.

 

실무 도입 시뮬레이션: 무엇을 먼저 정해야 하나

 

도입 전에는 어떤 작업을 sandbox에 맡길지, 어떤 상태를 하네스에 저장할지, 어떤 provider 비용과 보안 경계를 검토할지 정해야 합니다. 짧은 응답만 필요한 워크플로라면 Agents SDK보다 Responses API 직접 호출이 더 단순할 수 있습니다.

실무 도입은 “설치했습니다”에서 끝나지 않습니다. 특히 장기 실행 에이전트는 운영 모델을 먼저 정해야 합니다. 하네스는 control plane, sandbox는 execution plane이라는 구분을 팀 문서에 명확히 적어두는 것이 좋습니다.

제가 권하는 순서는 단순합니다.

1. 작업 범위: 저장소 분석, 테스트 실행, 문서 패킷 요약, 보고서 생성처럼 파일과 명령이 필요한 업무인지 확인합니다.
2. 상태 설계: `RunState`, provider session state, `snapshot` 중 무엇을 저장해야 실제로 이어갈 수 있는지 정합니다.
3. Manifest 계약: 입력 파일, output directory, remote storage mount, user/group, environment를 fresh-session 기준으로 정의합니다.
4. 보안 경계: secrets는 prompt, generated artifact, committed manifest에 두지 않고 provider-native secret이나 제한된 cloud storage credential을 씁니다.
5. 관측과 평가: sandbox를 늘리기 전에 tracing과 evals로 실패 패턴을 봅니다.

현재 대안과 비교하면 판단이 쉬워집니다. 단발성 챗봇 응답, 짧은 분류, 간단한 요약은 Responses API 직접 호출이 더 단순합니다. 반대로 파일을 읽고 쓰며, 테스트를 실행하고, 승인을 기다렸다가 다시 이어가는 workflow라면 Agents SDK의 하네스와 샌드박스 구조가 의미를 갖습니다.

한국 개발자에게는 특히 비용 경계가 중요합니다. OpenAI 발표는 표준 API 가격이 토큰과 tool use 기준이라고 설명하지만, sandbox provider의 compute, storage, preview, persistence 비용은 별도로 발생할 수 있습니다. 내부 자동화로 확장하기 전에는 provider별 비용과 데이터 보관 정책을 따로 봐야 합니다.

 

 

 

주의할 점: beta, TypeScript, 비용, 보안을 단정하지 말기

 

4월 발표의 GA 표현과 5월 현재 문서의 beta 표현은 날짜를 붙여 따로 설명해야 합니다. TypeScript, sandbox provider 비용, 보안 효과도 공식 문서 범위 밖으로 확대해 말하면 안 됩니다.

여기서 경계할 표현은 “이제 장기 실행 에이전트가 완전히 해결됐다”입니다. OpenAI Agents SDK 업데이트는 중요한 방향을 보여주지만, 실제 운영에서는 아직 확인할 것이 많습니다.

첫째, TypeScript 상태는 날짜 기준으로 말해야 합니다. 4월 발표는 Python-first와 향후 TypeScript 계획을 언급했고, 5월 28일 현재 문서에서는 TypeScript SDK 문서가 확인됩니다. 이 둘을 같은 출시 문장으로 합치면 오해가 생깁니다.

둘째, sandbox는 보안 경계를 만드는 도구이지 보안 검토의 대체물이 아닙니다. prompt injection, data exfiltration, egress control, secret handling은 별도로 점검해야 합니다. 특히 customer data, 사내 저장소, cloud bucket을 mount하는 경우에는 provider isolation과 persistence 정책을 문서로 남겨야 합니다.

셋째, 비용은 OpenAI API 비용과 sandbox provider 비용을 나눠 봐야 합니다. 모델 토큰과 tool use 비용만 보고 장기 실행 에이전트를 설계하면, 실제 실행 시간, storage, preview, 네트워크 비용이 뒤늦게 나타날 수 있습니다.

마지막으로, snapshot이 모든 것을 백업해준다고 생각하면 안 됩니다. workspace 파일 상태와 외부 mount, provider session, harness run state는 서로 다른 문제입니다. 장기 실행 에이전트를 제대로 운영하려면 “복구됐다”는 말을 상태별로 쪼개서 검증해야 합니다.

 

자주 묻는 질문

 

Q. OpenAI Agents SDK의 model-native harness란 무엇인가?
A. 모델 호출, 도구 라우팅, 승인, 추적, 실행 상태를 조율하는 제어 계층입니다. 샌드박스가 파일과 명령을 실행하는 공간이라면, 하네스는 그 실행을 관리하고 이어가는 쪽입니다.

Q. 하네스와 샌드박스를 분리하는 이유는 무엇인가?
A. 자격 증명, 감사, 비용, 승인, 복구 상태를 신뢰할 수 있는 제어 계층에 두고, 모델이 지시하는 파일 작업과 명령 실행을 제한된 실행 공간으로 분리하기 위해서입니다.

Q. 장기 실행 에이전트는 실패 후 어떻게 이어서 작업하나?
A. `RunState`로 하네스 진행 상태를 다루고, provider session state로 기존 sandbox 세션에 다시 붙으며, `snapshot`으로 workspace 파일 상태를 새 sandbox에 복원하는 방식으로 나눠 봐야 합니다.

Q. Python에서 처음 테스트하려면 무엇이 필요한가?
A. Python 3.10 이상, `OPENAI_API_KEY`, `pip install openai-agents` 설치가 기본 출발점입니다. 로컬 sandbox 테스트는 `UnixLocalSandboxClient`로 작은 파일 요약 작업부터 확인하고, Docker 격리가 필요하면 `pip install "openai-agents[docker]"`를 검토합니다.

Q. TypeScript 지원은 어떻게 봐야 하나?
A. 2026년 4월 15일 발표는 Python-first와 TypeScript 향후 계획을 말했습니다. 2026년 5월 28일 현재 문서에서는 TypeScript SDK 문서가 확인되지만, sandbox agents의 beta 표기도 함께 확인해야 합니다.

Q. Agents SDK와 Responses API 중 무엇을 선택해야 하나?
A. 짧은 응답, 단순 분류, 일회성 요약이면 Responses API 직접 호출이 더 단순합니다. 파일, 명령, 도구 루프, 승인, 세션, sandbox workspace, durable state가 필요하면 Agents SDK를 검토할 이유가 생깁니다.

함께 읽으면 좋은 글

 

• Claude 에이전트 보안 설계: Anthropic이 말한 샌드박스와 egress control — AI UPDATES
• Gemini Interactions API 변경: steps 스키마 전환 체크리스트 — AI UPDATES
• Spring AI 1.0.8·1.1.7·2.0.0-M7 릴리스: MCP와 Gemini 연동 변경점 — AI UPDATES

참조 링크

 

• The next evolution of the Agents SDK — updated Agents SDK, model-native harness, native sandbox execution, snapshotting, rehydration의 원문 업데이트
• OpenAI for Startups — 2026년 5월 28일 Build Hour: Agents SDK 안내와 시의성 근거
• Build Hour: Agents SDK — OpenAI Startups 페이지에서 연결된 공식 이벤트 페이지
• Agents SDK - OpenAI API docs — SDK 선택 기준, orchestration, tool execution, state, approvals, MCP, product infrastructure integration 확인
• Sandbox Agents - OpenAI API docs — sandbox architecture, RunState, session state, snapshot, provider caveats, beta 표현 확인
• OpenAI Agents SDK Python docs — Python SDK 설치와 기본 사용 경로 확인
• Sandbox agents quickstart - OpenAI Agents SDK Python — Python 3.10 이상, UnixLocalSandboxClient, Docker extras, sandbox agent 첫 테스트 근거
• OpenAI Agents SDK TypeScript docs — 2026년 5월 28일 현재 TypeScript SDK 문서 상태를 날짜 기준으로 확인하기 위한 보조 출처