Cómo Probar Agentes de IA que Usan tus APIs Sin Perder Datos

Un agente de codificación de IA ejecutó un script, lo vio terminar correctamente y después desapareció una tabla de la base de datos de producción. El post-mortem en Hacker News se hizo viral con una frase directa: “La IA no eliminó tu base de datos, tú lo hiciste”. El punto es correcto: el agente siguió una definición de herramienta, la herramienta llamó a un endpoint real, el endpoint no tenía salvaguardas y un humano había dado acceso de escritura a un proceso que no se detiene a preguntar si DELETE FROM users parece peligroso. En r/ClaudeAI apareció un caso parecido: un agente atrapado en un bucle de facturación consumió cientos de dólares en tokens antes de que alguien lo detectara. Superficie distinta, misma causa raíz: nadie probó la API.

Prueba Apidog hoy

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

TL;DR

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

La solución práctica:

1. Valida las definiciones de herramientas contra tu especificación OpenAPI.
2. Usa servidores mock para endpoints destructivos.
3. Exige claves de idempotencia en operaciones de escritura.
4. Aplica presupuestos por agente: tokens, solicitudes, coste y tiempo.
5. Reproduce escenarios de fallo en CI.

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

Introducción

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

Los agentes actuales llaman funciones. Esas funciones llaman APIs. Y esas APIs escriben en bases de datos, procesadores de pago, CRMs, sistemas de correo y servicios internos.

Una mala definición de herramienta ya no es un problema de estilo. Es un riesgo operativo.

El problema no suele estar en el modelo. Está en que la API acepta llamadas peligrosas sin validar:

• quién puede ejecutarlas;
• cuántas veces pueden repetirse;
• si la operación ya se ejecutó;
• si el esquema de entrada sigue siendo válido;
• si el agente está consumiendo más recursos de los permitidos.

Este artículo muestra cómo probar integraciones agente-API de extremo a extremo con patrones que puedes aplicar hoy.

Por qué los fallos de agentes parecen fallos de API

Cuando revisas incidentes de agentes, el patrón se repite: el modelo no es el componente crítico. La API lo es.

Inyección de prompt

Un usuario sube un PDF con instrucciones ocultas. El agente lo lee y llama a:

POST /admin/users

con un payload como:

{
  "delete_all": true
}

El modelo siguió instrucciones. La API fue la que permitió que un token asociado a una sesión de usuario llegara a una operación administrativa.

La mitigación no es solo endurecer el prompt. Es aplicar autorización del lado de la API. Si el usuario original no puede borrar usuarios, el agente que actúa en su nombre tampoco debe poder hacerlo.

Deriva de esquema

Tu OpenAPI define:

{
  "amount": {
    "type": "integer",
    "description": "Importe en céntimos"
  }
}

Pero la herramienta del agente define:

{
  "amount": {
    "type": "number",
    "description": "Importe en dólares"
  }
}

Meses después, alguien reembolsa 19 dólares en lugar de 19 céntimos.

El modelo no “se equivocó”. Usó el contrato que le diste. El contrato estaba roto.

Falta de límites de velocidad

Un agente reintenta una operación de correo porque su planificador marca el paso como “no completado”. En dos minutos llama mil veces a tu proveedor transaccional.

Resultado:

• coste innecesario;
• cola de correos saturada;
• clientes recibiendo spam;
• proveedor bloqueando la cuenta.

La API debería haber aplicado límites por agente, sesión y operación.

Falta de idempotencia

El agente llama a:

POST /payments

La red devuelve timeout. El agente reintenta. El primer cobro sí se procesó, pero el agente no lo sabe. El cliente termina cobrado dos veces.

La API debería aceptar una cabecera como:

Idempotency-Key: 8d41f0f8-5d5b-4e0d-a4e5-7f8bbf2d7d51

y devolver la misma respuesta para reintentos de la misma operación lógica.

Las cuatro salvaguardas que toda integración agente-API necesita

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 validarse contra ella.

