¿Por qué separar el template del contexto en un agente conversacional con LangChain?

Cuando se construye un agente conversacional con LangChain + FastAPI, hay una tensión habitual: mezclar en el mismo repositorio la arquitectura genérica (rutas, memoria, sesiones) con la lógica específica del negocio (qué herramientas tiene disponibles, qué puede y no puede responder, con qué tono habla). El resultado es un monolito difícil de reutilizar y más difícil aún de mantener.

La separación en dos repositorios resuelve exactamente este acoplamiento. Un repositorio contiene la plomería — la arquitectura que funciona para cualquier caso de uso. El otro contiene las instrucciones — lo que hace que este agente sea útil para este cliente concreto. Son dos capas con ciclos de vida completamente distintos.

El context-repo importa el template-repo como dependencia — puede ser un submódulo Git, un paquete privado en PyPI, o simplemente un directorio clonado y referenciado. El mecanismo exacto importa menos que el principio: el contexto no duplica la arquitectura, solo la extiende.

Imagina que has construido un agente de gestión de proyectos conectado a Jira. El cliente siguiente necesita exactamente el mismo agente pero integrado con Google Calendar en lugar de Jira. Con la arquitectura de un solo repositorio, tienes que bifurcar todo el proyecto, extraer manualmente la lógica genérica y reescribir las partes específicas.

Con la separación en dos repositorios, el cambio se limita al context-repo: creas un nuevo contexto con las herramientas de Google Calendar, el system prompt adaptado y las reglas de negocio del nuevo cliente. El template-repo no se toca. Los endpoints REST, la gestión de sesiones, el middleware — todo permanece idéntico.

Para proyectos muy pequeños — un agente de un solo uso, un prototipo de fin de semana — la separación añade fricción sin beneficio proporcional. Mantener dos repositorios, dos pipelines de CI, dos conjuntos de secrets tiene un coste real. En ese contexto, un único repositorio bien estructurado con carpetas core/ y context/ puede ser suficiente.

Pero incluso en proyectos pequeños, vale la pena respetar la separación lógica aunque no la física: que quede claro qué código es genérico y reutilizable y qué código es específico del dominio. Cuando el proyecto crezca o llegue un segundo cliente, la migración a dos repositorios será trivial porque la separación mental ya existía.