AI 에이전트 테스트, 매번 실제 API를 불러야 할까? 도구 결과를 고정하는 6칸 계약

왜 매번 실제 API를 부르면 테스트가 흔들릴까요?

검색 결과를 요약해 고객 응대 초안을 만들고 CRM 조회를 다음 단계로 넘기는 에이전트를 생각해 보세요. 같은 질문이라도 검색 순위와 인덱스는 달라질 수 있고, CRM에는 새 필드가 생기거나 권한이 바뀔 수 있습니다. 분석 API는 일시적인 제한이나 장애 응답을 돌려줄 수도 있습니다. CI가 이 모든 변화를 매 실행마다 실제 호출로 받아들이면, 코드가 바뀌지 않았는데도 결과가 달라져 원인을 찾기 어려워집니다.

OpenAI의 agent workflow 평가 안내는 trace가 모델 호출, 도구 호출, guardrail, handoff를 함께 기록한다고 설명합니다. 또한 좋은 결과의 기준이 잡히면 반복 가능한 dataset과 eval run으로 옮겨 비교하라고 권합니다. 여기서 중요한 점은 “항상 같은 외부 결과”가 아니라, 어떤 입력을 반복 비교 대상으로 삼을지 팀이 명확히 정하는 것입니다.

실제 호출을 줄이는 일은 비용만의 문제가 아닙니다. 개발용 자격 증명의 범위, 테스트가 만지는 데이터의 성격, 외부 시스템에 남는 기록까지 함께 판단해야 합니다. 반대로 예전에 저장한 응답만 계속 쓰면 새 권한 오류나 schema 변화, 비어 있는 결과를 놓칠 수 있습니다. 이 둘을 분리하는 장치가 fixture 계약입니다.

live·record·replay를 나누는 6칸 계약

fixture 계약은 도구별로 여섯 가지를 기록하는 짧은 운영 문서입니다. 도구 이름과 변동성만 적는 대신, 기본 모드와 보관 범위·마스킹·만료·실제 재검증 신호까지 같은 줄에 둡니다. 담당자가 바뀌어도 왜 이 응답을 고정했는지, 언제 다시 확인해야 하는지 알 수 있습니다.

이 표의 기본 모드는 영구 규칙이 아닙니다. 예를 들어 검색 도구의 새 질의가 실제로 필요한지, CRM의 새 권한이 필요한지는 release 전에 다시 판단해야 합니다. 만료일은 단순한 달력 날짜보다 “권한 정책, schema, 대상 범위가 유지되는 동안”처럼 변경 원인과 함께 적는 편이 더 실용적입니다.

검색·CRM·분석 API를 분류하는 예시

검색 API의 fixture에는 순위 숫자를 그대로 고정하기보다, 에이전트가 꼭 읽어야 하는 제목·URL·발췌·결과 없음 상태를 최소 단위로 담는 편이 좋습니다. 이렇게 하면 정렬 변화에 끌려가지 않으면서도 “출처가 없을 때 멈추는가”를 검증할 수 있습니다. 새 검색 결과를 실제로 반영해야 하는 날에는 승인된 질의만 별도 live probe로 확인합니다.

CRM 조회는 더 보수적으로 다뤄야 합니다. 테스트에서는 가명 고객 ID와 필요한 상태값만 사용하고, 원문 메모·연락처·토큰을 fixture에 남기지 않습니다. 에이전트가 조회 결과를 다음 단계로 넘긴다면, fixture에는 소비하는 필드와 허용되지 않은 필드가 빠졌을 때의 처리도 함께 넣으세요. 이 설계는 권한 범위와 데이터 품질을 같은 화면에서 점검하게 합니다.

분석 API는 정상 결과만 저장하면 부족합니다. 빈 기간, 지연된 집계, rate limit, 서비스 오류처럼 실제 운영에서 흔한 응답을 별도 fixture로 두는 편이 낫습니다. Google Developers의 장기 실행 에이전트 사례는 오래 이어지는 흐름에서 명시적인 상태와 대표 평가 시나리오를 사용해 중단·재개를 검증하는 방식을 보여 줍니다. 특정 SDK의 보장을 일반화할 필요는 없지만, 오류와 재개 경로를 대표 사례로 반복 확인해야 한다는 원칙에는 참고가 됩니다.

replay만으로 넘기면 안 되는 경로

외부 상태를 바꾸는 도구는 읽기 도구와 분리해야 합니다. 실제 쓰기, 환불, 발행, 권한 변경처럼 되돌리기 어렵거나 외부에 영향을 남기는 작업은 replay를 통과해도 자동 live 실행으로 연결하지 마세요. sandbox 또는 dry-run에서 범위와 결과를 확인하고, 별도 승인 경계를 두는 편이 안전합니다.

