El código que presentas define una Arquitectura de Agente de Investigación Autónoma con Planificación y Replanificación utilizando LangGraph (una extensión de LangChain) en Python. Este sistema está específicamente diseñado para abordar preguntas complejas de arqueología, genética y lingüística histórica (Neolítico a Edad del Hierro), incluso contrastando estas disciplinas académicas con teorías «tradicionalistas» (como las de Guénon y Evola).

🏗️ Modelo de Arquitectura de IA (LangGraph)

La arquitectura sigue un patrón de Planificación-Ejecución-Replanificación con bucle continuo, diseñado para manejar tareas complejas y de larga duración:

1. Componentes Clave

💻 Explicación Detallada del Código

1. Configuración y Herramientas (Tool and Model Setup)

• Modelos LLM: Se cargan dos modelos LLM:
  • gpt4o_model_loaded: Utilizado para tareas de alto nivel (Planificación y Replanificación/Decisión) debido a su capacidad de razonamiento y su manejo de estructuras Pydantic.
  • deepseek_model_loaded: Utilizado como el agente de ejecución, optimizado para la interacción con herramientas (patrón ReAct).
• Herramientas (planner_tools): El código centraliza las herramientas disponibles para el agente ejecutor (agent):
  • Herramientas Externas: wikipedia_tool, ddg_news_tool (búsqueda general), request_human_feedback_tool.
  • Agentes RAG: Una amplia lista de agentes RAG especializados (ej. "georgia_agent", "hierro_agent", "vasciberaqui_agent", "Tradition_agent"), cargados desde agent_tools. Esto dota al sistema de conocimiento especializado sobre el contexto histórico-arqueológico-lingüístico.

2. Estructuras de Datos (Pydantic Data Structures y PlanExecute)

• Pydantic: Se utilizan tres clases Pydantic (Plan, Response, Act) para garantizar que las salidas de los LLMs sean estructuradas y predecibles. El replan debe devolver un objeto Act, que a su vez contiene un Response (finalizar) o un Plan (continuar).
• Estado (PlanExecute): Es el diccionario de estado central de LangGraph. El operador operator.add en past_steps asegura que las nuevas tuplas (tarea, resultado) se añadan al historial en cada paso, proporcionando la memoria del proceso.

3. Definición de Agentes y Runnables

• planner_runnable (GPT-4o): Define la estrategia inicial. El prompt se centra en la investigación diacrónica (Neolítico → Edad del Hierro) para asegurar una cobertura lógica y exhaustiva de la historia temporal.
• planner_agent (Deepseek): El agente ejecutor ReAct. Su prompt lo instruye a ser un «Investigador Histórico y Arqueológico experto» y a centrarse en evidencias cronológicas, arqueológicas y genéticas al usar las herramientas.
• replanner_runnable (GPT-4o): El editor/crítico que revisa el trabajo realizado. Su prompt le exige una evaluación crítica del plan y del resultado en función del marco temporal histórico, garantizando que el bucle no termine hasta que la evidencia sea sólida.

4. Flujo del Workflow (El Bucle Principal)

El grafo (workflow) establece un bucle de tres nodos centrales:

1. Inicio (START) → Planificación (planner)
2. Ejecución (agent): El agente Deepseek utiliza las herramientas RAG o web para ejecutar el primer paso del plan.
3. Replanificación (replan): El agente GPT-4o revisa el resultado de la ejecución y el plan.
4. Bucle Condicional (should_end):
   • Si response tiene contenido → FIN (END).
   • Si el plan restante está vacío, pero no hay respuesta → FIN (END).
   • De lo contrario → Regresa al nodo de Ejecución (agent) para tomar el siguiente paso.

El uso de nodos de log_* (como log_plan y log_exec) garantiza que cada fase clave del proceso sea registrada en el disco antes de pasar a la siguiente etapa de procesamiento del LLM.

El TypedDict PlanExecute juega el papel central de la Memoria de Estado o Contexto Compartido del flujo de trabajo en LangGraph. Esencialmente, define qué información persiste y es transferida entre cada nodo (planner, agent, replan, log_*) del grafo.

🧠 Papel de PlanExecute (El Estado del Workflow)

En LangGraph, el StateGraph (Gráfico de Estado) trabaja sobre un objeto de estado que evoluciona. PlanExecute es ese objeto. Su principal rol es:

1. Definir la Memoria Compartida

Es un diccionario tipado que actúa como un contenedor para toda la información necesaria para el ciclo de Planificación-Ejecución-Replanificación. Cada nodo accede y modifica las claves definidas aquí.

2. Soportar el Bucle Continuo

Permite que el sistema recuerde su progreso y contexto a medida que itera. Sin este estado, el nodo agent no sabría qué paso ejecutar, y el nodo replan no sabría qué se ha hecho ni cuál era la pregunta original.

🔑 Desglose de Claves en PlanExecute

Exportar a Hojas de cálculo

En resumen, PlanExecute garantiza la coherencia y el flujo de información dentro del complejo bucle del agente. Es el «tablero de control» que permite que los agentes gpt-4o (planificación) y Deepseek (ejecución) trabajen juntos de forma secuencial y lógica.