Cuando un agente con LangGraph empieza a crecer en nodos, prompts, tools y RAGs, mantener todo en un solo archivo se vuelve insostenible. Aquí aprendes a organizar tu proyecto con una estructura modular inspirada en la documentación oficial de LangGraph, pensada para escalar features sin perder visibilidad sobre la orquestación.

¿Por qué necesitas refactorizar tu agente cuando crece?

Un agente que empieza simple termina con muchos nodos, prompts largos, tools externas y estados con 20 o 30 atributos. Si todo vive en un solo archivo, mantenerlo se convierte en un dolor: el ruido visual aumenta, los imports se mezclan y mejorar un nodo específico te obliga a navegar entre líneas que no te interesan.

La documentación oficial de LangGraph tiene una sección llamada Production donde proponen una arquitectura basada en carpetas para tools, nodos y estado [04:12]. Sobre esa base, puedes ir un paso más allá y segmentar cada nodo como su propia unidad con todo lo que necesita para funcionar.

¿Qué es el scaffolding en un agente LangGraph? Es la estructura base de carpetas y archivos que define dónde vive cada pieza del sistema: estado, nodos, prompts y tools. Te permite escalar sin romper lo que ya funciona.

¿Cómo se estructura una carpeta de agente en LangGraph?

En vez de tener un archivo support.py con todo el RAG dentro, conviertes el agente en una carpeta. Esa carpeta es la unidad mínima del sistema y contiene tanto la definición del grafo como sus nodos individuales.

La estructura propuesta queda así:

• agents/support/__init__.py para que Python reconozca la carpeta como módulo.
• agents/support/state.py con la definición del estado, importando MessagesState.
• agents/support/agent.py con la construcción del grafo y la conexión entre nodos.
• agents/support/nodes/ como subcarpeta donde vive cada nodo.

En agent.py solo importas el estado y los nodos ya construidos. Esto deja la orquestación limpia y enfocada únicamente en cómo se conectan las piezas.

¿Qué archivos debe tener cada nodo?

Cada nodo tiene su propia carpeta dentro de nodes/. Por ejemplo, para el RAG de soporte tendrás nodes/extractor/ y nodes/conversation/. Dentro de cada una vive lo siguiente:

• node.py con la lógica del nodo y la declaración del large language model mediante init_chat_model.
• prompt.py con el system prompt de ese nodo, aislado para iterar técnicas de prompting sin tocar la lógica.
• tools.py (en plural) cuando el nodo necesita herramientas externas, como en conversation que se conecta a una tool de OpenAI [16:30].

Si un nodo no usa tools, simplemente no creas ese archivo. El extractor, por ejemplo, solo necesita node.py y prompt.py.

¿Cómo refactorizar un RAG existente paso a paso?

Partiendo de un archivo único que mezcla estado, nodos y grafo, mueves cada pieza a su lugar. El estado se va a state.py, importando MessagesState desde LangGraph. Cada nodo migra a su carpeta con sus imports corregidos: por ejemplo, from agents.support.state import State reemplaza referencias relativas confusas que el editor a veces genera mal.

Dentro del nodo extractor declaras el modelo con init_chat_model y el esquema de structured output. El system prompt ("Tú eres un asistente que ayuda a extraer información dada una conversación") vive en prompt.py y lo importas para concatenarlo con el historial de mensajes.

La concatenación se hace tratando el prompt como una tupla ("system", system_prompt) dentro de un array, al que luego se le suma el history. Así el modelo recibe primero las instrucciones del sistema y después la conversación del usuario.

¿Por qué separar el prompt del nodo? Porque te permite iterar técnicas de prompting, hacer inyección de contexto y mantener prompts dinámicos sin tocar la lógica del nodo. La inyección con format y variables como customer_name se trabaja después [22:45].

¿Cómo queda el nodo de conversation con tools?

El nodo conversation sigue el mismo patrón pero suma tools.py. Dentro de ese archivo declaras todas las herramientas y exportas un array tools que se enlaza al language model con bind_tools. En node.py solo importas ese array y se lo pasas al modelo, manteniendo la responsabilidad bien delimitada.

El prompt de conversation se deja estático por ahora. La inyección dinámica con variables como el nombre del cliente queda pendiente para cuando se trabaje prompt injection y contexto dinámico.

¿Qué ganas con esta arquitectura modular?

Navegar el proyecto se vuelve evidente. Si necesitas mejorar el prompt del extractor, entras a nodes/extractor/prompt.py y nada más. Si quieres cambiar el modelo del nodo de conversación, vas a nodes/conversation/node.py. Cada decisión vive en un solo lugar.

Agregar un nodo nuevo significa crear una carpeta con su node.py, su prompt.py y, si aplica, su tools.py. El agent.py solo se actualiza para conectar el nuevo nodo al grafo. Nada más se rompe.

Al correr el agente support en LangGraph UI, el comportamiento es idéntico al RAG original: responde "Hola, ¿en qué te puedo ayudar?" usando los documentos cargados. La diferencia está en que ahora puedes seguir creciendo sin que el proyecto colapse.

¿Cómo organizas tú tus agentes cuando empiezan a crecer? Cuéntame en los comentarios qué patrones te han funcionado.