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

AI 에이전트는 호출하는 API만큼만 신뢰할 수 있습니다. 모델은 도구를 선택하고, 인수를 채우고, 요청을 보냅니다. 만약 해당 요청이 실패하거나, 잘못된 형식으로 반환되거나, 멈추면 에이전트는 잘못된 데이터를 기반으로 확신에 찬 결정을 내리게 됩니다. 대부분의 에이전트 데모는 이 부분을 건너뜁니다. 하지만 실제 운영 환경의 에이전트는 이 부분에 성패가 달려 있습니다.

이 가이드에서는 실제 도구를 호출하는 에이전트를 구축하는 방법과, 더 중요하게는 Apidog를 API 계층이자 테스트 하네스로 활용하는 방법을 보여줍니다. 도구 엔드포인트를 설계하고, 오프라인 개발을 위해 목업(mock)하며, 사용자에게 도달하기 전에 잘못된 도구 호출을 잡아내는 단언(assertion)을 작성할 것입니다. 목표는 한 번의 성공적인 시나리오 때문이 아니라, 테스트를 통해 신뢰할 수 있는 에이전트를 만드는 것입니다.

앱 다운로드 버튼

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

프레이밍을 제거하면 에이전트 루프는 간단합니다:

모델은 사용자 목표와 도구 목록을 받습니다.
도구 호출(도구 이름과 JSON 인수)을 반환합니다.
코드가 해당 호출을 실행합니다. 일반적으로는 특정 API에 대한 HTTP 요청입니다.
결과가 모델로 다시 전달됩니다.
모델은 다른 도구를 호출하거나 답변합니다.

모든 흥미로운 실패는 3단계와 4단계에서 발생합니다. 모델이 인수를 환각하거나, API가 422를 반환하거나, 응답 스키마가 변경되거나, 호출 시간이 초과되거나, 루프 중간에 속도 제한에 걸릴 수 있습니다. 새로운 API 소비자인 AI 에이전트에 대해 읽어보셨다면, 이것이 그 아이디어의 구체적인 버전입니다. 즉, 에이전트는 API를 호출하는 클라이언트이며, 다른 클라이언트와 동일한 테스트 엄격함을 받을 자격이 있습니다.

따라서 작업은 두 가지로 나뉩니다. 도구를 실제 테스트 가능한 API 작업으로 정의한 다음, 에이전트가 좋은 조건과 나쁜 조건 모두에서 도구를 올바르게 호출하는지 확인하는 것입니다.

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

에이전트 코드를 한 줄도 작성하기 전에, 각 도구를 Apidog에서 API 엔드포인트로 정의하세요. 도구 스키마와 API 스키마를 동일하게 취급해야 합니다. 왜냐하면 실제로 동일하기 때문입니다. get_weather 도구와 GET /weather 엔드포인트는 동일한 계약(동일한 매개변수, 동일한 응답 형태)을 공유합니다.

Apidog에서 각 도구에 대해 OpenAPI 스키마(경로, 쿼리 및 본문 매개변수, 유형이 지정된 응답)로 엔드포인트를 생성하세요. 이렇게 하면 다음 세 가지를 무료로 얻을 수 있습니다.

에이전트 프롬프트와 테스트 모두가 읽어들이는 도구 계약에 대한 단일 진실 공급원.
도구 정의로 모델에 제공할 수 있는 자동 생성 문서.
나중에 유효성을 검사할 스키마로, 응답이 일치하지 않는 순간 변경 사항을 감지할 수 있습니다.

이 스키마 우선 접근 방식은 일반적으로 견고한 API 설계 작업의 기반이 되는 습관과 동일합니다. 에이전트의 경우 특별한 이점이 있습니다. 도구 정의와 실제 엔드포인트가 하나의 스키마에서 나올 때, 모델은 API가 지원하지 않는 도구를 호출할 수 없습니다.

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

모든 개발 실행이 비용이 들거나, 속도 제한이 있거나, 아직 구축되지 않은 라이브 API를 호출하는 것을 원치 않을 것입니다. Apidog는 방금 정의한 스키마에서 직접 목업 서버를 생성합니다. 각 도구 엔드포인트는 백엔드 없이 현실적이고 스키마 유효한 샘플 데이터를 반환합니다.

이는 에이전트를 구축하는 방식을 바꿉니다. 다음을 수행할 수 있습니다.

합의된 계약과 일치하는 목업을 사용하여 실제 API가 존재하기 전에 전체 에이전트 루프를 개발합니다.
유료 엔드포인트를 건드리지 않는 CI에서 통합 테스트를 실행합니다.
빈 결과, 500 오류, 잘못된 형식의 필드와 같은 특정 응답을 강제로 발생시켜 에이전트가 어떻게 반응하는지 확인합니다.

