Cómo diseñar contratos de herramientas para agentes

Una herramienta de agente no es solo una función que llama a la API del producto. Es un contrato escrito para el modelo: nombre, descripción, qué datos puede enviar y qué forma de respuesta recibirá. El modelo elige si llamar a esa herramienta y con qué argumentos; el programa del producto valida, comprueba permisos, ejecuta la acción real y devuelve un resultado que el modelo puede leer en el siguiente paso. Si el contrato es vago, el modelo rellena mal. Si la ejecución no tiene reglas, un fallo se convierte en tres llamadas iguales.

Este artículo responde cómo definir esa herramienta (en inglés suele llamarse tool) para que el modelo la use con criterio, el sistema la ejecute con los permisos correctos y los errores no rompan la tarea entera.

Si buscas el mapa de capas del agente (modelo, acciones, memoria, permisos, registro), está en el modelo no es el agente. Este artículo baja un nivel: cómo escribir el contrato de una tool concreta antes de exponerla en producción.

Los proveedores lo documentan como function calling o tool use: el modelo no ejecuta la API del producto directamente. Devuelve una propuesta en JSON (qué herramienta y con qué parámetros) y el código del servidor decide si ejecuta, con qué credenciales y qué devolver al modelo.

Esa definición (nombre, descripción, esquema, forma de la respuesta) es independiente de cómo se ejecute la acción después. Cuando la tool está disponible, el modelo recibe una definición del contrato; el harness puede decidir cuándo exponerla (filtrar, versionar, agrupar o descubrir tools dinámicamente). La ejecución puede ser una llamada HTTP interna, un comando en un entorno acotado o un servidor MCP que el cliente del agente descubre: eso es lo que comparamos en MCP frente a CLI. Cambiar de superficie sin endurecer el contrato solo mueve el problema de sitio.

Por qué el contrato importa más que la función

En una demo suele bastar con enseñar una acción concreta: por ejemplo, una herramienta llamada create_refund que recibe un order_id y, en la reunión, devuelve "reembolso creado" una vez. En la sala solo se ve el escenario que el equipo ya había ensayado, y es fácil dar por hecho que el agente sabrá reembolsar en cualquier situación real.

En producción el modelo no ve la función en el código fuente. Ve la definición de la tool en texto, en cada turno en que esa tool está disponible. Si la descripción dice solo "gestiona pedidos" y el esquema permite diez campos opcionales, el modelo probará combinaciones que la API no acepta: montos sin moneda, IDs de otro formato o acciones mezcladas con lecturas.

El contrato es lo que el modelo lee. La función en el servidor es lo que realmente muta datos. Cuando el equipo confunde las dos cosas, aparecen dos síntomas típicos: se reescribe el prompt durante semanas cuando el problema es el esquema, o se endurece el prompt cuando el problema es que la API devuelve errores que el modelo no puede interpretar.

Anthropic documenta el uso de tools con nombres claros y esquemas acotados; en Building effective agents, al hablar de agentes que resuelven issues en SWE-bench, cuentan que les llevó más tiempo afinar el formato de las tools (rutas, parámetros, salidas) que las instrucciones del sistema. OpenAI describe el mismo flujo en function calling (descripción, parámetros tipados, validación en servidor) y en salidas estructuradas insiste en ceñirse al esquema. Lo que muchos equipos SaaS echan en falta no es el enlace al proveedor, sino un mapa interno: esquema, permisos, errores legibles y reintentos sin duplicar efectos en negocio.

Qué debe incluir un contrato de tool

Son cuatro piezas que el modelo y el programa de ejecución deben compartir: nombre, descripción (para qué sirve), parámetros de entrada y forma de la salida (éxito o error).

Nombre y descripción que el modelo entiende

El nombre es un identificador estable: get_order, no fetchOrderData_v2. El modelo lo repetirá en cada propuesta de llamada; si cambia cada release, las trazas y las pruebas de regresión dejan de cuadrar.

