OpenAI Agents SDK (이전 명칭 Swarm, 2026년 초 안정 버전으로 출시)는 멀티 에이전트 (multi-agent) AI 시스템을 구축하기 위한 Python 라이브러리입니다. LangChain의 추상화 중심적인 접근 방식이나 CrewAI의 역할 수행 (role-playing) 모델과 달리, Agents SDK는 5가지의 깔끔한 기본 요소 (primitives)를 노출하며 불필요한 간섭을 하지 않습니다.

이 가이드는 핸드오프 (handoffs), 가드레일 (guardrails), 세션 (sessions), 트레이싱 (tracing)을 포함하여 설정부터 프로덕션 배포까지의 모든 과정을 다룹니다.

설치 및 설정

pip install openai-agents

Python 3.10 이상이 필요합니다. API 키를 설정하세요:

export OPENAI_API_KEY=sk-...

이 SDK는 LiteLLM을 통해 OpenAI가 아닌 모델과도 작동합니다 — 이에 대해서는 나중에 더 자세히 다루겠습니다.

5가지 핵심 기본 요소 (Core Primitives)

Agent      → LLM + 시스템 지침 (system instructions) + 도구 (tools) + 핸드오프 (handoffs)
Runner     → 에이전트 루프를 실행 (동기 또는 비동기)
Tools      → 에이전트가 호출할 수 있는 Python 함수
...

첫 번째 에이전트 만들기

from agents import Agent, Runner