개발 중에 에이전트의 도구 실행기를 목업 기본 URL로 지정하세요. 모델이 get_weather를 호출하면 코드가 Apidog 목업을 호출하고, 유효한 응답이 즉시 반환됩니다. 실제 환경에 준비되면 환경 변수를 통해 기본 URL을 변경하세요. 목업은 에이전트 개발을 빠르고 결정론적으로 만듭니다. 동일한 접근 방식이 모든 진지한 AI 에이전트 테스트 워크플로를 구동합니다.

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

엔드포인트와 목업이 준비되면 에이전트 코드는 간결하게 유지됩니다. 다음은 Claude Messages API를 사용한 도구 호출 루프의 형태입니다. 도구 정의는 Apidog에서 구축한 스키마를 반영합니다.

import anthropic, requests, os

client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"]  # 개발 중에는 Apidog 목업, 프로덕션에서는 실제 API

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":
        r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
        r.raise_for_status()
        return r.json()

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

timeout=10 및 raise_for_status() 줄은 모델 호출보다 더 중요합니다. 이들은 실패를 명확하게 알리는 에이전트와 중단되거나 오류가 발생한 요청을 조용히 루프에 다시 공급하는 에이전트의 차이입니다. 에이전트가 API 워크플로에 어떻게 적용되는지에 대한 더 넓은 시야를 원한다면, API 워크플로를 위한 5가지 AI 에이전트의 패턴이 유용한 참고 자료가 될 것입니다.

4단계: 도구 호출을 테스트하고, 단순히 분위기만 보지 마세요

대부분의 팀이 건너뛰는 부분입니다. 각 도구 엔드포인트를 Apidog에 저장된 요청으로 모델과 독립적으로 단언(assertion)과 함께 실행하세요. 에이전트의 신뢰성은 도구의 신뢰성에 의해 제한되므로, 도구를 먼저 테스트해야 합니다.

각 도구 엔드포인트에 대해 다음을 단언하세요:

유효한 입력에 대해 상태는 200입니다.
응답 본문이 스키마와 일치합니다. Apidog는 OpenAPI 정의에 대해 응답의 유효성을 자동으로 검사합니다.
모델이 읽을 필수 필드가 존재하고 올바른 유형으로 지정되어 있습니다.
응답 시간이 에이전트가 적용하는 시간 초과 내에 있습니다.

그런 다음 문제가 발생하는 경로를 테스트하세요. 에이전트가 오작동하는 지점이기 때문입니다.

모델이 환각할 수 있는 잘못된 형식의 인수(예: 빈 city 값, 문자열이 들어가야 할 곳에 숫자)를 보내고, 500 대신 깔끔한 400/422를 받는지 단언합니다.
목업에서 오류 응답을 강제로 발생시키고 에이전트의 run_tool이 잘못된 데이터를 반환하는 대신 예외를 발생시키는지 확인합니다.
빈 결과를 테스트하고 에이전트가 답변을 지어내는 대신 "데이터 없음"을 처리하는지 확인합니다.

이는 에이전트 도구에 적용된 계약 테스트입니다. API 계약 테스트에서 다루는 것과 동일한 원칙이며, 모델이 호출하는 엔드포인트를 대상으로 합니다. 도구의 응답 형태가 변경되면 CI에서 단언이 실패하고, 에이전트가 손상된 페이로드를 기반으로 추론하기 전에 이를 수정할 수 있습니다.

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

에이전트는 불안정한 API를 증폭시킵니다. 일반 앱에서 한 번의 재시도는 한 번이지만, 에이전트 루프에서는 실패하는 도구를 계속해서 재호출하는 모델이 속도 제한과 예산을 빠르게 소진시킬 수 있습니다. 제어 장치를 구축하고 테스트하세요:

타임아웃. 위 예시처럼 모든 도구 요청에 명시적인 타임아웃을 설정하세요. 그런 다음 Apidog를 사용하여 느린 엔드포인트를 시뮬레이션하고 클라이언트가 전체 루프를 멈추는 대신 깔끔하게 포기하는지 확인하세요.
백오프를 사용한 재시도. 일시적인 실패는 재시도하지만, 횟수를 제한하고 백오프를 적용하세요. 두 번 실패한 다음 성공하는 목업에 대해 테스트하고, 에이전트가 무한 루프에 빠지는 대신 복구되는지 단언합니다.
속도 제한. 부하 시 429 오류를 예상하세요. 속도 제한 응답을 목업하고, 에이전트가 계속해서 요청을 보내는 대신 기다렸다가 재시도하는지 확인하세요. 원시 모델 API에서 이러한 문제를 경험했다면(GPT API 속도 제한에서 동일한 종류의 문제를 참고하세요), 에이전트 버전은 루프가 모든 호출을 증폭시키기 때문에 더 엄격합니다.
서킷 브레이킹. 한 도구에서 N번 실패한 후에는 해당 도구 호출을 중단하고, 에이전트가 계속 시도하는 대신 실패를 보고하도록 하세요. 브레이커가 작동하는지 테스트합니다.

