OpenAI Agents SDK가 뭐길래 지금 주목해야 하나

OpenAI Agents SDK는 OpenAI가 공식 릴리스한 경량 파이썬 라이브러리로, 에이전틱 AI 애플리케이션을 구축하기 위한 최소한의 추상화 집합을 제공합니다. 전신은 실험적 프로젝트였던 Swarm이지만, 2025년 초 프로덕션 준비 수준으로 전면 재설계된 뒤 현재는 TypeScript 버전도 지원하며 글로벌 기업들의 에이전트 인프라로 자리 잡고 있습니다.

다른 에이전트 프레임워크(LangChain, LangGraph, CrewAI 등)와 비교했을 때 Agents SDK의 핵심 철학은 명확합니다 — “기본 구성 요소를 최소화하되, 그 조합은 무한히 강력하게.” 에이전트(Agent), 핸드오프(Handoff), 가드레일(Guardrail) 세 가지만 제대로 이해하면 실제 서비스 수준의 자율 에이전트를 구현할 수 있습니다.

왜 지금 배워야 하는가

2026년 3월 현재, GPT-5.4를 포함한 최신 OpenAI 모델들은 기본적으로 에이전트형 동작(컴퓨터 사용, 웹 검색, 코드 실행)을 지원합니다. Agents SDK는 이 모든 기능을 프로그래밍 방식으로 제어하고 오케스트레이션할 수 있는 공식 경로입니다. 모델만 아는 것으로는 부족하고, SDK를 통해 에이전트를 설계하는 역량이 2026년 AI 개발자의 핵심 경쟁력이 됐습니다.

▲ 목차로 돌아가기

5분 설치부터 Hello World까지 — 첫 에이전트 만들기

OpenAI Agents SDK 설치는 단 한 줄입니다. Python 3.9 이상 환경에서 아래 명령어를 실행하면 모든 의존성이 함께 설치됩니다. 가상 환경을 먼저 만드는 것을 강력히 권장합니다 — 버전 충돌 없이 깔끔하게 관리할 수 있기 때문입니다.

# 가상환경 생성 및 활성화
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
# Agents SDK 설치
pip install openai-agents
# API 키 환경변수 설정
export OPENAI_API_KEY=sk-...  # Windows: set OPENAI_API_KEY=sk-...

가장 짧은 에이전트 코드 — 5줄

아래는 OpenAI 공식 문서의 Hello World 예제입니다. Agent와 Runner 두 클래스만 알면 첫 에이전트가 완성됩니다. instructions는 에이전트의 성격과 역할을 정의하는 시스템 프롬프트에 해당하며, 이 한 줄이 에이전트 품질의 80%를 결정합니다.

from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a helpful assistant"
)
result = Runner.run_sync(agent, "재귀에 관한 하이쿠를 한국어로 써줘.")
print(result.final_output)

비동기 방식으로 실행하기

실제 프로덕션에서는 Runner.run_sync 대신 비동기 방식인 await Runner.run()을 사용하는 것이 표준입니다. 여러 에이전트를 병렬로 실행하거나, FastAPI 같은 비동기 프레임워크에 통합할 때 반드시 필요한 패턴입니다.

import asyncio
from agents import Agent, Runner
agent = Agent(
name="History Tutor",
instructions="역사 질문에 명확하고 간결하게 답변합니다.",
)
async def main():
result = await Runner.run(agent, "로마 제국은 언제 멸망했나요?")
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())

▲ 목차로 돌아가기

에이전트에 도구(Tool) 붙이기 — 진짜 일 시키는 방법

단순히 텍스트를 생성하는 LLM과 에이전트의 결정적 차이는 바로 도구(Tool)입니다. Agents SDK에서 도구를 추가하는 방법은 매우 직관적입니다 — @function_tool 데코레이터를 일반 파이썬 함수에 붙이기만 하면, SDK가 자동으로 JSON 스키마를 생성하고 Pydantic 기반 유효성 검사를 처리합니다.

import asyncio
from agents import Agent, Runner, function_tool
@function_tool
def get_stock_price(ticker: str) -> str:
"""주식 티커 심볼로 현재 주가를 조회합니다."""
# 실제 환경에서는 금융 API 호출
prices = {"AAPL": "221.50", "NVDA": "875.00", "TSLA": "295.30"}
return prices.get(ticker.upper(), "데이터 없음")
@function_tool
def get_company_info(ticker: str) -> str:
"""주식 티커 심볼로 기업 기본 정보를 반환합니다."""
info = {
"AAPL": "Apple Inc. — 소비자 전자제품 및 소프트웨어",
"NVDA": "NVIDIA Corp. — GPU 및 AI 반도체",
}
return info.get(ticker.upper(), "정보 없음")
agent = Agent(
name="Stock Analyst",
instructions="주식 분석가입니다. 티커 심볼로 주가와 기업 정보를 조회하고 분석합니다.",
tools=[get_stock_price, get_company_info],
)
async def main():
result = await Runner.run(agent, "NVDA 주가와 회사 정보를 알려줘.")
print(result.final_output)
asyncio.run(main())

