데이터 손실 없이 API 호출 AI 에이전트 테스트하는 방법

AI 코딩 에이전트가 스크립트를 실행하고 성공하는 것을 지켜보다가, 운영 데이터베이스 테이블이 사라지는 것을 목격했습니다. 이 사건에 대한 해커 뉴스 부검 글은 "AI가 당신의 데이터베이스를 삭제한 것이 아니라, 당신이 삭제한 것이다"라는 날카로운 제목으로 빠르게 퍼졌습니다. 이 주장은 사실이었기 때문에 설득력을 얻었습니다. 에이전트는 도구 정의를 따랐고, 도구는 실제 엔드포인트를 호출했으며, 해당 엔드포인트에는 안전장치가 없었습니다. 그리고 인간은 DELETE FROM users가 의심스러운지 묻는 과정 없이 키를 넘겨주었습니다. 별개의 r/ClaudeAI 스레드에서는 다른 관점에서 비슷한 이야기를 들려주었습니다: 한 에이전트가 과금 루프에 빠져 아무도 알아차리지 못하는 사이에 수백 달러 상당의 토큰을 소비했습니다. 표면은 다르지만, 동일한 유형의 실패였습니다. 문제는 모델이 멍청해서가 아닙니다. 문제는 아무도 API를 테스트하지 않았다는 것입니다.

💡

이 가이드는 API를 호출하는 자율 에이전트를 배포하는 여러분을 위한 것입니다. 에이전트 개발 중 외부 엔드포인트를 모의(mock)하는 방법, 파괴적인 작업을 샌드박스 처리하는 방법, 도구 스키마에 대한 계약 테스트를 작성하는 방법, 에이전트별 예산 제한을 설정하는 방법, 그리고 프로덕션에 적용하기 전에 실패 모드를 예행연습하는 방법을 배우게 될 것입니다. Apidog는 OpenAPI를 기본적으로 지원하고, 접착 코드(glue code) 작성 없이 모의 서버를 실행하며, 에이전트 도구 호출 시퀀스와 깔끔하게 연결되는 시나리오 테스트를 제공하기 때문에 테스트 스캐폴딩에 Apidog를 사용할 것입니다.

버튼

요약 (TL;DR)

에이전트는 API 측 안전장치(예: 누락된 비율 제한, 비멱등성, 핫 삭제, 손상된 스키마)가 없을 때 프로덕션에서 실패합니다. 이를 해결하기 위한 네 가지 방법이 있습니다: 에이전트의 도구 정의를 OpenAPI 사양에 대해 계약 테스트하고, 파괴적인 엔드포인트에 대한 모의 서버를 실행하며, 에이전트별 예산 및 멱등성 키를 적용하고, CI에서 실패 시나리오를 재현하는 것입니다. Apidog는 이 모든 것을 하나의 프로젝트에서 수행할 수 있도록 OpenAPI 가져오기, 모의(mock), 그리고 시나리오 러너를 제공합니다.

서론

1년 전, "AI 에이전트 테스트"는 Claude 또는 GPT에게 프롬프트를 입력하고 답변을 평가하는 것을 의미했습니다. 이제는 더 이상 그렇지 않습니다. 오늘날의 에이전트는 함수를 호출하고, 그 함수는 여러분의 API를 호출하며, 여러분의 API는 실제 데이터베이스, 결제 처리기 및 타사 서비스와 통신합니다. 잘못된 도구 정의나 누락된 비율 제한은 스타일 문제가 아닙니다. 그것은 여러분의 이름이 새겨질 운영 사고입니다.

이번 달 해커 뉴스에서 입소문이 난 이야기는 이러한 변화를 잘 보여줍니다. 작성자는 AI가 데이터베이스를 삭제한 것이 아니라, 모델과 데이터 사이에 어떤 제어도 두지 않고 에이전트에게 쓰기 권한을 부여한 인간이 삭제한 것이라고 주장했습니다. 이 글은 모든 개발자가 "나도 저렇게 할 뻔했다"고 생각했기 때문에 큰 반향을 일으켰습니다. 몇 주 전, Reddit 게시물에서는 에이전트가 실패한 호출을 너무 많이 재시도하여 아무도 알아차리기 전에 청구액이 800유로를 넘어선 과금 루프에 대해 설명했습니다. 근본 원인은 동일했습니다: 잘못된 계층에 대한 신뢰였습니다.

