DEV Community

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

Posted on • Originally published at apidog.com

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

AI 코딩 에이전트가 스크립트를 실행하고 “성공”했다고 보고한 직후, 프로덕션 데이터베이스 테이블이 사라지는 사고가 있었습니다. Hacker News의 사후 분석 글은 “AI가 당신의 데이터베이스를 삭제한 것이 아니라, 당신이 한 일이다.”라는 제목으로 퍼졌습니다. 맞는 말입니다. 에이전트는 도구 정의를 따랐고, 도구는 실제 엔드포인트를 호출했으며, 엔드포인트에는 안전장치가 없었습니다. 사람은 DELETE FROM users가 의심스러운지 확인하지 않는 프로세스에 접근 권한을 넘겼습니다. r/ClaudeAI에서도 비슷한 사례가 있었습니다. 빌링 루프에 빠진 에이전트가 아무도 알아차리기 전에 수백 달러 상당의 토큰을 소모했습니다. 표면은 달랐지만 실패 유형은 같았습니다. 문제는 모델이 아니라, 테스트되지 않은 API였습니다.

오늘 Apidog를 사용해 보세요

💡 여러분의 API를 호출하는 자율 에이전트를 출시할 예정이라면, 개발 중 외부 엔드포인트를 모의(mock)하고, 파괴적인 작업을 샌드박스에서 실행하며, 도구 스키마에 대한 계약 테스트를 작성하고, 에이전트별 예산 상한을 설정해야 합니다. 이 글에서는 OpenAPI 가져오기, 모의 서버, 시나리오 테스트를 제공하는 Apidog를 테스트 스캐폴딩으로 사용합니다.

요약

에이전트는 API 측 안전장치가 없을 때 프로덕션에서 실패합니다. 대표적인 원인은 다음과 같습니다.

  • 누락된 비율 제한
  • 비멱등성 쓰기 작업
  • 즉시 실행되는 하드 삭제
  • API와 불일치하는 도구 스키마
  • 재시도 루프와 예산 제한 부재

해결책은 네 가지입니다.

  1. 에이전트의 도구 정의를 OpenAPI 사양에 대해 계약 테스트합니다.
  2. 파괴적인 엔드포인트는 모의 서버 또는 샌드박스에서 실행합니다.
  3. 에이전트별 예산 상한과 멱등성 키를 강제합니다.
  4. CI에서 실패 시나리오를 반복 실행합니다.

Apidog는 OpenAPI 가져오기, 모의 서버, 시나리오 러너를 하나의 프로젝트에서 제공합니다.

서론

1년 전 “AI 에이전트 테스트”는 Claude나 GPT에 프롬프트를 입력하고 응답 품질을 확인하는 정도였습니다. 이제는 다릅니다.

오늘날의 에이전트는 함수를 호출합니다. 그 함수는 API에 연결됩니다. API는 실제 데이터베이스, 결제 처리기, 이메일 시스템, 서드파티 서비스와 통신합니다.

따라서 잘못된 도구 정의나 누락된 비율 제한은 스타일 문제가 아닙니다. 프로덕션 사고입니다.

문제는 모델 계층에서만 해결되지 않습니다. 출혈을 막는 위치는 API 계층입니다. 이 글에서는 AI 에이전트와 API 통합을 테스트하는 실전 패턴을 다룹니다.

구체적으로 다음을 구현합니다.

  • OpenAPI 기반 도구 스키마 계약 테스트
  • 파괴적인 엔드포인트에 대한 mock 서버
  • 멱등성 키와 소프트 삭제
  • 에이전트별 예산 제한
  • CI에서 시나리오 재실행
  • 모델 버전 변경 시 도구 호출 비교

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

에이전트 사고를 분석하면 공통 패턴이 보입니다. 주인공은 모델이 아니라 API입니다.

프롬프트 주입

사용자가 숨겨진 지침이 포함된 PDF를 업로드했다고 가정해 봅시다. 에이전트가 이를 읽고 다음 도구 호출에서 /admin/users에 delete_all=true를 전달합니다.

모델은 “악의적으로” 선택한 것이 아닙니다. 신뢰할 수 없는 입력을 지침으로 받아들였을 뿐입니다.

