OpenAI Agents SDK 실전 가이드 — 멀티스텝 에이전트 구축 5단계

OpenAI Agents SDK로 멀티스텝 에이전트 만들려는데 어디서부터 시작해야 할지 막막하시죠?

저도 그랬어요. 4월 15일에 SDK 메이저 업데이트 나오자마자 바로 시도해봤는데, 처음 일주일은 무한 루프·도구 호출 실패로 한도 초과만 5번 떴거든요. 그 후 한 달 동안 실전 패턴을 정리해서 결국 작동하는 5단계 구축법을 찾았어요.

오늘은 OpenAI Agents SDK 공식 문서 + 실측 결과 기반으로 멀티스텝 에이전트를 안전하게 구축하는 5단계 가이드를 정리할게요. 코드 복붙해서 바로 쓸 수 있게 만들었습니다.

1단계 — 단일 에이전트 + 단일 도구로 시작

가장 큰 실수는 처음부터 멀티 에이전트로 시작하는 거예요. OpenAI 공식 권장도 "단일 에이전트 + 단일 도구로 작동 확인 후 확장"입니다.

환경 설정:

pip install openai-agents
export OPENAI_API_KEY=sk-...

가장 단순한 에이전트:

from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    # 실제로는 OpenWeather API 호출
    return f"{city}: 맑음, 18도"

agent = Agent(
    name="Weather Assistant",
    instructions="You help users check weather. Use Korean for responses.",
    tools=[get_weather],
    model="gpt-5.2",
)

result = Runner.run_sync(agent, "서울 날씨 어때?")
print(result.final_output)
# "서울 날씨는 맑음이고 18도예요."

10줄 코드로 동작 확인. 이 단계에서 도구 호출 패턴을 확실히 이해하고 가야 다음 단계가 안 무너져요.

2단계 — Manager 패턴으로 멀티 에이전트 오케스트레이션

여러 전문 에이전트를 중앙 매니저가 도구처럼 호출하는 구조예요. 가장 안정적이고 디버깅 쉬워서 95% 사용자에게 권장.

from agents import Agent, Runner, function_tool

# 전문 에이전트 1: 리서치
research_agent = Agent(
    name="Research Agent",
    instructions="당신은 리서치 전문가. 주제에 대해 핵심 정보 5개 추출.",
    model="gpt-5.2",
)

# 전문 에이전트 2: 작성
writer_agent = Agent(
    name="Writer Agent",
    instructions="리서치 결과를 받아 한국어 블로그 글 초안 작성.",
    model="gpt-5.2",
)

# 매니저 - 전문가들을 도구로 호출
manager = Agent(
    name="Content Manager",
    instructions="""당신은 콘텐츠 매니저.
사용자 요청 → research_agent로 정보 수집 → writer_agent로 글 작성.
모든 단계 완료 후 사용자에게 최종 결과 전달.""",
    tools=[
        research_agent.as_tool(
            tool_name="research_topic",
            tool_description="주제에 대한 리서치 수행",
        ),
        writer_agent.as_tool(
            tool_name="write_draft",
            tool_description="리서치 결과 기반 글 작성",
        ),
    ],
    model="gpt-5.2",
)

result = Runner.run_sync(manager, "AI 자동화 트렌드 글 써줘")

Manager 패턴 장점:

• 모든 결과가 매니저로 모임 → 디버깅 쉬움
• 권한 이양이 명확하지 않아 무한 루프 위험 적음
• tracing 시 흐름 한눈에 파악 가능

Notion AI 에이전트 컨설팅 글에서도 이 Manager 패턴이 가장 자주 등장해요.

3단계 — Handoff 패턴 (필요한 경우만)

특정 시나리오에서 Manager보다 Handoff가 더 자연스러워요. 1차 응답 → 전문가 직접 이양 같은 흐름.

from agents import Agent, handoff

# 전문 에이전트
korean_specialist = Agent(
    name="Korean Specialist",
    instructions="한국어 전문 답변.",
    model="gpt-5.2",
)

english_specialist = Agent(
    name="English Specialist",
    instructions="Answer in English only.",
    model="gpt-5.2",
)

# 트리아주 에이전트 - 언어 감지 후 handoff
triage = Agent(
    name="Triage",
    instructions="""사용자 메시지의 언어를 감지.
한국어면 korean_specialist에게, 영어면 english_specialist에게 handoff.""",
    handoffs=[korean_specialist, english_specialist],
    model="gpt-5.2",
)

result = Runner.run_sync(triage, "안녕하세요")
# korean_specialist가 응답

Handoff 사용 기준:

• 명확한 분기 조건이 있을 때 (언어, 주제, 사용자 역할)
• 한 번에 한 에이전트만 활성화 OK일 때
• 매니저 오버헤드가 부담될 때

주의: Handoff 후엔 원래 매니저로 돌아오기 어려워요. 결과를 한 곳에 모아야 한다면 Manager 패턴이 정답.

4단계 — Guardrails로 안전성 확보

프로덕션 배포 전 필수 단계예요. 입력·출력에 안전장치를 박아둡니다.

Input Guardrail (PII 차단 예시):