내장 도구 vs 함수 도구

직접 만드는 함수 도구 외에도 OpenAI가 호스팅하는 내장 도구들이 있습니다. WebSearchTool은 실시간 웹 검색을, FileSearchTool은 벡터스토어 기반 문서 검색을, CodeInterpreterTool은 샌드박스 내 파이썬 코드 실행을 제공합니다. 이 내장 도구들은 별도 구현 없이 한 줄로 에이전트에 강력한 능력을 추가해 줍니다.

from agents import Agent, WebSearchTool, CodeInterpreterTool
research_agent = Agent(
name="Research Agent",
instructions="최신 AI 뉴스를 검색하고 코드를 실행하여 데이터를 분석합니다.",
tools=[WebSearchTool(), CodeInterpreterTool()],
)

▲ 목차로 돌아가기

핸드오프(Handoff)와 멀티에이전트 오케스트레이션

단일 에이전트는 만능이 될 수 없습니다. 고객 문의 봇 하나가 배송 추적, 환불 처리, 기술 지원을 모두 담당하면 프롬프트가 비대해지고 성능이 떨어집니다. 이때 필요한 것이 핸드오프(Handoff)입니다 — 트리아지 에이전트가 요청을 분류하고, 해당 전문 에이전트에게 대화 제어권을 넘기는 패턴입니다.

핸드오프 vs Agents as Tools — 언제 무엇을 쓸까

Agents SDK에는 두 가지 멀티에이전트 패턴이 있습니다. 핸드오프는 전문 에이전트가 해당 턴부터 대화를 직접 이어받으므로 프롬프트를 집중시킬 수 있고, Agents as Tools는 관리자 에이전트가 제어권을 유지하면서 전문 에이전트를 도구처럼 호출합니다. 두 패턴을 상황에 맞게 조합하는 것이 실전 설계의 핵심입니다.

from agents import Agent, Runner
import asyncio
# 전문 에이전트 정의
history_agent = Agent(
name="History Tutor",
handoff_description="역사 관련 질문을 담당하는 전문 에이전트",
instructions="역사 질문에 명확하고 간결하게 답변합니다.",
)
math_agent = Agent(
name="Math Tutor",
handoff_description="수학 관련 질문을 담당하는 전문 에이전트",
instructions="수학 문제를 단계별로 풀이하고 예시를 포함합니다.",
)
# 트리아지(분류) 에이전트
triage_agent = Agent(
name="Triage Agent",
instructions="각 질문을 적합한 전문 에이전트에게 라우팅합니다.",
handoffs=[history_agent, math_agent],
)
async def main():
result = await Runner.run(
triage_agent,
"미국 독립선언서는 언제 작성됐나요?",
)
print(result.final_output)
print(f"응답한 에이전트: {result.last_agent.name}")
asyncio.run(main())

▲ 목차로 돌아가기

가드레일 — 비용 폭탄과 오용을 막는 안전장치

고성능 모델을 사용하는 에이전트를 배포하면 악의적 사용자가 비싼 작업을 남발할 위험이 있습니다. 가드레일(Guardrail)은 이 문제를 해결하는 핵심 메커니즘으로, 빠르고 저렴한 모델로 입력/출력을 먼저 검증한 뒤, 검증을 통과한 경우에만 고성능 모델이 실행되도록 합니다. 입력 가드레일, 출력 가드레일, 도구 가드레일 세 종류가 있습니다.

입력 가드레일 — 불량 요청 차단하기

아래 예제는 수학 숙제 도움 요청을 차단하는 고객 지원 에이전트입니다. 저렴한 모델로 가드레일을 먼저 실행하고, 악의적 사용이 감지되면 tripwire_triggered=True를 반환하여 비싼 메인 에이전트 실행 자체를 막습니다.

from pydantic import BaseModel
from agents import (
Agent, GuardrailFunctionOutput,
InputGuardrailTripwireTriggered,
RunContextWrapper, Runner,
TResponseInputItem, input_guardrail,
)
class MathHomeworkOutput(BaseModel):
is_math_homework: bool
reasoning: str
# 가드레일 전용 경량 에이전트
guardrail_agent = Agent(
name="Guardrail Check",
instructions="사용자가 수학 숙제를 대신 풀어달라고 요청하는지 확인하세요.",
output_type=MathHomeworkOutput,
)
@input_guardrail
async def math_guardrail(
ctx: RunContextWrapper[None],
agent: Agent,
input: str | list[TResponseInputItem],
) -> GuardrailFunctionOutput:
result = await Runner.run(guardrail_agent, input, context=ctx.context)
return GuardrailFunctionOutput(
output_info=result.final_output,
tripwire_triggered=result.final_output.is_math_homework,
)
# 메인 에이전트에 가드레일 적용
support_agent = Agent(
name="Customer Support",
instructions="고객 문의를 친절하게 도와줍니다.",
input_guardrails=[math_guardrail],
)
async def main():
try:
result = await Runner.run(support_agent, "2x + 3 = 11을 풀어줘.")
print(result.final_output)
except InputGuardrailTripwireTriggered:
print("⚠️ 가드레일 발동: 수학 숙제 요청이 차단되었습니다.")
import asyncio
asyncio.run(main())

