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

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

저도 그랬어요. 처음 붙여봤을 땐 무한 루프와 도구 호출 실패로 한도 초과 경고만 반복해서 봤거든요. 그 뒤로 실전 패턴을 하나씩 정리하면서 결국 작동하는 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="<사용할 모델 ID>",
)

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

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

이 글의 모든 예제에서 model 값은 실제 모델명 대신 "사용할 모델 ID"라는 자리 표시자로 두었어요. 모델 라인업과 정식 ID는 자주 바뀌기 때문에, 실제로 돌릴 땐 OpenAI 공식 모델 문서에서 지금 사용 가능한 ID를 확인해 그대로 넣어주세요. 처음에는 가벼운 모델로 흐름만 확인하고, 품질이 부족한 단계만 상위 모델로 올리는 순서가 비용 면에서 유리해요. 매니저와 전문 에이전트에 서로 다른 모델을 쓰는 것도 가능하니, 판단이 필요한 매니저 쪽에만 더 좋은 모델을 붙이는 구성도 검토해볼 만해요.

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

여러 전문 에이전트를 중앙 매니저가 도구처럼 호출하는 구조예요. 구조가 단순하고 디버깅이 쉬워서 대부분의 경우 먼저 권합니다.

from agents import Agent, Runner, function_tool

# 전문 에이전트 1: 리서치
research_agent = Agent(
    name="Research Agent",
    instructions="당신은 리서치 전문가. 주제에 대해 핵심 정보 5개 추출.",
    model="<사용할 모델 ID>",
)

# 전문 에이전트 2: 작성
writer_agent = Agent(
    name="Writer Agent",
    instructions="리서치 결과를 받아 한국어 블로그 글 초안 작성.",
    model="<사용할 모델 ID>",
)

# 매니저 - 전문가들을 도구로 호출
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="<사용할 모델 ID>",
)

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="<사용할 모델 ID>",
)

english_specialist = Agent(
    name="English Specialist",
    instructions="Answer in English only.",
    model="<사용할 모델 ID>",
)

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

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

Handoff 사용 기준:

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

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

판단이 애매하면 이렇게 물어보세요. "이 요청을 처리하는 동안 다른 에이전트 결과를 다시 합쳐야 하나?" 합쳐야 하면 Manager, 넘기고 끝나도 되면 Handoff예요. 두 패턴을 섞어 쓰는 것도 가능하지만, 처음부터 섞으면 흐름이 복잡해져서 문제가 생겼을 때 원인을 찾기 어려워집니다.

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="<사용할 모델 ID>",
)

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 오류 트러블슈팅 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="<사용할 모델 ID>",
)

# 실행 시 안전 설정
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" 설정 필수예요. 이거 안 하면 무한 루프 한 번에 월 예산 다 날립니다.

표의 권장값은 절대 기준이 아니라 출발점이에요. max_turns는 실제 로그에서 정상 처리가 몇 단계 만에 끝나는지 확인한 뒤, 그 값보다 한두 단계 여유를 두는 식으로 조정하는 게 맞아요. timeout도 마찬가지로 사용자가 화면 앞에서 기다리는 대화형이면 짧게, 배치로 돌리는 파이프라인이면 길게 잡습니다. 중요한 건 숫자 자체가 아니라 "값을 명시했는가"예요. 비워두면 라이브러리 기본값에 운영 안정성을 맡기게 되고, 그 기본값이 바뀌면 내 서비스 동작도 같이 바뀝니다.

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

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

# Step 1: 키워드 리서치
keyword_agent = Agent(
    name="Keyword Research",
    instructions="주제에서 SEO 키워드 5개 추출.",
    model="<사용할 모델 ID>",
)

# Step 2: 아웃라인 작성
outline_agent = Agent(
    name="Outline Writer",
    instructions="키워드 받아 H2 5개 + H3 15개 아웃라인 생성.",
    model="<사용할 모델 ID>",
)

# Step 3: 본문 작성
content_agent = Agent(
    name="Content Writer",
    instructions="아웃라인 받아 한국어 블로그 본문 2500자+ 작성.",
    model="<사용할 모델 ID>",
)

