¿Qué es un contrato de herramienta en un agente de voz?
Un contrato de herramienta define qué operación puede solicitar el agente, qué datos necesita, qué resultados devuelve y cómo representa errores o estados incompletos.
En voz, el contrato debe ser preciso y rápido porque la persona espera en línea mientras se ejecuta.
Una función ambigua como «gestionar cliente» deja demasiado espacio al modelo. Es preferible separar consultar, crear, modificar, cancelar y transferir.
Entradas pequeñas y validadas
El schema debe indicar campos obligatorios, formatos, valores permitidos y significado. Fechas y zonas horarias se normalizan; teléfonos e identificadores se validan antes de llamar al backend.
Los datos inferidos y los confirmados por el usuario no deben tratarse igual. Una herramienta sensible puede exigir un campo explícito de confirmación.
Resultados que representan el negocio
La salida debe distinguir encontrado, no encontrado, no autorizado, conflicto, pendiente y error técnico. Un booleano genérico impide explicar qué ocurrió y elegir el siguiente paso.
Cuando una operación crea un registro, conviene devolver su identificador y estado final. El agente puede confirmar utilizando esos datos, no una suposición.
Timeouts, reintentos e idempotencia
El contrato necesita un tiempo máximo compatible con la conversación. Si la operación tarda más, puede transformarse en un proceso asíncrono y ofrecer seguimiento.
Los reintentos deben ser seguros. Consultar puede repetirse; crear una cita o emitir un pago necesita una clave idempotente que evite duplicados.
Autorización por operación
La herramienta comprueba permisos en el backend y no confía únicamente en lo que afirma el prompt. El número de teléfono de origen puede ayudar a localizar una cuenta, pero no siempre autentica a la persona.
Lectura y escritura deben separarse. Las acciones de mayor impacto pueden exigir verificación adicional o revisión humana.
Evitar falsos éxitos
Una herramienta no debe responder éxito sólo porque aceptó la petición. Debe comprobar que el cambio existe en el sistema de destino o devolver un estado pendiente.
El agente tampoco debe anunciar una acción antes de recibir el resultado. En voz, una confirmación falsa se recuerda más que un mensaje de error transparente.
Probar el límite entre agente y backend
Las pruebas de contrato cubren schemas, campos faltantes, permisos, conflictos, timeouts, errores y repetición. Son más rápidas y localizan mejor el fallo que una prueba completa de llamada.
Los logs deben relacionar llamada, turno, tool call y operación real para reconstruir qué se pidió y qué sucedió.
¿Qué es una API?
Arquitectura de agentes de IA
Niveles de autonomía
Casos límite y escalado
Integrar IA con el CRM
Si quieres aplicar IA en tu negocio,
Te explico qué hago y cómo trabajo: Aquí