해결책은 프롬프트만 강화하는 것이 아닙니다. 사용자 컨텍스트 세션에서 온 토큰이 delete_all=true 같은 작업을 수행하지 못하도록 API 권한 부여를 강제해야 합니다.

OWASP LLM Top 10의 LLM01도 같은 문제를 다룹니다. 핵심 완화책은 프롬프트 엔지니어링이 아니라 API 측 권한 부여입니다.

도구 스키마 오류

OpenAPI 사양에는 amount가 센트 단위의 정수라고 정의되어 있습니다.

{
  "amount": {
    "type": "integer",
    "description": "Amount in cents"
  }
}
Enter fullscreen mode Exit fullscreen mode

그런데 에이전트 도구 정의에는 달러 단위의 부동 소수점 숫자라고 되어 있습니다.

{
  "amount": {
    "type": "number",
    "description": "Amount in dollars"
  }
}
Enter fullscreen mode Exit fullscreen mode

이 경우 19센트 환불이 19달러 환불로 처리될 수 있습니다. 모델이 틀린 것이 아닙니다. 여러분이 제공한 스키마가 API와 불일치한 것입니다.

비율 제한 누락

재시도 루프에 빠진 에이전트가 2분 동안 트랜잭션 이메일 엔드포인트를 수천 번 호출할 수 있습니다.

각 재시도는 비용을 발생시킵니다. 각 호출은 실제 이메일을 대기열에 추가합니다. 사람이 알아차렸을 때는 이미 제공업체가 계정에 플래그를 지정하고 고객이 스팸을 받은 뒤일 수 있습니다.

멱등성 누락

에이전트가 POST /payments를 호출해 고객에게 요금을 청구합니다. 네트워크 타임아웃이 발생합니다. 플래너는 실패했다고 판단하고 재시도합니다. 고객은 두 번 결제됩니다.

에이전트 계층은 첫 번째 호출이 성공했는지 알 수 없습니다. API가 이를 확인할 방법을 제공하지 않았기 때문입니다.

이 문제는 멱등성 키로 해결할 수 있습니다. 하지만 API에서 직접 구현해야 합니다.

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

이번 분기에 하나만 추가할 시간이 있다면 첫 번째부터 시작하십시오. 네 가지를 모두 적용하면 대부분의 에이전트 사고를 API 계층에서 차단할 수 있습니다.

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 means 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}: "
                    f"API={api_def.get('type')} "
                    f"tool={tool_def_prop.get('type')}"
                )

    return errors
Enter fullscreen mode Exit fullscreen mode

CI에서는 다음처럼 사용합니다.

with open("openapi.json") as f:
    openapi_spec = json.load(f)

with open("agent_tools.json") as f:
    tools = json.load(f)

all_errors = []

for tool in tools:
    all_errors.extend(validate_tool_against_openapi(tool, openapi_spec))

if all_errors:
    for error in all_errors:
        print(error)
    raise SystemExit(1)
Enter fullscreen mode Exit fullscreen mode

OpenAPI 사양 또는 도구 정의가 변경되는 모든 PR에서 실행하십시오. 오류 목록이 비어 있지 않으면 빌드를 실패시키십시오.

2. 파괴적인 엔드포인트에 대한 샌드박스 및 mock 환경

에이전트에게는 연습할 환경이 필요합니다. 프로덕션에서 연습하게 해서는 안 됩니다.

기본 패턴은 다음과 같습니다.

  • 상태를 변경하는 모든 엔드포인트에 mock 응답을 제공합니다.
  • 에이전트 개발 루프는 mock 서버를 사용합니다.
  • 스테이징 테스트는 샌드박스 데이터베이스를 사용합니다.
  • 프로덕션은 사람이 승인한 배포 이후에만 접근합니다.

Apidog는 OpenAPI 사양에서 mock 응답을 생성할 수 있습니다. Faker 패턴을 사용해 현실적인 필드 값을 만들고, 에이전트의 기본 URL을 mock 서버로 지정해 도구 호출을 반복 실행할 수 있습니다.

예를 들어 에이전트가 실수로 다음 호출을 반복해도:

DELETE /users/123
Enter fullscreen mode Exit fullscreen mode

mock 서버에서는 가짜 사용자 응답만 반환됩니다. 실제 사용자 테이블은 변경되지 않습니다.

