Cómo Probar las Llamadas a Herramientas de un Agente de IA con Apidog (Antes de que Fallen en Producción)

Un agente de IA es tan fiable como las API a las que llama. El modelo elige una herramienta, completa argumentos y envía una solicitud; si esa solicitud falla, devuelve una forma inesperada o se queda colgada, el agente tomará decisiones con datos incorrectos. En producción, la capa de API no es un detalle: es el punto donde el agente se vuelve confiable o frágil.

Prueba Apidog hoy

Esta guía muestra cómo construir un agente que llama herramientas reales y cómo usar Apidog como capa de API y arnés de pruebas. Vas a definir endpoints para las herramientas, simularlos para desarrollar offline y escribir aserciones que detecten llamadas rotas antes de que lleguen a usuarios.

Qué hace realmente un agente en la capa de API

Un ciclo de agente suele ser este:

1. El modelo recibe un objetivo del usuario y una lista de herramientas.
2. Devuelve una llamada a herramienta: nombre de herramienta + argumentos JSON.
3. Tu código ejecuta esa llamada, normalmente como una solicitud HTTP.
4. El resultado vuelve al modelo.
5. El modelo llama otra herramienta o responde al usuario.

Los fallos importantes aparecen en los pasos 3 y 4:

• El modelo alucina un argumento.
• La API devuelve 422.
• El esquema de respuesta cambió.
• La llamada expira.
• Un límite de velocidad aparece a mitad del ciclo.

Si ya has leído sobre los agentes de IA como los nuevos consumidores de API, esta es la aplicación práctica: tu agente es un cliente de API y debe probarse con el mismo rigor que cualquier otro consumidor.

El trabajo se divide en dos partes:

1. Definir herramientas como operaciones de API reales.
2. Verificar que el agente las llama correctamente en condiciones buenas y malas.

Paso 1: Diseñar las herramientas como operaciones de API reales

Antes de escribir código del agente, define cada herramienta como un endpoint en Apidog.

Por ejemplo:

Herramienta del agente	Endpoint
get_weather	GET /weather
search_orders	GET /orders
create_ticket	POST /tickets

Una herramienta get_weather y el endpoint GET /weather comparten el mismo contrato:

• Parámetros
• Tipos
• Campos requeridos
• Forma de respuesta
• Errores esperados

En Apidog, crea un endpoint por herramienta con su esquema OpenAPI:

• Parámetros de ruta
• Parámetros de consulta
• Cuerpo de solicitud
• Respuestas tipadas
• Códigos de error esperados

Esto te da tres ventajas prácticas:

• Una única fuente de verdad para el contrato de la herramienta.
• Documentación autogenerada que puedes usar como definición de herramienta.
• Validación de respuesta para detectar desviaciones del esquema.

Este enfoque schema-first es el mismo que se usa en un buen proceso de diseño de API. Para agentes, la ventaja es directa: si la herramienta y el endpoint salen del mismo contrato, el modelo no debería llamar algo que la API no soporta.

Paso 2: Simular las herramientas para construir offline

No conviene que cada ejecución local llame APIs reales que:

• Cuestan dinero.
• Tienen límites de velocidad.
• Todavía no existen.
• Cambian durante el desarrollo.

Apidog puede generar un servidor mock desde el esquema definido. Cada endpoint de herramienta devuelve datos de ejemplo válidos sin necesitar backend.

Con esto puedes:

• Construir el ciclo completo del agente antes de tener la API real.
• Ejecutar pruebas de integración en CI sin tocar endpoints de pago.
• Forzar respuestas específicas para probar errores:
  • Resultado vacío
  • 500
  • Campo malformado
  • Timeout
  • 429

Durante desarrollo, apunta el ejecutor de herramientas del agente a la URL base del mock:

TOOL_BASE_URL=https://mock-api.example.com

En producción, cambia la URL base:

TOOL_BASE_URL=https://api.example.com

El modelo llama get_weather, tu código llama al mock de Apidog y recibe una respuesta válida. Cuando pases a producción, solo cambias la variable de entorno.

Este patrón hace que el desarrollo de agentes sea rápido y determinista. Es la misma lógica detrás de un flujo serio de pruebas de agentes de IA.

Paso 3: Conectar el agente para que llame a las herramientas

Con los endpoints y mocks listos, el código del agente debe mantenerse simple.

Ejemplo de bucle de llamada a herramientas usando la API de Mensajes de Claude. Las definiciones de herramientas reflejan los esquemas creados en Apidog:

import anthropic
import requests
import os

client = anthropic.Anthropic()

# Mock de Apidog en desarrollo, API real en producción
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

Las líneas más importantes no son las del modelo, sino estas:

timeout=10
response.raise_for_status()

Sin timeout, una llamada colgada puede bloquear el ciclo.

Sin raise_for_status(), un 500, 422 o 429 puede volver al modelo como si fuera un resultado válido.

Para ver más patrones de agentes en flujos de trabajo de API, revisa 5 agentes de IA para su flujo de trabajo de API.

Paso 4: Probar las llamadas a herramientas, no solo las “vibes”

Muchos equipos prueban el agente completo y asumen que si respondió bien una vez, está listo. Eso no alcanza.

Primero prueba cada endpoint de herramienta de forma aislada en Apidog.

Para cada herramienta, crea una solicitud guardada y añade aserciones como:

• El estado es 200 para una entrada válida.
• La respuesta coincide con el esquema OpenAPI.
• Los campos que leerá el modelo existen.
• Los tipos son correctos.
• El tiempo de respuesta está dentro del timeout del agente.

Ejemplo de contrato esperado para GET /weather:

{
  "city": "Tokyo",
  "temperature": 24,
  "condition": "cloudy"
}

Aserciones mínimas:

• city existe y es string.
• temperature existe y es number.
• condition existe y es string.
• La respuesta cumple el esquema.
• La latencia es menor que el timeout configurado.

Después prueba caminos infelices.

Casos que deberías cubrir

Argumentos malformados:

{
  "city": ""
}

Resultado esperado:

422 Unprocessable Entity

Tipo incorrecto:

{
  "city": 123
}

Resultado esperado:

400 Bad Request

Respuesta vacía:

{
  "results": []
}

Resultado esperado: el agente debe reconocer “sin datos” y no inventar una respuesta.

Error interno simulado:

500 Internal Server Error

Resultado esperado: run_tool debe lanzar una excepción o devolver un error controlado, no alimentar basura al modelo.

Esto es prueba de contrato aplicada a herramientas de agente. Es la misma disciplina descrita en pruebas de contrato de API, pero enfocada en los endpoints que el modelo llama.

Si la forma de respuesta cambia, la aserción falla en CI antes de que el agente razone sobre una carga útil rota.

Paso 5: Gestionar reintentos, tiempos de espera y límites de velocidad

Los agentes amplifican las API inestables. Una app tradicional puede hacer un reintento. Un agente puede volver a llamar la misma herramienta varias veces dentro del mismo ciclo y agotar rápido tus límites.

Implementa controles explícitos y pruébalos.

Tiempos de espera

Cada solicitud de herramienta debe tener timeout:

requests.get(url, timeout=10)

Luego simula en Apidog un endpoint lento y valida que el cliente falla de forma controlada.

Reintentos con retroceso exponencial

Reintenta solo errores transitorios y limita los intentos.

Ejemplo básico:

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)

Prueba este comportamiento con un mock que:

1. Falla.
2. Falla.
3. Responde correctamente.

El agente debe recuperarse, no entrar en bucle infinito.

Límites de velocidad

Espera respuestas 429 bajo carga. Simula una respuesta con límite de velocidad y verifica que el agente espera o aborta de forma controlada.

Si ya has trabajado con límites en APIs de modelos, el problema es similar al de los límites de velocidad de la API de GPT. En agentes, el riesgo es mayor porque el ciclo puede multiplicar llamadas.

Corte de circuito

Después de N fallos consecutivos, deja de llamar la herramienta y permite que el agente informe el problema.

Ejemplo simplificado:

class CircuitBreaker:
    def __init__(self, max_failures=3):
        self.max_failures = max_failures
        self.failures = 0
        self.open = False

    def record_success(self):
        self.failures = 0
        self.open = False

    def record_failure(self):
        self.failures += 1
        if self.failures >= self.max_failures:
            self.open = True

    def allow_request(self):
        return not self.open

Úsalo antes de ejecutar la herramienta:

breaker = CircuitBreaker(max_failures=3)

def safe_run_tool(name, args):
    if not breaker.allow_request():
        raise RuntimeError("Tool temporarily disabled after repeated failures")

    try:
        result = run_tool(name, args)
        breaker.record_success()
        return result
    except Exception:
        breaker.record_failure()
        raise

