OpenAI Agents SDK

챗봇 하나를 만드는 일과 인공지능(AI) 에이전트 팀을 만드는 일은 다르다.

챗봇은 질문을 받고 답을 돌려주면 끝난다. 에이전트는 다르다. 필요한 도구를 고르고, 작업 결과를 다시 읽고, 다른 전문가에게 일을 넘긴 뒤 조건을 만족할 때까지 다음 행동을 결정해야 한다. 정작 어려운 부분은 모델 호출보다 그 주변의 실행 흐름에 있다.

OpenAI Agents SDK는 바로 이 흐름을 파이썬 코드로 다루기 위한 오픈소스 소프트웨어 개발 키트(Software Development Kit, SDK)다. 거대한 워크플로 엔진을 먼저 배우지 않아도 Agent, Runner, 도구, handoff, guardrail 같은 몇 가지 개념만으로 에이전트 애플리케이션을 구성할 수 있다.

이 프로젝트를 한 문장으로 정리하면 이렇다.

OpenAI Agents SDK는 AI가 답변만 생성하는 단계를 넘어, 도구를 사용하고 다른 에이전트와 협업하며 작업을 끝낼 때까지 실행하는 런타임이다.

---

모델보다 중요한 것은 실행 흐름이다

일반적인 대규모 언어 모델(Large Language Model, LLM) 애플리케이션은 입력을 모델에 보내고 결과를 받는다.

에이전트 애플리케이션이라면 그 사이에 여러 단계가 들어간다.

사용자 입력
  ↓
에이전트가 다음 행동 판단
  ↓
도구 실행 또는 다른 에이전트로 handoff
  ↓
실행 결과를 다시 모델에 전달
  ↓
가드레일과 출력 형식 검증
  ↓
최종 결과 또는 다음 반복

이 반복 구조를 직접 구현하려면 도구 호출, 오류 처리, 대화 이력, 상태 저장, 스트리밍, 실행 중단과 재개까지 관리해야 한다. Agents SDK의 Runner가 이 반복을 맡는다. 개발자에게 남는 일은 각 에이전트의 역할과 사용할 수 있는 도구를 선언하는 것이다.

핵심은 모델에게 더 긴 프롬프트를 주는 데 있지 않다. 모델이 어떤 범위 안에서 무엇을 할 수 있는지 코드로 정의하는 것, 그것이 출발점이다.

---

네 가지 개념으로 시작한다

1. Agent: 역할과 권한을 가진 작업자

Agent는 단순한 모델 별칭이 아니다. 역할과 실행 조건을 다음과 같이 한데 묶는다.

• 이름과 업무 지침
• 사용할 모델
• 호출할 수 있는 도구
• 업무를 넘길 수 있는 다른 에이전트
• 입력과 출력을 검사하는 가드레일
• 구조화된 출력 타입

가장 작은 에이전트부터 살펴보자.

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="질문에 짧고 정확한 한국어로 답하세요.",
)

result = Runner.run_sync(
    agent,
    "멀티 에이전트 시스템이 필요한 이유를 한 문장으로 설명해 줘.",
)

print(result.final_output)

동기 실행이 필요하지 않다면 비동기 Runner.run()이나 스트리밍 실행을 선택할 수 있다. 네트워크 요청과 도구 실행이 많은 실제 서비스에서는 비동기 방식이 자연스럽다.

2. Tool: 답변을 행동으로 바꾸는 연결점

에이전트가 사내 데이터 조회, 계산, 검색, 파일 처리 같은 일을 하려면 도구가 필요하다. Agents SDK는 파이썬 함수의 타입 정보를 읽어 도구 스키마를 만들고, Pydantic 기반 검증을 적용한다.

from agents import Agent, Runner
from agents.decorators import tool


@tool
def get_order_status(order_id: str) -> str:
    """주문 번호로 현재 배송 상태를 조회한다."""
    return f"{order_id}: 배송 준비 중"


agent = Agent(
    name="Order Support",
    instructions="주문 문의를 처리하세요. 필요한 경우 주문 조회 도구를 사용하세요.",
    tools=[get_order_status],
)

