Tool calling con modelos locales: troubleshooting
Cuando un agente local falla, a veces el modelo no es “tonto”: simplemente no está emitiendo llamadas a herramientas en el formato que tu runtime espera. La solución empieza por pruebas pequeñas y trazas claras.
Objetivos de aprendizaje
- Distinguir fallo de razonamiento, fallo de parser y fallo de permisos.
- Probar tools con un caso mínimo antes de usar repos reales.
- Elegir cuándo usar Ollama, Open WebUI, Hermes, MCP o vLLM.
En cristiano: tool calling. Es cuando el modelo no solo responde texto, sino que pide ejecutar una herramienta con argumentos estructurados: buscar, leer archivo, consultar API, calcular o modificar algo.
Diagnóstico en capas
- Modelo: ¿sabe seguir formato JSON/tool?
- Runtime: ¿Ollama, Hermes, Open WebUI o vLLM esperan el mismo formato?
- Parser: ¿extrae argumentos o se queda con texto libre?
- Permisos: ¿la tool existe y puede ejecutarse?
Terminal
Prueba mínima:
Herramienta disponible: get_time({ "timezone": "Europe/Madrid" })
Pregunta:
"Usa la herramienta get_time para decirme la hora en Madrid.
No inventes la hora. Si no puedes llamar la herramienta, dilo."
Resultado esperado:
- llamada estructurada a get_time
- argumentos válidos
- respuesta basada en salida real Idea clave. Si el modelo no puede llamar una tool de juguete, no lo pongas a gestionar GitHub, archivos o bases de datos.
Fallos típicos
- El modelo describe la tool en texto, pero no la invoca.
- Genera JSON inválido o con campos inventados.
- El runtime oculta el error y parece que “no pasa nada”.
- Una cuantización o conversión ha degradado el comportamiento con tools.
- La tool ejecuta código arbitrario sin revisión humana.
Cuidado. Open WebUI advierte que Tools, Functions, Pipes, Filters y Pipelines ejecutan Python en el servidor. Trátalos como código con permisos, no como “plugins inocentes”.
Terminal
Checklist: - Log de prompt completo - Log de tool schema - Log de salida del modelo antes del parser - Log de argumentos parseados - Log de ejecución real - Regla de aprobación humana para escritura
Comprueba que funciona. Haz una matriz modelo/runtime/tool. Si una combinación falla, no cambies todo: prueba el mismo modelo con otra tool o la misma tool con otro modelo.
Guardar y reabrir el proyecto.
Tool calling estable es ingeniería de interfaces: schema pequeño, parser compatible, permisos mínimos y trazas. Sin eso, el agente solo parece autónomo.