Apidog에서 이를 반복 가능한 시나리오로 실행하여, 오류 처리의 회귀가 프로덕션 사고가 아닌 실패한 테스트로 나타나도록 하세요.

6단계: CI에서 목업에 대해 E2E(End-to-End) 실행

모두 연결하세요. CI에서 Apidog 목업 서버를 가리키는 에이전트를 시작하고, 고정된 사용자 목표 세트를 제공한 다음, 최종 결과와 도구 호출 시퀀스를 단언하세요. 목업은 결정론적이기 때문에 동일한 입력은 모든 실행에서 동일한 도구 호출을 생성하므로, 에이전트 테스트의 불안정성이 사라집니다. 확신이 생기면 기본 URL을 실제 API로 전환하여 더 작은 라이브 스모크 테스트를 수행하세요. 대량의 테스트를 위한 결정론적 목업과 현실 확인을 위한 가벼운 라이브 검사라는 이러한 분할은 에이전트 기반 AI 테스트를 이상이 아닌 실용적인 것으로 만듭니다.

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

[ ] 모든 도구가 OpenAPI 스키마를 가진 실제 API 작업으로 정의되어 있습니다.
[ ] 오프라인에서 구축하고 테스트할 수 있도록 모든 도구에 대한 목업이 존재합니다.
[ ] 각 도구 엔드포인트는 상태, 스키마 및 타이밍에 대한 단언을 가집니다.
[ ] 잘못된 인수, 오류, 빈 결과와 같은 문제가 발생하는 경로가 명시적으로 테스트됩니다.
[ ] 타임아웃, 백오프를 사용한 재시도, 속도 제한 처리가 코드에 구현되어 있고 테스트됩니다.
[ ] 결정론적 목업에 대해 전체 루프를 실행하는 엔드투엔드 CI가 실행됩니다.

이 여섯 가지를 모두 충족하면 희망이 아닌 증거로 신뢰성을 설명할 수 있는 에이전트를 갖게 됩니다.

자주 묻는 질문 (FAQ)

에이전트를 실행하는 대신 API 클라이언트를 사용하여 에이전트를 테스트하는 이유는 무엇인가요? 에이전트를 실행하면 모델과 도구가 함께 테스트되어 실패의 원인이 모호해집니다. Apidog에서 각 도구 엔드포인트를 테스트하면 API 계층이 분리되어 문제가 모델의 추론 때문인지 아니면 손상된 도구 때문인지 알 수 있습니다.

에이전트를 구축하기 전에 실제 API를 구축해야 하나요? 아닙니다. Apidog에서 도구 계약을 스키마로 정의하고, 목업을 생성하며, 해당 목업에 대해 전체 에이전트 루프를 구축하세요. 나중에 환경 변수를 통해 실제 엔드포인트를 교체할 수 있습니다.

실패하는 도구에서 에이전트가 무한 루프에 빠지는 것을 어떻게 막을 수 있나요? 재시도 횟수를 제한하고, 백오프를 추가하며, 반복되는 실패 후에는 서킷 브레이커를 작동시켜 에이전트가 계속 시도하는 대신 문제를 보고하도록 하세요. 오류를 반환하는 목업에 대해 각 제어 장치를 테스트하세요.

모델 및 API 호출에 비용을 들이지 않고 에이전트를 테스트할 수 있나요? 대체로 그렇습니다. 결정론적이고 무료인 통합 테스트를 위해 Apidog에서 도구 API를 목업하고, 라이브 모델 호출은 작은 스모크 테스트 스위트로 제한하세요.

이것이 LangChain이나 Claude Agent SDK와 같은 프레임워크에서도 작동하나요? 네. 도구 계층은 단지 HTTP일 뿐입니다. 어떤 프레임워크가 루프를 구동하든, 테스트를 위해서는 Apidog 목업을, 프로덕션을 위해서는 실제 엔드포인트를 가리키도록 도구 호출을 설정하면 됩니다. 그러한 루프에 대해서는 Claude Code SDK 가이드를 참조하세요.

마무리

신뢰할 수 있는 에이전트는 더 영리한 프롬프트가 아니라, 테스트된 도구 계층입니다. 도구를 실제 API 작업으로 정의하고, 개발이 빠르고 결정론적이도록 목업하며, 모든 응답 형태에 대해 단언하고, 의도적으로 실패를 테스트하세요. Apidog는 이러한 엔드포인트를 설계하고, 목업하며, 테스트 하네스로 실행할 수 있는 하나의 장소를 제공하여 에이전트의 동작을 증명할 수 있게 합니다. Apidog를 다운로드하고 프로덕션에서 실제로 신뢰할 수 있는 에이전트를 구축하세요.

앱 다운로드 버튼