OpenAI Agent Improvement Loop 실전 가이드: 에이전트는 배포 후 trace·eval·Codex handoff로 계속 고쳐야 하는 이유

1. 한 줄 문제 정의

핵심 요약: 에이전트는 데모가 아니라 반복 운영 대상이기 때문에, 실패를 다시 학습 가능한 작업 단위로 바꾸는 구조가 필요합니다.

OpenAI Cookbook의 Agent Improvement Loop with Traces, Evals, and Codex 예제는 에이전트를 만든 뒤 “어떻게 더 좋아지게 만들 것인가”를 다룹니다. 여기서 문제는 모델 성능이 낮다는 단순한 이야기가 아닙니다. 실제 문제는 사용자가 불만을 말해도 그 피드백이 다음 프롬프트, 도구, 검증 조건, 테스트로 연결되지 않는다는 점입니다.

이 글은 이미 간단한 에이전트를 만들 수 있는 개발자와 팀 리더를 대상으로 합니다. OpenAI Agents SDK를 처음 설치하는 튜토리얼이라기보다, 운영 중인 에이전트에 추적(trace), 피드백, 평가(eval), Codex 수정 지시를 붙이는 실전 기준을 설명합니다. 단발성 챗봇, 사내 FAQ, 간단한 요약기처럼 실패 비용이 낮은 작업에는 과할 수 있습니다.

2. 먼저 결론

핵심 요약: 에이전트 개선 루프는 “실행 기록 - 피드백 - 평가 - 코드 수정”을 하나의 계약으로 묶을 때 가치가 생깁니다.

추천 대상은 세 가지입니다. 첫째, 에이전트가 도구를 호출하고 여러 단계로 답을 만드는 팀입니다. 둘째, 답변 품질을 감으로만 판단하지 않고 회귀 테스트로 관리해야 하는 팀입니다. 셋째, Codex 같은 코딩 에이전트에게 수정 작업을 맡기되 사람이 승인하는 리뷰 흐름을 두고 싶은 팀입니다.

반대로 아직 하루 호출량이 적고, 사용자 피드백이 거의 없고, 실패 유형도 정리되지 않았다면 먼저 수동 로그 리뷰부터 시작하는 편이 낫습니다. 개선 루프는 품질 문제를 자동으로 해결해 주는 장치가 아니라, 문제를 재현 가능한 증거와 수정 과제로 바꾸는 운영 방식입니다.

3. 핵심 구조 분해

핵심 요약: 이 구조의 중심 단어는 harness입니다. harness는 모델 주변의 지시문, 도구, 정책, 출력 형식, 검증 조건을 합친 실행 계약입니다.

OpenAI Cookbook 예제는 금융 실사 에이전트를 대상으로 다섯 번의 추적 실행을 만들고, 그 실행에 사람 피드백과 모델 피드백을 붙입니다. 이후 피드백을 Promptfoo 평가 케이스로 바꾸고, HALO가 어떤 harness 변경이 우선인지 정리한 뒤, Codex가 구현할 수 있는 handoff 문서로 넘깁니다.

흐름을 단순화하면 아래와 같습니다.

1. Trace: 에이전트가 어떤 입력을 받고, 어떤 도구를 호출했고, 어떤 답을 냈는지 기록합니다.
2. Feedback: 사람 또는 모델이 “무엇이 문제였는지”를 trace에 붙입니다.
3. Eval: 그 피드백을 나중에도 반복 실행 가능한 테스트로 바꿉니다.
4. Diagnosis: 실패가 프롬프트 문제인지, 도구 스키마 문제인지, 출력 검증 문제인지 나눕니다.
5. Codex handoff: 수정해야 할 파일, 기대 동작, 검증 명령을 코딩 작업으로 넘깁니다.

초보 개발자 관점에서는 trace를 “블랙박스 녹화”, eval을 “재시험 문제”, harness를 “에이전트 실행 규칙 묶음”으로 이해하면 됩니다. 중요한 것은 기록만 남기는 것이 아니라, 기록이 다시 테스트와 코드 변경으로 이어지는 점입니다.

4. 설계 의도 해설

핵심 요약: 이 루프는 프롬프트 튜닝을 줄이자는 이야기가 아니라, 프롬프트 튜닝을 증거 기반 변경으로 제한하자는 이야기입니다.

많은 팀은 에이전트가 틀리면 system prompt를 더 길게 씁니다. 처음에는 빨라 보이지만, 몇 주 지나면 왜 그 문장이 들어갔는지 모르는 프롬프트가 됩니다. OpenAI 예제가 trace와 eval을 먼저 두는 이유는 수정의 근거를 남기기 위해서입니다.

Agents SDK 문서에 따르면 SDK는 도구 호출, handoff, guardrail, session, tracing 같은 런타임 요소를 제공합니다. 이 말은 에이전트 품질이 모델 호출 한 번으로 결정되지 않는다는 뜻입니다. 실제 품질은 어떤 도구를 언제 부를지, 어떤 출력은 막을지, 실패 시 어떤 근거를 남길지에 의해 결정됩니다.

