Abstract

Este trabajo presenta un sistema multiagente avanzado basado en LangGraph para la generación de análisis exegéticos estructurados sobre la Tradición Primordial. El modelo combina tres componentes principales: un planificador estructurado, un agente de ejecución exegético y un replanner editorial, todos ellos coordinados mediante un grafo de estados que garantiza trazabilidad, control y coherencia narrativa. El sistema integra múltiples modelos de lenguaje (Deepseek, GPT‑4o y o3‑mini), herramientas externas y un conjunto de agentes RAG especializados, entre los que destacan catolico_agent y Tradition_agent, diseñados para recuperar información doctrinal, histórica y simbólica desde bases de conocimiento específicas. Se incorporan mecanismos robustos de truncado, normalización y logging en Markdown para asegurar reproducibilidad y estabilidad en contextos de alta carga semántica. El resultado es un pipeline capaz de producir respuestas didácticas, verificables y estructuradas, con un flujo de trabajo transparente y auditable.

Introducción

La investigación asistida por modelos de lenguaje ha evolucionado hacia arquitecturas cada vez más modulares, donde múltiples agentes colaboran para producir respuestas complejas, verificables y adaptadas a dominios especializados. En este contexto, presentamos un sistema multiagente diseñado para el análisis exegético de la Tradición Primordial, combinando técnicas de planificación automática, razonamiento estructurado y recuperación de información.

El núcleo del sistema es un workflow construido con LangGraph, que organiza el proceso en tres etapas fundamentales: planificación, ejecución y replanificación. Cada etapa está respaldada por un agente especializado: un planificador que descompone la consulta en pasos concretos, un agente exegético que ejecuta cada paso con acceso a herramientas RAG y fuentes externas, y un replanner que evalúa la coherencia del material obtenido y decide si continuar o producir la respuesta final.

Una de las características distintivas del sistema es la integración de agentes RAG temáticos, en particular catolico_agent y Tradition_agent, que permiten acceder a corpus doctrinales, patrísticos, simbólicos y tradicionales de forma precisa y contextualizada. Estos agentes actúan como “bibliotecarios especializados”, proporcionando citas textuales, referencias cruzadas y material de apoyo que enriquece el análisis exegético generado por el modelo.

El sistema incorpora modelos de lenguaje complementarios —Deepseek, GPT‑4o y o3‑mini— seleccionados estratégicamente según la naturaleza de cada tarea. Además, se incluyen mecanismos avanzados de truncado por tokens, normalización de mensajes y logging estructurado en Markdown, lo que permite manejar entradas extensas, evitar errores de contexto y generar trazas auditables del proceso completo.

Este enfoque ofrece una arquitectura robusta, extensible y orientada a la producción, capaz de generar análisis exegéticos profundos, didácticos y bien estructurados, manteniendo al mismo tiempo un control estricto sobre la coherencia, la claridad y la fidelidad a las fuentes tradicionales.

Visión general del modelo

El código implementa un workflow multi-etapa basado en LangGraph para responder preguntas complejas sobre Tradición Primordial y exégesis simbólica, combinando:

• Un agente de ejecución exegético (planner_agent), construido con create_agent.
• Un planificador estructurado (planner_runnable), que genera planes de trabajo exegéticos.
• Un replanner/editor exegético (replanner_runnable), que decide si seguir investigando o producir la respuesta final.
• Un grafo de estados (StateGraph) con nodos planner → agent → replan y nodos de logging intermedios.
• Mecanismos avanzados de truncado, normalización y robustez frente a respuestas heterogéneas de los modelos.

Todo el sistema está alineado con un objetivo claro: producir respuestas exegéticas bien estructuradas, no repetitivas, trazables y registradas en Markdown.

2. Capa de modelos y herramientas

2.1. Selección de modelos LLM

Se cargan tres modelos:

• Deepseek
• gpt-4o
• o3-mini

En este diseño:

• deepseek_model se usa como motor de ejecución del agente exegético (planner_agent).
• o3mini_model se utiliza como motor de razonamiento estructurado para:
  • Generar planes (Plan)
  • Devolver decisiones del replanner (Act = Response o Plan)

Si deepseek u o3-mini no están disponibles, el sistema lanza un RuntimeError explícito. No hay dummies: esto subraya que el workflow está pensado para producción, no para ejemplos degradados.

2.2. Registro de herramientas

Se cargan tres herramientas externas básicas:

• wikipedia_tool
• ddg_news_tool
• request_human_feedback_tool

Y se añaden herramientas RAG especializadas desde el registro agent_tools, usando estas claves:

• catolico_agent
• Tradition_agent
• templarios_agent
• carlista_agent
• isidoro_agent