from agents import Agent, GuardrailFunctionOutput, input_guardrail
import re

@input_guardrail
async def block_pii(ctx, agent, input_text: str) -> GuardrailFunctionOutput:
    # 주민번호 패턴 차단
    if re.search(r'\d{6}-\d{7}', input_text):
        return GuardrailFunctionOutput(
            output_info="PII detected: SSN",
            tripwire_triggered=True,
        )
    return GuardrailFunctionOutput(
        output_info="Clean",
        tripwire_triggered=False,
    )

agent = Agent(
    name="Safe Agent",
    instructions="...",
    input_guardrails=[block_pii],
    model="gpt-5.2",
)

Output Guardrail (환각 차단 예시):

from agents import output_guardrail

@output_guardrail
async def check_factual(ctx, agent, output: str) -> GuardrailFunctionOutput:
    # 의학 답변에 "확신할 수 없습니다" 같은 면책 문구 필수 체크
    forbidden = ["100% 확실", "절대로", "항상 효과"]
    if any(word in output for word in forbidden):
        return GuardrailFunctionOutput(
            output_info="Overconfident claim detected",
            tripwire_triggered=True,
        )
    return GuardrailFunctionOutput(output_info="OK", tripwire_triggered=False)

GPT-5.2 자주 발생하는 오류 7가지에서 정리한 도구 호출 실패도 guardrail로 일부 차단 가능해요.

5단계 — Tracing + max_turns로 안정 배포

마지막 단계, 프로덕션 배포 시 절대 빠뜨리면 안 되는 설정 3가지.

from agents import Agent, Runner, RunConfig

agent = Agent(
    name="Production Agent",
    instructions="...",
    tools=[...],
    input_guardrails=[block_pii],
    output_guardrails=[check_factual],
    model="gpt-5.2",
)

# 실행 시 안전 설정
config = RunConfig(
    max_turns=5,           # 무한 루프 방지
    workflow_name="prod",   # tracing 그룹화
    trace_metadata={
        "user_id": "user_123",
        "session_id": "sess_abc",
    },
)

result = await Runner.run(
    agent,
    user_input,
    run_config=config,
)

프로덕션 체크리스트 (5월 4일 기준 권장):

OpenAI 대시보드에서 "Daily spending limit" 설정 필수예요. 이거 안 하면 무한 루프 한 번에 월 예산 다 날립니다.

실전 적용 — 멀티스텝 콘텐츠 파이프라인 예제

위 5단계를 모두 적용한 실제 예제예요. 블로그 글 자동 생성 파이프라인.

# Step 1: 키워드 리서치
keyword_agent = Agent(
    name="Keyword Research",
    instructions="주제에서 SEO 키워드 5개 추출.",
    model="gpt-5.2",
)

# Step 2: 아웃라인 작성
outline_agent = Agent(
    name="Outline Writer",
    instructions="키워드 받아 H2 5개 + H3 15개 아웃라인 생성.",
    model="gpt-5.2",
)

# Step 3: 본문 작성
content_agent = Agent(
    name="Content Writer",
    instructions="아웃라인 받아 한국어 블로그 본문 2500자+ 작성.",
    model="gpt-5.2",
)

# Manager가 3단계 순차 실행
content_manager = Agent(
    name="Content Pipeline",
    instructions="""사용자 주제 받으면:
1. keyword_research로 키워드 추출
2. outline_writer로 아웃라인 생성
3. content_writer로 본문 작성
모든 단계 결과를 사용자에게 전달.""",
    tools=[
        keyword_agent.as_tool("keyword_research", "키워드 추출"),
        outline_agent.as_tool("outline_writer", "아웃라인 생성"),
        content_agent.as_tool("content_writer", "본문 작성"),
    ],
    model="gpt-5.2",
    input_guardrails=[block_pii],
)

result = await Runner.run(
    content_manager,
    "AI 자동화 트렌드 2026",
    run_config=RunConfig(max_turns=5, workflow_name="blog_pipeline"),
)

Zapier ChatGPT 통합 같은 노코드 자동화에서 한계 느끼면 이런 SDK 기반으로 옮기는 게 답이에요. 비용·정확도·확장성 모두 좋아져요.

마무리 — 지금 시작할 수 있는 3가지

오늘 글 읽고 30분 안에 할 수 있는 것:

1. 단일 에이전트 + 단일 도구 hello world 실행 — 1단계 코드 그대로 복붙해서 작동 확인
2. OpenAI 대시보드 일일 한도 설정 — Daily spending limit 5달러로 시작
3. Tracing 대시보드 즐겨찾기 — Logs 탭에서 첫 실행 결과 확인

OpenAI Agents SDK는 4월 출시라 아직 한국어 자료가 부족하지만, 공식 GitHub의 examples 폴더에 7~8개 실전 예제가 있어요. AI 에이전트 활용 사례 7가지에서 어떤 케이스에 SDK가 빛나는지도 정리해뒀으니 참고하세요. 처음 2주는 단일 에이전트 마스터하고, 그 다음에 Manager 패턴으로 확장하는 게 가장 안전한 학습 경로입니다.