Ejemplo mínimo en Python para detectar divergencias entre una definición de herramienta y OpenAPI:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Devuelve una lista de errores. Lista vacía = contrato válido."""
    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"Falta un campo requerido en la herramienta: {missing}")

    for extra in tool_props - api_props:
        errors.append(f"La herramienta define un campo inexistente en la 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"Desajuste de tipo en {prop}: "
                    f"API={api_def.get('type')} "
                    f"herramienta={tool_def_prop.get('type')}"
                )

    return errors

Úsalo en CI cada vez que cambie:

• la especificación OpenAPI;
• una definición de herramienta;
• un SDK usado por el agente;
• un endpoint llamado por el agente.

Ejemplo de fallo esperado:

$ python validate_tools.py

ERROR:
- Desajuste de tipo en amount: API=integer herramienta=number
- Falta un campo requerido en la herramienta: customer_id

La build debe fallar. No lo dejes como warning.

2. Mocks para endpoints destructivos

Los agentes necesitan practicar, pero no en producción.

Crea mocks para todos los endpoints que muten estado:

• POST;
• PUT;
• PATCH;
• DELETE.

Durante desarrollo, el agente debe llamar al mock. En staging, a una base de datos de prueba. En producción, solo después de pasar los escenarios y con permisos acotados.

Apidog genera mocks desde OpenAPI, incluyendo respuestas con estructura realista. El flujo recomendado:

1. Importa tu OpenAPI.
2. Identifica endpoints destructivos.
3. Define respuestas mock.
4. Configura el agente con la URL base del mock.
5. Ejecuta escenarios repetibles.
6. Revisa trazas de llamadas a herramientas.

Ejemplo:

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

Así, una llamada como:

DELETE /users/123

devuelve una respuesta controlada sin tocar producción.

Para profundizar en este patrón, revisa el artículo sobre desarrollo contract-first.

3. Idempotencia y eliminaciones suaves

Toda escritura invocada por un agente debe ser idempotente.

Ejemplo de middleware 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: "Falta la cabecera Idempotency-Key"
    });
  }

  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 { randomUUID } from "crypto";

const idempotencyKey = randomUUID();

await fetch(`${process.env.API_BASE_URL}/payments`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey
  },
  body: JSON.stringify({
    customer_id: "cus_123",
    amount: 1999,
    currency: "eur"
  })
});

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

Para eliminaciones, usa eliminación suave por defecto:

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

Reserva la eliminación física para rutas separadas, con aprobación humana.

4. Presupuestos por agente

Cada agente debe tener límites explícitos:

• tokens por sesión;
• llamadas por minuto;
• coste acumulado;
• tiempo máximo de ejecución;
• profundidad máxima de llamadas a herramientas.

Ejemplo de política:

{
  "agent_id": "support-triage-agent",
  "limits": {
    "tokens_per_session": 50000,
    "api_calls_per_minute": 30,
    "cost_cents_per_task": 500,
    "tool_call_depth": 10,
    "max_runtime_seconds": 300
  }
}

Cuando se supera un límite, devuelve 429 con información estructurada:

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,
  "action": "escalate_to_human"
}

El planificador del agente debe detenerse, registrar el evento y escalar.

Probar llamadas de API del agente con Apidog

Este flujo usa Apidog como entorno de diseño, mock y pruebas.

Necesitas:

• una especificación OpenAPI 3.x;
• las definiciones de herramientas del agente;
• un conjunto de escenarios representativos;
• variables de entorno para cambiar entre mock, staging y producción.

Paso 1: Importa la especificación OpenAPI

En Apidog:

1. Crea un proyecto.
2. Importa tu archivo OpenAPI.
3. Revisa rutas, esquemas y ejemplos.
4. Corrige nombres ambiguos o tipos incompletos.
5. Marca endpoints destructivos.

Si tu API aún no está documentada con OpenAPI, empieza ahí. La fiabilidad del agente depende de tener una fuente de verdad compartida.

La guía de flujo de trabajo design-first explica cómo estructurarlo desde cero.

Paso 2: Define respuestas mock para endpoints destructivos

Para cada endpoint que modifica datos:

• abre el endpoint;
• crea una respuesta mock;
• usa datos de prueba evidentes;
• evita valores que parezcan producción;
• añade casos de error.

Ejemplo de respuesta mock para DELETE /users/{id}:

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

Usa convenciones visibles:

• prefijos mock_;
• fechas antiguas;
• emails como user@example.test;
• IDs imposibles en producción.

Después, inicia el servidor mock y configura el agente:

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

No codifiques esta URL en prompts. Usa variables de entorno.

Paso 3: Escribe escenarios que reproduzcan llamadas del agente

Los escenarios de Apidog permiten encadenar llamadas y añadir aserciones.

Para un agente que clasifica tickets de soporte, el escenario puede ser:

1. POST /auth/token con credenciales de prueba.
2. Capturar el bearer token.
3. GET /tickets?status=open.
4. Capturar el ID del primer ticket.
5. POST /tickets/{id}/triage.
6. Asertar 200.
7. Validar que la categoría pertenece al enum permitido.
8. POST /notifications.
9. Asertar que el mensaje no contiene PII.

Ejemplo de aserciones útiles:

status == 200
response.body.assignee_id exists
response.body.category in ["billing", "technical", "account"]
response.body.message matches /^[A-Z].{20,500}$/

Este escenario prueba la secuencia real que ejecutará el agente, pero contra mocks o staging.

Para un manual más amplio, consulta pruebas de API para ingenieros de QA.

Paso 4: Ejecuta escenarios desde CI

La CLI de Apidog puede ejecutarse desde GitHub Actions, GitLab CI u otro runner.

Ejemplo:

apidog run -t scenario-id --env test

Ejemplo de workflow:

name: Agent API Contract Tests

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agents/tools/**"
      - ".github/workflows/agent-api-tests.yml"

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

    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog scenario
        run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} --env test
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}

Haz que esta pipeline sea obligatoria para mergear cambios que afecten a la API o a herramientas del agente.

Paso 5: Compara modelos en paralelo

Cuando cambies de modelo, no evalúes solo calidad de respuesta. Evalúa llamadas a herramientas.

Proceso:

1. Ejecuta el agente con el modelo A contra el escenario de Apidog.
2. Guarda la traza de llamadas.
3. Ejecuta el agente con el modelo B.
4. Guarda la nueva traza.
5. Compara métodos, rutas, payloads y orden de llamadas.

Diferencias que debes detectar:

• el nuevo modelo omite campos;
• cambia formatos de fecha;
• usa otro valor de enum;
• llama endpoints adicionales;
• reintenta más veces;
• cambia el orden de operaciones.

Esto ayuda a detectar deriva de comportamiento antes del despliegue. Este patrón también aparece en la integración de la API de GPT-5.5, donde comparar modelos es una necesidad recurrente.

Técnicas avanzadas

Fija la temperatura a cero en pruebas

Para pruebas de herramientas, usa comportamiento determinista:

{
  "temperature": 0,
  "top_p": 1
}

Estás probando integración, no creatividad.

Guarda trazas de llamadas a herramientas

Registra en cada ejecución:

• nombre de herramienta;
• método HTTP;
• ruta;
• argumentos;
• status code;
• latencia;
• idempotency key;
• presupuesto consumido.

Ejemplo de traza:

{
  "agent_id": "support-triage-agent",
  "tool_calls": [
    {
      "tool": "list_tickets",
      "method": "GET",
      "path": "/tickets",
      "status": 200
    },
    {
      "tool": "triage_ticket",
      "method": "POST",
      "path": "/tickets/123/triage",
      "status": 200
    }
  ]
}

Compara la traza con una línea base. Si el agente empieza a llamar /users dos veces, debes verlo antes de que llegue la factura.

Nunca des credenciales de producción al agente

Usa:

• cuentas de servicio con scope mínimo;
• tokens de corta duración;
• proxy de firma;
• permisos separados por entorno;
• rotación automática.

Evita archivos .env con credenciales amplias que el agente pueda leer.

Separa claves de lectura y escritura

Muchas tareas son de solo lectura. Emite claves separadas:

agent_read_key
agent_write_key

Las claves de escritura deberían requerir:

• aprobación humana;
• límites más estrictos;
• logging adicional;
• idempotencia obligatoria.

Usa HTTP 423 para aprobación humana

Cuando una operación requiere confirmación, responde:

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

{
  "error": "human_approval_required",
  "confirmation_url": "https://internal.example.com/approvals/req_123"
}

423 Locked comunica mejor “todavía no puedes hacerlo” que 403 Forbidden.

Falla cerrado ante deriva de esquema

Si la herramienta y OpenAPI no coinciden, la build debe fallar.

No permitas despliegues con:

• campos requeridos faltantes;
• tipos divergentes;
• enums incompletos;
• formatos incompatibles;
• rutas inexistentes;
• métodos HTTP incorrectos.

Errores comunes que debes evitar

• Codificar URLs de mock dentro de prompts.
• Probar agentes directamente contra producción.
• Omitir idempotencia en endpoints “pequeños”.
• Registrar payloads completos con PII.
• Dar acceso directo a la base de datos.
• Confiar en la puntuación de confianza del modelo.
• Usar la misma clave API para lectura y escritura.
• No limitar reintentos.
• No probar respuestas 429, 423, 500 y timeouts.
• Tratar OpenAPI como documentación opcional.

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

Alternativas y herramientas

Si ya usas LangSmith, mantenlo para evaluación del agente y añade pruebas de API separadas. Si buscas reemplazar Postman, Apidog es una alternativa fuerte. Si empiezas desde cero, prioriza una herramienta que maneje OpenAPI, mocks y escenarios juntos.

Casos de uso reales

Agente que actualiza filas de producción

Un equipo de soporte creó un agente que actualiza campos de cuentas desde tickets. Antes del lanzamiento:

• exigieron Idempotency-Key en cada escritura;
• ejecutaron 200 repeticiones de escenarios en Apidog;
• probaron contra base de datos de staging;
• validaron enums en todos los campos actualizables.

Las pruebas detectaron que el agente intentaba asignar subscription_status a una cadena fuera del enum. Añadieron validación y lanzaron sin incidentes.

Agente que llama una API de pagos

Un equipo fintech creó un agente de reembolsos automatizados con límites estrictos:

• máximo 5 reembolsos por sesión;
• máximo 50 dólares por reembolso;
• idempotencia obligatoria;
• aprobación humana para importes superiores al límite.

Además, ejecutaron la suite de contrato contra la OpenAPI de Stripe en cada PR.

Agente que clasifica issues de GitHub

Un equipo de plataforma construyó un agente de clasificación inspirado en Clawsweeper.

Antes de lanzarlo:

• simularon la API de GitHub en Apidog;
• ejecutaron 50 escenarios;
• cubrieron issues eliminados, etiquetas faltantes y entradas mal formadas;
• revisaron trazas de llamadas a herramientas.

Encontraron tres fallos antes de producción.

Checklist de implementación

Usa esta lista antes de permitir que un agente toque APIs reales:

• [ ] La API tiene especificación OpenAPI actualizada.
• [ ] Las herramientas del agente se validan contra OpenAPI.
• [ ] CI falla si hay deriva de esquema.
• [ ] Todos los endpoints destructivos tienen mock.
• [ ] El agente usa variables de entorno para cambiar base URL.
• [ ] Las escrituras requieren Idempotency-Key.
• [ ] Las eliminaciones son suaves por defecto.
• [ ] Hay límites por agente, sesión y tarea.
• [ ] Los errores 429, 423, 500 y timeouts están probados.
• [ ] Las credenciales están acotadas por scope.
• [ ] Lectura y escritura usan claves separadas.
• [ ] Las trazas de herramientas se guardan y comparan.
• [ ] No se registra PII sin redactar.
• [ ] Producción requiere aprobación humana para operaciones irreversibles.

Conclusión

El agente no es el único riesgo. La API es donde puedes convertir un fallo costoso en un error controlado.

Cinco acciones concretas:

1. Trata los esquemas de herramientas como contratos.
2. Simula endpoints destructivos durante desarrollo.
3. Exige idempotencia en cada escritura.
4. Establece presupuestos por agente.
5. Ejecuta escenarios en CI para cada cambio de API o herramienta.

Los incidentes virales no serán los últimos. La diferencia está en si tu API falla abierta o falla cerrada.

Descarga Apidog y empieza por el servidor mock. Es la protección más rápida de implementar. Para la perspectiva de QA, consulta herramientas de prueba de API para ingenieros de QA. Para escribir definiciones de herramientas más seguras, revisa cómo escribir archivos AGENTS.md.

Preguntas frecuentes

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

Ejecuta el agente contra un servidor mock durante desarrollo. Las URLs mock de Apidog devuelven respuestas realistas sin tocar servicios reales. Fija la temperatura en 0 y usa un conjunto pequeño de prompts repetibles. Consulta la lista de verificación de pruebas para QA.

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

Las pruebas del agente verifican si el modelo elige la herramienta correcta y rellena argumentos válidos. Las pruebas de API verifican si el endpoint se comporta correctamente cuando se llama. Necesitas ambas capas.

¿Necesito idempotencia en todos los endpoints?

En todos los endpoints de escritura, sí. Las lecturas ya son idempotentes por naturaleza. Las escrituras no. Los agentes reintentan, y cada reintento puede duplicar efectos si la API no lo evita.

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

No dependas solo del prompt. La API debe aplicar autorización usando el contexto del usuario original. Si ese usuario no puede acceder a /admin/delete-all-users, el agente tampoco debe poder hacerlo.

¿Puedo usar Apidog con Claude o GPT directamente?

Durante pruebas, apunta las herramientas del agente a la URL mock de Apidog mediante una variable de entorno. Cuando pases a staging o producción, cambia la URL base. Mantén el mismo contrato y los mismos escenarios.

¿Cuál es un buen límite presupuestario inicial?

Empieza estricto y ajusta con métricas:

• 50.000 tokens por sesión;
• 30 llamadas API por minuto;
• 5 dólares por tarea;
• 10 llamadas de herramienta anidadas;
• 5 minutos de ejecución.

Revisa los datos durante dos semanas y ajusta.

¿Cómo detecto deriva de esquema?

Ejecuta una comparación en CI entre la definición de herramienta del agente y el esquema OpenAPI del endpoint correspondiente. Si difieren en campos, tipos, enums o requeridos, falla la build. El snippet de Python anterior es suficiente para empezar.