OpenAI Agents SDK

이 문서는 자라는 중인 질문입니다. 아직 증거를 모으고 있으며, 내용이 바뀔 수 있습니다.

OpenAI Agents SDK는 “모델을 한 번 호출한다”와 “에이전트가 여러 단계를 거쳐 일을 끝낸다” 사이의 빈칸을 메우려는 도구야. 단순한 답변 생성만 필요하면 모델 API를 직접 부르면 돼. 하지만 도구를 실행하고, 그 결과를 다시 모델에 넣고, 다른 에이전트에게 넘기고, 중간 기록을 추적해야 하면 실행 구조가 따로 필요해져.

그래서 이 SDK를 볼 때 중요한 질문은 기능 목록이 아니야. OpenAI가 에이전트 실행에서 어느 부분을 런타임으로 묶고, 어느 부분은 개발자 코드가 직접 판단하게 두는지야. 그 경계가 앞으로 agent loop와 컨텍스트 엔지니어링을 실제 제품에 옮길 때 비교 기준이 된다.

한 줄로 말하면

OpenAI Agents SDK는 OpenAI 모델 호출 위에 도구 실행, 여러 에이전트 조정, guardrail, session, tracing을 얹어 agentic app을 만들게 하는 Python 중심 런타임이야.

무엇인가

OpenAI 문서는 Agents SDK를 agentic AI app을 만들기 위한 가벼운 패키지라고 설명해. 핵심 primitive는 도구와 instructions를 가진 Agent, 다른 agent에게 일을 넘기는 agents as tools와 handoff, 그리고 입력과 출력을 검증하는 guardrail이야.¹

이 SDK의 위치는 Responses API 바로 위야. OpenAI 모델을 쓸 때 기본적으로 Responses API를 쓰지만, 그 위에 더 높은 수준의 실행 runtime을 더한다고 설명돼. Responses API를 직접 쓰면 loop, tool dispatch, state handling을 애플리케이션이 직접 소유한다. Agents SDK를 쓰면 turns, tool execution, guardrails, handoffs, sessions 같은 반복 실행 요소를 runtime에 맡기는 쪽으로 간다.¹

여기서 SDK는 “프롬프트 템플릿 묶음”보다 넓고, LangGraph 같은 낮은 수준 그래프 런타임과는 결이 달라. OpenAI 모델과 가까운 경로에서 agent loop를 빠르게 만들고, 필요하면 Python 코드로 조정하는 쪽에 가깝다.

왜 계속 등장하는가

에이전트 개발의 어려운 부분은 첫 응답이 아니라 두 번째 행동부터야. 도구 결과를 어떻게 다시 읽을지, 실패하면 어디까지 되돌아갈지, 다른 역할의 agent에게 무엇을 넘길지, 실행 기록을 어디서 볼지가 문제가 된다.

OpenAI Agents SDK는 이 문제를 “적은 primitive”로 묶으려 해. 문서는 내장 agent loop가 tool invocation을 처리하고, 결과를 LLM에 되돌려 보내며, task가 끝날 때까지 계속한다고 설명해.¹ 이 말은 agent loop가 추상 개념에서 개발자가 가져다 쓰는 runtime 기능으로 내려온다는 뜻이야.

또 하나의 이유는 비교 기준이 생기기 때문이야. Claude Agent SDK, LangGraph, Microsoft 계열 agent runtime, A2A protocol은 모두 “에이전트”라는 같은 단어를 쓰지만 맡는 층이 달라. OpenAI Agents SDK는 그중에서도 모델 제공사가 직접 제공하는 agent runtime이라는 점에서 계속 같이 놓고 봐야 해.

이 대상을 볼 때의 핵심 축

첫 번째 축은 loop 소유권이야. 짧은 작업이면 Responses API를 직접 써도 된다. 반대로 여러 turn, 도구 실행, session, handoff가 필요한 일이라면 SDK가 runtime을 맡는 편이 자연스러워진다.

두 번째 축은 handoff와 agents as tools의 경계야. 여러 agent가 함께 움직일 때 단순 함수 호출처럼 쓰는지, 아예 다른 agent에게 업무 책임을 넘기는지에 따라 multi-agent collaboration의 모양이 달라져.

세 번째 축은 session과 context야. 작업이 길어질수록 무엇을 다음 호출의 맥락으로 남길지 결정해야 해. SDK의 session 기능은 이 문제를 runtime 기능으로 다루는 지점이야.

