De la decisión a la acción: cómo implementar tool calling, idempotencia y observabilidad en agentes de IA

En la primera parte de esta serie planteamos un principio: la autonomía de un agente y su autoridad para ejecutar acciones son cosas distintas que se gobiernan por separado.

Aquí bajamos ese principio a código: cómo se implementa esa frontera en un sistema real, sin depender de que el modelo "se porte bien".

¿Cómo se conecta un agente de IA a un sistema real sin darle acceso arbitrario?

No dejando que el modelo genere código o consultas libres contra tu base de datos o tu API. El patrón correcto es exponerle un conjunto cerrado de herramientas con un esquema explícito — tool calling o function calling — donde el modelo solo puede pedir una acción con una forma exacta de parámetros, nunca ejecutar algo fuera de ese contrato:

export const createPurchaseOrderTool = {
  name: "create_purchase_order",
  description: "Crea una orden de compra para un proveedor autorizado.",
  parameters: {
    type: "object",
    properties: {
      sku: { type: "string", description: "Código de inventario único" },
      quantity: { type: "integer", minimum: 1 },
      supplierId: { type: "string" },
      expectedDeliveryDate: { type: "string", format: "date" }
    },
    required: ["sku", "quantity", "supplierId", "expectedDeliveryDate"],
    additionalProperties: false
  }
} as const;

Aquí hay un matiz importante que suele pasarse por alto: un esquema validado no es lo mismo que una decisión correcta. La documentación de Anthropic sobre salidas estructuradas es explícita en esto — garantizar que la salida de un modelo cumple un JSON Schema asegura la forma de la respuesta, no que su contenido sea preciso; el modelo puede seguir generando una respuesta perfectamente válida y a la vez equivocada. El esquema es una barrera de forma, no una barrera de verdad. La verificación del contenido — ¿este proveedor existe? ¿esta cantidad tiene sentido? ¿este SKU está activo? — tiene que vivir en una capa aparte, después de la validación de esquema y antes de la ejecución.

¿Qué pasa si un agente ejecuta la misma acción dos veces?

Pasa más de lo que parece, y casi siempre por la misma razón: el agente envía una petición, la operación se completa del lado del servidor, pero la respuesta se pierde por un timeout de red. El agente interpreta que falló y reintenta. Resultado: dos órdenes de compra donde debía haber una.

La solución no es nueva — es la misma que usan las APIs de pago desde hace más de una década. Stripe resuelve esto con una idempotency key: un identificador único que el cliente genera para cada operación; si la API recibe dos peticiones con la misma clave, la segunda no se vuelve a ejecutar — simplemente devuelve el resultado guardado de la primera, incluso si esa primera petición fue un error.

Para un agente, la clave natural combina el identificador de la ejecución con el de la acción concreta dentro de ella:

// 1. Generación determinista por acción y corrida del agente
const idempotencyKey = `${runId}:${actionId}`;

// 2. Encabezado HTTP inyectado hacia la API transaccional (ERP / Pasarela)
const requestHeaders = {
  "Idempotency-Key": idempotencyKey, // ej: "run_8f31:create_po"
  "X-Agent-Step": "po_replenishment"
};

Ese detalle — que suena a nota al pie de página — es exactamente lo que separa una demo de un sistema de producción. En una demo, nadie reintenta nada. En producción, las redes fallan constantemente, y cualquier acción con efectos secundarios reales necesita esta protección implementada en el servicio que ejecuta la operación, nunca confiando en que el agente "recuerde" que ya lo hizo.

¿Dónde debe vivir el estado de un agente: en la conversación o en la base de datos?

En ninguno de los dos exclusivamente — y mezclarlos es uno de los errores más comunes al pasar de un prototipo a un sistema real. Conviene separar tres cosas que se parecen pero no son lo mismo:

• Estado de negocio — inventario, órdenes, proveedores, contratos. Vive en los sistemas transaccionales de siempre (ERP, base de datos), no en el agente. Es la fuente de verdad.
• Estado de ejecución — en qué paso va el flujo, qué herramientas se llamaron, qué aprobaciones están pendientes, cuántos reintentos ha habido. Esto sí necesita persistirse para poder pausar una ejecución y retomarla después — por ejemplo, mientras se espera una aprobación humana.
• Memoria y contexto — instrucciones, documentación, resultados anteriores relevantes para interpretar la tarea actual.

Tratar la memoria conversacional como si fuera el estado operativo del sistema es lo que hace que un agente se vuelva errático con el tiempo: la ventana de contexto se satura con ruido que no debería estar ahí, y la fuente de verdad del negocio termina dependiendo de lo que el modelo "recuerda" haber hecho, en lugar de lo que el sistema transaccional confirma que ocurrió.

¿Cómo se audita la decisión de un agente sin depender de su cadena de pensamiento?

No registrando el razonamiento interno del modelo como mecanismo de auditoría — es un texto no estructurado, no verificable y que puede cambiar de formato entre una llamada y otra. Lo que sí es auditable es una traza estructurada de la ejecución: qué información se consultó, qué herramientas se usaron, qué política se aplicó, qué decisión se produjo y qué autorización recibió.