result = Runner.run_sync(agent, "ORDER-1024의 상태를 확인해 줘.")
print(result.final_output)

도구는 일반 함수에만 머물지 않는다. AI 애플리케이션과 외부 도구를 표준 방식으로 연결하는 Model Context Protocol(MCP) 서버, OpenAI 호스팅 도구, 다른 에이전트, 그리고 실험적인 로컬 Codex CLI까지 연결할 수 있다.

3. Handoff: 적합한 전문가에게 실행권 넘기기

멀티 에이전트 구성에서 중요한 것은 에이전트의 수가 아니라 책임의 경계다.

결제 문의와 기술 장애를 하나의 프롬프트에 모두 넣을 수도 있다. 하지만 업무별 정책, 도구, 출력 형식이 달라진다면 전문 에이전트를 나누는 편이 관리하기 쉽다.

from agents import Agent, Runner

billing_agent = Agent(
    name="Billing Specialist",
    handoff_description="결제, 청구서, 환불 문의를 담당합니다.",
    instructions="결제 정책에 따라 문의를 처리하세요.",
)

technical_agent = Agent(
    name="Technical Specialist",
    handoff_description="로그인, 오류, 성능 문제를 담당합니다.",
    instructions="증상을 확인하고 재현 가능한 진단 절차를 안내하세요.",
)

triage_agent = Agent(
    name="Triage",
    instructions="문의 내용을 분류해 적합한 전문가에게 넘기세요.",
    handoffs=[billing_agent, technical_agent],
)

result = Runner.run_sync(
    triage_agent,
    "결제는 됐는데 구독 기능이 활성화되지 않았어요.",
)

print(result.final_output)

Handoff가 일어나면 다음 에이전트가 실행 흐름을 이어받는다. 반대로 총괄 에이전트가 하위 에이전트의 결과를 받아 직접 최종 답변을 작성해야 한다면, 전문 에이전트를 ‘agent as tool’ 형태로 등록할 수 있다.

4. Guardrail: 모델 앞뒤에 세우는 검증선

가드레일은 모델이 스스로 지켜 주기를 기대하는 프롬프트 문장이 아니다. 애플리케이션 실행 경로에 포함되는 검사다.

예를 들어 다음 조건을 코드로 분리할 수 있다.

• 입력에 개인정보나 금지된 요청이 포함됐는가
• 사용자의 질문이 에이전트의 업무 범위에 속하는가
• 결과가 요구한 타입과 필드를 만족하는가
• 도구에 전달할 인자가 정책을 위반하지 않는가
• 특정 조건에서는 사람의 승인이 필요한가

검증에 실패하면 실행을 중단하거나 별도 처리 경로로 보낼 수 있다. 생성형 모델의 불확실성을 없애지는 못하지만, 실패를 발견하고 통제할 위치를 만들어 준다.

---

실제 서비스에 필요한 주변 기능

Agents SDK의 강점은 멀티 에이전트 데모를 만드는 데서 끝나지 않는다. 운영 환경에 필요한 기능도 실행 런타임 주변에 모여 있다.

세션과 대화 상태

여러 실행 사이에서 대화 이력을 유지할 수 있다. 저장 방식도 하나로 고정되지 않는다. 기본 SQLite 구성뿐 아니라 SQLAlchemy, Redis, 암호화 세션과 사용자 정의 저장소를 선택할 수 있다.

세션은 ‘AI의 기억’이라는 추상적인 표현보다 다음 실행에 어떤 대화 상태를 다시 공급할 것인가에 가깝다. 서비스에서는 사용자별 격리, 보존 기간, 암호화와 삭제 정책을 함께 설계해야 한다.

Human-in-the-loop

환불, 배포, 파일 삭제, 외부 메시지 전송처럼 되돌리기 어려운 행동은 사람의 승인을 기다리게 만들 수 있다. 실행을 중단하고 상태를 저장한 뒤, 승인 또는 거절 결과를 받아 이어서 실행하는 방식이다.