네 번째 축은 검증과 관측이야. guardrail은 입력과 출력을 검사하는 층이고, tracing은 agentic flow를 시각화하고 디버깅하는 층이야. 에이전트가 실제 업무에 들어가면 실행이 맞았는지 보는 장치가 모델 성능만큼 중요해져.

flowchart TD
    A["목표와 입력"] --> B["Agent instructions와 tools"]
    B --> C["Runner 실행"]
    C --> D["도구 호출과 결과 반영"]
    D --> E{"끝났나?"}
    E -->|"아니오"| C
    E -->|"다른 역할 필요"| F["Handoff 또는 agent-as-tool"]
    F --> C
    E -->|"완료"| G["최종 결과"]
    H["Guardrails"] -.-> C
    I["Sessions"] -.-> C
    J["Tracing"] -.-> C

최근 관찰된 신호

OpenAI 문서는 Agents SDK를 Swarm 이후의 production-ready upgrade라고 부른다.¹ 실험용 패턴에서 출발한 agent orchestration이, 이제 모델 호출 API 옆의 정식 개발 경로로 굳어지는 신호로 볼 수 있어.

기능 범위도 단순한 tool calling에 머물지 않아. 문서에는 built-in agent loop, Python-first orchestration, agents as tools와 handoff, sandbox agents, guardrails, function tools, MCP server tool calling, sessions, human-in-the-loop, tracing, realtime agents가 함께 놓여 있어.¹ 이 묶음은 에이전트 제품화의 관심사가 “답을 잘 생성하는가”에서 “상태, 권한, 검증, 관측을 어떻게 묶는가”로 옮겨가고 있다는 신호야.

다만 아직 이 페이지는 seed로 두는 게 맞아. 공식 문서의 큰 구조는 잡혔지만, 버전 변화, production case, sandbox agents의 실제 경계, 다른 runtime과의 비교는 더 읽어야 한다.

헷갈리지 말아야 할 점

OpenAI Agents SDK는 OpenAI 모델 자체와 같은 말이 아니야. 모델은 추론을 하고, SDK는 그 추론을 도구, 상태, handoff, 검증, 관측과 엮는 실행 계층에 가까워.

또 SDK를 쓴다고 agentic workflow 설계가 자동으로 끝나는 것도 아니야. 어떤 도구를 허용할지, 어떤 실패는 멈출지, 어떤 단계는 사람에게 넘길지, 어떤 기록을 남길지는 여전히 제품과 업무 쪽의 판단이야.

마지막으로, Responses API와 Agents SDK는 둘 중 하나를 영원히 고르는 문제가 아니야. OpenAI 문서도 많은 애플리케이션이 관리되는 workflow에는 SDK를 쓰고, 낮은 수준 경로에는 Responses API를 직접 호출할 수 있다고 설명해.¹ 같은 제품 안에서도 두 경로가 함께 존재할 수 있다는 뜻이야.

이어서 읽기

에이전트가 결과를 보고 다음 행동을 고르는 기본 반복은 agent loop에서 먼저 보면 돼. 다음 호출에 무엇을 남길지의 문제는 컨텍스트 엔지니어링과 바로 이어져.

여러 agent가 역할을 나누는 구조는 multi-agent collaboration이 설명해. 상태 있는 그래프 런타임과 비교하려면 LangGraph, Anthropic 쪽 SDK와 비교하려면 Claude Agent SDK, 서로 다른 agent 사이의 통신층은 A2A protocol을 같이 보면 좋아.

남은 질문들

• OpenAI Agents SDK의 Runner와 RunState는 실패, 중단, 재개, 사람 개입을 어떤 상태 모델로 표현할까?
• handoff와 agents as tools는 실제 업무 설계에서 어디서 갈라지고, 어떤 정보를 넘길 때 디버깅이 쉬워질까?
• session은 단순 대화 기록과 어떻게 다르고, 긴 작업에서 어떤 기록을 저장하거나 버리게 할까?
• sandbox agents는 코드·문서·파일 작업에서 일반 tool execution과 어떤 권한 경계를 만들까?
• LangGraph, Claude Agent SDK, Microsoft Agent Framework와 비교하면 OpenAI Agents SDK의 추상화 비용과 장점은 어디서 갈릴까?

각주

1. OpenAI, 「OpenAI Agents SDK」(2026-07-12 캡처) 공식 문서 ↩︎ ↩︎² ↩︎³ ↩︎⁴ ↩︎⁵ ↩︎⁶