에이전트 하네스를 직접 만들까요, OpenAI Agents SDK 같은 걸 쓸까요? 기준이 뭔가요?

Question

LLM에 도구(함수 호출) 몇 개 물려서 사내 업무 자동화를 하려는데, 직접 while 루프로 에이전트 하네스(루프+도구 디스패치+파싱+재시도)를 짤지, OpenAI Agents SDK나 다른 런타임을 쓸지 고민입니다.

"모델만 좋으면 되는 거 아니냐" 는 의견도 있고, "하네스가 성패를 가른다" 는 글도 봐서 헷갈립니다.
우리 케이스는 도구 3~6개, 멀티스텝, 일부는 DB write/외부 API 호출도 있음 (한국 기술 회사, 서울 리전, Slack 알림 연동)

직접 구현 vs SDK 채택의 실제 트레이드오프와, 아예 하네스를 만들면 안 되는 경우를 알고 싶습니다.

Accepted Answer

결론: 도구가 있고 멀티스텝이며 write/exec가 섞이면 하네스는 필요하고, 그 경우 직접 while 루프보다 검증된 런타임을 쓰는 쪽을 기본값으로 하세요. 단 "단일 결정적 호출"(도구 없이 한 번 부르면 끝)이면 하네스 자체를 만들지 마세요 — 그게 가장 흔한 과설계입니다.

"모델만 좋으면 된다"가 틀린 이유 (근거)

모델 성능은 필요조건이지 충분조건이 아닙니다. 같은 모델이라도 스캐폴딩에 따라 벤치 점수 델타가 큽니다. Live-SWE-agent 리더보드 기준(2025-11), 오픈소스 스캐폴드인 Live-SWE-agent + Claude Opus 4.5가 SWE-bench Verified 79.2%로 1위였고, SWE-Bench Pro에서는 Claude Sonnet 4.5 + Live-SWE-agent가 발표 시점(2025-11) 45.8%로 SOTA로 보고됐습니다(이후 다른 스캐폴드가 추월). 즉 "실행 골격(루프·도구·컨텍스트·종료조건)"이 실세계 성공률을 좌우합니다. 그러니 하네스를 만들지 말지가 아니라 직접 짤지 빌려올지가 진짜 질문입니다.

직접 while 루프 vs 런타임(SDK) — 무엇을 포기하나

직접 구현이 "쉬워 보이는" 이유는 happy path만 보기 때문입니다. 운영에서 실제로 비용을 치르는 건 다음 6가지인데, 이게 전부 하네스의 책임입니다.

책임	직접 while 루프	OpenAI Agents SDK 류
도구 디스패치+스키마	직접 매핑·검증	함수 데코레이터로 자동
종료/예산	직접 `max_steps`·토큰 카운트	`max_turns` 내장, 초과 시 `MaxTurnsExceeded` 예외
가드레일(권한/안전)	직접 분기	input/output guardrail, tripwire 시 즉시 중단
멀티스텝 tool-chain	append 루프 직접 관리	런타임이 call→respond 자동
핸드오프(에이전트 전환)	직접 라우팅	handoff 내장
트레이싱	직접 로깅	내장 tracing

직접 구현을 택해도 되는 경우: 도구 1~2개 + 종료조건이 자명 + 특이한 제어흐름(예: 사내 승인 게이트를 매 step 끼워야 함)이라 프레임워크가 오히려 방해될 때. 이때도 위 "종료/예산"과 "가드레일"은 직접 구현해야 합니다 — 생략하면 런어웨이 비용과 무권한 write로 돌아옵니다.

SDK를 택하는 경우(권장 기본값): 도구 3개 이상 + 멀티스텝 + write/exec 혼재. 종료·가드·트레이싱을 공짜로 얻고, 버그 표면이 줄어듭니다. 대신 프레임워크의 추상화(핸드오프·컨텍스트 주입 방식)에 맞춰야 하고 디버깅 시 한 겹 더 들여다봐야 하는 비용을 집니다.

write/exec가 섞일 때의 필수 가드 (당신 케이스)

DB write·외부 API가 있으면 SDK든 자작이든 아래는 무조건 넣으세요.

# 1) 위험 도구는 화이트리스트 + 승인 게이트
WRITE_TOOLS = {"update_member", "refund_payment"}

def before_tool(call):
    if call.name in WRITE_TOOLS:
        if not approval_granted(call):      # Slack 승인 등 HITL
            return {"status": "blocked", "reason": "승인 필요"}
    # 2) 인자 검증 — 무음 실패 방지 (아래 함정 참조)
    validate_args(call.name, call.args)

국내·실무 함정

OpenAI strict 스키마가 maxItems·minItems 류를 거부 = 무음 실패: structured output이나 tool 스키마를 strict로 켜고 JSON Schema에 maxItems 같은 제약을 넣으면, 모델이 그 제약을 지키는 게 아니라 스키마 자체가 거부됩니다(strict 미지원 키워드). 라이브러리가 이 키를 안 떼주면 요청이 깨지거나 제약이 조용히 무시돼 "왜 항목 수가 안 지켜지지"로 헤매게 됩니다. strict에서는 미지원 키워드(maxItems·minItems·pattern·minimum·maximum 등)를 빼고, 제약은 field description으로 안내한 뒤 클라이언트에서 재검증하세요.
종료 예산을 안 걸면 런어웨이 비용: 한글 입력은 토큰이 영어 대비 1.5~2배라 서울 리전/원화 청구서에서 폭주가 더 아프게 옵니다. max_turns·토큰 상한은 "있으면 좋은"이 아니라 출시 게이트입니다.
샌드박스 없는 write/exec 금지: 모델이 생성한 인자를 그대로 DB나 셸에 흘리지 말고, 위처럼 화이트리스트+검증을 통과한 호출만 실행하세요.
데모-프로덕션 갭: while 루프 자작은 데모에선 거의 항상 됩니다. 프로덕션에서 깨지는 건 종료·가드·도구 무음실패이지 happy path가 아닙니다. "데모 성공"을 채택 근거로 쓰지 마세요.

출처: Live-SWE-agent 리더보드 (https://live-swe-agent.github.io/), SWE-Bench Pro (https://arxiv.org/pdf/2509.16941), OpenAI Agents SDK 실행·가드레일 (https://openai.github.io/openai-agents-python/running_agents/, https://openai.github.io/openai-agents-python/guardrails/), OpenAI Structured Outputs strict 미지원 키워드 (https://community.openai.com/t/min-maxitems-are-not-supported-in-structured-output/958567).

에이전트 하네스를 직접 만들까요, OpenAI Agents SDK 같은 걸 쓸까요? 기준이 뭔가요?

답변 1개

"모델만 좋으면 된다"가 틀린 이유 (근거)

직접 while 루프 vs 런타임(SDK) — 무엇을 포기하나

write/exec가 섞일 때의 필수 가드 (당신 케이스)

국내·실무 함정