이 기능의 목적은 AI가 모든 것을 자동 처리하게 만드는 데 있지 않다. 자동화할 부분과 사람이 책임질 부분을 분리하는 장치에 가깝다.

Tracing

에이전트가 어떤 판단을 거쳐 어느 도구를 호출했고, 언제 다른 에이전트로 넘어갔는지 추적할 수 있다. 모델 호출 시간, 도구 실행, 오류와 토큰 사용량을 살펴보며 병목과 실패 지점을 찾는 데 유용하다.

멀티 에이전트 시스템은 최종 답변만 봐서는 문제의 원인을 찾기 어렵다. 추적 정보가 있다면 잘못된 분류인지, 도구 오류인지, handoff 이후의 문맥 손실인지 구분할 수 있다.

Sandbox Agent

코드 저장소를 읽고 명령을 실행하거나 파일을 수정하는 작업에는 실제 작업공간이 필요하다. SandboxAgent는 로컬 Unix 환경, Docker 또는 호스팅 샌드박스와 연결해 격리된 작업을 수행한다.

파일 접근 범위, 네트워크 사용, 명령 실행 권한은 명확히 제한해야 한다. 일반 텍스트 에이전트에 셸 권한을 무심코 붙이지 않고 작업공간과 권한을 별도 경계로 다루는 이유가 여기에 있다.

Realtime Agent와 Voice Pipeline

저지연 음성 대화에는 WebSocket 기반 RealtimeAgent를 사용할 수 있다. 음성 인식, 일반 에이전트 실행, 음성 합성을 단계별로 조합하고 싶다면 VoicePipeline을 선택할 수 있다.

두 기능은 비슷해 보이지만 구조가 다르다. Realtime Agent는 지속적인 실시간 세션에 가깝다. Voice Pipeline은 음성 인식(Speech-to-Text, STT) → 에이전트 → 음성 합성(Text-to-Speech, TTS) 처리 흐름에 가깝다.

---

OpenAI 모델만 사용할 수 있는 것은 아니다

프로젝트 README는 이 SDK를 provider-agnostic, 즉 특정 모델 제공자에만 묶이지 않는 구조로 설명한다. OpenAI Responses API(Application Programming Interface)와 Chat Completions API뿐 아니라 OpenAI 호환 엔드포인트와 외부 어댑터도 연결할 수 있다는 뜻이다.

예를 들어 DeepSeek API를 기본 모델 클라이언트로 지정할 수 있다.

import os

from openai import AsyncOpenAI
from agents import (
    Agent,
    Runner,
    set_default_openai_client,
    set_tracing_disabled,
)

client = AsyncOpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

set_default_openai_client(
    client,
    use_for_tracing=False,
)
set_tracing_disabled(True)

agent = Agent(
    name="DeepSeek Assistant",
    instructions="정확하고 간결한 한국어로 답하세요.",
    model="deepseek-v4-flash",
)

result = Runner.run_sync(agent, "에이전트와 챗봇의 차이를 설명해 줘.")
print(result.final_output)

위 코드는 연결 형태를 보여 주는 예제이며, 이 글을 작성한 환경에서는 실제 DeepSeek API 키를 사용한 호출까지 검증하지 않았다.

2026년 8월 10일 기준으로 DeepSeek의 Responses API는 deepseek-v4-flash를 지원하지만 일부 OpenAI 기능과 완전히 같지는 않다. previous_response_id, 서버 측 conversation 저장, 파일·이미지 입력, MCP와 일부 호스팅 도구에는 제약이 있다. 모델 제공자를 바꿀 때는 ‘요청 형식이 비슷하다’는 사실과 ‘기능이 동일하다’는 판단을 구분해야 한다.

---

설치하고 첫 실행까지

이 저장소의 현재 패키지는 Python 3.10 이상을 요구한다. 아래 절차는 macOS 또는 Linux의 표준 셸 환경을 기준으로 한다.

1. 가상환경과 패키지 준비

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install openai-agents

확인:

python -c "import agents; print(agents.__version__)"

버전 번호가 출력되면 패키지를 불러올 수 있는 상태다.

