Cómo probar agentes de IA que llaman a tus APIs sin perder datos

Un agente de codificación de IA ejecutó un script, lo vio tener éxito y después vio desaparecer una tabla de la base de datos de producción. La autopsia en Hacker News se volvió viral con una frase incómoda: “La IA no borró tu base de datos, tú lo hiciste”. El punto es válido: el agente siguió una definición de herramienta, la herramienta llamó a un endpoint real, el endpoint no tenía barreras de seguridad y un humano entregó acceso de escritura a un proceso que no se detiene a preguntar si DELETE FROM users parece sospechoso. En otro caso, un agente entró en un bucle de facturación y consumió cientos de euros en tokens antes de que alguien lo detectara. Superficie distinta, mismo fallo: nadie probó la API.

Prueba Apidog hoy

💡 Si estás implementando agentes autónomos que llaman a tus APIs, esta guía es para ti. Verás cómo simular endpoints externos durante el desarrollo, proteger operaciones destructivas, escribir pruebas de contrato para esquemas de herramientas, aplicar límites de presupuesto por agente y ensayar fallos antes de llegar a producción. Usaremos Apidog porque trabaja con OpenAPI de forma nativa, levanta servidores mock sin código pegamento y permite crear escenarios que se parecen a las secuencias reales de llamadas del agente.

En resumen

Los agentes fallan en producción cuando sus herramientas no tienen controles del lado de la API: límites de tasa ausentes, operaciones no idempotentes, eliminaciones directas, esquemas rotos o permisos demasiado amplios.

La solución práctica:

1. Prueba las definiciones de herramientas del agente contra tu especificación OpenAPI.
2. Usa un servidor mock para endpoints destructivos.
3. Aplica claves de idempotencia y límites de presupuesto por agente.
4. Reproduce escenarios de fallo en CI antes de desplegar.

Apidog te permite importar OpenAPI, crear mocks y ejecutar escenarios desde un mismo proyecto.

Introducción

Hace un año, “probar un agente de IA” significaba enviarle prompts a Claude o GPT y revisar la respuesta. Eso ya no basta.

Los agentes actuales llaman funciones. Esas funciones llaman APIs. Y esas APIs pueden tocar bases de datos reales, procesadores de pagos, CRMs, herramientas internas y servicios de terceros. Una mala definición de herramienta o un endpoint sin límite de tasa ya no es un detalle de implementación: es un incidente de producción.

La lección de los casos virales recientes es clara: el problema no suele estar en que el modelo sea “tonto”. El problema está en confiar en la capa equivocada. El modelo ejecuta lo que sus herramientas permiten. Si la API permite borrar, cobrar, reenviar o modificar sin controles, el agente podrá hacerlo.

Este artículo se centra en la capa donde puedes aplicar defensas reales: la API.

Vas a ver:

• Cómo validar herramientas de agentes contra OpenAPI.
• Cómo simular endpoints destructivos con Apidog.
• Cómo implementar idempotencia.
• Cómo limitar presupuesto y llamadas por agente.
• Cómo ejecutar escenarios en CI.
• Qué errores evitar antes de poner agentes en producción.

Por qué los fallos de los agentes se parecen a los fallos de las API

Lee suficientes autopsias de agentes y aparece el mismo patrón: el modelo no es el protagonista. La API lo es.

Inyección de prompt

Un usuario sube un PDF con instrucciones ocultas. El agente lo lee. La siguiente llamada de herramienta intenta acceder a:

POST /admin/users

con un cuerpo como:

{
  "delete_all": true
}

El problema no se resuelve solo con un prompt más estricto. Se resuelve con autorización del lado de la API.

Si el usuario original no puede acceder a /admin/users, el agente que actúa en su nombre tampoco debería poder hacerlo.

Esquemas de herramientas defectuosos

Tu OpenAPI dice que amount es un entero en centavos:

{
  "amount": {
    "type": "integer",
    "description": "Amount in cents"
  }
}

Pero la herramienta del agente dice que amount es un número decimal en dólares:

{
  "amount": {
    "type": "number",
    "description": "Amount in dollars"
  }
}

Tres meses después, alguien reembolsa 19 dólares en vez de 19 centavos.

El modelo no falló. Usó el esquema que le diste. Lo que falló fue el contrato.

Sin límites de tasa

Un agente entra en un bucle de reintentos y llama mil veces a un endpoint de correos transaccionales:

POST /emails/send