이 방식은 계약 우선 개발(contract-first development)과 잘 맞습니다.

3. 되돌릴 수 없는 작업에 대한 멱등성 키 및 소프트 삭제

에이전트가 호출할 수 있는 모든 쓰기 엔드포인트는 멱등성 키를 받아야 합니다.

또한 삭제는 기본적으로 소프트 삭제여야 합니다. 하드 삭제는 별도 경로로 분리하고 사람 승인을 요구하는 것이 안전합니다.

Express에서 멱등성 미들웨어는 다음처럼 시작할 수 있습니다.

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);
Enter fullscreen mode Exit fullscreen mode

에이전트는 논리적 작업마다 UUID를 생성하고 재시도 시 같은 키를 재사용해야 합니다.

import { randomUUID } from "crypto";

const idempotencyKey = randomUUID();

await fetch("https://api.example.com/payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({
    customerId: "cus_123",
    amount: 1900,
  }),
});
Enter fullscreen mode Exit fullscreen mode

첫 번째 호출이 성공했지만 네트워크 타임아웃이 발생해도, 두 번째 호출은 중복 결제 대신 캐시된 응답을 반환합니다.

이 패턴은 다음 사고를 막습니다.

  • 중복 결제
  • 중복 이메일 전송
  • CRM 중복 행 생성
  • 재시도로 인한 티켓 중복 생성

4. 에이전트별 예산 상한

모든 에이전트에는 예산이 필요합니다.

  • 토큰 예산
  • 요청 예산
  • 금액 예산
  • 시간 예산
  • 도구 호출 깊이 제한

예산이 소진되면 에이전트는 멈춰야 합니다. 예외를 두지 마십시오.

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

  • 세션당 토큰: 50,000개
  • 분당 API 호출: 30개
  • 누적 지출: 500센트
  • 도구 호출 깊이: 10단계

상한에 도달하면 HTTP 429를 반환합니다.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: api_calls_per_minute
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "error": "budget_exceeded",
  "limit": "api_calls_per_minute",
  "message": "Agent exceeded 30 API calls per minute"
}
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 에이전트 플래너는 다음 중 하나를 선택할 수 있습니다.

  • 사람에게 에스컬레이션
  • 작업 취소
  • Retry-After 이후 재시도
  • 더 작은 작업 단위로 분할

네 가지 안전장치는 서로 보완됩니다.

  • 계약 테스트는 스키마 오류를 잡습니다.
  • mock 서버는 파괴적인 호출을 격리합니다.
  • 멱등성은 재시도 폭주를 제어합니다.
  • 예산 제한은 무한 루프를 차단합니다.

목표는 “에이전트가 끔찍한 일을 했다”가 아니라 “에이전트가 429를 받고, 로그를 남기고, 도움을 요청했다”로 바꾸는 것입니다.

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

이제 Apidog에서 에이전트-API 테스트 워크플로를 구성해 보겠습니다.

필요한 것은 두 가지입니다.

  1. 에이전트가 호출하는 API의 OpenAPI 사양
  2. 에이전트의 도구 정의 목록

Apidog 프로젝트 인터페이스 스크린샷

1단계: OpenAPI 사양 가져오기

Apidog에서 새 프로젝트를 만들고 OpenAPI 3.x 파일을 가져옵니다.

Apidog는 다음을 프로젝트로 변환합니다.

  • paths
  • request schema
  • response schema
  • examples
  • parameters
  • authentication metadata

API가 아직 OpenAPI로 문서화되어 있지 않다면 먼저 사양을 작성하십시오. 에이전트 안정성은 사람과 AI 에이전트가 모두 읽는 단일 진실 소스(single source of truth)에 달려 있습니다.

처음부터 설계해야 한다면 디자인 우선 API 워크플로 가이드를 참고하십시오.

2단계: 파괴적인 엔드포인트에 대한 mock 응답 정의

상태를 변경하는 엔드포인트를 모두 찾습니다.

  • POST
  • PUT
  • PATCH
  • DELETE

각 엔드포인트에 mock 응답을 추가합니다.

Apidog는 스키마에서 mock 응답을 자동 생성할 수 있지만, 테스트 데이터임을 명확히 드러내도록 값을 재정의하는 것이 좋습니다.

