DEV Community

Cover image for Apidog로 AI 에이전트 툴 호출 테스트 방법: 운영 환경 장애 사전 방지
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Apidog로 AI 에이전트 툴 호출 테스트 방법: 운영 환경 장애 사전 방지

AI 에이전트는 자신이 호출하는 API만큼만 신뢰할 수 있습니다. 모델은 도구를 선택하고, 인수를 채우고, 요청을 보냅니다. 요청이 실패하거나, 잘못된 형식으로 반환되거나, 타임아웃되면 에이전트는 잘못된 데이터를 근거로 확신에 찬 결정을 내립니다. 데모에서는 이 문제가 잘 보이지 않지만, 운영 환경에서는 에이전트의 신뢰성을 좌우하는 핵심 지점입니다.

지금 Apidog 사용해 보기

이 글에서는 실제 도구를 호출하는 AI 에이전트를 구축하는 방법과, Apidog를 API 계층 및 테스트 하네스로 사용하는 방법을 다룹니다. 도구 엔드포인트를 설계하고, 오프라인 개발용 목업을 만들고, 사용자에게 도달하기 전에 잘못된 도구 호출을 잡아내는 단언(assertion)을 작성합니다. 목표는 “한 번 잘 동작한 데모”가 아니라, 테스트로 검증된 에이전트를 만드는 것입니다.

에이전트가 API 계층에서 실제로 하는 일

에이전트 루프를 단순화하면 다음과 같습니다.

  1. 모델이 사용자 목표와 사용 가능한 도구 목록을 받습니다.
  2. 모델이 도구 이름과 JSON 인수를 포함한 도구 호출을 반환합니다.
  3. 애플리케이션 코드가 해당 도구 호출을 실행합니다. 대부분 HTTP API 요청입니다.
  4. API 응답이 다시 모델에 전달됩니다.
  5. 모델이 추가 도구를 호출하거나 최종 답변을 생성합니다.

실패는 주로 3단계와 4단계에서 발생합니다.

  • 모델이 존재하지 않는 인수를 생성합니다.
  • API가 400, 422, 500을 반환합니다.
  • 응답 스키마가 변경됩니다.
  • 요청이 타임아웃됩니다.
  • 루프 중간에 속도 제한에 걸립니다.

새로운 API 소비자인 AI 에이전트에서 설명한 것처럼, 에이전트는 결국 API를 호출하는 클라이언트입니다. 따라서 다른 API 클라이언트와 동일하게 계약, 목업, 테스트, 오류 처리가 필요합니다.

작업은 두 가지로 나눌 수 있습니다.

  1. 도구를 실제 테스트 가능한 API 작업으로 정의합니다.
  2. 에이전트가 정상 조건과 실패 조건 모두에서 도구를 올바르게 호출하는지 검증합니다.

1단계: 도구를 실제 API 작업으로 설계하기

에이전트 코드를 작성하기 전에, 각 도구를 Apidog에서 API 엔드포인트로 정의하세요.

예를 들어 get_weather 도구가 있다면 이는 사실상 다음 API 작업과 같습니다.

GET /weather?city=Tokyo
Enter fullscreen mode Exit fullscreen mode

도구 스키마와 API 스키마는 동일한 계약을 공유해야 합니다.

  • 입력 파라미터
  • 필수 여부
  • 타입
  • 응답 구조
  • 오류 응답

Apidog에서 각 도구를 OpenAPI 스키마 기반 엔드포인트로 생성합니다.

예시:

paths:
  /weather:
    get:
      summary: Get current weather
      parameters:
        - name: city
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Weather response
          content:
            application/json:
              schema:
                type: object
                required:
                  - city
                  - temperature
                  - condition
                properties:
                  city:
                    type: string
                  temperature:
                    type: number
                  condition:
                    type: string
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 다음을 얻을 수 있습니다.

  • 에이전트 프롬프트와 테스트가 함께 참조할 단일 계약
  • 모델에 제공할 도구 정의의 기반 문서
  • 응답이 스키마와 달라질 때 즉시 감지할 수 있는 검증 기준

이 스키마 우선 접근 방식은 일반적인 API 설계와 동일합니다. 에이전트에서는 특히 중요합니다. 도구 정의와 실제 엔드포인트가 같은 스키마에서 나오면, 모델이 API가 지원하지 않는 도구 형태를 호출할 가능성을 줄일 수 있습니다.

2단계: 오프라인 개발을 위해 도구 목업(Mock)하기

에이전트 개발 중 매번 라이브 API를 호출할 필요는 없습니다.

