En este tutorial desarrollamos un agente de inteligencia artificial avanzado basado en grafos, utilizando el framework GraphAgent junto con el modelo Gemini 1.5 Flash. La idea es definir un grafo dirigido compuesto por nodos, cada uno con una función específica: un planificador que descompone la tarea, un router que controla el flujo, nodos de investigación y cálculo que aportan evidencia externa y realizan operaciones matemáticas, un escritor que sintetiza la respuesta, y un crítico que valida y mejora el resultado final. Integrando Gemini a través de un envoltorio que maneja prompts estructurados en JSON, y utilizando funciones locales en Python para evaluar operaciones matemáticas de forma segura y para realizar búsquedas en documentos, conseguimos un sistema modular donde el razonamiento, la recuperación de información y la validación se combinan en un solo pipeline coherente.
Para empezar, importamos librerías fundamentales de Python para manejo de datos, tiempo y evaluación segura de expresiones matemáticas, además de utilidades para estructurar estados con dataclasses y typing. También incluimos el cliente de Google Generative AI para acceder a Gemini, y opcionalmente NetworkX para visualizar los grafos.
Luego, definimos una función para configurar el modelo Gemini con una instrucción del sistema personalizada, que indica que el agente debe funcionar como un planificador-ejecutor ordenado, preferentemente entregando salidas estructuradas y concisas, y que utilice las herramientas disponibles cuando se lo requiera. Otra función se encarga de enviar prompts al LLM controlando la temperatura para asegurar consistencia en las respuestas.
Entre las herramientas implementadas para el agente se incluye un evaluador matemático seguro, que analiza y verifica la expresión aritmética mediante el módulo ast antes de ejecutarla, y una función simple de búsqueda documental que recupera fragmentos relevantes de un pequeño corpus en memoria. Esto proporciona capacidades confiables de cálculo y recuperación sin depender de recursos externos.
El estado del agente se guarda en una clase State, que mantiene la tarea, el plan, notas de apoyo, evidencia recopilada, el resultado final y el control del proceso. Definimos funciones para cada nodo: el planificador formula un plan con subtareas y herramientas necesarias; el router decide el siguiente paso según el contexto; el nodo de investigación genera consultas para buscar información; el nodo matemático extrae y evalúa expresiones numéricas; el escritor construye la respuesta final utilizando la evidencia y los cálculos; y el crítico revisa y perfecciona el resultado para asegurar coherencia y claridad. Estas funciones modifican el estado y devuelven la etiqueta del siguiente nodo, permitiendo recorrer el grafo hasta completar el proceso.
Para ejecutar el sistema, se define un ciclo que itera por los nodos hasta entregar una respuesta definitiva o alcanzar un límite máximo de pasos. También se incluye una función para visualizar el flujo general del grafo de control.
Finalmente, al correr el programa, se solicita de forma segura la clave API de Gemini y se recibe la tarea del usuario. Tras ejecutar el agente, se muestra el flujo del grafo, el resultado final, la evidencia recopilada y las últimas notas internas para transparencia.
En resumen, este enfoque muestra cómo un agente estructurado en grafo permite diseñar flujos de trabajo deterministas sobre un modelo probabilístico como Gemini. El planificador descompone la tarea, el router elige dinámicamente entre investigación y cálculo, y el crítico refina la respuesta. Gemini actúa como motor central de razonamiento, mientras que los nodos del grafo aportan estructura, verificaciones de seguridad y manejo transparente del estado. Así, se construye un agente funcional que aprovecha la orquestación en grafo junto con un LLM moderno, abriendo posibilidades para integrar cadenas de herramientas personalizadas, memoria multi-turno o ejecución paralela en escenarios más complejos.