예를 들어:

{
  "id": "mock_user_123",
  "email": "mock_user_123@example.test",
  "deleted_at": "1970-01-01T00:00:00.000Z"
}
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 로그에서 mock 데이터와 실제 데이터를 쉽게 구분할 수 있습니다.

이후 mock 서버를 시작합니다. Apidog는 다음과 같은 안정적인 URL을 제공합니다.

https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

개발 중에는 에이전트의 API 기본 URL을 이 mock 서버로 지정합니다.

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

이제 에이전트가 다음 호출을 하더라도 실제 DB는 변경되지 않습니다.

DELETE /users/{id}
Enter fullscreen mode Exit fullscreen mode

관련 개념은 계약 우선 개발(contract-first development)을 참고하십시오.

3단계: 에이전트 호출 시퀀스를 시나리오로 작성

Apidog 시나리오를 사용하면 여러 API 호출을 연결하고 각 단계에 어설션을 추가할 수 있습니다.

예를 들어 지원 티켓을 분류하는 에이전트라면 시나리오는 다음과 같습니다.

  1. 테스트 자격 증명으로 POST /auth/token 호출
  2. 응답에서 bearer token 캡처
  3. GET /tickets?status=open 호출
  4. 첫 번째 ticket ID 캡처
  5. POST /tickets/{id}/triage 호출
  6. 응답 상태 코드가 200인지 확인
  7. 할당된 담당자 필드가 존재하는지 확인
  8. POST /notifications 호출
  9. 메시지 본문이 정규식과 일치하는지 확인

예상 어설션은 다음과 같이 정의할 수 있습니다.

status == 200
body.assignee_id exists
body.category in ["billing", "bug", "question"]
body.message matches /^Hello/
Enter fullscreen mode Exit fullscreen mode

이 시나리오는 실제로 에이전트가 수행할 작업을 mock 서버에서 예행연습합니다.

개발자가 티켓 스키마를 변경해 category 값이 달라지면 시나리오가 실패합니다. 에이전트가 프로덕션을 호출하기 전에 문제를 발견할 수 있습니다.

더 넓은 테스트 플레이북은 QA 엔지니어를 위한 API 테스트를 참고하십시오.

4단계: CI에서 실행

Apidog는 GitHub Actions, GitLab CI 또는 일반 CI 러너에서 시나리오를 실행할 수 있는 CLI를 제공합니다.

예시는 다음과 같습니다.

apidog run -t scenario-id --env test
Enter fullscreen mode Exit fullscreen mode

PR 파이프라인에서는 다음 변경이 발생할 때 시나리오를 재실행하십시오.

  • OpenAPI 사양 변경
  • 에이전트 도구 정의 변경
  • 인증 정책 변경
  • 쓰기 엔드포인트 변경
  • 결제, 삭제, 알림 관련 코드 변경

GitHub Actions 예시는 다음과 같이 구성할 수 있습니다.