라이브 API는 다음 문제를 만들 수 있습니다.

  • 아직 구현되지 않았을 수 있습니다.
  • 호출 비용이 발생할 수 있습니다.
  • 속도 제한에 걸릴 수 있습니다.
  • 테스트 결과가 외부 상태에 따라 달라질 수 있습니다.

Apidog는 정의한 스키마를 기반으로 목업 서버를 생성할 수 있습니다. 각 도구 엔드포인트는 실제 백엔드 없이도 스키마에 맞는 샘플 응답을 반환합니다.

이를 사용하면 다음이 가능합니다.

  • 실제 API 구현 전에 전체 에이전트 루프 개발
  • CI에서 유료 또는 외부 API 호출 없이 통합 테스트 실행
  • 빈 결과, 500 오류, 잘못된 필드 타입 등 특정 응답 강제
  • 모델이 실패 상황에서 어떻게 행동하는지 반복적으로 확인

개발 환경에서는 에이전트의 도구 실행기가 Apidog 목업 URL을 바라보게 합니다.

TOOL_BASE_URL=https://mock.apidog.example
Enter fullscreen mode Exit fullscreen mode

프로덕션에서는 같은 코드가 실제 API를 바라보게 합니다.

TOOL_BASE_URL=https://api.example.com
Enter fullscreen mode Exit fullscreen mode

즉, 환경 변수만 바꾸면 됩니다.

목업은 에이전트 개발을 빠르고 결정론적으로 만듭니다. 이 방식은 AI 에이전트 테스트 워크플로의 핵심입니다.

3단계: 에이전트가 도구를 호출하도록 연결하기

엔드포인트와 목업이 준비되면 에이전트 코드는 단순해야 합니다.

아래 예시는 Claude Messages API를 사용하는 도구 호출 루프입니다. 도구 정의는 Apidog에서 정의한 API 스키마를 반영합니다.

import os
import anthropic
import requests

client = anthropic.Anthropic()

# 개발 환경: Apidog 목업 URL
# 프로덕션 환경: 실제 API URL
TOOL_BASE = os.environ["TOOL_BASE_URL"]

tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string"
                }
            },
            "required": ["city"],
        },
    }
]

def run_tool(name, args):
    if name == "get_weather":
        response = requests.get(
            f"{TOOL_BASE}/weather",
            params={"city": args["city"]},
            timeout=10,
        )
        response.raise_for_status()
        return response.json()

    raise ValueError(f"Unknown tool: {name}")

messages = [
    {
        "role": "user",
        "content": "What should I wear in Tokyo today?"
    }
]

while True:
    resp = client.messages.create(
        model="claude-fable-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

    if resp.stop_reason == "tool_use":
        block = next(b for b in resp.content if b.type == "tool_use")

        result = run_tool(block.name, block.input)

        messages.append({
            "role": "assistant",
            "content": resp.content,
        })

        messages.append({
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": str(result),
                }
            ],
        })
    else:
        print(resp.content[0].text)
        break
Enter fullscreen mode Exit fullscreen mode

여기서 중요한 부분은 모델 호출보다 다음 두 줄입니다.

timeout=10
response.raise_for_status()
Enter fullscreen mode Exit fullscreen mode

이 두 줄은 실패한 요청을 명확히 실패로 처리합니다. 그렇지 않으면 에이전트가 중단된 요청이나 오류 응답을 정상 데이터처럼 다시 모델에 전달할 수 있습니다.

에이전트가 API 워크플로에 어떻게 적용되는지 더 넓게 보고 싶다면 API 워크플로를 위한 5가지 AI 에이전트를 참고할 수 있습니다.

4단계: 도구 호출을 테스트하기

에이전트 테스트에서 가장 자주 빠지는 부분은 도구 자체의 테스트입니다.

모델을 실행하기 전에 각 도구 엔드포인트를 독립적으로 테스트하세요. 에이전트의 신뢰성은 도구의 신뢰성보다 높을 수 없습니다.

Apidog에 저장된 요청으로 각 도구 엔드포인트를 실행하고 다음을 단언합니다.

  • 유효한 입력에 대해 상태 코드가 200인지
  • 응답 본문이 OpenAPI 스키마와 일치하는지
  • 모델이 읽을 필수 필드가 존재하는지
  • 각 필드 타입이 올바른지
  • 응답 시간이 에이전트의 타임아웃보다 짧은지

예를 들어 GET /weather?city=Tokyo에 대해 다음을 확인합니다.

{
  "city": "Tokyo",
  "temperature": 24.5,
  "condition": "cloudy"
}
Enter fullscreen mode Exit fullscreen mode