병렬 실행 vs 차단 실행

입력 가드레일은 두 가지 모드를 지원합니다. 기본값은 병렬 실행(run_in_parallel=True)으로, 가드레일과 메인 에이전트가 동시에 시작되어 지연 시간을 최소화합니다. 반면 차단 실행(run_in_parallel=False)은 가드레일이 먼저 완료된 후 메인 에이전트가 시작되어, 토큰 낭비와 사이드 이펙트를 원천 차단합니다. 비용 최적화가 중요한 서비스라면 차단 실행을 권장합니다.

▲ 목차로 돌아가기

MCP 서버 연동 — 에이전트를 외부 세계에 연결하는 법

MCP(Model Context Protocol)는 AI 에이전트가 외부 시스템(데이터베이스, API, 파일 시스템, SaaS 서비스 등)과 표준화된 방식으로 통신하기 위한 프로토콜입니다. Agents SDK는 MCP 서버 도구 통합을 내장으로 지원하며, 함수 도구와 동일한 방식으로 동작합니다. 이 기능이 활성화된 순간, 여러분의 에이전트는 GitHub, Slack, Notion, 데이터베이스 등 수십 가지 서비스를 직접 사용하는 “디지털 동료”로 변신합니다.

from agents import Agent, Runner
from agents.mcp import MCPServerStdio
import asyncio
async def main():
# 파일시스템 MCP 서버 연결 예시
async with MCPServerStdio(
name="filesystem",
params={
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
},
) as mcp_server:
agent = Agent(
name="File Manager",
instructions="파일 시스템을 탐색하고 파일을 읽거나 생성합니다.",
mcp_servers=[mcp_server],
)
result = await Runner.run(
agent,
"/tmp 디렉토리에 있는 파일 목록을 보여줘."
)
print(result.final_output)
asyncio.run(main())

어떤 MCP 서버들이 있나요

Anthropic이 관리하는 공식 MCP 서버 저장소에는 파일시스템, GitHub, Slack, PostgreSQL, Brave Search 등 수십 개의 공식 서버가 있습니다. 또한 FastMCP 라이브러리를 사용하면 자신만의 MCP 서버를 몇 줄의 코드로 만들어 에이전트에 연결할 수 있습니다. 개인적으로 생각했을 때, MCP 생태계의 성숙도가 에이전트 활용 범위를 결정하는 시대가 이미 도래했습니다.

▲ 목차로 돌아가기

트레이싱으로 에이전트 실행 디버깅하기

에이전트는 실행 중 무슨 일이 일어나는지 눈에 보이지 않아 디버깅이 어렵습니다. Agents SDK의 내장 트레이싱은 이 문제를 해결합니다. 에이전트 실행, 도구 호출, 핸드오프, 가드레일 동작이 모두 자동으로 기록되며, OpenAI Platform Trace Viewer에서 시각적으로 확인할 수 있습니다. 별도 설정 없이 SDK 설치만으로 즉시 활성화됩니다.

트레이싱이 기록하는 것들

트레이스 한 건에는 LLM 호출(입력/출력 토큰), 도구 호출 및 결과, 핸드오프 발생 시점과 대상 에이전트, 가드레일 실행 결과, 총 실행 시간과 비용이 모두 포함됩니다. 이 데이터는 에이전트 평가(Evals)와 파인튜닝의 입력 데이터로도 활용할 수 있어, 시간이 지날수록 에이전트를 지속적으로 개선하는 피드백 루프를 만들 수 있습니다.

# 트레이싱은 자동으로 동작하며, 별도 설정이 필요하지 않습니다.
# API 키가 설정되어 있으면 platform.openai.com/traces에서 확인 가능
from agents import Agent, Runner
import asyncio
agent = Agent(
name="Debug Agent",
instructions="테스트 에이전트입니다.",
)
async def main():
# 이 실행의 모든 동작이 자동으로 트레이싱됨
result = await Runner.run(agent, "안녕하세요.")
print(result.final_output)
# → platform.openai.com/traces에서 실행 내역 확인 가능
asyncio.run(main())

▲ 목차로 돌아가기