Function calling y herramientas: reglas para que un agente no rompa tu negocio

Function calling es una de las piezas más importantes para construir agentes útiles. También es una de las más mal usadas. Darle herramientas a un modelo no significa dejarlo hacer cualquier cosa. Significa darle acciones pequeñas, tipadas y verificables.

Un agente confiable no "decide llamar una API" de forma libre. Llama una herramienta declarada con parámetros permitidos y reglas claras.

Herramienta mala

runAction({ instruction: string })

Esta herramienta parece flexible, pero es peligrosa. El modelo puede mandar cualquier instrucción, mezclar acciones y saltarse validaciones.

Herramienta buena

createSupportTicket({
 customerId: string,
 category: "billing" | "technical" | "complaint",
 summary: string,
 priority: "low" | "normal" | "urgent"
})

Aquí hay un contrato. El sistema puede validar customerId, limitar categorías, revisar prioridad y auditar que se creó.

Reglas básicas

1. Una herramienta debe hacer una cosa.
2. Los parámetros deben ser estrictos.
3. El backend debe validar todo otra vez.
4. Las acciones irreversibles requieren confirmación.
5. Las herramientas deben devolver resultados estructurados.
6. Los errores deben ser claros para el agente y para logs humanos.

Permisos por contexto

No todas las herramientas deben estar disponibles siempre. Un usuario anónimo no debería poder consultar órdenes. Un agente en Telegram de comunidad no debería tener acceso a datos internos. Un agente de soporte puede crear tickets, pero no aprobar reembolsos sin humano.

Define permisos por:

• Usuario.
• Canal.
• Estado de conversación.
• Riesgo de la acción.
• Autorización comprobada en el servidor; la confianza expresada por el modelo no concede permisos.

Confirmaciones

Antes de una acción sensible, el agente debe resumir lo que va a hacer y pedir confirmación. Ejemplos:

• Cancelar una reserva.
• Cambiar una dirección.
• Enviar un mensaje masivo.
• Crear una orden.
• Modificar datos personales.

Auditoría

Guarda cada llamada con traceId, nombre de herramienta, resultado, identidad autorizada y versión del prompt/modelo. Minimiza o redacta inputs y outputs: no vuelques tokens, documentos privados ni datos personales completos a logs. Define retención y acceso. Una traza útil permite reconstruir la decisión sin convertirse en otra fuga de datos.

Un contrato descargable: preparar no es ejecutar

Descarga contrato-herramienta.json. Es una especificación didáctica de preparar_reembolso, no una API de pagos ni código conectado a un proveedor. Úsala para revisar una herramienta con tu equipo antes de implementar una escritura real.

El modelo propone pedidoId y un motivo permitido. El servidor obtiene por su cuenta usuario, tenant, roles e importe real. No confía en un customerId o importe porque el modelo lo haya escrito correctamente. Validar el schema evita formas inválidas; no prueba que quien pide el reembolso sea dueño del pedido.

Divide el flujo en dos operaciones:

1. Preparar: validar el pedido, comprobar permisos y devolver una propuesta con ID, importe calculado, destinatario y vencimiento. Todavía no hay pago.
2. Ejecutar: recibir una aprobación humana autenticada sobre esa propuesta exacta, revalidar permisos y vigencia y llamar al proveedor con una clave de idempotencia durable.

Un “sí” en texto libre no basta para aprobar una propuesta distinta o modificada. Si cambia el importe, el destinatario o el pedido, invalida la aprobación y pide una nueva. Si la API externa devuelve timeout después de recibir la solicitud, primero consulta el estado de la operación: reintentar sin conciliar puede duplicar el reembolso.

Matriz de pruebas que sí puede bloquear una herramienta

Caso	Preparación	Ejecución permitida
Pedido propio, rol válido	Propuesta con importe de la base	Solo tras aprobar la propuesta exacta
Pedido de otro tenant	Rechazar sin filtrar datos del pedido	Nunca
Importe enviado por el modelo	Ignorar/rechazar; calcular desde la base	Nunca con importe no validado
Aprobación vencida	Revalidar y generar otra propuesta	No reutilizar la anterior
Dos solicitudes concurrentes	Misma operación lógica identificada	Un único efecto externo
Timeout del proveedor	Estado pendiente de conciliación	No reintentar a ciegas

Estas pruebas son un plan para tu implementación, no resultados observados en una pasarela real. Empieza con un proveedor sandbox y una base de prueba. Inyecta explícitamente una caída después del envío y antes de guardar el resultado: es una ventana de fallo que una prueba feliz no descubre.

Errores que el agente puede entender sin recibir secretos

Define códigos estables como argumentos_invalidos, sin_permiso, requiere_aprobacion y resultado_pendiente. Incluye un identificador de traza que permita consultar el incidente con permisos adecuados; no devuelvas el stack trace ni cabeceras de autorización al modelo.

Un error corregible permite pedir un dato faltante. Un rechazo de permisos termina la acción: no invites al agente a buscar otro endpoint para hacer lo mismo. Pon límite total de pasos y reintentos; un JSON válido repetido mil veces sigue siendo una incidencia.

Para practicar el despacho de herramientas sin dinero ni escrituras, utiliza el agente de stock con pruebas locales. Luego añade evals de seguridad y decide si las herramientas se exponen directamente o mediante MCP. El curso gratuito sirve como alternativa si prefieres configurar un runtime existente.

La decisión final no es cuántas herramientas tiene el agente: es si puedes demostrar quién autorizó cada efecto, con qué datos y cómo evitas repetirlo.