검증해야 할 항목은 다음과 같습니다.

status == 200
body.city is string
body.temperature is number
body.condition is string
response_time < 10000ms
Enter fullscreen mode Exit fullscreen mode

정상 경로만 테스트하지 마세요. 에이전트는 주로 실패 경로에서 망가집니다.

다음 케이스를 추가로 테스트합니다.

  • city가 빈 문자열인 경우
  • city에 숫자가 들어온 경우
  • 필수 파라미터가 누락된 경우
  • API가 500을 반환하는 경우
  • 응답 본문이 스키마와 다른 경우
  • 결과가 없는 경우

예시 요청:

GET /weather?city=
Enter fullscreen mode Exit fullscreen mode

기대 결과:

422 Unprocessable Entity
Enter fullscreen mode Exit fullscreen mode

잘못된 입력이 들어왔을 때 500이 아니라 400 또는 422로 명확히 실패해야 합니다. 그래야 에이전트가 잘못된 호출과 서버 장애를 구분할 수 있습니다.

이는 에이전트 도구에 적용하는 계약 테스트입니다. API 계약 테스트와 같은 원칙을 모델이 호출하는 엔드포인트에 적용하는 것입니다.

응답 형태가 변경되면 CI에서 테스트가 실패해야 합니다. 에이전트가 손상된 페이로드를 기반으로 추론하기 전에 문제를 잡아야 합니다.

5단계: 재시도, 타임아웃, 속도 제한 처리하기

에이전트는 불안정한 API를 증폭시킵니다.

일반 애플리케이션에서는 실패한 요청을 한 번 재시도하면 끝날 수 있습니다. 하지만 에이전트 루프에서는 모델이 같은 도구를 반복 호출하며 속도 제한과 비용을 빠르게 소모할 수 있습니다.

다음 제어 장치를 구현하고 테스트하세요.

타임아웃

모든 도구 요청에 명시적인 타임아웃을 설정합니다.

requests.get(url, timeout=10)
Enter fullscreen mode Exit fullscreen mode

Apidog 목업으로 느린 응답을 시뮬레이션하고, 클라이언트가 전체 루프를 멈추지 않고 깔끔하게 실패하는지 확인합니다.

백오프를 사용한 재시도

일시적인 실패는 재시도할 수 있습니다. 단, 횟수 제한과 백오프가 있어야 합니다.

예시:

import time
import requests

