Llamada a herramientas: diseñar herramientas que el agente use bien
Cuando un agente se porta mal, el instinto es reescribir el prompt. En nuestra experiencia el prompt es la causa quizá un tercio de las veces; el resto, las herramientas se diseñaron para un programa y no para quien debe deducir de nombres y descripciones qué hace una función.
Las herramientas son toda la capacidad del agente de afectar al mundo, y sus definiciones son literalmente parte del contexto del modelo. Diseñarlas bien es más barato y mucho más duradero que ajustar prompts, porque una buena herramienta restringe el comportamiento en vez de pedirlo.
Siete reglas que evitan casi toda llamada mala#
- Una herramienta, un trabajo. `search_orders` y `refund_order` ganan a un `manage_order` con modo.
- Tipos antes que prosa. Enumeraciones, rangos y formatos hacen lo que ninguna descripción hará.
- Nombres que digan lo que pasa. `send_email_to_customer` es inequívoco; `notify`, no.
- Errores como instrucciones: qué estuvo mal y qué hacer ahora, en una frase corta.
- Los resultados vacíos son resultados. Un no-encontrado explícito gana a una excepción.
- Claves de idempotencia en todo lo que tenga efecto, para que un reintento no duplique.
- Devoluciones pequeñas. Recorta a los campos necesarios; 40 KB de JSON compran confusión.
Antes y después#
| Diseño débil | Por qué falla | Mejor |
|---|---|---|
| `query(sql)` | Poder ilimitado, no auditable | `get_orders_by_customer(customer_id, limit)` |
| `date: string` | El modelo inventa formatos | `date: string, formato YYYY-MM-DD` |
| `HTTP 500` | No implica acción, se reintenta siempre | `Servicio de pedidos no disponible. Di al usuario que lo intente luego.` |
| Devuelve el registro entero | Llena el contexto, diluye la atención | Devuelve seis campos nombrados |
| `update_status(id, status)` | Cualquier estado, cualquier registro | `cancel_order(id)` con comprobación de permisos |
Las descripciones son prompt#
El campo de descripción no es documentación para tus colegas: es texto que el modelo lee al decidir. Di cuándo usar la herramienta y cuándo no, nombra la precondición importante y da un ejemplo de argumento. Tres frases ganan a tres párrafos. Y revísalas juntas en un fichero: herramientas que tienen sentido por separado suelen solaparse de formas que solo se ven leídas como conjunto.
Si dos herramientas pueden atender la misma petición, el agente elegirá mal a veces. Únelas o haz explícita la frontera en ambas descripciones.
Valida siempre antes de ejecutar#
Nunca pases la salida del modelo a una llamada de sistema sin comprobar. Valida los argumentos contra el esquema, resuelve identificadores contra registros que ese usuario pueda ver y rechaza lo que no encaje en vez de forzarlo. Un rechazo con mensaje claro es un buen resultado: el agente aprende la restricción y prueba otra cosa. Forzar en silencio es cómo se actualiza el registro equivocado sin que nadie se entere.
Prueba las herramientas aparte del agente#
Cada herramienta con sus pruebas: llamada válida, argumentos inválidos, permiso denegado, resultado vacío, timeout. Después prueba el agente contra una capa simulada para forzar esas condiciones. Casi todos los incidentes en producción que hemos revisado se reproducen trivialmente a este nivel — en particular el resultado vacío, raro en desarrollo y rutinario un martes por la tarde.
Preguntas frecuentes
¿Cuántas herramientas son demasiadas?
Más allá de unas diez en un bucle, la precisión de selección baja y las descripciones llenan el contexto. Si necesitas más, agrúpalas tras un router estrecho o divide en agentes especializados con conjuntos pequeños.
¿Deben devolver respuestas API en crudo?
No. Devuelve una forma pequeña y estable con los campos necesarios. Las respuestas crudas gastan contexto, exponen campos peligrosos y acoplan tu comportamiento a la versión de otra API.
¿Cómo evito que invente argumentos?
Restringiendo: enumeraciones en vez de texto libre, formatos explícitos e identificadores que deban resolverse. Luego valida y rechaza con claridad. Un argumento inventado suele indicar que la herramienta pedía algo que el agente no podía saber.
llamada a herramientasfunction calling agentesdiseño de herramientasjson schema herramientaserrores de herramientas llm