La lista final planner_tools se convierte en el arsenal del agente exegético: puede consultar RAG temáticos, Wikipedia, noticias, y pedir feedback humano. Esto permite combinar tradición textual con contexto histórico y técnico más amplio.

3. Ingeniería de seguridad y robustez de entrada/salida

Antes de definir los agentes, el código introduce una capa sólida de utilidades de seguridad y normalización.

3.1. Truncado por caracteres y por tokens

Funciones clave:

• shorten_for_model(text, max_chars)
• shorten_for_model_tokens(text, max_tokens, encoding_name)

Estas funciones:

• Detectan entradas demasiado largas.
• Conservan el inicio y el final del texto (p.e. 60% cabeza, 40% cola).
• Insertan un marcador explícito: ... [TRUNCATED: input too long] ...
• Usan tiktoken si está disponible; si no, aproximan por caracteres.

Esto está pensado para:

• Proteger el contexto del LLM.
• Evitar errores por exceder límites de tokens.
• Mantener suficiente contexto semántico.

3.2. Preparación y normalización de mensajes

• prepare_messages_for_model(messages) Convierte una lista heterogénea de mensajes u objetos en strings truncados, listos para ser enviados a los modelos.
• _get_text_from_msg(msg) y _extract_last_message_text(response) Extraen texto de:
  • dicts con messages
  • objetos con .messages
  • listas
  • strings

Son funciones defensivas: aceptan diferentes formatos de respuesta (pydantic, dicts, listas, etc.) y los normalizan a texto, evitando que el sistema reviente cuando cambie el backend.

3.3. Normalización de estado

• state_as_dict(state) Convierte el estado en un dict, ya sea:
  • un BaseModel de Pydantic
  • un dict
  • u otra estructura coercible a dict

Esto es fundamental para que los nodos del grafo manejen el estado de forma uniforme, sin acoplarse al tipo concreto de objeto.

4. Modelo de datos del workflow

Se definen tres modelos Pydantic:

• Plan:pythonsteps: List[str] Representa una lista de pasos técnicos o exegéticos.
• Response:pythonresponse: str Respuesta final al usuario.
• Act:pythonaction: Union[Response, Plan] Es la salida del replanner: o bien una respuesta final, o bien un nuevo plan.

Y un modelo de estado global:

• PlanExecuteModel:pythoninput: Optional[str] plan: Optional[List[str]] past_steps: Optional[List[Tuple]] response: Optional[str] log_filename: Optional[str] last_node_output: Optional[str]

Este PlanExecuteModel es el estado compartido que fluye por el grafo LangGraph.

5. El agente exegético: identidad, estilo y formato

5.1. System prompt exegético

El corazón del sistema es el system_prompt_text, que define la personalidad:

• Rol: “Analista Exegético de la Tradición Primordial (desde sus orígenes hasta el catolicismo)”.
• Objetivo: Explicar textos, símbolos, prácticas y conceptos tradicionales con rigor filológico, histórico y metafísico.
• Reglas clave:
  1. No repetir contenido en varias secciones.
  2. Estructurar la salida en: Introducción, Contexto Histórico, Análisis Exegético, Implicaciones, Conclusión.
  3. Citar fuentes y páginas cuando sea posible.
  4. Generar comparaciones entre tradiciones (pagana, islámica, judía, cristiana).
  5. Explicar términos técnicos; mantener claridad didáctica.
  6. Responder en español.
  7. Envolver la respuesta en un bloque:text<<MESSAGE_BOX agent="Tradition_Exegesis">> ...contenido... <<END_MESSAGE_BOX>>
  8. Indicar cuando se use RAG: Fuente RAG: <nombre_db>.
  9. Evitar narrativas repetitivas.

Esto define un agente con identidad clara, control de formato y alta legibilidad.

5.2. Construcción del planner_agent

Se construye con:

python

planner_agent = create_agent(
    model=deepseek_model,
    tools=planner_tools,
    system_prompt=system_prompt_text,
    name="Tradition_Exegesis",
)

Este agente:

• Usa Deepseek como motor.
• Tiene acceso a herramientas RAG y externas.
• Está especializado en respuestas exegéticas, no en planificación.

6. Planner y Replanner: arquitectura de control

6.1. Planner (generador de Plan)

planner_runnable:

• Usa un prompt de Planificador de Investigación Exegética.
• Tarea: generar un Plan de pasos concretos para abordar la pregunta del usuario.
• Modelo: o3mini_model.with_structured_output(Plan).

La salida es siempre una instancia de Plan, no texto libre. Esto obliga al modelo a producir una estructura programáticamente usable.

6.2. Replanner (editor exegético)

replanner_runnable:

• Rol: Editor Exegético.
• Revisa:
  • la tarea inicial,
  • el plan restante,
  • y los pasos ya ejecutados.
• Decide:
  • Si puede generar una respuesta final → devuelve Response.
  • Si faltan pasos → devuelve un nuevo Plan.

Salida tipada mediante Act (Union[Response, Plan]) con o3-mini.

7. Los nodos del workflow LangGraph

El grafo de estados tiene tres nodos principales y tres de logging.

7.1. Nodo planner (plan_step)

Función:

• Extraer de forma robusta el input del estado (dict/BaseModel, con varias formas posibles).
• Truncar el input si es largo (shorten_for_model_tokens).
• Invocar planner_runnable para obtener un Plan.
• Construir un string Markdown con el plan para logging.
• Actualizar el estado con:
  • plan: List[str]
  • last_node_output: str

Si no hay input válido, devuelve un error expositivo en last_node_output.

7.2. Nodo agent (execute_step)

Función:

• Tomar el primer paso del plan.
• Construir un contexto textual con:
  • Plan completo numerado.
  • Instrucciones para centrar el análisis en la tradición.
• Truncar el contexto a tokens seguros.
• Invocar planner_agent (via .ainvoke) con payload tipo:python{"messages": [{"role": "user", "content": task_short}]}
• Manejar errores y reintentos con truncado más agresivo.
• Normalizar la respuesta del agente a un dict con messages.
• Extraer el texto final (response_content).
• Devolver:
  • plan sin el primer paso
  • past_steps con el par (tarea, resultado)
  • last_node_output con un bloque Markdown del resultado.

7.3. Nodo replan (replan_step)

Función:

• Normalizar el estado (state_as_dict).
• Resumir past_steps en texto corto.
• Construir contexto con:
  • Tarea inicial
  • Plan restante
  • Pasos completados
• Truncar el contexto y pasarlo como lista de strings a replanner_runnable.
• Si la salida es:
  • Response: se fija response y se registra el mensaje de decisión final.
  • Plan: se fija un nuevo plan y se registra el nuevo plan.
  • Otro tipo: error de replanificación.

8. Logging estructurado en Markdown

El nodo log_to_file:

• Crea (si no existe) un archivo en ../informes_trace con nombre trace_YYYYMMDD_HHMMSS.md.
• Añade:
  • Cabecera.
  • Tarea inicial.
  • Cada salida de nodo (last_node_output) con timestamp.
• Imprime también por stdout los eventos de logging para captura inmediata.

Esto convierte cada ejecución en una traza auditable, útil para:

• depuración,
• revisión exegética,
• documentación,
• e incluso publicación de “cadernos de investigación”.

9. Condición de finalización y bucle del grafo

El grafo workflow se construye así:

• Nodos:
  • planner
  • agent
  • replan
  • log_plan
  • log_exec
  • log_replan
• Edges:
  1. Flujo inicial:
     • START → planner → log_plan → agent
  2. Bucle de ejecución:
     • agent → log_exec → replan → log_replan
  3. Condicional en log_replan:
     • Si response existe → END
     • Si no y plan no está vacío → vuelve a agent

should_end(state) decide si se termina o se sigue. El workflow se compila con app = workflow.compile() y se ejecuta de forma asíncrona con app.astream.

10. Ejecución completa y visualización

10.1. Ejecución

run_planner_agent(question):

• Construye un PlanExecuteModel como input.
• Configura un RunnableConfig(recursion_limit=100).
• Recorre el stream de eventos de app.astream.
• Detecta __end__ y extrae response del estado final.
• Imprime la respuesta final en un marco visual (líneas de =) y la devuelve.

El __main__ ejecuta:

• Una pregunta compleja sobre el simbolismo tradicional de los Reyes Magos y el Reino del Preste Juan, basada en Guénon.
• Luego intenta generar un gráfico del grafo de estados mediante:
  • generar_edge_labels
  • draw_graph_with_graphviz
  • merge_graph_and_legend

Esto permite tener no solo la traza textual sino también una visualización gráfica del pipeline.

11. Síntesis

Este modelo implementa un pipeline de investigación exegética asistida por IA, donde:

• Un planificador estructurado genera pasos de trabajo concretos.
• Un agente exegético especializado ejecuta esos pasos con acceso a RAG y herramientas externas.
• Un replanner/editor decide cuándo el material es suficiente para formular una respuesta final.
• Un grafo de estados gobierna el flujo plan → execute → replan, con logging exhaustivo en Markdown.
• La infraestructura de truncado, normalización y manejo de errores hace que el sistema sea robusto y preparado para producción, no un simple demo.

Basado en

ReAct Tradition_agent: arquitectura, heurísticas y control doctrinal