실패한다면 현재 셸에서 .venv가 활성화됐는지, python --version이 3.10 이상인지 먼저 확인한다.

2. API 키 설정

export OPENAI_API_KEY="발급받은_API_키"

실제 키를 소스 코드나 Git 저장소에 저장하지 않는다. 서비스 환경에서는 운영체제의 비밀 저장소나 배포 플랫폼의 secret 기능을 사용한다.

3. 예제 실행

다음 내용을 hello_agent.py로 저장한다.

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="친절하고 정확한 한국어로 답하세요.",
)

result = Runner.run_sync(agent, "오늘 해야 할 일을 세 단계로 정리해 줘.")
print(result.final_output)

실행:

python hello_agent.py

정상이라면 모델이 생성한 답변이 터미널에 출력된다.

Missing credentials 오류가 나오면 OPENAI_API_KEY가 현재 셸에 설정됐는지 확인한다. 401 오류가 나오면 키의 유효성과 API 프로젝트 권한을 확인한다.

---

이 SDK가 잘 맞는 경우

다음 조건이라면 Agents SDK의 장점이 분명하다.

• 모델이 여러 도구를 선택하며 반복적으로 작업해야 한다
• 역할이 다른 전문 에이전트에게 업무를 위임해야 한다
• 입력, 출력과 도구 호출을 별도로 검증해야 한다
• 대화 상태와 장기 실행을 관리해야 한다
• 중요한 행동 전에 사람의 승인이 필요하다
• 실행 경로를 추적하고 디버깅해야 한다
• 실제 파일과 명령을 다루는 격리 작업공간이 필요하다

반대로 한 번의 요청으로 짧은 텍스트를 생성하고 끝나는 기능이라면 Responses API나 Chat Completions API를 직접 호출하는 편이 단순할 수 있다. 에이전트 수가 많다고 좋은 구조가 되는 것도 아니다. 책임과 권한이 분리되지 않은 에이전트는 이름만 여러 개인 하나의 복잡한 프롬프트가 되기 쉽다.

---

AI 팀을 만든다는 것

멀티 에이전트 시스템을 소개할 때는 종종 조직도 같은 그림이 먼저 등장한다. 총괄 에이전트 아래에 조사, 개발, 검토 에이전트를 배치한 모습은 제법 그럴듯하다.

그렇다면 에이전트를 많이 배치할수록 결과도 좋아질까? 실제 품질을 결정하는 것은 숫자가 아니다.

누가 어떤 정보를 볼 수 있는지, 어떤 도구를 실행할 수 있는지부터 정해야 한다. 언제 다른 에이전트에게 넘길지, 실패하면 어디에서 중단할지, 마지막 결과를 누가 책임질지도 빠질 수 없다. OpenAI Agents SDK는 이런 결정을 파이썬 코드로 옮길 수 있게 해 준다.

복잡한 프레임워크 없이 시작할 수 있다는 말이 설계까지 필요 없다는 뜻은 아니다. 오히려 작은 문법으로 책임과 경계를 또렷하게 드러낼 수 있다는 뜻에 가깝다.

AI에게 일을 시키는 시대를 지나 AI 팀을 운영하려 한다면, 이 프로젝트는 꽤 현실적인 출발점이다.

---

참고 자료

• OpenAI Agents SDK Python GitHub 저장소
• OpenAI Agents SDK 공식 문서
• OpenAI Agents SDK PyPI
• DeepSeek Responses API 호환성 문서

검증 기준

이 글의 프로젝트 기능과 설치 조건은 2026년 8월 10일에 다음 로컬 소스를 기준으로 확인했다.

• 저장소 브랜치: main
• 확인 커밋: 54cc7d93
• 패키지 버전: openai-agents 0.19.4
• 패키지 요구 조건: Python 3.10 이상
• 로컬 확인 환경: macOS, Python 3.13.7, uv

저장소 설치와 Python import는 로컬에서 검증했다. 글에 포함한 OpenAI 및 DeepSeek API 호출 예제는 실제 자격 증명을 사용해 실행하지 않았으므로 API 응답 결과는 미검증이다.