설계상 포기하는 것도 있습니다. 모든 피드백을 자동으로 반영하면 빠르지만 위험합니다. 예제도 개발자가 검토하는 change set부터 시작할 수 있다고 설명합니다. 운영 초반에는 자동 병합보다 “Codex가 수정안을 만들고 사람이 diff를 승인하는 방식”이 더 안전합니다.

5. 근거 및 비교

핵심 요약: trace만 보는 방식, eval만 두는 방식, 개선 루프 방식은 서로 다른 문제를 해결합니다.

접근	잘하는 일	약한 지점	추천 상황
수동 로그 리뷰	초기 실패 유형을 빠르게 파악	리뷰어 기억에 의존하고 회귀 방지가 약함	호출량이 적고 실패 유형을 아직 모를 때
Trace 중심 운영	도구 호출, handoff, guardrail 실패 위치를 확인	기록을 봐도 수정 우선순위가 자동으로 나오지는 않음	복잡한 agent flow를 디버깅할 때
Eval 중심 운영	회귀 테스트와 배포 gate를 만들기 좋음	실제 사용자 실패가 eval에 반영되지 않으면 형식적 테스트가 됨	이미 중요한 실패 케이스가 정리돼 있을 때
Trace + feedback + eval + Codex 루프	실패를 증거, 테스트, 수정 과제로 연결	초기 구성 비용과 검토 시간이 필요	운영 중 에이전트를 지속 개선해야 할 때

OpenAI tracing 문서는 Agents SDK가 기본적으로 전체 Runner 실행, agent span, LLM generation, function tool call, guardrail, handoff를 추적한다고 설명합니다. 또한 장기 실행 작업에서는 trace export가 지연될 수 있으므로 작업 단위 끝에서 flush_traces()를 호출할 수 있습니다. 이 세부사항은 운영에서 중요합니다. trace가 늦게 올라오면 “실패가 없었다”고 착각하기 쉽기 때문입니다.

6. 실제 동작 흐름과 단계별 실행 방법

핵심 요약: 처음부터 완전 자동화하지 말고, 한 업무에 대해 trace 5~20개와 eval 10개 정도로 작은 루프를 먼저 고정하는 편이 좋습니다.

실무에서는 아래 순서로 시작하면 됩니다.

1. 업무 하나를 고릅니다. 예를 들어 “계약서 요약 에이전트”, “고객 문의 triage 에이전트”, “리포트 검수 에이전트”처럼 결과 검수가 가능한 업무를 고릅니다.
2. harness를 파일로 고정합니다. 지시문, 도구 목록, 출력 스키마, 금지 조건, 검증 명령을 저장소에 둡니다.
3. trace를 켭니다. Agents SDK는 tracing이 기본 활성화되어 있으나, 민감 데이터 정책이 있으면 저장 범위부터 확인합니다. ZDR 정책 조직에서는 tracing을 사용할 수 없다는 문서상 제한도 확인해야 합니다.
4. 실패 trace를 5개 이상 모읍니다. 단순히 틀린 답만 모으지 말고, 도구를 잘못 고른 사례, 출처를 빠뜨린 사례, 답은 맞지만 형식이 깨진 사례를 섞습니다.
5. 피드백을 문장 하나로 끝내지 않습니다. “나쁨” 대신 “출처 A와 B가 충돌할 때 controlled source를 우선해야 함”처럼 수정 가능한 규칙으로 씁니다.
6. eval로 바꿉니다. Promptfoo든 내부 테스트든 상관없지만, 입력, 기대 조건, 실패 메시지가 있어야 합니다.
7. Codex handoff를 만듭니다. 수정 대상 파일, 변경 목표, 금지할 변경, 검증 명령을 포함합니다.

최소 실행 예시는 다음과 같습니다.

python -m venv .venv
source .venv/bin/activate
pip install openai openai-agents halo-engine
npx promptfoo@0.121.9 eval -c promptfoo.yaml

실제 운영에서는 모델 이름보다 산출물 경로가 더 중요합니다. 예제의 핵심 산출물은 trace 파일, eval 설정, 그리고 codex_handoff.md입니다. 이 파일이 있어야 개선이 “다음 사람의 기억”이 아니라 “다음 작업의 입력”이 됩니다.

7. 실수와 함정

핵심 요약: 개선 루프의 실패는 대부분 자동화 부족이 아니라 기준 부족에서 생깁니다.

함정 1: trace를 모았지만 평가 기준이 없다

trace dashboard를 보는 것만으로는 품질이 좋아지지 않습니다. 예방하려면 trace마다 “어떤 조건을 어겼는가”를 한 문장으로 붙입니다. 복구하려면 최근 실패 10개를 다시 읽고 공통 실패 조건을 eval로 추출합니다.

함정 2: LLM judge를 정답처럼 믿는다

모델 피드백은 빠르지만 조직의 품질 기준을 대신하지 못합니다. 예방하려면 사람 리뷰 샘플을 섞고, judge prompt 안에 금지 조건과 우선순위를 명시합니다. 복구하려면 judge가 통과시킨 실패 답변을 별도 regression case로 추가합니다.