Estos escenarios deben ejecutarse de forma repetible en Apidog para que una regresión aparezca como prueba fallida, no como incidente de producción.

Paso 6: Ejecutar pruebas end-to-end contra mocks en CI

Conecta todo en CI:

1. Configura TOOL_BASE_URL apuntando al mock de Apidog.
2. Ejecuta el agente con objetivos de usuario fijos.
3. Verifica la respuesta final.
4. Verifica la secuencia de llamadas a herramientas.
5. Falla el pipeline si cambia el contrato o aparece un error inesperado.

Ejemplo de variables:

export TOOL_BASE_URL="https://mock-api.example.com"
export ANTHROPIC_API_KEY="..."

Ejemplo de prueba de alto nivel:

def test_agent_uses_weather_tool():
    result = run_agent("What should I wear in Tokyo today?")

    assert "Tokyo" in result
    assert "wear" in result.lower() or "clothing" in result.lower()

Como los mocks son deterministas, la misma entrada produce respuestas estables. Esto reduce la inestabilidad típica de las pruebas con agentes.

Cuando el flujo esté cubierto con mocks, añade una prueba de humo pequeña contra APIs reales. La división recomendada es:

• Muchas pruebas contra mocks deterministas.
• Pocas pruebas en vivo contra APIs reales.

Este enfoque hace que las pruebas de IA agéntica sean prácticas.

Lista de verificación para un agente confiable

Usa esta checklist antes de mover un agente a producción:

• [ ] Cada herramienta está definida como una operación de API real con esquema OpenAPI.
• [ ] Hay mocks para cada herramienta.
• [ ] El agente puede ejecutarse contra mocks usando una variable de entorno.
• [ ] Cada endpoint de herramienta tiene aserciones de estado, esquema y tiempo.
• [ ] Los argumentos inválidos se prueban explícitamente.
• [ ] Los errores 400, 422, 429 y 500 tienen comportamiento definido.
• [ ] Los resultados vacíos no hacen que el agente invente datos.
• [ ] Cada llamada HTTP tiene timeout.
• [ ] Los reintentos tienen límite y retroceso exponencial.
• [ ] Hay corte de circuito después de fallos repetidos.
• [ ] CI ejecuta el ciclo completo contra mocks deterministas.
• [ ] Existe una prueba de humo pequeña contra APIs reales.

Si cumples estos puntos, puedes describir la fiabilidad del agente con pruebas, no con esperanza.

Preguntas frecuentes

¿Por qué usar un cliente de API para probar un agente en lugar de simplemente ejecutar el agente?

Porque ejecutar el agente completo mezcla dos fuentes de fallo:

• Razonamiento del modelo.
• Capa de herramientas/API.

Si una prueba falla, no sabes cuál de las dos falló. Probar cada endpoint en Apidog aísla la capa de API y facilita el diagnóstico.

¿Tengo que construir las APIs reales antes de construir el agente?

No. Define los contratos de herramientas como esquemas en Apidog, genera mocks y construye el ciclo completo contra esos mocks. Más tarde, cambia a endpoints reales mediante una variable de entorno.

¿Cómo evito que mi agente entre en un bucle infinito con una herramienta que falla?

Implementa tres controles:

1. Límite de reintentos.
2. Retroceso exponencial.
3. Corte de circuito después de fallos repetidos.

Después prueba cada caso contra un mock que devuelva errores.

¿Puedo probar el agente sin gastar dinero en llamadas al modelo y a la API?

En gran parte, sí. Simula las APIs de herramientas en Apidog para pruebas de integración deterministas. Mantén las llamadas reales al modelo y a APIs de pago solo para un conjunto pequeño de pruebas de humo.

¿Funciona con frameworks como LangChain o el SDK de Agente de Claude?

Sí. La capa de herramientas normalmente termina siendo HTTP. El framework puede manejar el bucle, pero tus llamadas a herramientas pueden apuntar a mocks de Apidog en pruebas y a endpoints reales en producción.

Para un ejemplo de este tipo de bucles, revisa la guía del SDK de Código de Claude.

Conclusión

Un agente fiable no depende solo de un prompt mejor. Depende de una capa de herramientas probada.

Define tus herramientas como operaciones de API reales, simúlalas para desarrollar rápido, valida cada respuesta y prueba los fallos a propósito. Apidog te da un lugar para diseñar esos endpoints, simularlos y ejecutarlos como arnés de pruebas, de modo que el comportamiento del agente sea verificable antes de llegar a producción.