이 문제를 해결할 수 있습니다. 모델 계층도 중요하지만, API 계층이야말로 문제를 막는 곳입니다. 이 글은 AI 에이전트 API 통합을 종단 간(end-to-end)으로 테스트하는 방법을 보여줍니다. 모든 에이전트-API 설정에 필요한 네 가지 안전장치를 다루고, 파괴적인 엔드포인트를 모의(mocking)하기 위한 단계별 Apidog 워크플로를 안내하며, 스키마 불일치 감지 및 이중 키 분리와 같은 고급 기술로 마무리할 것입니다. 오늘 여러분의 리포지토리에 복사할 수 있는 구체적인 패턴을 얻게 될 것입니다. 모의 서버 단계를 따라 하려면 시작하기 전에 Apidog를 다운로드하세요.

에이전트 실패가 API 실패처럼 보이는 이유

에이전트 사후 분석을 충분히 읽다 보면 한 가지 패턴이 나타납니다. 즉, 모델이 주인공이 아니라는 것입니다. API가 주인공입니다.

프롬프트 주입을 예로 들어보겠습니다. 사용자가 숨겨진 지침이 포함된 PDF를 업로드하고, 에이전트가 이를 읽은 다음, 다음 도구 호출은 delete_all=true와 함께 여러분의 /admin/users 엔드포인트로 이동합니다. 모델은 이것을 선택하지 않았습니다. 의심할 이유가 없는 지침을 따랐을 뿐입니다. 해결책은 프롬프트를 강화하는 것이 아닙니다. 해결책은 사용자 컨텍스트 세션에서 온 토큰에 delete_all=true를 노출하지 않는 API를 구축하는 것입니다. OWASP는 LLM Top 10에서 이것을 LLM01이라고 부르며, 완화책은 프롬프트 엔지니어링이 아니라 API 측 인증입니다.

잘못된 도구 스키마를 예로 들어보세요. 여러분의 OpenAPI 사양은 amount가 센트 단위의 정수라고 말합니다. 에이전트의 도구 정의는 amount가 달러 단위의 부동 소수점이라고 말합니다. 석 달 후, 누군가가 19센트 청구를 19달러로 환불했고, 여러분은 회계 부서로부터 이 불일치를 알게 됩니다. 모델이 틀린 것이 아니었습니다. 모델은 여러분이 제공한 스키마를 사용했습니다. 스키마가 API와 동떨어져 있었습니다. 아무도 계약을 테스트하지 않았습니다.

누락된 비율 제한을 예로 들어보세요. 재시도 루프에 빠진 에이전트가 2분 만에 트랜잭션 이메일 엔드포인트를 1000번 호출합니다. 에이전트의 플래너가 해당 단계를 "아직 성공하지 못했다"고 계속 표시했기 때문입니다. 각 재시도는 비용이 듭니다. 각 재시도는 실제 이메일을 큐에 넣습니다. 여러분이 잠에서 깼을 때, 공급자는 여러분의 계정을 플래그했고 고객들은 스팸을 받고 있습니다. 모델은 악의적이지 않았습니다. 모델은 제한이 없는 도구를 통해 작동하고 있었습니다.

누락된 멱등성을 예로 들어보세요. 에이전트가 고객에게 요금을 청구하기 위해 POST /payments를 호출하고, 네트워크 시간 초과가 발생하며, 플래너가 호출이 실패했다고 생각하여 재시도한 결과 고객에게 두 번 청구됩니다. 에이전트 계층은 원래 호출이 성공했는지 알 수 없습니다. API가 이를 확인할 방법을 제공하지 않았기 때문입니다. 멱등성 키는 다섯 줄의 서버 코드로 이 문제를 해결할 수 있지만, 여러분이 직접 작성해야 합니다.

공통점은 이 모든 사고에서 에이전트가 자신의 도구가 지시하는 대로 정확히 수행하고 있다는 것입니다. 도구는 곧 API입니다. 따라서 에이전트 안정성이 무너지는 지점을 감사할 때, API 계약을 먼저 보고, 에이전트 하네스를 두 번째로 보며, 모델 자체는 거의 보지 않습니다. 이러한 재정의는 어디에 투자해야 하는지 알려주기 때문에 중요합니다. 더 똑똑한 모델이 필요한 것이 아닙니다. 안전장치가 켜진 테스트 가능한 API가 필요합니다.