Cada reintento cuesta dinero. Cada reintento puede enviar un email real. Cuando lo detectas, tu proveedor ya ha marcado tu cuenta y tus usuarios han recibido spam.

La solución es un límite en la API o en la pasarela, no confiar en que el agente “se dé cuenta”.

Sin idempotencia

El agente llama a:

POST /payments

La red falla. El agente reintenta. La primera llamada sí había llegado al backend, pero el agente no lo sabe. Resultado: doble cobro.

La API necesita una forma de reconocer que ambos intentos pertenecen a la misma operación lógica. Para eso sirven las claves de idempotencia.

Las cuatro barreras de seguridad que toda integración agente-API necesita

Si estás integrando agentes con APIs reales, empieza por estos cuatro controles.

1. Pruebas de contrato para esquemas de herramientas

Tu especificación OpenAPI debe ser la fuente de verdad. Las definiciones de herramientas del agente deben derivarse de ella o, como mínimo, validarse contra ella.

Ejemplo mínimo en Python para comparar una herramienta con la especificación OpenAPI:

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

Úsalo en CI cada vez que cambien:

• La especificación OpenAPI.
• La definición de herramientas del agente.
• El endpoint que el agente puede invocar.

Si errors no está vacío, falla el build.

Ejemplo de uso:

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

with open("agent-tools/refund.json") as f:
    tool_def = json.load(f)

errors = validate_tool_against_openapi(tool_def, openapi_spec)

if errors:
    for error in errors:
        print(error)
    raise SystemExit(1)

2. Mocks para endpoints destructivos

Los agentes necesitan practicar. No deberían practicar en producción.

El patrón recomendado:

Todo endpoint que modifique estado debería tener un mock:

• POST /payments
• POST /refunds
• PATCH /users/{id}
• DELETE /users/{id}
• POST /emails/send
• POST /notifications

Apidog genera mocks desde OpenAPI, con respuestas que respetan tus esquemas. Durante el desarrollo, apuntas la URL base del agente al servidor mock y ejecutas iteraciones sin tocar datos reales.

Ejemplo:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id

Si el agente intenta borrar usuarios por una mala interpretación de la documentación, el mock lo mostrará en el rastro de llamadas. Tu base de datos real no verá nada.

Para el patrón completo, consulta desarrollo basado en contratos.

3. Idempotencia y borrado suave

Cada endpoint de escritura que pueda llamar un agente debería aceptar una clave de idempotencia.

Ejemplo en 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);

El agente debe generar un UUID por operación lógica:

import crypto from "node:crypto";

const idempotencyKey = crypto.randomUUID();

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

Si hay timeout y el agente reintenta con la misma clave, la API devuelve la respuesta cacheada en vez de ejecutar el cobro dos veces.

Para borrados, evita el borrado físico por defecto. Usa borrado suave:

UPDATE users
SET deleted_at = NOW()
WHERE id = $1;

Y reserva el borrado definitivo para rutas separadas con aprobación humana.

4. Límites de presupuesto por agente

Cada agente debe tener presupuesto. Cuando lo agota, se detiene.

Presupuestos útiles:

• Tokens por sesión.
• Llamadas API por minuto.
• Coste acumulado.
• Tiempo máximo de ejecución.
• Profundidad máxima de llamadas a herramientas.
• Número máximo de operaciones de escritura.

Ejemplo de respuesta cuando se excede un límite:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: api_calls_per_minute
Content-Type: application/json

{
  "error": "Budget exceeded",
  "limit": "api_calls_per_minute",
  "retry_after_seconds": 60
}

El planificador del agente puede escalar a un humano, pausar la tarea o cancelar la ejecución.

Estos cuatro controles se complementan:

• Las pruebas de contrato detectan desviaciones de esquema.
• Los mocks detectan comportamiento destructivo antes de producción.
• La idempotencia protege contra reintentos.
• Los presupuestos detienen bucles descontrolados.

El resultado esperado no es “el agente nunca falla”. El estándar correcto es: “cuando falla, falla cerrado”.

Probar llamadas de agentes con Apidog

Ahora veamos un flujo práctico con Apidog.

Necesitas:

• Una especificación OpenAPI 3.x.
• Las definiciones de herramientas del agente.
• Una lista de endpoints que el agente puede llamar.
• Casos de prueba o escenarios esperados.

Paso 1: Importar la especificación OpenAPI

Crea un proyecto en Apidog e importa tu archivo OpenAPI.