{
  "run_id": "run_8f31",
  "workflow": "inventory_replenishment",
  "sku": "ABC-123",
  "tools_used": [
    "get_inventory",
    "get_demand_forecast",
    "calculate_reorder_point"
  ],
  "decision": {
    "action": "CREATE_PURCHASE_ORDER",
    "quantity": 500,
    "supplier": "SUP-42"
  },
  "policy_applied": {
    "max_order_value": 10000,
    "requires_approval": true
  },
  "approval": {
    "approved_by": "operations_manager",
    "approved_at": "2026-09-10T14:32:00Z"
  },
  "execution": {
    "idempotency_key": "run_8f31:create_po",
    "result": "success",
    "erp_reference": "PO-10452"
  }
}

Esto ya no es un capricho de ingeniería prolija — se está convirtiendo en un estándar de facto. OpenTelemetry, el proyecto de referencia para observabilidad en sistemas distribuidos, publica convenciones semánticas específicas para agentes de IA que estandarizan cómo se registran las llamadas a herramientas, el razonamiento entre pasos y la coordinación entre agentes, precisamente para que estas trazas sean comparables entre proveedores y frameworks distintos.

¿Cómo se sabe si un sistema agéntico está listo para producción?

Con métricas distintas a las que se usan para evaluar un chatbot. La calidad de una respuesta conversacional no dice nada sobre si un agente puede operar de forma segura contra un sistema real. Las que sí importan:

• Tasa de intervención humana — qué porcentaje de acciones necesitó revisión.
• Tasa de rechazo — cuántas propuestas del agente fueron rechazadas por un operador.
• Tool-call success rate — cuántas llamadas a herramientas terminaron correctamente al primer intento.
• Duplicación de operaciones — la métrica que confirma si la idempotencia está realmente funcionando.
• Coste por workflow completo — no el coste de una sola llamada al modelo, sino de todo el ciclo hasta la acción final.
• Impacto operativo real — ¿bajaron de verdad los stockouts, el inventario excedente o las compras urgentes? Esta es la única métrica que realmente le importa al negocio; todas las anteriores existen para diagnosticar por qué esta sube o baja.

Un sistema que exige revisión humana en el 90% de sus acciones no está fallando técnicamente — pero tampoco está automatizando nada. Esa tasa de intervención es la señal más honesta de qué tan bien calibrada está la arquitectura de autonomía por niveles que vimos en la primera parte.

¿Qué pasa cuando dos pasos del sistema recomiendan acciones distintas?

Aparece en cuanto hay más de una fuente de señal alimentando la misma decisión — un modelo de demanda que sugiere comprar más, y una regla de presupuesto que sugiere esperar. La forma robusta de resolverlo no es dejar que el propio modelo "decida cuál argumento es más convincente", sino convertir cada recomendación en un objeto estructurado con su propia evidencia y nivel de confianza, y dejar que un motor de reglas explícito — no el LLM — aplique la política final:

SI proyección_stockout < 14 días
Y  proveedor_aprobado == true
Y  valor_orden < límite_presupuesto
ENTONCES
  aprobación = "automática"
SI NO
  aprobación = "revisión_humana_obligatoria"

El modelo interpreta y propone. La política, escrita como código determinista, decide qué está permitido. Esa separación es la que hace que el sistema sea auditable y predecible incluso cuando el modelo detrás cambia de versión.

Preguntas frecuentes

¿Qué es tool calling o function calling en un agente de IA?

Es el mecanismo por el que un modelo de lenguaje solicita ejecutar una acción específica — con parámetros que cumplen un esquema predefinido — en lugar de generar código o consultas libres contra un sistema. Es lo que permite conectar un agente a un ERP u otra API sin darle acceso irrestricto.

¿Qué es una idempotency key y por qué la necesita un agente?

Es un identificador único asociado a una operación concreta que permite que un reintento por fallo de red no duplique la acción — el sistema receptor reconoce que ya procesó esa clave y devuelve el resultado original en lugar de repetir la operación. Es indispensable en cualquier acción del agente con efectos secundarios reales, como crear una orden o enviar un pago.

¿Por qué no se debe usar la cadena de pensamiento del modelo como registro de auditoría?

Porque es texto no estructurado, no verificable y puede variar de formato entre ejecuciones. Una auditoría defendible se basa en una traza estructurada: qué datos se consultaron, qué herramientas se usaron, qué política se aplicó y qué resultado produjo la ejecución — no en la explicación en lenguaje natural que el modelo genera sobre su propio razonamiento.

¿Qué métricas indican que un agente está listo para producción?

Como mínimo: tasa de intervención humana, tasa de rechazo de sus propuestas, porcentaje de llamadas a herramientas exitosas, tasa de operaciones duplicadas, coste por flujo completo y, sobre todo, si mejoró un indicador operativo real del negocio.

¿El estado del agente debe guardarse junto con el historial de la conversación?

No. El estado de negocio vive en los sistemas transaccionales, el estado de ejecución (en qué paso va el flujo) se persiste aparte para poder pausar y reanudar, y la memoria conversacional es solo contexto de apoyo — mezclar estas capas es una de las causas más comunes de comportamiento errático en agentes que llevan tiempo corriendo.

Esta es la segunda parte de la serie sobre arquitectura de sistemas agénticos. Si no has leído la primera — autonomía frente a autoridad de ejecución — ahí está el principio de gobernanza que sostiene todo lo anterior. Ambas piezas continúan la línea de nuestra guía sobre desarrollo agéntico en equipos de software.

Fuentes técnicas

• Structured outputs — Claude Docs (Anthropic): docs.claude.com
• Idempotent requests — Stripe Documentation: docs.stripe.com
• Semantic Conventions for GenAI agent spans — OpenTelemetry: opentelemetry.io