Construir prototipos de agentes con Python es relativamente fácil, pero llevar esos agentes a producción exige una arquitectura sólida. Aquí aprenderás a montar un entorno profesional con UV como gestor de paquetes, organizar carpetas escalables y dejar todo listo para orquestar múltiples agentes y exponerlos por API.

Por qué usar UV en lugar de pip para proyectos de agentes

Cuando tu proyecto crece, pip se queda corto. Necesitas herramientas extra como pip-tools, Poetry o virtualenv para manejar dependencias, entornos y builds. UV reemplaza todo eso en una sola herramienta escrita en Rust, y corre hasta 10 veces más rápido.

¿Qué es UV en Python? Es un gestor de paquetes y entornos virtuales escrito en Rust que reemplaza pip, pip-tools, Poetry y virtualenv en una sola herramienta, con velocidad muy superior.

La instalación depende de tu sistema operativo: hay un comando para Mac/Linux y otro para Windows. Si usas WSL con Ubuntu, instalas como Linux. Verifica con uv version que quedó bien instalado [01:50].

Cómo migrar tu entorno virtual existente a UV

Si ya tenías un entorno creado con Python, el flujo es directo:

• Desactiva el entorno actual con deactivate.
• Elimina la carpeta del entorno con rm -rf.
• Ejecuta uv init para que UV genere los archivos del proyecto.

Con uv init aparecen automáticamente el .python-version, el .gitignore y el pyproject.toml, que es el corazón de la configuración [03:30].

Cómo configurar gitignore y dependencias de desarrollo

Antes de seguir, ajusta el .gitignore para evitar subir cosas sensibles o innecesarias al repositorio. Agrega la carpeta interna de LangGraph y cualquier archivo terminado en .env, porque ahí viven tus API keys y variables de entorno.

Para instalar dependencias, cambias pip install por uv add. Ejemplo: uv add langgraph langchain. Listo, sin activar entornos manualmente.

¿Cómo instalo una dependencia solo para desarrollo con UV? Usas la bandera de dev, así esa librería no se incluye cuando empaquetes para producción. Es ideal para herramientas como el CLI de LangGraph o Jupyter.

En este caso, instala como dependencia de desarrollo:

• El LangGraph CLI, útil solo en local.
• El kernel de Jupyter, para explorar agentes, tools y RAG en notebooks.

En el pyproject.toml verás separadas las dependencias de producción y las de desarrollo, además de la versión exacta de Python del proyecto [05:40].

Cómo correr LangGraph y notebooks con UV

Con UV ya no tienes que activar ni desactivar entornos. Basta con prefijar uv run antes de tu comando y UV resuelve el entorno automáticamente. Para levantar tu agente: uv run langgraph dev.

Si te aparece un error sobre un servidor ya corriendo, simplemente cierra el proceso anterior y vuelve a ejecutar. Al recargar LangGraph Studio, podrás crear un nuevo thread (un hilo de conversación paralelo que LangGraph usa para orquestar agentes) y enviar un mensaje de prueba [07:20].

Cómo visualizar tu grafo de agente desde Jupyter

Dentro del notebook, selecciona el kernel del entorno gestionado por UV (la carpeta .venv). Importa tu agente desde main y usa la clase de IPython.display para graficarlo:

python from IPython.display import Image, display display(Image(agent.get_graph().draw_mermaid_png()))

Si falla por dependencia de un servidor externo, cambia a formato Mermaid y pega el resultado en un visualizador online. Verás el mismo grafo que muestra LangGraph Studio, útil cuando quieras debuguear visualmente arquitecturas más complejas [09:50].

Cómo organizar carpetas para escalar agentes y exponer una API

La estructura plana con un solo main.py no aguanta proyectos serios. La idea es separar agentes, API y notebooks en módulos independientes.

Crea esta jerarquía dentro de tu proyecto:

• Carpeta raíz src con su __init__.py.
• Subcarpeta agents con su __init__.py y mueve ahí tu main.py.
• Subcarpeta api con su __init__.py para la futura API.
• Carpeta notebooks para todos tus archivos de exploración.

Cada subcarpeta necesita su __init__.py porque así Python las reconoce como paquetes [11:30].

Cómo configurar pyproject.toml para que encuentre los módulos

Al mover archivos a subcarpetas, los imports clásicos rompen. Para arreglarlo, agrega al pyproject.toml la sección que indique la carpeta raíz de paquetes y que incluya todos los módulos sin importar su profundidad.

Luego corre uv pip install -e . para compilar e instalar tu proyecto en modo editable. Eso le dice a Python que tu código es un paquete instalable y resuelve los imports correctamente.

¿Por qué necesito instalar mi propio proyecto con UV? Porque al tener una estructura de paquetes anidada, Python necesita registrar tu código como módulo instalado para resolver imports como agents.main desde cualquier notebook o archivo.

Después de eso, tus imports cambian de from main import agent a from agents.main import agent. Si el notebook sigue mostrando errores, ciérralo y reinícialo: a veces el kernel cachea la configuración previa [13:40].

Cómo verificar que toda la arquitectura funciona

Vuelve a correr uv run langgraph dev y recarga LangGraph Studio. Crea un nuevo thread, manda un saludo y confirma que el agente responde. Si todo fluye, tienes:

• Un gestor de paquetes moderno con UV.
• Dependencias separadas entre producción y desarrollo.
• Una estructura de carpetas lista para múltiples agentes.
• Notebooks funcionando para experimentar.
• Base preparada para exponer una API.

Esta configuración es la que vas a usar de aquí en adelante para orquestar agentes, conectar tools, implementar RAG y publicar tu trabajo a Internet. ¿Ya migraste tus proyectos de pip a UV? Cuéntame en los comentarios cómo te fue con la transición.