La descripción debe decir cuándo usar la tool y cuándo no. "Devuelve el estado de un pedido por ID" es mejor que "herramienta de pedidos". Una frase del tipo "no uses esto para crear reembolsos; usa create_refund" suele reducir más errores que un párrafo extra en las instrucciones generales del agente.

Si el catálogo tiene muchas tools, el contrato incluye también si esta tool está visible en esta tarea. Meter cincuenta definiciones en el primer mensaje llena el contexto y empeora la elección. En el harness del agente (el programa que orquesta el bucle modelo-tools-permisos) suele haber descubrimiento o agrupación por caso de uso: una tool puede existir en el sistema pero no estar ofrecida al modelo hasta que la tarea la necesite.

Parámetros, tipos y campos obligatorios

El esquema, a menudo JSON Schema en las APIs de OpenAI y Anthropic, fija tipos, campos obligatorios y a veces valores permitidos. Pedir order_id como texto obligatorio evita que el modelo envíe un objeto anidado que la API no entiende.

Reglas que funcionan en SaaS:

• Una intención por tool. Mezclar "buscar" y "borrar" en la misma función obliga al modelo a elegir modo con un interruptor; dos tools separadas suelen fallar menos.

• IDs de negocio en el esquema (order_id, identificador de cuenta de cliente) cuando la acción es por cliente, sin asumir que "ya está en el chat".

• Límites numéricos en el esquema (por ejemplo limit máximo 20) alineados con lo que la API rechaza, no con lo que el modelo considere razonable.

El proveedor puede rechazar la propuesta antes de ejecutar; el servidor del producto debe validar otra vez antes de la API de negocio.

Qué devuelve la tool (y qué no)

La salida vuelve al modelo en el siguiente mensaje de tipo tool, como texto o JSON acotado: campos para el siguiente paso y, si falla, un código estable más un mensaje breve. No conviene reenviar el JSON crudo de la API ni secretos, tokens o datos de otro cliente. Identidad y permisos aplican también a lo que devuelve la tool.

Permisos: el modelo propone, el sistema ejecuta

El modelo solo emite una propuesta: nombre de tool y argumentos. Quien ejecuta es el servicio del producto, con la identidad del agente, la cuenta del cliente y los permisos del usuario que inició la tarea. Si se omite esa capa porque "el modelo ya sabe que no debe", no hay contrato de ejecución: hay confianza ciega.

Flujo mínimo:

1. El modelo propone create_refund con { "order_id": "…", "amount": 50 }.

2. El programa de ejecución comprueba que la tool existe, que los parámetros cumplen el esquema y que el agente puede hacer esa acción en esa cuenta.

3. Solo entonces se llama a la API de negocio, a menudo con credenciales de servicio acotadas, no con la sesión amplia de un administrador.

La misma tool puede comportarse distinto según el rol: lectura sin fricción, escritura con umbral o cola de aprobación humana. Eso no debería ser la única barrera en el texto que lee el modelo; va en la política del harness.

Errores que el modelo puede corregir

Si la API responde con HTML o un texto genérico, el modelo no tiene material para ajustar nada. Si la tool devuelve un JSON pequeño con un code estable, el harness y el modelo pueden reaccionar distinto según el tipo:

Evita mensajes del tipo "error al procesar". En trazabilidad esos bucles a veces parecen varias respuestas HTTP correctas y un fallo de negocio que nadie ve.

Reintentos, timeouts y límites

Un timeout en la API no es permiso para que el modelo lance la misma tool cinco veces. Tras un timeout no sabes si la acción llegó a ejecutarse: antes de repetir una mutación, consulta el estado (por ejemplo si el reembolso ya existe) o reenvía la misma clave de idempotencia que la API de negocio entienda. Sin esa regla, un reembolso duplicado es un incidente, no un detalle de red.

Política práctica:

• Reintentos automáticos solo en errores transitorios, con tope (por ejemplo 2) y clave de idempotencia en acciones con efecto lateral.

• Sin reintento automático en validación, permisos o resultados de negocio de la tabla anterior.

• Tope de llamadas a la misma tool por tarea, para cortar bucles del tipo "buscar de nuevo" diez veces.