Apidog leerá:

• Rutas.
• Métodos.
• Parámetros.
• Cuerpos de request.
• Esquemas.
• Ejemplos.
• Respuestas.

Si todavía no tienes OpenAPI, créala antes de exponer la API al agente. La fiabilidad del agente depende de tener una fuente de verdad compartida entre humanos, backend y herramientas.

Si empiezas desde cero, revisa la guía de flujo de trabajo API design-first.

Paso 2: Crear respuestas mock para endpoints destructivos

Localiza todos los endpoints que modifican datos:

POST /payments
POST /refunds
PATCH /accounts/{id}
DELETE /users/{id}
POST /notifications

Para cada uno:

1. Abre el endpoint en Apidog.
2. Añade una respuesta mock.
3. Usa datos claramente falsos.
4. Evita copiar valores de producción.
5. Usa prefijos reconocibles como mock_user_, test_ o fechas antiguas.

Ejemplo de respuesta mock para un borrado suave:

{
  "id": "mock_user_123",
  "deleted": true,
  "deleted_at": "1970-01-01T00:00:00Z"
}

Después, inicia el servidor mock y usa su URL como base URL del agente:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id

Ahora el agente puede llamar a DELETE /users/{id} sin tocar producción.

Paso 3: Escribir un escenario que simule al agente

Los escenarios de Apidog permiten encadenar llamadas con aserciones. Esto se parece al flujo real del agente.

Ejemplo para un agente que clasifica tickets de soporte:

1. POST /auth/token

   • Usa credenciales de prueba.
   • Captura el token.

2. GET /tickets?status=open

   • Envía el token.
   • Captura el ID del primer ticket.

3. POST /tickets/{id}/triage

   • Envía la categoría.
   • Verifica HTTP 200.
   • Captura el usuario asignado.

4. POST /notifications

   • Envía un mensaje.
   • Verifica que el cuerpo cumpla una expresión regular.

Ejemplo de aserciones:

status == 200
response.body.assigned_to != null
response.body.category in ["billing", "technical", "account"]

Estás ensayando el comportamiento del agente contra un mock, con validaciones en cada salto.

Si alguien cambia el esquema de tickets y el agente deja de enviar el campo correcto, el escenario falla antes del despliegue.

Para un enfoque más amplio, revisa pruebas de API para ingenieros de QA.

Paso 4: Ejecutar escenarios desde CI

Ejecuta los escenarios en cada PR que afecte:

• OpenAPI.
• Definiciones de herramientas.
• Endpoints llamados por agentes.
• Middleware de autenticación.
• Validaciones de request.
• Límites de tasa o presupuesto.

Ejemplo de comando:

apidog run -t scenario-id --env test

Ejemplo conceptual para GitHub Actions:

name: Agent API Scenarios

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agent-tools/**"
      - "src/api/**"

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

    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog scenario
        run: apidog run -t scenario-id --env test

El objetivo es que ningún cambio de contrato llegue a producción sin ejecutar el flujo del agente.

Paso 5: Comparar modelos en paralelo

Cuando evalúas cambiar de un modelo a otro, no basta con comparar respuestas en lenguaje natural. Debes comparar llamadas a herramientas.

Proceso recomendado:

1. Ejecuta el agente con el modelo A contra el escenario de Apidog.
2. Guarda el rastro de llamadas.
3. Ejecuta el mismo escenario con el modelo B.
4. Compara:
   • Endpoints llamados.
   • Orden de llamadas.
   • Cuerpos de request.
   • Campos omitidos.
   • Formatos de fecha.
   • Valores por defecto.

Diferencias típicas:

- "priority": "high"
+ "priority": "medium"

- "due_date": "2026-05-01"
+ "due_date": "05/01/2026"

- "amount": 1900
+ "amount": 19

Detectar esto antes del despliegue evita que una actualización de modelo cambie silenciosamente el comportamiento operativo del agente.

Este patrón también aparece en integraciones de modelos nuevos, como la integración de la API de GPT-5.5.

Técnicas avanzadas

Una vez que tengas mocks, contratos e idempotencia, añade estos patrones.

Fija la temperatura a cero en pruebas

Si estás probando llamadas a herramientas, reduce la no determinación:

{
  "temperature": 0
}

No estás evaluando creatividad. Estás validando que el agente llame al endpoint correcto con argumentos correctos.

Guarda instantáneas de llamadas a herramientas

Cada ejecución debería registrar:

• Herramienta llamada.
• Endpoint.
• Método HTTP.
• Argumentos.
• Código de respuesta.
• Tiempo.
• ID de sesión.
• ID de agente.

Ejemplo de traza:

[
  {
    "tool": "list_tickets",
    "method": "GET",
    "path": "/tickets",
    "args": {
      "status": "open"
    }
  },
  {
    "tool": "triage_ticket",
    "method": "POST",
    "path": "/tickets/t_123/triage",
    "args": {
      "category": "billing"
    }
  }
]

Compara estas trazas contra una línea base. Si el agente empieza a llamar /users dos veces, debes detectarlo en CI, no en la factura.

Nunca des credenciales de producción al agente

Los agentes deben usar cuentas de servicio con permisos mínimos.

Evita:

PROD_DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_...

Prefiere:

• Tokens de corta duración.
• Scopes limitados.
• Proxy de API.
• Separación por entorno.
• Secretos en bóveda.
• Rotación automática.

Separa claves de lectura y escritura

Muchas tareas de agentes son principalmente de lectura. Usa claves diferentes:

Ejemplo:

Authorization: Bearer agent_readonly_token

Para operaciones de escritura, exige aprobación o un token diferente.

Usa HTTP 423 para aprobación humana

Cuando una operación necesita confirmación, responde con 423 Locked:

HTTP/1.1 423 Locked
Content-Type: application/json

{
  "error": "Human approval required",
  "confirmation_url": "https://internal.example.com/approvals/req_123"
}

Esto comunica mejor el estado que un 403. No significa “nunca puedes hacerlo”, sino “no puedes hacerlo todavía”.

Falla cerrado ante desviación de esquema

Si la definición de herramienta no coincide con OpenAPI, falla el build.

No lo conviertas en advertencia.

Schema mismatch detected
Tool missing required field: customer_id
Type mismatch on amount: API=integer tool=number

Resultado esperado:

exit 1

El coste de romper un PR es menor que el coste de un incidente.

Errores comunes que debes evitar

• Codificar URLs mock directamente en prompts.
• Omitir idempotencia en endpoints “pequeños”.
• Registrar cuerpos completos con PII en producción.
• Permitir acceso directo a base de datos.
• Reutilizar tokens de producción en desarrollo.
• Confiar en la puntuación de confianza del modelo.
• Usar la misma clave para lectura, escritura y administración.
• No probar timeouts, errores 429 y respuestas parciales.
• No validar enums, rangos y formatos de fecha.
• No probar qué ocurre cuando el agente reintenta.

Si tu agente llama servicios internos distribuidos, revisa los patrones de prueba para microservicios.

Alternativas y herramientas

Hay varias formas de probar integraciones agente-API.

Resumen práctico:

• Si ya usas LangSmith, mantenlo para evaluación del agente y añade pruebas de API aparte.
• Si Postman se queda corto en mocks o coste, Apidog es una alternativa fuerte.
• Si empiezas de cero, prioriza OpenAPI, mocks y escenarios en una sola herramienta.

Muchos equipos combinan herramientas: LangSmith para evaluación de prompts y Apidog para contratos, mocks y escenarios de API.

Casos de uso reales

Agente que actualiza filas en producción

Un equipo de soporte creó un agente que actualiza campos de cuenta desde tickets.

Antes del lanzamiento:

• Exigieron idempotencia en todos los endpoints de escritura.
• Ejecutaron 200 escenarios en Apidog contra una base de datos de pruebas.
• Validaron enums y esquemas.

Las pruebas detectaron casos donde el agente enviaba un valor inválido para subscription_status. Añadieron validación y desplegaron sin incidentes.

Agente que llama una API de pagos

Un equipo fintech construyó un agente de reembolsos automatizados.

Controles aplicados:

• Máximo 5 reembolsos por sesión.
• Máximo 50 dólares por reembolso.
• Idempotencia obligatoria.
• Pruebas de contrato en cada PR.

También ejecutaron una suite de pruebas de contrato contra la API de pagos. Seis meses después, procesaron miles de reembolsos sin cargos duplicados.

Agente que clasifica incidencias de GitHub

Un equipo de plataforma creó un agente de triage inspirado en Clawsweeper.

Antes de lanzarlo:

• Simularon la API de GitHub en Apidog.
• Ejecutaron 50 escenarios.
• Cubrieron incidencias eliminadas, etiquetas faltantes y entradas mal formadas.
• Encontraron bloqueos antes del despliegue.

El agente ahora gestiona clasificación en un repositorio público con miles de incidencias abiertas.

Checklist de implementación

Antes de conectar un agente a una API real, valida esto:

[ ] Existe una especificación OpenAPI actualizada.
[ ] Las herramientas del agente se validan contra OpenAPI.
[ ] Los endpoints destructivos tienen mocks.
[ ] Los escenarios principales se ejecutan en CI.
[ ] Toda escritura exige Idempotency-Key.
[ ] Los borrados son suaves por defecto.
[ ] Hay límites por agente, sesión y minuto.
[ ] Las claves de lectura y escritura están separadas.
[ ] El agente no tiene credenciales de producción.
[ ] Los logs redactan PII y secretos.
[ ] Los errores 429, 423, 500 y timeouts están probados.
[ ] Las operaciones críticas requieren aprobación humana.

Conclusión

Si te llevas una idea, que sea esta: el agente no es el problema principal. La API es el problema o la solución, dependiendo de si la probaste.

Cinco acciones concretas:

1. Trata los esquemas de herramientas como contratos.
2. Ejecuta pruebas de contrato en CI.
3. Simula endpoints destructivos durante el desarrollo.
4. Requiere idempotencia en cada escritura.
5. Aplica presupuestos por agente y falla cerrado.

Los incidentes con agentes no van a desaparecer. Cada equipo que despliegue agentes autónomos se encontrará con bucles, reintentos, esquemas desviados o permisos excesivos. Los equipos que se recuperan rápido serán los que ya tenían barreras de seguridad en la API.

Descarga Apidog y empieza por el servidor mock. Es el cambio más rápido para evitar que un agente practique contra producción.

También puedes revisar herramientas de prueba de API para ingenieros de QA y cómo escribir archivos AGENTS.md para definir herramientas que los agentes puedan usar de forma más segura.

Preguntas frecuentes

¿Cómo pruebo llamadas de agentes sin gastar dinero en tokens?

Usa un servidor mock durante el desarrollo. Las URLs mock de Apidog devuelven respuestas realistas sin llamar servicios reales. Fija la temperatura a 0, usa un conjunto pequeño de prompts y ejecuta escenarios repetibles. Para una lista más completa, consulta la lista de verificación de pruebas para QA.

¿Cuál es la diferencia entre probar el agente y probar la API?

Probar el agente verifica si el modelo elige la herramienta correcta y rellena argumentos válidos.

Probar la API verifica si el endpoint se comporta correctamente cuando recibe la llamada.

Necesitas ambas capas. Un agente correcto llamando una API rota sigue produciendo resultados rotos. Un agente roto llamando una API correcta sigue ejecutando acciones equivocadas.

¿Necesito idempotencia en cada endpoint?

En cada endpoint de escritura, sí.

Las lecturas son idempotentes por definición. Las escrituras no. Los agentes reintentan por timeouts, errores 500, respuestas ambiguas o planificación incorrecta. Una clave de idempotencia evita duplicados.

¿Cómo evito que una inyección de prompt dispare llamadas peligrosas?

No dependas solo del prompt. La API debe aplicar autorización según el usuario original y el scope del agente.

Si el usuario no puede acceder a:

DELETE /admin/users

el agente que actúa en su nombre tampoco debe poder hacerlo, aunque el prompt lo pida.

¿Puedo usar Apidog con Claude o GPT?

Sí. Durante pruebas, apunta las herramientas del agente a la URL mock de Apidog mediante una variable de entorno:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id

Cuando quieras probar en staging o producción, cambia esa variable.

¿Cuál es un buen límite de presupuesto para un agente?

Empieza estricto y ajusta con métricas.

Valores iniciales razonables:

• 50.000 tokens por sesión.
• 30 llamadas API por minuto.
• 5 dólares por tarea.
• 10 llamadas de herramienta anidadas.
• Máximo 5 escrituras por sesión.

Revisa los datos durante dos semanas y ajusta. El objetivo es detectar bucles descontrolados sin bloquear trabajo legítimo.

¿Cómo detecto desviación entre herramientas y API?

Ejecuta una comparación de esquemas en CI. Compara el JSON Schema de la herramienta del agente con el request body definido en OpenAPI para el mismo endpoint.

Si divergen, falla el build. El fragmento de Python de la sección de pruebas de contrato es suficiente para empezar.