Guía Completa de Navidrome - Instalación y Primeros Pasos

Resumen ampliado

Un agente de inteligencia artificial no es simplemente una función que envía un prompt a un modelo y devuelve texto. Para resultar útil en automatización necesita, como mínimo, una entrada bien definida, una política o prompt de sistema, un modelo configurable, una capa de herramientas, control de errores y una salida verificable. Esta guía parte de una antigua prueba interna de Jesanre AI Agent y la convierte en un ejemplo genérico que cualquier usuario puede reproducir sin depender de la infraestructura privada de Jesanre Stack.

La implementación utiliza Python, FastAPI, Docker y OpenRouter. OpenRouter expone una API compatible con Chat Completions y permite seleccionar modelos mediante identificadores del tipo proveedor/modelo. La clave se mantiene fuera del código, en variables de entorno, y el servicio local añade un segundo token para proteger su propia API. El modelo tampoco se fija en el código: se define con OPENROUTER_MODEL, de modo que cambiar de proveedor o modelo no obliga a reconstruir la aplicación.

La guía construye primero un gateway LLM mínimo y después lo amplía con un bucle de herramientas. Para evitar un ejemplo peligroso, las herramientas son deliberadamente limitadas: contar palabras y guardar un fichero de texto dentro de un directorio de salida controlado. El modelo puede solicitar una herramienta, la aplicación valida sus argumentos, ejecuta la función local y devuelve el resultado al modelo para obtener una respuesta final. Este patrón permite entender el tool calling sin dar al modelo acceso arbitrario al shell, a Docker, al sistema de archivos completo o a credenciales del host.

El despliegue se realiza con una imagen Python ligera, usuario no privilegiado, .dockerignore, healthcheck y Docker Compose. El secreto de OpenRouter nunca se incluye en la imagen. También se explica cómo limitar la exposición del puerto, colocar el servicio detrás de HTTPS, revisar logs, añadir timeouts, gestionar respuestas HTTP y evitar que un endpoint público se convierta en una fuente de gasto o abuso.

La parte práctica incluye estructura de archivos, requirements.txt, Dockerfile, compose.yaml, configuración .env, API FastAPI y pruebas con curl. Se añaden comprobaciones para distinguir un fallo de red, autenticación, modelo inexistente, timeout o error interno de herramienta. La persistencia del ejemplo se limita a archivos de salida; una aplicación real puede añadir base de datos, cola de trabajos o memoria vectorial solo cuando exista una necesidad concreta.

El resultado es un agente pequeño pero técnicamente reconocible como tal: recibe una tarea, decide si necesita una herramienta, ejecuta esa herramienta bajo reglas locales y genera la respuesta final. No pretende sustituir frameworks de agentes más complejos. Su valor está en enseñar los componentes esenciales con una arquitectura que puede auditarse, contenerizarse y ampliarse gradualmente.

Guía completa: Leer la guía técnica completa en Jesanre Stack