La descripción puede orientar al modelo ("si devuelve not_found, pide otro id"); el harness debe imponer topes aunque el modelo ignore esa frase.

Ejemplo mínimo en código

Definición que el modelo ve (forma habitual en APIs compatibles con JSON Schema):

{
  "name": "get_order",
  "description": "Obtiene el estado de un pedido por ID en la cuenta actual. No crea ni modifica pedidos. Usar solo cuando ya tienes order_id.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Identificador del pedido en el sistema de facturación."
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

{
  "name": "get_order",
  "description": "Obtiene el estado de un pedido por ID en la cuenta actual. No crea ni modifica pedidos. Usar solo cuando ya tienes order_id.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Identificador del pedido en el sistema de facturación."
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

{
  "name": "get_order",
  "description": "Obtiene el estado de un pedido por ID en la cuenta actual. No crea ni modifica pedidos. Usar solo cuando ya tienes order_id.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Identificador del pedido en el sistema de facturación."
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

additionalProperties: false reduce campos inventados por el modelo; conviene comprobar que la API del proveedor lo admite en el esquema (por ejemplo modo estricto en function calling de OpenAI o las reglas de tu versión en Anthropic).

Ejecución en el servidor (idea, no librería concreta):

async function runToolCall(proposal, ctx) {
  if (proposal.name !== "get_order")
    return toolError("tool_not_allowed", "Esta tool no está habilitada en esta tarea");
  const parsed = validateGetOrder(proposal.arguments);
  if (!parsed.ok) return toolError("invalid_argument", parsed.message);
  if (!ctx.can("orders:read", ctx.tenantId))
    return toolError("permission_denied", "Sin permiso de lectura de pedidos");
  const order = await billingApi.getOrder(ctx.tenantId, parsed.value.order_id);
  if (!order) return toolError("not_found", "Pedido no encontrado en esta cuenta");
  return toolSuccess({ order_id: order.id, status: order.status, total: order.total });
}

async function runToolCall(proposal, ctx) {
  if (proposal.name !== "get_order")
    return toolError("tool_not_allowed", "Esta tool no está habilitada en esta tarea");
  const parsed = validateGetOrder(proposal.arguments);
  if (!parsed.ok) return toolError("invalid_argument", parsed.message);
  if (!ctx.can("orders:read", ctx.tenantId))
    return toolError("permission_denied", "Sin permiso de lectura de pedidos");
  const order = await billingApi.getOrder(ctx.tenantId, parsed.value.order_id);
  if (!order) return toolError("not_found", "Pedido no encontrado en esta cuenta");
  return toolSuccess({ order_id: order.id, status: order.status, total: order.total });
}

async function runToolCall(proposal, ctx) {
  if (proposal.name !== "get_order")
    return toolError("tool_not_allowed", "Esta tool no está habilitada en esta tarea");
  const parsed = validateGetOrder(proposal.arguments);
  if (!parsed.ok) return toolError("invalid_argument", parsed.message);
  if (!ctx.can("orders:read", ctx.tenantId))
    return toolError("permission_denied", "Sin permiso de lectura de pedidos");
  const order = await billingApi.getOrder(ctx.tenantId, parsed.value.order_id);
  if (!order) return toolError("not_found", "Pedido no encontrado en esta cuenta");
  return toolSuccess({ order_id: order.id, status: order.status, total: order.total });
}

La propuesta del modelo nunca llama a billingApi directamente. Ese middleware es el contrato de ejecución.

Checklist antes de exponer una tool en producción

Cuando el checklist se cumple, la tool puede entrar en el catálogo del agente con el mismo rigor que una ruta HTTP pública: versión, prueba de regresión con propuestas reales del modelo y revisión cuando cambie la API de negocio.

Si el siguiente paso es montar muchas tools a la vez, conviene un catálogo pequeño por caso de uso y contratos estrechos antes que un envoltorio de toda la API. El modelo no necesita el mapa completo; necesita la acción correcta con datos mínimos y un sistema que ejecute con criterio.