한 줄 정의

Agents SDK는 OpenAI 모델로 에이전트를 만들 때, 모델 호출만이 아니라 도구, 파일 작업, 상태, 추적, 샌드박스 실행까지 한 루프로 묶어 주는 개발자용 SDK야. 2026년 4월 15일 OpenAI 업데이트 기준으로는 파일을 읽고, 셸 명령을 실행하고, 코드를 고치고, 오래 걸리는 작업을 제어된 작업공간에서 이어 가는 쪽이 중심에 있어.

그래서 이 이름은 새 모델명보다 실행 하네스 이름에 가까워. OpenAI SDK가 API를 코드에서 부르기 쉽게 하는 클라이언트라면, Agents SDK는 그 위에서 에이전트가 어떤 도구를 쓰고, 어떤 작업공간에서 실행하고, 중간 상태를 어떻게 이어 갈지 조직하는 층이야.

실제로 무엇을 하나

가장 눈에 띄는 변화는 샌드박스야. OpenAI 글은 Agents SDK가 제어된 작업공간, 명시 지시문, 필요한 도구를 에이전트에게 주고, SandboxAgent, RunConfig, SandboxRunConfig 같은 구성으로 실행 환경을 묶는 Python 예시를 보여 줘. 설치 줄도 openai-agents>=0.14.0이라서, 이 업데이트를 읽을 때는 openai-agents>=0.14.0 조건을 같이 보면 좋아.

작업공간은 별도 설명 객체로 잡아. 여기에는 입력 파일, 출력 디렉터리, 객체 저장소에서 가져오는 데이터가 들어가고, 모델은 어디서 파일을 읽고 어디에 결과를 써야 하는지 더 예측 가능하게 알 수 있어. OpenAI는 로컬 파일과 여러 클라우드 객체 저장소를 예로 들어.

샌드박스 공급자도 직접 고를 수 있어. OpenAI는 기본 지원 공급자를 7개로 적었고, 공급자 문서들은 에이전트가 격리된 환경에서 파일을 편집하고 셸 명령을 실행하며, 미리보기 URL과 결과물을 남기고, 여러 샌드박스를 병렬로 돌리는 장면을 보여 줘. Vercel 가이드는 sales.csv 파일을 넣고 Shell() 권한을 준 에이전트가 마이크로VM 안에서 cat이나 awk 같은 명령으로 답을 만드는 흐름을 보여 줘.

왜 중요한가

Agents SDK가 중요한 이유는 agentic-coding과 업무 자동화의 질문을 바꾸기 때문이야. 예전에는 “모델이 답을 잘 쓰나”가 중심이었다면, 여기서는 “모델이 안전한 작업공간에서 파일과 명령을 다룰 수 있나”, “실패한 샌드박스를 새 컨테이너에서 이어 갈 수 있나”, “도구 권한과 로그를 어디서 잡나”가 같이 따라와.

비슷한 이름과 비교하면 차이가 더 잘 보여. Responses API는 OpenAI API 안에서 응답, 도구 호출, 상태를 다루는 인터페이스야. Agents SDK는 그 인터페이스와 모델을 써서 실제 에이전트 객체, 실행 설정, 도구 권한, 샌드박스 클라이언트를 코드로 엮는 쪽에 가까워. MCP나 Codex식 파일 도구가 언급될 때도, 그건 Agents SDK가 여러 실행 부품을 한 하네스 안에 묶는다는 뜻으로 읽으면 덜 헷갈려.

실무 장면은 두 가지가 선명해. 하나는 데이터룸, CSV, 리포지토리처럼 파일이 있는 작업이야. 에이전트가 파일을 직접 읽고 셸 명령을 돌려 결과를 만들면 단순 챗봇보다 작업 범위가 넓어져. 다른 하나는 웹 페이지 생성, 코드 리뷰, 데이터 과학 작업처럼 결과물을 실행해 보고 사람이 검토해야 하는 작업이야. 이때 샌드박스는 결과물을 바로 배포하는 곳이 아니라, 먼저 실행하고 확인하는 격리된 작업대에 가까워.

주의해서 볼 점

첫째, 샌드박스가 있다고 보안이 끝나는 건 아니야. OpenAI 글은 에이전트 시스템을 prompt-injection과 데이터 유출 시도를 전제로 설계해야 한다고 말해. 하네스와 compute를 분리하는 이유도 모델이 생성한 코드가 실행되는 환경에 자격 증명을 넣지 않기 위해서야. Vercel 쪽은 외부 통신을 특정 도메인으로 제한하는 egress control을 별도 장점으로 적어.

둘째, Python과 TypeScript 상태를 섞으면 안 돼. OpenAI는 새 하네스와 샌드박스 기능이 Python에서 먼저 나온다고 설명하고, TypeScript 지원은 이후 계획으로 둬. 샌드박스 공급자 문서도 현재 지원 범위를 Python Agents SDK 쪽으로 적었어. 문서에서 Agents SDK라는 이름만 봤다고 모든 언어용 SDK가 같은 기능을 갖췄다고 보면 금방 틀어져.

셋째, 비용과 실행 조건은 OpenAI API와 샌드박스 공급자를 나눠 봐야 해.

  • OpenAI API 쪽: OpenAI는 새 Agents SDK 기능이 표준 API 가격, 토큰, 도구 사용 기준을 따른다고 설명해.
  • 공급자 계정 쪽: 샌드박스 공급자 문서는 공급자 계정과 OpenAI API 계정을 따로 요구할 수 있다고 적어.
  • 실행 시간 쪽: Vercel 가이드는 샌드박스 기본 유지 시간을 270초로 설명해.
  • 실행 환경 쪽: 같은 가이드는 python3.12나 node22 같은 실행 환경, 2 vCPU가 4GB 메모리에 해당하는 리소스 설정, 공개 HTTPS 포트 노출을 따로 다뤄.

SDK가 한 줄로 보인다고 운영 조건까지 한 줄이 되는 건 아니야.