이는 테스트를 느리게 만들자는 제안이 아닙니다. 오히려 테스트가 무엇을 증명하는지 분명히 하는 방법입니다. replay는 파서·분기·요약 형식의 회귀를 빠르게 찾고, 제한된 live 검증은 연결·권한·현재 schema를 확인합니다. 실제 변경은 그 둘과 다른 증거, 즉 대상 목록·변경 diff·되돌리기 경로·승인 기록을 요구합니다.

OpenAI Codex의 Record & Replay 안내도 안정적 단계와 명확한 성공 기준을 가진 반복 워크플로를 기록해 재사용하는 방법을 설명합니다. 이 기능을 외부 API 결과의 보안 또는 결정론적 재현을 보장하는 장치로 해석해서는 안 됩니다. 팀의 외부 도구 계약은 별도로 설계해야 합니다.

CI에 넣을 6개 실패 케이스

처음에는 도구 하나에 아래 여섯 가지 경우만 선언해도 큰 차이를 만들 수 있습니다. 각 케이스는 “에이전트가 답을 잘 쓰는가”뿐 아니라, 다음 호출을 해도 되는지와 사람에게 무엇을 알려야 하는지를 함께 검사합니다.

작은 팀의 도입 순서와 체크리스트

모든 도구를 한 번에 정리하려고 하면 계약 자체가 방치되기 쉽습니다. 먼저 실패했을 때 영향이 크거나 호출 비용이 높은 읽기 도구 하나를 고르세요. 정상·빈 결과·권한 거부 세 fixture부터 만들고, 그다음 만료와 실제 재검증 규칙을 붙이면 됩니다. fixture를 갱신하는 사람과 승인 기준도 한 줄로 남겨 두세요.

• 도구가 읽기인지, 외부 상태를 바꾸는지 분리했나요?
• fixture에서 비밀값·고객 식별자·대화 원문을 최소화하거나 가명화했나요?
• 기본 모드와 fixture 만료 기준, 재녹화 승인자를 정했나요?
• schema·권한·목적지·빈 결과·제한 오류에서 실제 재검증으로 전환하나요?
• 쓰기 작업은 sandbox 또는 dry-run과 별도 승인을 거치나요?
• replay 통과를 최신성·권한·안전성 보장으로 과장하지 않았나요?

도구 호출 자체의 승인 경계를 더 세밀하게 설계해야 한다면 외부 상태 변경 도구를 승인 경계로 분리하는 방법을 함께 보세요. 응답 schema를 검증하는 흐름은 AI 에이전트 구조화 출력 검증, 일시 장애 뒤의 품질 경로는 fallback 품질 게이트 테스트에서 이어 볼 수 있습니다.

자주 묻는 질문

fixture는 얼마나 오래 보관해야 하나요?

정해진 기간 하나보다 schema, 권한 정책, 대상 범위가 바뀌지 않는 동안이라는 기준을 함께 두세요. 만료 표식과 재녹화 담당자를 두면 오래된 응답을 무심코 계속 쓰는 일을 줄일 수 있습니다.

모든 API에 live 검증이 필요한가요?

아닙니다. 영향이 작고 안정적인 내부 도구는 replay 중심으로 운영할 수 있습니다. 다만 새 권한, 새 목적지, schema 변경, 빈 결과처럼 계약을 깨는 신호가 있을 때는 좁은 범위에서 실제 확인이 필요합니다.

fixture에 실제 고객 데이터를 넣어도 되나요?

가능하면 넣지 않는 편이 좋습니다. 가명 ID와 필요한 최소 필드로 대표 사례를 만들고, 비밀값·연락처·원문 메모는 제거하세요. 실제 연결 확인은 권한이 제한된 별도 환경에서 수행하세요.

503이 오면 바로 다른 경로로 넘어가도 되나요?

대체 경로의 입력·출력 계약과 중단 조건이 검증된 경우에만 가능합니다. 그렇지 않다면 제한된 재시도 또는 안전한 중단으로 처리하고, 실패 사실을 남기는 편이 낫습니다.

참고 자료

• OpenAI — Evaluate agent workflows: trace, grader, dataset, eval run을 통해 에이전트 워크플로의 반복 평가를 구분하는 공식 안내입니다.
• OpenAI Codex — Record & Replay: 안정적이고 성공 기준이 분명한 작업을 기록해 재사용 가능한 skill로 만드는 기능을 설명합니다.
• Google Developers Blog — Build Long-running AI agents with ADK: 명시적 상태, 중단·재개, 대표 평가 시나리오를 사용하는 장기 에이전트 사례입니다.