에이전트는 데모에서 잘 작동했습니다. 티켓을 읽고, 세 개의 API를 호출하며, 깔끔한 요약을 게시했습니다. 그리고 당신은 이를 배포했습니다. 일주일 후, 에이전트는 동일한 고객에게 두 번 이메일을 보내고, 재시도 루프에 하루치 토큰 예산을 소진했으며, 프론트엔드에 파싱할 수 없는 페이로드를 전달했습니다.
작동하는 프로토타입과 신뢰할 수 있는 에이전트 사이의 간극에서 대부분의 팀이 어려움을 겪습니다. 모델은 거의 범인이 아닙니다. 문제는 배관처럼 취급되는 부분에 있습니다: 에이전트가 답변을 얻기 위해 호출하는 API들입니다. 에이전트는 도구 호출의 루프이며, 모든 도구 호출은 실패하거나, 스로틀링되거나, 시간 초과되거나, 예상치 못한 것을 반환할 수 있는 HTTP 요청입니다. 다른 프로덕션 API를 테스트하는 방식으로 이러한 호출을 테스트하지 않으면, 에이전트는 잘못된 응답 한 번으로 사고로 이어질 수 있습니다.
여기서 안심할 수 있는 부분이 있습니다: 에이전트의 신뢰성은 테스트 가능합니다. 모델이 올바르게 작동할 것이라고 믿을 필요가 없습니다. 사용자가 실패 경로를 발견하기 전에 의도적으로 해당 경로를 테스트해야 합니다. 이 가이드는 에이전트 실패를 다섯 가지 모드로 분류하고 각 모드를 포착하는 방법을 보여줍니다. 작업은 API 경계에서 이루어지므로, 에이전트의 종속성을 지정하여 계약을 설계하고, 실패를 모의(mock)하며, 반환되는 것을 확인할 수 있는 플랫폼이 필요합니다. Apidog는 이 작업을 처리하며, 아래 예제를 통해 설명합니다.
에이전트는 프롬프트가 아닌 API 경계에서 실패합니다
에이전트가 프로덕션에서 오작동할 때, 즉각적인 반응은 프롬프트를 수정하는 것입니다. 때로는 도움이 되기도 합니다. 하지만 더 자주 실패는 단어 선택과 관련이 없습니다. 에이전트가 실제 API에 무언가를 요청했고, 응답이 느리거나, 형식이 잘못되었거나, 속도 제한이 걸렸거나, 에이전트가 예상했던 것과 다른 형태였습니다. 모델은 그 후에 잘못된 입력을 기반으로 추론하여 자신감 있지만 틀린 행동을 했습니다.
단일 에이전트 단계가 무엇을 포함하는지 살펴보세요. 모델은 도구를 선택합니다. 귀하의 코드는 그 선택을 HTTP 요청으로 전환합니다. 외부 서비스가 응답합니다. 귀하의 코드는 그 결과를 모델에 다시 제공합니다. 네 번의 핸드오프 중 세 번은 기계 학습이 아닌 일반적인 API 통합입니다. 이것은 좋은 소식입니다. 왜냐하면 API 통합은 이미 해결된 테스트 문제이기 때문입니다. 느린 엔드포인트를 모의(mock)하거나 JSON 스키마에 대해 어설션하는 방법을 이미 알고 있습니다. 에이전트는 모델이 깔끔한 예외를 발생시키는 대신 수신하는 모든 것에 따라 행동하기 때문에 위험을 높입니다.
따라서 신뢰성 질문은 "모델이 충분히 똑똑한가?"가 아닙니다. "에이전트의 API 호출이 잘못될 수 있는 모든 방법을 테스트했는가?"입니다. 다섯 가지 모드가 대부분을 다룹니다.
실패 모드 1: 계약에서 벗어나는 도구 호출
가장 흔한 에이전트 실패는 호출하는 API와 일치하지 않는 도구 호출입니다. 모델은 매개변수를 임의로 만들거나, 필수 필드를 누락시키거나, 스키마가 정수를 원하는 곳에 문자열을 보내거나, 의미 없는 인수로 올바른 엔드포인트를 호출합니다. 예를 들어, 예약 에이전트가 guests: 2 대신 guests: "two"로 POST /reservations를 호출한다고 가정해 봅시다. API는 400을 반환하거나, 더 나쁜 경우 본문에 오류가 숨겨진 200을 반환하며, 에이전트는 성공한 것처럼 계속 진행합니다.
도구 호출을 계약으로 테스트하여 이를 잡아낼 수 있습니다. 에이전트가 호출할 수 있는 각 도구에 대한 스키마를 정의한 다음, 나가는 요청이 일치하는지(필수 필드 존재, 유형 올바름, 열거형 유효) 어설션합니다. 에이전트가 계약을 위반하는 호출을 생성할 때, 프로덕션에서 조용히 실패하는 것이 아니라 테스트에서 크게 실패하도록 해야 합니다. AI 에이전트의 도구 호출 테스트에 대한 우리의 자세한 설명은 이 부분을 심층적으로 다루며, API를 호출하는 에이전트 테스트를 위한 더 넓은 방법은 전체 설정을 다룹니다.
실용적인 방법: 에이전트가 사용하는 도구 스키마를 캡처하여 Apidog에 로드하고, 해당 정의에 대해 에이전트의 실제 도구 호출을 실행합니다. 불일치는 문제가 발생한 정확한 필드를 명시하는 유효성 검사 실패로 나타납니다.
실패 모드 2: 업스트림 오류 및 속도 제한
에이전트가 수행하는 모든 외부 호출은 429, 500을 반환하거나, 시간 초과 전에 아무것도 반환하지 않을 수 있습니다. 잘 구축된 에이전트는 재시도와 백오프를 사용하여 이를 처리합니다. 취약한 에이전트는 첫 번째 오류에서 포기하거나, 더 위험하게는 너무 열심히 재시도하여 더 많은 스로틀링을 유발하고 예산을 소진하는 루프에 빠집니다. Anthropic SDK 토론 게시판에서 가장 많이 묻는 질문은 말 그대로 에이전트 오류 복구 패턴에 관한 것인데, 이는 이 문제가 얼마나 흔한지 보여줍니다.
정상적인 API를 대상으로 복구를 테스트할 수는 없습니다. 왜냐하면 정상적인 API는 처리해야 할 오류를 절대 반환하지 않기 때문입니다. 여기서 모의(mocking)가 제 역할을 합니다. 에이전트 종속성에 대한 모의를 설정하고 일련의 상황을 프로그래밍합니다: Retry-After 헤더를 포함한 429, 그 다음 500, 그리고 성공. 이제 에이전트가 어떻게 작동하는지 지켜보세요. 지터(jitter)를 사용하여 백오프합니까? 헤더를 준수합니까? 합리적인 횟수 시도 후 우아하게 포기하거나, 명백히 다운된 서비스를 계속 공격하는 것을 중단하기 위해 서킷 브레이커를 엽니까? 그리고 재시도된 작업이 멱등적(idempotent)이지 않다면, 반복이 이중 청구 또는 이중 전송을 유발합니까? 멱등성 키는 재시도를 안전하게 반복할 수 있도록 합니다.
속도 제한은 자체적인 연습이 필요합니다. 공급자가 에이전트를 스로틀링할 때 에이전트가 어떻게 작동하는지 보지 못했다면, 속도 제한 초과 응답이 의미하는 것에 대한 저희 가이드를 읽고 시뮬레이션하십시오. AI 에이전트 오류 복구에 대한 전용 가이드는 재시도, 시간 초과, 백오프 및 서킷 브레이커 패턴을 전체적으로 다룹니다.
실패 모드 3: 비결정적 출력
온도를 0으로 설정해도 실행 간에 바이트 단위로 동일한 출력을 얻지는 못할 것입니다. 개발자들은 이를 끊임없이 다시 발견합니다. 재현성을 위해 시드와 온도가 충분하지 않다는 긴 vLLM 스레드가 있습니다. 하드웨어, 배치 처리 및 공급자 측 변경 사항은 모두 변동을 유발합니다. 테스트가 정확한 문자열에 대해 어설션하면 불안정해지고, 불안정한 테스트는 무시되어 테스트가 없는 것보다 더 나쁩니다. 불안정한 테스트의 원인에 대한 우리의 분석이 여기에 직접 적용됩니다.
해결책은 정확한 텍스트가 아니라 구조와 의미에 대해 어설션하는 것입니다. 응답이 JSON 스키마에 대해 유효한지 확인하십시오. 도구 호출이 올바른 형태와 올바른 대상을 가지고 있는지 확인하십시오. 숫자 답변이 합리적인 범위 내에 있는지 확인하십시오. 필수 키가 존재하고 금지된 필드가 없는지 확인하십시오. "응답에 0과 장바구니 값 사이의 total이 포함되어 있다"고 말하는 테스트는 모델의 자연스러운 변동에도 살아남으면서 실제 회귀를 포착합니다. 비결정적 AI 에이전트 테스트에 대한 가이드는 전체 전략을 제시하며, 에이전트 메모리가 작동하는 방식에 대한 글은 상태가 이 작업을 더 어렵게 만드는 이유를 보여줍니다.
실패 모드 4: 폭주하는 비용
에이전트는 루프를 돌고, 루프는 비용이 듭니다. 실패하는 호출을 수천 번 재시도하는 단일 정지된 에이전트는 하룻밤 사이에 작은 청구서를 큰 청구서로 바꿀 수 있습니다. SDK 토론의 한 현장 보고서는 에이전트 비용을 월 500달러에서 80달러로 품질 저하 없이 줄였다고 설명하며, 이는 비용이 얼마나 빨리 증가하는지와 디자인에 얼마나 많은 여유가 숨어 있는지를 보여줍니다.
비용은 재정적인 문제뿐만 아니라 신뢰성 문제입니다. 왜냐하면 돈을 낭비하는 버그(루프, 중복 호출, 과도한 컨텍스트)는 에이전트를 느리고 예측 불가능하게 만들기 때문입니다. 실행당 토큰을 추적하고, 작업당 예산을 제한하며, 가능한 한 캐싱하십시오. 이의 명령줄 측면에 대해서는, 에이전트 토큰 비용 절감에 대한 저희 가이드에 구체적인 지렛대가 있습니다. 모의(mock)를 대상으로 복구 경로를 테스트할 때 호출 횟수도 주시하십시오. 성공했지만 거기에 도달하기 위해 40번의 호출을 하는 에이전트는 비용 문제가 발생하기를 기다리는 것입니다.
실패 모드 5: 가드레일 누락
가장 큰 피해를 주는 실패는 에이전트가 지시받은 대로 정확히 수행했지만 결과가 여전히 좋지 않은 경우입니다. 모델의 결정과 실제 행동 사이에 아무것도 없었기 때문에 이메일을 보내거나, 기록을 삭제하거나, 주문을 합니다. SDK 게시판에는 새벽 3시에 누군가의 상사에게 이메일을 보낸 에이전트에 대한 기억에 남는 스레드가 있습니다. 한 번은 재미있지만, 두 번은 값비싼 대가를 치르게 됩니다.
가드레일은 안전벨트입니다. 에이전트가 승인 없이 취할 수 있는 조치에 허용 목록을 설정하십시오. 파괴적이거나 돌이킬 수 없는 호출은 인간의 확인 뒤에 게이트하십시오. 에이전트에게 실제로 수행하지 않고 무엇을 할 것인지 설명하는 드라이런 모드를 제공하십시오. 그런 다음 가드레일이 작동하는지 테스트하십시오: 부작용을 일으키는 엔드포인트를 모의(mock)하고, 에이전트를 실행하며, 실제 행동 대신 확인 경로를 따르는지 어설션하십시오. LLM 애플리케이션을 위한 OWASP Top 10과 같은 보안 지침은 보호해야 할 사항에 대한 확실한 체크리스트입니다. AI 에이전트 가드레일에 대한 가이드는 승인 게이트 및 폭발 반경 제어를 심층적으로 다룹니다.
에이전트 테스트를 구성하는 방법
다섯 가지 모드는 하나의 테스트 형태를 공유하며, 이를 재사용할 수 있습니다:
- 에이전트가 호출할 수 있는 도구 스키마를 캡처하여 어설션할 계약을 확보합니다.
- 각 종속성을 모의(mock)하여 타이밍, 상태 코드 및 본문을 제어하고 실제 부작용을 방지합니다.
- 실제 API가 요청 시 생성하지 않을 불행한 경로를 포함하여 시나리오를 통해 에이전트를 구동합니다.
- 에이전트가 보낸 내용과 반응 방식(요청 형태, 복구 동작, 호출 횟수, 가드레일 작동 여부)에 대해 어설션합니다.
한 도구에 대해 이 루프를 실행한 다음 다음 도구를 추가합니다. 이 설정은 사용자가 발견하기 전에 깨진 도구 호출을 처음으로 포착할 때 그 가치를 증명합니다.
에이전트 신뢰성 체크리스트
에이전트가 프로덕션에 배포되기 전에 다음 목록을 확인하십시오:
- 모든 도구 호출은 스키마에 대해 유효성 검사를 거치며, 계약 위반 시 테스트가 실패합니다.
- 업스트림 429, 500 및 시간 초과 응답이 시뮬레이션되며, 에이전트는 백오프를 통해 복구됩니다.
- 재시도된 작업은 멱등적(idempotent)이므로 반복으로 인해 이중 청구 또는 이중 전송이 발생하지 않습니다.
- 테스트는 정확한 문자열이 아닌 구조와 의미에 대해 어설션하므로, 정상적인 변동이 불안정성을 유발하지 않습니다.
- 실행당 토큰 사용량이 측정되며, 예산 상한선이 폭주하는 루프를 중지시킵니다.
- 파괴적인 작업은 허용 목록 또는 인간 승인 게이트 뒤에 위치합니다.
- 가드레일 경로는 가정하는 것이 아니라 모의(mock)를 통해 테스트됩니다.
이 일곱 가지 항목을 모두 확인하면 프로덕션에서 에이전트가 고장나는 방식들을 테스트한 것입니다.
Apidog의 역할 (그리고 역할이 아닌 것)
도구의 역할을 명확히 하십시오. Apidog는 에이전트 프레임워크, 모델 호스트 또는 평가 하네스가 아닙니다. 에이전트를 구축하거나 실행하지 않습니다. Apidog의 역할은 에이전트가 의존하는 API 계층을 담당하는 것이며, 바로 이 계층에서 이러한 실패들이 발생합니다.
실제로는 세 가지를 의미합니다. 에이전트가 호출하는 도구에 대한 계약을 설계하고 저장하여 나가는 요청을 그에 대해 유효성 검사할 수 있습니다. 해당 종속성을 모의(mock)하고, 라이브 API가 요청 시 생성하지 않을 실패 응답(429, 500, 시간 초과, 잘못된 형식의 본문)을 프로그래밍하여 복구를 연습할 수 있습니다. 그리고 비결정적 출력을 견뎌낼 응답(스키마, 형태, 범위, 필수 키)에 대한 어설션을 작성합니다. 이것이 솔직한 적합성입니다: Apidog는 에이전트가 호출하는 API를 테스트하고, 처리해야 할 실패를 모의(mock)하며, 반환되는 것을 확인합니다. 에이전트 AI 테스트에 대한 저희 개요는 이를 더 넓은 QA 그림에 배치합니다.
자주 묻는 질문
에이전트 신뢰성은 모델 문제인가 아니면 엔지니어링 문제인가요? 대부분 엔지니어링 문제입니다. 모델 선택이 중요하지만, 사고를 유발하는 실패(잘못된 도구 호출, 처리되지 않은 속도 제한, 가드레일 누락)는 모델을 변경하지 않고도 해결할 수 있는 통합 및 테스트 문제입니다.
실제 API를 호출하지 않고 에이전트를 테스트할 수 있나요? 네, 그리고 그렇게 해야 합니다. 오류 응답을 강제하고, 타이밍을 제어하며, 부작용을 피할 수 있도록 종속성을 모의(mock)하십시오. 그것이 복구 및 가드레일 경로를 테스트하는 유일한 신뢰할 수 있는 방법입니다.
실행마다 출력이 변경될 때 어떻게 테스트를 작성해야 하나요? 정확한 텍스트 대신 구조와 의미에 대해 어설션하십시오. 응답을 스키마에 대해 유효성 검사하고, 도구 호출 형태를 확인하며, 숫자에 범위(range)를 사용하십시오. 비결정적 AI 에이전트 테스트 가이드에서 이를 자세히 다룹니다.
무엇을 먼저 테스트해야 하나요? 파괴적인 행동에 대한 가드레일, 그 다음 오류 복구입니다. 이 두 가지는 가장 값비싼 실패로부터 당신을 보호합니다: 에이전트가 해로운 행동을 취하거나, 에이전트가 루프에 빠져 예산을 소진하는 것입니다.
하나의 실패 모드부터 시작하십시오
다섯 가지 모드를 한 번에 모두 테스트할 필요는 없습니다. 가장 걱정되는 것(대개 가드레일 또는 오류 복구)을 선택하여 이번 주에 모의(mock)를 대상으로 연습하십시오. 실패를 프로그래밍하고, 에이전트를 실행하며, 에이전트가 어떻게 작동하는지 지켜보십시오. 예산 소진 루프 대신 깔끔한 백오프로 시뮬레이션된 429를 에이전트가 처리하는 것을 처음 보게 되면, 녹색 데모보다 더 나은 이유로 에이전트를 더 신뢰하게 될 것입니다.
계약을 설계하고, 실패를 모의(mock)하며, 에이전트가 의존하는 응답에 대해 어설션하려면 Apidog를 다운로드하십시오.