name: Agent API Contract Tests

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agent_tools/**"
      - "src/api/**"

jobs:
  test-agent-api:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run Apidog scenario
        run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} --env test
Enter fullscreen mode Exit fullscreen mode

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

모델 A에서 모델 B로 업그레이드할 때는 응답 품질만 보면 안 됩니다. 도구 호출이 어떻게 달라지는지도 확인해야 합니다.

테스트 방법은 다음과 같습니다.

  1. 모델 A로 동일한 Apidog 시나리오를 실행합니다.
  2. 도구 호출 트레이스를 저장합니다.
  3. 모델 B로 같은 시나리오를 실행합니다.
  4. 요청 본문과 호출 순서를 비교합니다.

비교할 항목은 다음과 같습니다.

  • 호출한 엔드포인트
  • HTTP method
  • request body
  • 누락된 필드
  • enum 값 변화
  • 날짜 형식 변화
  • 호출 횟수 증가
  • 재시도 패턴

예를 들어 모델 B가 다음처럼 다른 값을 전달할 수 있습니다.

{
-  "priority": "medium"
+  "priority": "normal"
}
Enter fullscreen mode Exit fullscreen mode

또는 날짜 형식이 바뀔 수 있습니다.

{
-  "due_date": "2026-05-06"
+  "due_date": "May 6, 2026"
}
Enter fullscreen mode Exit fullscreen mode

이런 변화는 배포 전에 잡아야 합니다. 새로운 모델 동작 평가에 대한 패턴은 GPT-5.5 API 통합에서도 다룹니다.

고급 기술 및 전문가 팁

기본 안전장치를 적용했다면 다음 패턴을 추가하십시오.

테스트 시 temperature를 0으로 고정

도구 호출 동작을 테스트할 때는 비결정성을 줄여야 합니다.

{
  "temperature": 0,
  "top_p": 1
}
Enter fullscreen mode Exit fullscreen mode

에이전트의 창의성을 테스트하는 것이 아니라 API 도구 계층을 테스트하는 것입니다.

도구 호출 트레이스를 스냅샷

각 테스트 실행에서 다음을 저장하십시오.

  • 호출 순서
  • 엔드포인트
  • request body
  • response status
  • retry count
  • budget usage

이전 기준선과 비교합니다. 에이전트가 /users를 한 번 호출하다가 갑자기 두 번 호출하기 시작했다면, 청구서가 나온 뒤가 아니라 PR 단계에서 알아야 합니다.

프로덕션 자격 증명을 에이전트에 직접 주지 않기

에이전트에는 범위가 제한된 서비스 계정만 제공하십시오.

프로덕션 자격 증명은 에이전트가 읽을 수 있는 .env 파일이 아니라 vault에 보관해야 합니다.

프로덕션 엔드포인트 호출이 필요하다면 다음 구조를 사용하십시오.

Agent -> Proxy -> Short-lived token -> Production API
Enter fullscreen mode Exit fullscreen mode

읽기 키와 쓰기 키 분리

대부분의 에이전트 작업은 읽기 중심입니다.

읽기 전용 작업에는 read-only key를 발급하십시오. 쓰기 키는 사람 승인 게이트가 있는 작업에만 사용합니다.

AGENT_READ_API_KEY=...
AGENT_WRITE_API_KEY=...
Enter fullscreen mode Exit fullscreen mode

이 한 가지 분리만으로 손상된 에이전트의 피해 범위를 크게 줄일 수 있습니다.

사람 승인이 필요한 작업에는 HTTP 423 사용

에이전트가 사람 확인이 필요한 엔드포인트를 호출하면 403 Forbidden보다 423 Locked가 더 명확합니다.

HTTP/1.1 423 Locked
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "error": "human_confirmation_required",
  "confirmation_url": "https://app.example.com/confirm/task_123"
}
Enter fullscreen mode Exit fullscreen mode

403은 “할 수 없다”에 가깝고, 423은 “아직 할 수 없다”에 가깝습니다. 에이전트 플래너는 URL을 사람에게 표시하고 대기할 수 있습니다.

스키마 드리프트는 경고가 아니라 실패로 처리

도구 정의가 OpenAPI 사양과 다르면 빌드를 실패시키십시오.

경고만 보내면 무시됩니다. 실패해야 수정됩니다.

피해야 할 일반적인 실수

  • mock URL을 프롬프트에 하드코딩하지 마십시오. 환경 변수를 사용하십시오.
  • “작은” 쓰기 엔드포인트라고 멱등성을 생략하지 마십시오.
  • 프로덕션에서 전체 request body를 로깅하지 마십시오. PII가 유출됩니다.
  • 에이전트가 데이터베이스에 직접 접근하게 하지 마십시오. 항상 API를 통과시키십시오.
  • 에이전트의 confidence score를 API 안전성과 혼동하지 마십시오.
  • 삭제 엔드포인트를 하드 삭제로 바로 연결하지 마십시오.
  • 테스트 중 temperature를 높게 두지 마십시오.

에이전트가 단일 API 게이트웨이 뒤에 있지 않은 내부 서비스와 통신한다면 마이크로서비스 테스트 패턴을 참고하십시오.

대안 및 도구

접근 방식 설정 시간 강점 약점 가장 적합한 경우
수작업 단위 테스트 낮음 완전한 제어, 공급업체 종속성 없음 유지보수 비용 높음, 실제 API와 쉽게 불일치 소규모 프로젝트, 단일 개발자 팀
LangSmith / LangGraph 평가 하네스 중간 트레이스 재생, 모델 인식 지표 에이전트 측에 집중, API 측 테스트는 약함 평가 중심 AI 팀
Postman + Postbot 중간 익숙한 UI, 방대한 템플릿 mock 서버가 유료 기능일 수 있음, 시나리오 구문이 오래됨 이미 Postman에 투자한 팀
Apidog 시나리오 + mock 중간 OpenAPI 중심, mock 서버, CI용 시나리오 CLI Postman보다 낮은 브랜드 인지도 디자인, mock, 테스트를 하나로 관리하려는 팀

이미 LangSmith를 사용 중이라면 에이전트 측 평가는 유지하고, 별도의 API 테스트 계층을 추가하십시오.

Postman의 가격 정책이나 mock 모델이 맞지 않는다면 Apidog는 강력한 대안입니다.

새로 시작한다면 OpenAPI, mock 서버, 시나리오 테스트를 한 프로젝트에서 처리하는 도구를 선택하는 것이 좋습니다. 에이전트-API 테스트 시간의 대부분은 이 세 영역에서 발생합니다.

실제 사용 사례

에이전트가 프로덕션 데이터베이스 행을 업데이트하는 경우

고객 성공 팀이 지원 티켓에서 계정 필드를 업데이트하는 에이전트를 만들었다고 가정합니다.

출시 전 적용할 체크리스트는 다음과 같습니다.

  • 모든 쓰기 엔드포인트에 Idempotency-Key 요구
  • 샌드박스 DB에서 Apidog 시나리오 200회 재실행
  • enum 필드에 서버 측 검증 추가
  • 쓰기 키를 별도로 분리
  • 사람 승인 없이 하드 삭제 금지

이 재실행 과정에서 에이전트가 subscription_status에 enum에 없는 문자열을 보내는 경우를 발견할 수 있습니다. 프로덕션 출시 전에 스키마 검증을 추가하면 사고를 막을 수 있습니다.

에이전트가 결제 API를 호출하는 경우

자동 환불 에이전트에는 제한을 강하게 걸어야 합니다.

예시 정책은 다음과 같습니다.

  • 세션당 최대 5회 환불
  • 환불당 최대 50달러
  • 모든 호출에 멱등성 키 필수
  • 고위험 환불은 사람 승인 필요
  • 모든 PR에서 계약 테스트 스위트 실행

결제 API는 “나중에 수정”할 수 있는 계층이 아닙니다. 처음부터 제한을 걸어야 합니다.

에이전트가 GitHub 이슈를 분류하는 경우

플랫폼 팀이 Clawsweeper에서 영감을 받아 이슈 분류 에이전트를 만든다고 가정합니다.

출시 전 테스트 시나리오는 다음을 포함해야 합니다.

  • 삭제된 이슈
  • 누락된 레이블
  • 권한 없는 사용자
  • 잘못된 markdown 입력
  • rate limit 응답
  • GitHub API 500 응답
  • 중복 triage 요청

GitHub API를 Apidog에서 mock하고 50개 이상의 엣지 케이스 시나리오를 실행하면, 실제 저장소에 배포하기 전에 충돌을 발견할 수 있습니다.

결론

이 글에서 한 가지만 기억한다면 이것입니다.

문제는 에이전트가 아닙니다. API가 문제이거나, API가 해결책입니다. 차이는 테스트 여부입니다.

실행 체크리스트는 다음과 같습니다.

  • 도구 스키마를 계약으로 취급하고 CI에서 테스트하십시오.
  • 모든 에이전트 개발 루프에서 파괴적인 엔드포인트를 mock하십시오.
  • 에이전트가 호출할 수 있는 모든 쓰기 작업에 멱등성 키를 요구하십시오.
  • 에이전트별 예산 상한을 설정하고, 초과 시 실패하게 하십시오.
  • API 또는 도구 정의에 영향을 주는 모든 PR에서 시나리오를 재실행하십시오.

에이전트 사고는 계속 발생할 것입니다. 빠르게 복구하는 팀은 이미 안전장치를 마련한 팀입니다.

Apidog를 다운로드하고 mock 서버 단계부터 시작하십시오. 이 한 단계만으로도 프로덕션 사고 가능성을 크게 줄일 수 있습니다.

QA 팀 관점의 API 테스트는 QA 엔지니어를 위한 API 테스트 도구를 참고하십시오. 에이전트가 안전하게 사용할 수 있는 도구 정의 작성은 AGENTS.md 파일을 작성하는 방법을 참고하십시오.

자주 묻는 질문

토큰 비용을 들이지 않고 AI 에이전트 API 호출을 테스트하려면 어떻게 해야 합니까?

개발 중에는 mock 서버에 대해 에이전트를 실행하십시오. Apidog의 mock URL은 실제와 유사한 응답을 반환하므로 테스트 루프가 실제 API 크레딧을 소모하지 않습니다.

추가로 다음을 적용하십시오.

  • temperature를 0으로 고정
  • 작은 고정 프롬프트 세트 사용
  • 도구 호출 트레이스 저장
  • 동일 시나리오 반복 실행

전체 체크리스트는 QA 엔지니어의 테스트 체크리스트를 참고하십시오.

에이전트 테스트와 API 테스트의 차이점은 무엇입니까?

에이전트 테스트는 모델이 올바른 도구를 선택하고 인수를 올바르게 채우는지 확인합니다.

API 테스트는 엔드포인트가 호출되었을 때 서버가 올바르게 동작하는지 확인합니다.

둘 다 필요합니다.

  • 완벽한 에이전트가 깨진 API를 호출하면 결과는 깨집니다.
  • 완벽한 API를 깨진 에이전트가 호출해도 결과는 깨집니다.

두 계층은 별도로 테스트해야 합니다.

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

읽기 엔드포인트는 정의상 멱등적입니다. 하지만 모든 쓰기 엔드포인트에는 멱등성 키가 필요합니다.

대상은 다음과 같습니다.

  • 결제
  • 환불
  • 이메일 전송
  • 알림 발송
  • 티켓 생성
  • CRM 업데이트
  • 파일 업로드
  • 삭제 요청

에이전트는 실패를 재시도합니다. API가 중복 처리를 막아야 합니다.

프롬프트 주입이 잘못된 API 호출을 유발하는 것을 어떻게 방지합니까?

프롬프트 계층에만 의존하지 마십시오.

API는 에이전트의 요청 문장이 아니라 원래 사용자 컨텍스트를 기반으로 권한 부여를 강제해야 합니다.

예를 들어 일반 사용자가 /admin/delete-all-users를 호출할 수 없다면, 그 사용자를 대신하는 에이전트도 호출할 수 없어야 합니다.

프롬프트 내용과 관계없이 서버 측 권한 검사가 최종 방어선이어야 합니다.

Claude 또는 GPT와 Apidog를 직접 사용할 수 있습니까?

테스트 중 에이전트의 도구 정의를 Apidog mock URL로 지정하면 됩니다.

환경 변수 하나로 전환할 수 있게 구성하십시오.

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

스테이징 또는 프로덕션 테스트가 필요하면 같은 변수만 변경합니다.

AGENT_API_BASE_URL=https://staging-api.example.com
Enter fullscreen mode Exit fullscreen mode

프롬프트는 그대로 두고 실행 환경만 바꾸는 것이 안전합니다.

에이전트의 적절한 예산 상한은 얼마입니까?

처음에는 엄격하게 시작하고 지표를 보고 완화하십시오.

초기값 예시는 다음과 같습니다.

  • 세션당 50,000 토큰
  • 분당 30 API 호출
  • 작업당 5달러
  • 도구 호출 깊이 10
  • 세션 시간 10분

2주 동안 관찰한 뒤 조정하십시오.

목표는 고정된 숫자가 아닙니다. 폭주 루프를 잡을 만큼 엄격하고, 실제 작업이 진행될 만큼 유연한 상한입니다.

에이전트 도구와 API 간 스키마 드리프트를 어떻게 감지합니까?

모든 PR에서 CI로 스키마 diff를 실행하십시오.

비교 대상은 다음입니다.

  • 에이전트 도구 정의의 JSON Schema
  • 동일 엔드포인트의 OpenAPI request body schema
  • required field
  • enum
  • type
  • format
  • nullable 여부

불일치가 있으면 빌드를 실패시키십시오. 위의 Python 스니펫을 저장소에 복사하고 GitHub Actions에 연결하면 됩니다.

Top comments (0)