Configuración de uv para escalar agentes de IA en producción

Escalar agentes de IA exige una arquitectura profesional, gestión confiable de dependencias y una API lista para producción. Aquí aprenderás a pasar de varios prototipos a un proyecto robusto: instalación de un gestor moderno llamado uv, separación de dependencias de desarrollo, configuración de carpetas y uso de LangGraph Studio y notebooks para depurar y visualizar grafos.

¿Cómo escalar agentes con una arquitectura profesional?

Adoptar una arquitectura modular evita fricciones al orquestar múltiples agentes, moverlos a producción y exponerlos en una API. La clave: configurar un gestor de paquetes moderno (uv), ordenar el repositorio y preparar herramientas de desarrollo como notebooks y observabilidad.

¿Qué problemas resuelve el gestor de paquetes uv?

• Reemplaza tareas dispersas que antes se hacían con pip, pip tools, Poetry y Virtualenv.
• Gestiona ambientes y dependencias de forma ligera y profesional.
• Acelera la instalación: el orador destaca que es “diez veces más rápido”.
• Centraliza la configuración con un archivo tipo project.toml y .gitignore.

¿Cómo se instala y verifica uv en el sistema?

• Instálalo según tu sistema operativo: Mac/Linux o Windows con WSL Ubuntu.
• Verifica la versión instalada:

uv version

• Si tienes un virtualenv previo, desactívalo y elimínalo para que uv gestione el entorno:

# Desactivar (ejemplo clásico)
source /bin/deactivate

# Eliminar la carpeta del entorno
RMF 

• Inicializa el proyecto y genera archivos base como project.toml y .gitignore:

uv init

¿Qué buenas prácticas de repositorio se aplican?

• Ignorar carpetas internas no necesarias para el código fuente (ejemplo: la de LangGraph).
• Ignorar variables de entorno para proteger tus keys:

*.env

• Definir explícitamente la versión de Python y separar dependencias de producción y desarrollo en el project.toml.

¿Cómo gestionar dependencias y entornos para producción y desarrollo?

Separar lo que necesitas para correr en producción de lo que usas para desarrollar evita empaquetar de más y reduce riesgos.

¿Cómo agregar dependencias con uv add?

• Sustituye pip install por el nuevo comando:

uv add  

• Reinstala las dependencias del proyecto con uv si eliminaste el entorno anterior.

¿Cómo separar dependencias de desarrollo como LangGraph CLI y Jupyter?

• El CLI se usa solo en desarrollo.
• Agrega el kernel de Jupyter para experimentos con notebooks, tools y flujos de agentes:

# Dependencias de desarrollo (ejemplo)
uv add  --dev
uv add jupyter --dev

• Visualiza en el project.toml qué es producción y qué es desarrollo.

¿Cómo ejecutar y verificar con uv run y LangGraph Studio?

• En lugar de activar/desactivar el entorno, ejecuta directo con uv:

uv run 

• Si usas LangGraph, el flujo clásico de desarrollo es:

langgraph dev

• Ante errores de puerto ocupado, detén el proceso previo y vuelve a correr. Abre LangGraph Studio y crea un thread nuevo para probar el agente con un “hola”.

¿Cómo organizar el proyecto para orquestar varios agentes y exponer una API?

Una estructura clara permite añadir agentes, tools, conexiones y una API sin romper nada. Además, facilita el uso de notebooks para visualización y pruebas.

¿Qué estructura de carpetas y módulos usar (CDC, agents, api, notebooks)?

• Crea una carpeta raíz, por ejemplo CDC.
• Dentro de CDC, crea:
• agents: mueve aquí el archivo principal (por ejemplo, main) y futuros agentes.
• api: el paquete para exponer los agentes vía API.
• notebooks: centraliza todos los notebooks de laboratorio.
• Asegúrate de incluir __init__.py en cada subcarpeta para que Python los trate como paquetes.

¿Cómo configurar project.toml para descubrir paquetes?

• Añade en el project.toml la sección que indica dónde buscar todos los paquetes y módulos del proyecto, sin importar la profundidad. Esto hace que Python “vea” correctamente CDC/agents, CDC/api y otros submódulos.
• Tras mover archivos, actualiza los imports según la nueva ruta de paquete, por ejemplo: agents.main.

¿Cómo compilar e integrar notebooks y visualización de grafos?

• Si un notebook no encuentra módulos tras reorganizar carpetas, reinicia el kernel y “compila/instala” el proyecto localmente:

install

• En notebooks, puedes importar el agente desde agents.main y visualizar su grafo. Si la imagen en formato PNG falla por depender de un servidor externo, solicita el formato del grafo y pégalo en la página sugerida para renderizarlo.
• Usa threads en LangGraph Studio para orquestar conversaciones en paralelo y depurar cómo fluye el grafo.

Habilidades y conceptos reforzados: orquestación de múltiples agentes, creación de una API para consumo externo, gestión de dependencias con uv, separación de entornos de producción y desarrollo, configuración de .gitignore y .env, manipulación de project.toml, uso de Jupyter y su kernel, depuración con LangGraph Studio, visualización de grafos, manejo de WSL Ubuntu, reinicio de notebooks y recompilación local.

¿Quieres que agreguemos tu estructura de carpetas y verifiquemos imports, dependencias y comandos paso a paso? Deja un comentario con tu caso y lo revisamos juntos.