def get_with_retry(url, params, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            response = requests.get(url, params=params, timeout=10)
            response.raise_for_status()
            return response.json()
        except requests.RequestException:
            if attempt == max_attempts - 1:
                raise

            sleep_seconds = 2 ** attempt
            time.sleep(sleep_seconds)
Enter fullscreen mode Exit fullscreen mode

테스트할 시나리오:

  • 첫 번째 요청 실패 후 두 번째 요청 성공
  • 두 번 실패 후 세 번째 요청 성공
  • 모든 재시도 실패 후 예외 발생

에이전트가 무한 루프에 빠지지 않는지 확인해야 합니다.

속도 제한

429 Too Many Requests를 예상해야 합니다.

Apidog 목업에서 429 응답을 만들고, 에이전트가 계속 요청을 보내지 않고 기다리거나 실패를 보고하는지 테스트합니다.

원시 모델 API에서도 GPT API 속도 제한 문제가 발생할 수 있습니다. 에이전트에서는 루프가 호출을 증폭하므로 더 엄격하게 다뤄야 합니다.

서킷 브레이커

특정 도구가 N번 연속 실패하면 더 이상 호출하지 않도록 차단합니다.

예시 정책:

get_weather가 3회 연속 실패하면 현재 에이전트 실행에서 해당 도구 호출 중단
Enter fullscreen mode Exit fullscreen mode

이후 에이전트는 계속 시도하는 대신 다음과 같이 보고해야 합니다.

현재 날씨 API가 응답하지 않아 도구 호출을 완료할 수 없습니다.
Enter fullscreen mode Exit fullscreen mode

Apidog에서 반복 가능한 실패 시나리오를 만들어 서킷 브레이커가 실제로 동작하는지 검증하세요.

6단계: CI에서 목업 기반 E2E 테스트 실행하기

마지막으로 전체 루프를 CI에 연결합니다.

CI에서는 에이전트가 Apidog 목업 서버를 바라보게 합니다.

TOOL_BASE_URL=https://mock.apidog.example
Enter fullscreen mode Exit fullscreen mode

그다음 고정된 사용자 목표를 입력합니다.

What should I wear in Tokyo today?
Enter fullscreen mode Exit fullscreen mode

그리고 다음을 단언합니다.

  • 에이전트가 예상한 도구를 호출했는지
  • 도구 인수가 올바른지
  • 도구 호출 횟수가 제한 안에 있는지
  • 최종 답변이 빈 값이 아닌지
  • 오류 응답에서 허위 답변을 만들지 않는지

목업은 결정론적이므로 동일한 입력은 매번 동일한 응답을 반환합니다. 이 방식은 에이전트 테스트의 불안정성을 줄입니다.

권장 구성은 다음과 같습니다.

테스트 유형 대상 목적
도구 계약 테스트 Apidog 요청 API 스키마와 응답 검증
목업 기반 E2E Apidog 목업 전체 에이전트 루프 검증
라이브 스모크 테스트 실제 API 운영 환경 기본 확인

대부분의 테스트는 결정론적 목업에서 실행하고, 실제 API 호출은 작은 스모크 테스트로 제한합니다. 이 분리는 에이전트 기반 AI 테스트를 실용적으로 만듭니다.

신뢰할 수 있는 에이전트를 위한 체크리스트

  • [ ] 모든 도구가 OpenAPI 스키마를 가진 실제 API 작업으로 정의되어 있다.
  • [ ] 모든 도구에 대해 오프라인 개발용 목업이 존재한다.
  • [ ] 각 도구 엔드포인트에 상태 코드, 스키마, 응답 시간 단언이 있다.
  • [ ] 잘못된 인수, 오류 응답, 빈 결과가 명시적으로 테스트된다.
  • [ ] 모든 도구 요청에 타임아웃이 설정되어 있다.
  • [ ] 재시도에는 횟수 제한과 백오프가 있다.
  • [ ] 429 속도 제한 응답을 처리한다.
  • [ ] 반복 실패 시 서킷 브레이커가 동작한다.
  • [ ] CI에서 목업 기반 E2E 테스트가 실행된다.
  • [ ] 실제 API에 대해서는 별도의 작은 스모크 테스트를 실행한다.

이 항목들을 충족하면 에이전트의 신뢰성을 감이 아니라 테스트 결과로 설명할 수 있습니다.

자주 묻는 질문

에이전트 전체를 실행하면 되는데 왜 API 클라이언트로 도구를 따로 테스트해야 하나요?

에이전트 전체를 실행하면 모델 추론과 API 계층이 함께 섞여 실패 원인을 파악하기 어렵습니다. Apidog에서 각 도구 엔드포인트를 독립적으로 테스트하면 문제가 모델의 판단인지, API 계약 위반인지 분리할 수 있습니다.

에이전트를 만들기 전에 실제 API를 먼저 구현해야 하나요?

아닙니다. Apidog에서 도구 계약을 스키마로 정의하고 목업을 생성하면 실제 API 없이도 전체 에이전트 루프를 개발할 수 있습니다. 이후 환경 변수로 실제 API URL만 교체하면 됩니다.

실패하는 도구 때문에 에이전트가 무한 루프에 빠지는 것을 어떻게 막나요?

재시도 횟수를 제한하고, 백오프를 적용하고, 반복 실패 후 서킷 브레이커를 작동시켜야 합니다. 각 제어 장치는 오류를 반환하는 목업에 대해 테스트해야 합니다.

모델 및 API 호출 비용 없이 에이전트를 테스트할 수 있나요?

대부분 가능합니다. 도구 API를 Apidog에서 목업하고 결정론적 통합 테스트를 실행하세요. 라이브 모델 호출과 실제 API 호출은 작은 스모크 테스트로 제한하는 것이 좋습니다.

LangChain이나 Claude Agent SDK 같은 프레임워크에서도 적용되나요?

네. 도구 계층은 결국 HTTP 호출입니다. 어떤 프레임워크가 에이전트 루프를 실행하든, 개발과 테스트에서는 Apidog 목업을 바라보게 하고 프로덕션에서는 실제 엔드포인트를 바라보게 설정하면 됩니다. Claude 기반 루프는 Claude Code SDK 가이드를 참고할 수 있습니다.

마무리

신뢰할 수 있는 에이전트는 더 복잡한 프롬프트가 아니라 테스트된 도구 계층에서 나옵니다. 도구를 실제 API 작업으로 정의하고, 목업으로 빠르게 개발하고, 응답 스키마와 실패 경로를 검증하세요. Apidog는 이러한 엔드포인트를 설계, 목업, 테스트할 수 있는 하나의 작업 공간을 제공하므로 에이전트가 실제 운영 환경에서 신뢰할 수 있는지 증명하는 데 사용할 수 있습니다.

Top comments (0)