모든 에이전트-API 통합에 필요한 네 가지 안전장치

네 가지 제어는 안전하게 실패하는 에이전트 설정과 값비싸게 실패하는 에이전트 설정을 구분합니다. 이번 분기에 하나만 추가할 시간이 있다면 가장 위에 있는 것부터 시작하십시오. 네 가지 모두를 할 수 있다면, 2026년에 보게 될 사고 시나리오의 90% 이상을 다룬 것입니다.

1. 도구 스키마 계약 테스트

여러분의 OpenAPI 사양은 API의 진실의 원천입니다. 에이전트는 별도의 도구 정의를 가지고 있는데, 이는 종종 수작업으로 작성되거나 문서에서 복사하여 붙여넣어집니다. 이 두 아티팩트는 지속적으로 불일치합니다. 계약 테스트는 이들이 달라지는 순간 CI 빌드를 실패시킵니다.

다음은 라이브 OpenAPI 사양에 대해 Claude 스타일 도구 정의를 검증하는 최소한의 Python 검사입니다.

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Return a list of mismatch errors, empty list = pass."""
    errors = []
    op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
    api_schema = op["requestBody"]["content"]["application/json"]["schema"]
    tool_schema = tool_def["input_schema"]

    api_props = set(api_schema.get("properties", {}).keys())
    tool_props = set(tool_schema.get("properties", {}).keys())

    for missing in api_props - tool_props:
        if missing in api_schema.get("required", []):
            errors.append(f"Tool missing required field: {missing}")
    for extra in tool_props - api_props:
        errors.append(f"Tool defines field not in API: {extra}")

    for prop, api_def in api_schema.get("properties", {}).items():
        if prop in tool_schema.get("properties", {}):
            tool_def_prop = tool_schema["properties"][prop]
            if api_def.get("type") != tool_def_prop.get("type"):
                errors.append(
                    f"Type mismatch on {prop}: API={api_def.get('type')} "
                    f"tool={tool_def_prop.get('type')}"
                )
    return errors

OpenAPI 사양이나 도구 정의를 건드리는 모든 PR에서 이것을 실행하십시오. 목록이 비어 있지 않으면 빌드를 실패시키십시오. 이 단일 검사는 이전 섹션의 부동 소수점 대 센트 버그를 환불이 나가기 몇 달 전에 미리 잡았을 것입니다.

2. 파괴적인 엔드포인트에 대한 샌드박스 및 모의(Mock) 환경

에이전트는 연습할 장소가 필요합니다. 절대로 운영 환경에서 연습해서는 안 됩니다. 패턴은 간단합니다: 상태를 변경하는 모든 엔드포인트는 실제 작업을 수행하지 않고도 동일한 형태의 응답을 반환하는 모의(mock) 버전을 가집니다. 에이전트 개발 루프는 이 모의를 사용합니다. 스테이징 테스트는 샌드박스 데이터베이스를 사용합니다. 운영 환경은 사람이 배포를 승인할 때까지 건드리지 않습니다.

Apidog는 Faker 패턴에 의해 구동되는 사실적인 필드 값을 포함하여 OpenAPI 사양에서 직접 모의(mock)를 생성합니다. 에이전트의 기본 URL을 모의 서버로 지정하고, 프롬프트를 수백 번 반복 실행하여 에이전트의 동작을 관찰하십시오. 에이전트가 문서를 오해하여 PUT /users/{id}/delete를 계속 시도한다면, 모의 서버가 이를 잡아냅니다. 운영 환경의 사용자 테이블은 이러한 실수를 절대 볼 수 없습니다. 이 패턴이 속하는 더 넓은 개념에 대해서는 계약 우선 개발을 참조하십시오.

3. 되돌릴 수 없는 작업에 대한 멱등성 키 및 논리적 삭제

에이전트가 호출할 수 있는 모든 쓰기 엔드포인트는 멱등성 키를 허용해야 합니다. 모든 삭제는 기본적으로 논리적 삭제여야 하며, 사람이 승인하는 별도의 물리적 삭제 경로가 있어야 합니다.

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers['idempotency-key'];
  if (!key) {
    return res.status(400).json({ error: 'Missing Idempotency-Key header' });
  }
  if (idempotencyCache.has(key)) {
    const cached = idempotencyCache.get(key);
    return res.status(cached.status).json(cached.body);
  }
  const originalJson = res.json.bind(res);
  res.json = function (body) {
    idempotencyCache.set(key, { status: res.statusCode, body });
    setTimeout(() => idempotencyCache.delete(key), 24 * 60 * 60 * 1000);
    return originalJson(body);
  };
  next();
}

app.post('/payments', idempotency, createPayment);

에이전트는 논리적 작업당 UUID를 생성하고 재시도 시 재사용합니다. 여러분의 API는 두 번째 호출에서 두 번 청구하는 대신 캐시된 응답을 반환합니다. 이와 동일한 패턴은 메시징 API의 이중 전송, CRM의 중복 행 생성, 그리고 대부분의 다른 "에이전트가 재시도하여 이제 엉망진창이 되었다" 시나리오로부터 보호합니다.

4. 에이전트별 예산 제한

모든 에이전트는 예산을 받습니다. 토큰 예산, 요청 예산, 금액 예산, 시간 예산. 예산이 소진되면 에이전트는 중단됩니다. 예외는 없습니다. 800유로 Reddit 사건은 아무도 폭주하는 루프에 상한선을 설정하지 않았고, 사람이 확인할 때쯤에는 이미 피해가 발생했기 때문에 일어났습니다.

API 게이트웨이를 감싸는 예산 미들웨어는 다음을 추적할 수 있습니다.

세션당 토큰, 50,000개로 제한
분당 API 호출, 30회로 제한
누적 지출 (센트 단위), 500으로 제한
도구 호출 깊이, 10개 중첩 호출로 제한

어떤 제한이든 초과되면, 구조화된 Retry-After 및 제한 이름을 명시하는 X-Budget-Exceeded 헤더와 함께 HTTP 429를 반환하십시오. 그러면 에이전트의 플래너는 사람에게 에스컬레이션하거나 작업을 되돌릴 수 있습니다. 이와 함께 로깅을 사용하여 어떤 에이전트가 제한에 도달하고 있는지 확인하고 그에 따라 조정하십시오.

이 네 가지 제어는 상호 보완적입니다. 계약 테스트는 명백한 스키마 오류를 잡아냅니다. 모의(mock)는 파괴적인 오류를 잡아냅니다. 멱등성은 재시도 폭주를 잡아냅니다. 예산은 폭주하는 루프를 잡아냅니다. 이 모든 것이 합쳐져 "에이전트가 끔찍한 일을 저질렀다"를 "에이전트가 429를 만났고, 문제를 기록하고, 도움을 요청했다"로 바꿉니다. 이것이 기준입니다.

Apidog로 에이전트 API 호출 테스트하기

이제 실용적인 부분입니다. Apidog에서 완전한 에이전트-API 테스트 워크플로를 설정하는 방법입니다. 에이전트가 호출하는 API의 OpenAPI 사양과 에이전트의 도구 정의 목록이 필요합니다.

1단계: OpenAPI 사양 가져오기

Apidog를 열고, 새 프로젝트를 생성한 다음, OpenAPI 3.x 파일을 가져옵니다. Apidog는 모든 경로, 스키마 및 예시를 구문 분석하고 프로젝트 내에 해당 엔드포인트를 생성합니다. 만약 API가 아직 OpenAPI로 문서화되지 않았다면, 지금이 바로 그럴 때입니다. 에이전트의 신뢰성은 사람과 AI 에이전트 모두가 읽는 단일 진실의 원천을 갖는 것에 달려있습니다. 처음부터 시작하는 경우 디자인 우선 API 워크플로 가이드가 이 과정을 안내합니다.

2단계: 파괴적인 엔드포인트에 대한 모의(Mock) 응답 정의

데이터를 변경하는 모든 엔드포인트(POST, PUT, PATCH, DELETE)를 찾으십시오. 각 엔드포인트에 대해 클릭하여 모의 응답을 추가하십시오. Apidog는 스키마에서 현실적인 모의 응답을 자동 생성할 수 있지만, 테스트 데이터처럼 보이도록 필드 값을 재정의해야 합니다(운영 데이터처럼 보이지 않도록). mock_user_와 같은 접두사와 1970년도 타임스탬프를 사용하여 로그에서 어떤 유출이라도 명확하게 드러나도록 하십시오.

모의 서버를 시작하십시오. Apidog는 https://mock.apidog.com/m1/your-project-id/와 같은 안정적인 URL을 제공합니다. 개발 중에 에이전트의 API 기본 URL을 모의 서버로 지정하십시오. 이제 DELETE /users/{id}는 가짜 사용자 페이로드와 함께 200을 반환하며, 실제 데이터베이스는 안전합니다.

3단계: 에이전트의 호출 시퀀스를 시뮬레이션하는 시나리오 작성

Apidog 시나리오를 사용하면 테스트 스위트와 동일한 방식으로 API 호출을 어설션과 연결할 수 있습니다. 지원 티켓을 분류하는 에이전트의 경우 시나리오는 다음과 같을 수 있습니다.

테스트 자격 증명으로 POST /auth/token을 호출하고, 베어러 토큰 캡처
토큰으로 GET /tickets?status=open을 호출하고, 첫 번째 티켓 ID 캡처
카테고리와 함께 POST /tickets/{id}/triage를 호출하고, 200을 어설션하며 할당된 필드 캡처
템플릿 메시지로 POST /notifications를 호출하고, 메시지 본문이 정규식과 일치하는지 어설션

여러분은 에이전트가 할 일을 모의 서버에서 각 단계마다 어설션과 함께 효과적으로 예행연습하는 것입니다. 만약 개발자가 티켓 스키마를 변경하고 정규식이 더 이상 일치하지 않으면 시나리오가 실패하며, 에이전트가 운영 환경에 배포되기 전에 이를 알게 됩니다. 더 넓은 시나리오 테스트 플레이북에 대해서는 QA 엔지니어를 위한 API 테스트를 참조하십시오.

4단계: CI에서 실행

Apidog는 GitHub Action, GitLab 파이프라인 또는 모든 CI 러너에서 시나리오를 실행하는 CLI를 제공합니다. 명령은 apidog run -t scenario-id --env test와 같습니다. 이것을 PR 파이프라인에 연결하여 OpenAPI 사양 또는 에이전트 도구 정의에 대한 모든 변경이 전체 시나리오 재연을 트리거하도록 하십시오.

5단계: 두 모델 버전 나란히 비교

한 모델에서 다른 모델로 업그레이드할지 여부를 평가할 때, 새 모델의 도구 호출이 동일한 시나리오에서 동일하게 작동하는지 알고 싶을 것입니다. 모델 A를 사용하여 동일한 Apidog 시나리오에 대해 에이전트를 실행하고, 트레이스를 캡처하십시오. 모델 B를 사용하여 다시 실행하고, 트레이스를 캡처하십시오. 요청 본문을 비교하십시오. 놀라운 점들이 즉시 나타날 것입니다: 모델 B가 다른 priority 값을 전달하거나, 필드를 생략하거나, 날짜에 다른 형식을 사용합니다. 여러분은 배포하기 전에 행동 변화를 잡아냅니다. 이는 새로운 모델 동작을 평가하는 것이 반복적으로 필요한 GPT-5.5 API 통합에서 다루는 패턴 중 하나입니다.

전체 워크플로는 처음 설정하는 데 약 1시간이 걸리며, 그 이후에는 실행당 몇 분이 소요됩니다. 그 대가는 API 또는 에이전트 도구에 대한 모든 변경 사항이 동일한 기대치 기준에 따라 실행된다는 것입니다.

고급 기술 및 전문가 팁

기본 사항이 갖춰진 후 숙련된 팀이 사용하는 몇 가지 패턴입니다.

테스트 시 온도를 0으로 고정하십시오. 비결정론적 에이전트는 비결정론적 테스트 실패를 야기합니다. 도구 호출 동작을 테스트할 때, 온도를 0으로 설정하고 모든 무작위성 소스를 시드하십시오. 여러분은 창의성 계층이 아닌 도구 계층을 테스트하는 것입니다.

도구 호출 트레이스 스냅샷을 찍으십시오. 모든 테스트 실행은 에이전트가 수행한 도구 호출의 정확한 순서를 인자와 함께 기록합니다. 이전 기준선과 비교하십시오. 만약 에이전트가 갑자기 /users를 한 번이 아닌 두 번 호출하기 시작한다면, 청구서가 도착하는 3주 후가 아니라 즉시 그 사실을 알아야 합니다.

에이전트에게 운영 환경 자격 증명을 절대 주지 마십시오. 에이전트는 범위가 지정된 서비스 계정을 갖습니다. 운영 자격 증명은 에이전트가 읽을 수 있는 .env 파일이 아닌 볼트에 저장됩니다. 에이전트가 운영 엔드포인트를 호출해야 하는 경우, 단기 토큰으로 요청에 서명하는 프록시를 통해 이루어집니다.

읽기 및 쓰기 API 키를 분리하십시오. 대부분의 에이전트 작업은 주로 읽기입니다. 이러한 작업에는 읽기 전용 키를 발급하십시오. 쓰기 키는 사람의 승인 게이트가 있는 작업에 예약됩니다. 이 한 가지 변경으로 손상된 에이전트의 피해 반경이 절반으로 줄어듭니다.

인간 승인 엔드포인트에 HTTP 423 Locked를 사용하십시오. 에이전트가 사람의 확인이 필요한 엔드포인트를 호출하려고 시도할 때, confirmation_url 필드와 함께 423을 반환하십시오. 에이전트의 플래너는 잠금 상태를 확인하고, URL을 사람에게 표시하며 기다립니다. 이는 403보다 깔끔한데, 403은 "이것을 할 수 없다"는 것을 의미하는 반면 423은 "아직 이것을 할 수 없다"는 것을 의미하기 때문입니다.

스키마 불일치 시 닫힌 상태로 실패하십시오. 에이전트의 도구 정의가 OpenAPI 사양과 일치하지 않으면 빌드가 실패합니다. 경고를 내보내지 마십시오. 오류를 내보내십시오. 몇 번의 추가 빌드 실패 비용은 한 번의 운영 사고 비용보다 훨씬 저렴합니다.

피해야 할 일반적인 실수:

모의 URL을 에이전트 프롬프트에 하드코딩하는 것. 동일한 프롬프트가 모의, 스테이징, 운영 환경에서 실행되도록 환경 변수를 사용하십시오.
"작은" 엔드포인트에서 멱등성을 건너뛰는 것. 모든 쓰기 작업에는 멱등성이 필요합니다. 이메일 전송도 예외는 아닙니다.
운영 환경에서 전체 요청 본문을 로깅하는 것. 개인 식별 정보(PII)가 관찰 가능성 스택으로 유출됩니다. 토큰, 이메일, 식별자는 로그에 도달하기 전에 수정(redact)하십시오.
에이전트가 데이터베이스에 직접 접근하도록 허용하는 것. 항상 API를 통해 접근하십시오. API는 여러분의 테스트가 존재하는 곳입니다.
에이전트의 신뢰도 점수를 믿는 것. 이 점수는 답변에 대한 모델의 확신을 반영할 뿐, API 안전성을 반영하는 것이 아닙니다. 99% 확신하는 에이전트도 여전히 잘못된 엔드포인트를 호출할 수 있습니다.

에이전트가 단일 API 게이트웨이 뒤에 있지 않은 내부 서비스와 통신하는 경우, 마이크로서비스 테스트 패턴에서 서비스 전반에 걸쳐 시나리오 테스트를 분산하는 방법을 다룹니다.

대안 및 도구

선택지는 다양합니다. 다음은 네 가지 일반적인 접근 방식에 대한 공정한 비교입니다.

접근 방식	설정 시간	강점	약점	가장 적합한 경우
수동 단위 테스트	낮음	완전한 제어, 벤더 종속성 없음	유지보수 비용 높음, 실제 API와 불일치하기 쉬움	소규모 프로젝트, 단일 개발자 팀
LangSmith / LangGraph 평가 하네스	중간	내장된 트레이스 재연, 모델 인식 메트릭	에이전트 측에 비중, API 측에 경량	평가 중심 AI 팀
Postman + Postbot	중간	친숙한 UI, 큰 템플릿 라이브러리	모의 서버는 유료 추가 기능, 시나리오 문법이 오래됨	이미 Postman에 투자한 팀
Apidog 시나리오 + 모의	중간	네이티브 OpenAPI, 무료 모의, CI용 시나리오 CLI	Postman보다 브랜드 인지도가 낮음	설계, 모의, 테스트를 위한 하나의 도구를 원하는 팀

솔직한 요약: LangSmith에 익숙하다면 에이전트 측에서 작동하는 방식을 계속 사용하고 별도의 API 테스트 계층을 추가하십시오. Postman의 가격 정책이나 모의 모델에서 벗어나고 싶다면, Apidog가 강력한 대안입니다. 새로 시작한다면 OpenAPI, 모의(mocks), 시나리오를 하나의 프로젝트에서 처리하는 도구를 선택하십시오. 에이전트-API 테스트 시간의 80%가 그곳에 할애되기 때문입니다.

일부 팀은 이들을 함께 사용합니다. 그들은 프롬프트 수준 평가에는 LangSmith를 유지하고, API 측 계약 테스트 및 시나리오 재연에는 Apidog를 사용합니다. 이는 잘 작동합니다. 각 도구가 다른 계층에 서비스를 제공하기 때문입니다.

실제 사용 사례

에이전트가 운영 데이터베이스 행을 업데이트합니다. 고객 성공 팀은 지원 티켓에서 계정 필드를 업데이트하는 에이전트를 구축했습니다. 출시 전, 그들은 모든 쓰기 엔드포인트가 멱등성 키를 요구하도록 연결하고, 샌드박스 데이터베이스에 대해 Apidog에서 200개의 시나리오 재연을 실행했습니다. 재연 과정에서 에이전트가 subscription_status를 열거형에 없는 문자열로 설정하려고 시도한 두 가지 경우를 발견했습니다. 그들은 스키마 유효성 검사를 추가하고 문제 없이 배포했습니다.

에이전트가 결제 API를 호출합니다. 자동 환불 에이전트를 구축하는 핀테크 팀은 세션당 최대 5회 환불, 환불당 최대 50달러, 모든 호출에 멱등성 필수라는 엄격한 제한을 설정했습니다. 그들은 모든 PR에서 Stripe의 OpenAPI에 대해 계약 테스트 스위트를 실행했습니다. 6개월 후, 그들은 중복 청구 없이 12,000건의 환불을 처리했습니다.

에이전트가 GitHub 이슈를 분류합니다. 플랫폼 팀은 Clawsweeper에서 영감을 받아 이슈 분류 에이전트를 구축했습니다. 그들은 Apidog에서 GitHub API를 모의(mock)하고, 에이전트를 통해 엣지 케이스(삭제된 이슈, 누락된 레이블, 잘못된 사용자 입력)를 다루는 50가지 시나리오 테스트를 실행하여 출시 전에 세 가지 충돌을 발견했습니다. 이제 에이전트는 5,000개의 열린 이슈가 있는 공개 저장소에서 분류를 처리합니다.

결론

이 가이드에서 한 가지를 얻어가야 한다면 이것입니다: 에이전트가 문제가 아닙니다. API가 문제입니다. 또는, 테스트 여부에 따라 해결책이 됩니다.

다섯 가지 핵심 사항:

도구 스키마를 계약으로 취급하고 CI에서 계약 테스트를 실행하십시오.
모든 에이전트 개발 루프를 위해 파괴적인 엔드포인트를 모의(mock)하십시오.
에이전트가 호출할 수 있는 모든 쓰기 작업에 멱등성 키를 요구하십시오.
제한에 도달하면 닫힌 상태로 실패하도록 에이전트별 예산 제한을 설정하십시오.
API 또는 도구 정의를 건드리는 모든 PR에서 시나리오를 재연하십시오.

올해의 바이럴 사고들이 마지막은 아닐 것입니다. 에이전트를 배포하는 모든 팀은 이러한 실패 모드 중 하나를 적어도 한 번은 겪게 될 것입니다. 빠르게 회복하는 팀은 이미 안전장치를 마련해 둔 팀입니다. Apidog를 다운로드하고 모의 서버 단계부터 시작하십시오. 그것만으로도 이번 분기에 밤샘을 피할 수 있을 것입니다. 이 동일한 문제에 대한 QA 팀의 관점은 QA 엔지니어를 위한 API 테스트 도구를 참조하십시오. 에이전트가 안전하게 사용할 수 있는 도구 정의를 작성하는 것에 대한 더 넓은 맥락은 AGENTS.md 파일을 작성하는 방법을 참조하십시오.

자주 묻는 질문 (FAQ)

토큰 비용 없이 AI 에이전트 API 호출을 테스트하는 방법은 무엇인가요?

개발 중에 모의 서버에 대해 에이전트를 실행하십시오. Apidog의 모의 URL은 무료로 현실적인 응답을 반환하므로, 테스트 루프가 실제 API 크레딧을 소모하지 않습니다. 온도를 0으로 고정하고 작은 고정 프롬프트 세트를 사용하십시오. 모의 서버 비용(0)으로 수천 번의 테스트 반복을 실행할 수 있습니다. 전체 설정은 QA 엔지니어의 테스트 체크리스트를 참조하십시오.

에이전트 테스트와 API 테스트의 차이점은 무엇인가요?

에이전트 테스트는 모델이 올바른 도구를 선택하고 인수를 올바르게 채우는지 확인합니다. API 테스트는 엔드포인트가 호출될 때 올바르게 작동하는지 확인합니다. 둘 다 중요합니다. 완벽한 에이전트가 손상된 API를 호출해도 여전히 손상된 결과를 초래하며, 손상된 에이전트가 완벽한 API를 호출해도 여전히 버그를 배포합니다. 두 계층 모두 별도로 테스트해야 합니다.

모든 엔드포인트에 멱등성 키가 필요한가요?

네, 모든 쓰기 엔드포인트에 필요합니다. 읽기(Read)는 정의상 멱등성이 있습니다. 쓰기(Write)는 그렇지 않으며, 에이전트는 재시도합니다. 멱등성 헤더를 지원하는 다섯 줄의 미들웨어 코드는 에이전트가 500 오류를 재시도했을 때 중복 행이 생성되지 않는 첫 번째 경우에 그 가치를 입증할 것입니다.

프롬프트 주입으로 인해 잘못된 API 호출이 트리거되는 것을 어떻게 방지하나요?

프롬프트 계층에만 의존하지 마십시오. API는 에이전트의 요청이 아닌, 원래 사용자 컨텍스트를 기반으로 권한 부여를 강제해야 합니다. 만약 사용자 컨텍스트 세션이 일반적으로 /admin/delete-all-users를 호출할 수 없다면, 프롬프트가 무엇이라고 말하든 그 사용자를 대신하는 에이전트도 그렇게 할 수 없어야 합니다. OWASP의 LLM Top 10에서 이를 자세히 다룹니다.

Apidog를 Claude 또는 GPT와 직접 사용할 수 있나요? 별도의 도구 계층을 작성할 필요 없이요?

테스트 중에 에이전트의 도구 정의를 Apidog 모의 URL로 지정합니다. Claude와 GPT 모두 도구 정의에서 임의의 HTTP 기본 URL을 지원하므로, 변경은 환경 변수 하나로 이루어집니다. 스테이징 또는 운영 환경에 대해 테스트할 준비가 되면 해당 변수를 변경하십시오.

에이전트에 대한 적절한 예산 제한은 얼마인가요?

엄격하게 시작하고 데이터를 통해 완화하십시오. 세션당 50,000 토큰, 분당 30 API 호출, 작업당 5달러로 시작하십시오. 2주 동안 메트릭을 관찰하십시오. 합리적으로 도달하는 상한선을 높이십시오. 결코 도달하지 않는 상한선은 낮추십시오. 매월 검토하십시오. 목표는 고정된 숫자가 아닙니다. 폭주하는 루프를 잡을 만큼 충분히 엄격하면서도 실제 작업이 진행될 수 있을 만큼 충분히 유연한 숫자입니다.

에이전트의 도구와 API 간의 스키마 불일치를 어떻게 감지하나요?

모든 PR에서 CI에서 스키마 차이(diff)를 실행하십시오. 에이전트의 도구 정의(JSON 스키마)와 동일한 엔드포인트에 대한 OpenAPI 요청 본문 스키마를 비교하십시오. 이들이 불일치하면 빌드를 실패시키십시오. 위 안전장치 섹션의 30줄 Python 코드 조각이 이 작업을 수행합니다. 이를 여러분의 리포지토리에 복사하여 GitHub Actions에 연결하십시오.