# 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="<사용할 모델 ID>",
    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 기반으로 옮기는 게 답이에요. 비용·정확도·확장성 모두 좋아져요.

이 SDK가 잘 맞는 사람, 굳이 안 써도 되는 사람

모든 자동화를 SDK로 옮길 필요는 없어요. 어떤 상황에서 본전을 뽑는지부터 정리하면 시행착오가 줄어요.

잘 맞는 경우는 세 가지예요. 첫째, 단계가 여러 개로 갈라지고 중간 결과를 다음 단계가 이어받아야 할 때입니다. 리서치 결과를 받아 초안을 쓰고, 그 초안을 다시 검수하는 흐름이 여기 해당해요. 둘째, 도구 호출 로그를 남겨 나중에 문제를 되짚어야 할 때예요. tracing이 기본으로 붙어 있어서 어느 단계에서 어긋났는지 추적하기 쉬워요. 셋째, 입력과 출력에 회사 규칙을 강제해야 할 때입니다. guardrail을 코드로 박아두면 규칙이 문서가 아니라 실제로 실행되는 장치가 돼요.

굳이 안 써도 되는 경우도 분명해요. 단계가 하나뿐이고 조건 분기도 없다면 API를 직접 호출하는 편이 단순합니다. 코드를 계속 유지보수할 사람이 없는 팀이라면 노코드 자동화 도구로 시작하는 게 현실적이고요. 사내 승인 절차 때문에 외부 라이브러리 도입이 오래 걸리는 환경이라면, 먼저 단일 호출로 가치를 증명한 뒤 SDK로 넘어가는 순서가 덜 막혀요.

처음 붙일 때 자주 밟는 실수 5가지

1. 에이전트를 처음부터 여러 개 만드는 것 — 어디서 틀어졌는지 추적이 안 돼요. 하나가 확실히 돌아간 다음 쪼개세요.
2. 도구 설명을 대충 쓰는 것 — 모델은 도구 설명만 보고 호출 여부를 결정해요. 설명이 모호하면 엉뚱한 도구를 부르거나 아예 안 불러요. 언제 쓰는 도구인지, 무엇을 돌려주는지를 한 문장씩 적어주세요.
3. max_turns를 정하지 않는 것 — 대화가 끝나지 않으면 비용이 조용히 쌓여요. 기본값에 기대지 말고 항상 명시하세요.
4. guardrail을 배포 직전에 붙이는 것 — 나중에 붙이면 이미 짜놓은 흐름을 다시 뜯어야 해요. 1단계 hello world가 돌아간 직후에 뼈대만이라도 넣어두는 편이 낫습니다.
5. tracing을 열어보지 않는 것 — 로그가 쌓여 있는데 안 보면 없는 것과 같아요. 실패한 실행 하나를 끝까지 따라가 보는 습관이 디버깅 속도를 가장 크게 바꿔요.

여기에 하나 더 붙이자면, 코드에 모델 ID를 여기저기 흩뿌리지 말고 설정 파일이나 환경 변수 한 곳에 모아두세요. 예제처럼 에이전트마다 문자열을 직접 적어두면 모델을 바꿀 때 파일을 뒤지며 전부 고쳐야 하고, 한두 곳을 놓치면 일부 단계만 다른 모델로 도는 상태가 됩니다. 이런 불일치는 결과 품질이 들쭉날쭉해지는 원인인데 로그만 봐서는 잘 드러나지 않아요.

에러가 반복될 땐 프롬프트부터 고치기보다 tracing에서 실제 호출 순서를 먼저 확인하세요. 원인은 모델보다 도구 정의나 지시문의 모호함인 경우가 많아요. 도구를 하나 줄이거나 지시문에서 조건을 한 줄 덜어내는 것만으로 해결되는 문제도 자주 있습니다.

운영에 올린 뒤에도 점검 루틴은 필요해요. 실패한 실행이 어떤 단계에서 멈췄는지, 특정 도구만 반복 호출되는 패턴은 없는지, 한 번의 요청이 평소보다 훨씬 많은 단계를 밟고 있지는 않은지를 주기적으로 확인하세요. 이 세 가지만 봐도 비용이 새는 곳과 품질이 떨어지는 지점이 대부분 드러나요.

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

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

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

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