agent = Agent(
...

Runner.run_sync()는 블로킹 (blocking) 버전입니다. 비동기 컨텍스트에서는 await Runner.run()을 사용하세요.

도구 (Tools): 에이전트의 능력 확장하기

@function_tool 데코레이터는 모든 Python 함수를 에이전트가 호출할 수 있는 도구로 변환합니다. 독스트링 (docstring)은 도구의 설명이 되므로 명확하게 작성해야 합니다:

from agents import Agent, Runner, function_tool
import subprocess
import os
...

에이전트가 언제 도구를 호출할지 결정하며, 사용자가 시퀀스를 오케스트레이션 (orchestrate)하지 않습니다. SDK는 에이전트가 최종 응답을 반환할 때까지 도구 호출 루프를 처리합니다.

내장 도구 (Built-in Tools)

from agents.tools import WebSearchTool, CodeInterpreterTool

research_agent = Agent(
...

WebSearchTool은 OpenAI의 내장 검색을 사용합니다. CodeInterpreterTool은 샌드박스 (sandbox) 내에서 Python을 실행하며, 보안 문제 없이 데이터 분석을 수행하는 데 유용합니다.

핸드오프 (Handoffs): 멀티 에이전트 시스템

가장 강력한 기능입니다. 에이전트가 handoff()를 호출하면, 전체 컨텍스트 (context)를 유지한 채 대화를 전문 에이전트에게 전달합니다:

from agents import Agent, Runner, handoff

typescript_expert = Agent(
...

코디네이터(coordinator)는 security_reviewer (SQL 인젝션), typescript_expert (타입이 지정되지 않은 id), 그리고 잠재적으로 performance_analyst (SELECT * 비효율성)로 경로를 라우팅합니다. 각 전문가(specialist)는 전체 대화 기록(conversation history)을 바탕으로 검토를 수행합니다.

타입이 지정된 핸드오프 (Typed Handoffs)

에이전트 간에 구조화된 데이터(structured data)를 전달합니다:

from pydantic import BaseModel

class BugReport(BaseModel):
...

가드레일 (Guardrails): 안전 및 검증

가드레일(Guardrails)은 에이전트가 입력을 처리하기 전 또는 출력을 생성한 후에 실행됩니다. 가드레일은 요청을 차단(block), 수정(modify) 또는 허용(allow)할 수 있습니다:

from agents import Agent, Runner, input_guardrail, output_guardrail, GuardrailTripwireTriggered, RunContextWrapper
from agents.guardrails import GuardrailFunctionOutput

...

가드레일은 에이전트와 병렬로 실행되므로 지연 시간(latency)을 추가하지 않습니다. tripwire_triggered=True 응답은 즉시 처리를 중단합니다.

구조화된 출력 (Structured Output)

에이전트가 특정 Pydantic 모델을 반환하도록 강제합니다:

from pydantic import BaseModel
from typing import Literal

...

SDK는 내부적으로 JSON 스키마(JSON schema)를 사용하여 모델 출력을 제한합니다. 파싱(parsing), json.loads(), 또는 잘못된 형식의 JSON에 대한 에러 처리(error handling)가 필요 없습니다.

세션 (Sessions): 지속적인 상태

세션(sessions)이 없으면 모든 Runner.run()은 새로 시작됩니다. 세션은 대화 기록(conversation history)을 유지합니다:

from agents import Agent, Runner
from agents.sessions import InMemorySession, SqliteSession

...

프로덕션 환경에서는 SqliteSession(포함됨)을 사용하거나 Redis/Postgres를 위해 Session 인터페이스를 구현하십시오:

from agents.sessions import SqliteSession

session = SqliteSession("./data/sessions.db")
...

트레이싱 및 관측 가능성 (Tracing and Observability)

import agents

# 단순 stdout 로깅
...

모든 도구 호출(tool call), 핸드오프(handoff), 가드레일 체크는 스팬(span)을 생성합니다. 에이전트가 무엇을 왜 했는지에 대한 완전한 가시성(visibility)을 확보할 수 있으며, 이는 멀티 에이전트 시스템(multi-agent systems)의 디버깅에 매우 중요합니다.

Non-OpenAI 모델 사용하기

SDK는 LiteLLM을 통해 모든 모델을 지원합니다:

from agents import Agent
from agents.models import LitellmModel

...

핸드오프 체인 (handoff chain) 내에서 모델을 혼합하여 사용할 수 있습니다. 추론 집약적인 작업에는 Claude를 사용하고, 단순한 라우팅 결정에는 GPT-4o-mini를 사용하십시오.

프로덕션 패턴: 지원 티켓 분류기 (Support Ticket Classifier)

프로덕션에서 실행 가능한 완전한 예시입니다:

from agents import Agent, Runner, handoff, function_tool
from agents.sessions import SqliteSession
from pydantic import BaseModel
...

Agents SDK vs LangGraph vs CrewAI

LangGraph는 결정론적 제어 흐름 (deterministic control flow)이 필요할 때, 즉 작업 순서가 명시적이고 예측 가능해야 할 때 유리합니다. Agents SDK는 에이전트가 스스로 라우팅 결정 (routing decisions)을 내리기를 원할 때 유리합니다.

프로덕션에서 작동하는 것들

여러 개의 Agents SDK 시스템을 구축한 결과, 몇 가지 패턴이 유효함을 확인했습니다:

지침(instructions)을 집중시키세요. 50개의 모호한 가이드라인을 가진 에이전트보다 10개의 명확한 규칙을 가진 에이전트가 더 나은 성능을 보입니다. 마치 신입 사원을 온보딩하는 것처럼 구체적이고, 완전하며, 모호하지 않게 지침을 작성하십시오.

가드레일 (Guardrails)은 선택 사항이 아닙니다. 내부 도구라 할지라도 입력값 검증 (input validation)이 필요합니다. 가드레일 없이 신뢰할 수 없는 사용자 입력을 처리하는 에이전트는 결국 예상치 못한 동작을 하게 될 것입니다.

세션에는 TTL (Time To Live)이 필요합니다. SqliteSession은 기본적으로 대화를 만료시키지 않습니다. 보유 정책 (retention policy)보다 오래된 세션을 제거하기 위한 정리 작업 (cleanup job)을 추가하십시오.

핸드오프 체인을 명시적으로 테스트하세요. 멀티 에이전트 시스템에서 가장 어려운 버그는 라우팅 실패 (routing failures)입니다. 즉, 코디네이터가 작업을 잘못된 전문가에게 보내거나 에이전트 간에 루프가 발생하는 경우입니다. 단순히 출력 품질뿐만 아니라 라우팅을 검증하는 통합 테스트 (integration tests)를 작성하십시오.

전체 기사는 stacknotice.com/blog/openai-agents-sdk-complete-guide-2026에서 확인하실 수 있습니다.