함정 3: Codex에게 너무 넓은 수정을 맡긴다

“에이전트 품질 개선해줘”는 좋은 handoff가 아닙니다. 예방하려면 수정 범위를 harness 파일, 도구 스키마, eval 파일처럼 좁힙니다. 복구하려면 Codex 결과를 바로 병합하지 말고 eval 실패와 diff를 함께 검토합니다.

함정 4: 민감 데이터를 trace에 그대로 남긴다

추적은 강력하지만 보안 검토 없이 켜면 위험합니다. 예방하려면 입력 마스킹, trace metadata 제한, 보존 기간을 정합니다. 복구하려면 민감 trace를 삭제하고, 재발 방지를 위해 tracing processor 또는 사전 필터를 둡니다.

8. 강점과 한계

핵심 요약: 이 방식의 강점은 반복 개선이고, 한계는 초기 설계와 데이터 거버넌스 비용입니다.

강점은 명확합니다. 실패가 흩어진 채팅 기록으로 남지 않고 테스트와 수정 작업으로 바뀝니다. 팀원이 바뀌어도 왜 프롬프트가 바뀌었는지 추적할 수 있습니다. 배포 전에 기존 실패가 재발했는지도 확인할 수 있습니다.

한계도 큽니다. 첫째, 좋은 eval을 쓰는 데 시간이 듭니다. 둘째, trace에 민감 정보가 들어갈 수 있어 보안 기준이 필요합니다. 셋째, 자동 개선 루프를 너무 빨리 믿으면 잘못된 judge 기준이 제품 전체에 퍼질 수 있습니다. 넷째, 작은 챗봇에는 비용 대비 효과가 낮습니다.

제 판단은 이렇습니다. 고객 응대, 문서 검토, 코드 변경, 금융/법무/보안처럼 실패 비용이 있는 에이전트에는 이 구조가 필요합니다. 반대로 사내 아이디어 생성, 짧은 요약, 개인 생산성 도구라면 trace와 수동 리뷰만으로 시작해도 충분합니다.

9. 더 깊게 공부할 포인트

핵심 요약: 다음 학습 순서는 Agents SDK 기본 구조, tracing, eval, Codex handoff입니다.

• Agents SDK의 기본 primitive: agent, tool, handoff, guardrail이 어떤 역할을 하는지 먼저 봐야 합니다.
• Tracing 구조: trace와 span의 차이를 이해하면 실패 위치를 훨씬 빨리 찾을 수 있습니다.
• Eval 설계: 정답 문자열 비교보다 “출처 포함”, “금지 행동 없음”, “우선순위 기준 준수” 같은 조건형 평가가 중요합니다.
• Codex handoff 작성법: 구현 요청에는 수정 범위, 파일 경계, 검증 명령, 회귀 방지 조건이 들어가야 합니다.
• 데이터 보안: trace에 고객 정보, 계약 정보, 내부 문서가 들어가는지 먼저 점검해야 합니다.

10. 실행 체크리스트와 작성자 관점

핵심 요약: 도입 기준은 “멋진 자동화”가 아니라 “실패를 재현하고 막을 수 있는가”입니다.

• 대상 에이전트의 핵심 업무가 한 문장으로 정의되어 있는가?
• harness가 저장소 파일로 관리되고 변경 이력이 남는가?
• 실패 trace 5개 이상이 실제 개선 후보로 정리되어 있는가?
• 사람 피드백과 모델 피드백을 구분해서 저장하는가?
• eval이 최소 10개 이상이고 배포 전에 재실행 가능한가?
• Codex handoff에 수정 범위, 금지 범위, 검증 명령이 포함되어 있는가?
• 민감 데이터가 trace와 eval fixture에 남지 않도록 마스킹 기준이 있는가?

Definition of Done: 최근 실패 trace에서 나온 요구사항이 최소 1개 이상의 eval로 고정되고, Codex가 만든 harness 변경이 그 eval을 통과하며, 사람이 diff를 승인한 상태입니다.

저는 이 방식을 “에이전트 품질 관리의 최소 운영 단위”로 봅니다. 모델을 바꾸는 일은 쉽지만, 실패를 다시 막는 일은 구조가 있어야 가능합니다. OpenAI의 예제가 중요한 이유도 여기에 있습니다. 에이전트 개발을 데모 제작이 아니라 운영 시스템 개선으로 다루기 때문입니다.

참고자료

• OpenAI Cookbook: Build an Agent Improvement Loop with Traces, Evals, and Codex (2026-05-19 확인)
• OpenAI Agents SDK 공식 문서 (2026-05-23 확인)
• OpenAI Agents SDK Tracing 문서 (2026-05-23 확인)
• Promptfoo 공식 사이트: LLM 평가와 회귀 테스트 도구 (2026-05-23 확인)
• HALO GitHub 저장소: trace와 feedback 기반 최적화 도구 (2026-05-23 확인)