Crea agentes de GraphRAG con el ADK

1. Descripción general

En este codelab, compilarás un sofisticado sistema de investigación de inversiones multiagente que combina el poder del Kit de desarrollo de agentes (ADK) de Google, la base de datos de gráficos Neo4j y la caja de herramientas del Protocolo de contexto del modelo (MCP). En este instructivo práctico, se muestra cómo crear agentes inteligentes que comprendan el contexto de los datos a través de las relaciones de gráficos y proporcionen respuestas a las consultas con gran precisión.

¿Por qué GraphRAG y los sistemas multiagente?

GraphRAG (Generación mejorada por recuperación basada en gráficos) mejora los enfoques tradicionales de la RAG aprovechando la rica estructura de relaciones de los gráficos de conocimiento. En lugar de solo buscar documentos similares, los agentes de GraphRAG pueden hacer lo siguiente:

  • Recorrer relaciones complejas entre entidades
  • Comprende el contexto a través de la estructura del gráfico
  • Proporcionar resultados explicables basados en los datos conectados
  • Ejecutar el razonamiento de múltiples saltos en el gráfico de conocimiento

Los sistemas multiagente te permiten hacer lo siguiente:

  • Descomponer problemas complejos en subtareas especializadas
  • Compila aplicaciones de IA modulares y fáciles de mantener
  • Habilita el procesamiento paralelo y el uso eficiente de los recursos
  • Crea patrones de razonamiento jerárquico con la organización

Qué compilarás

Crearás un sistema completo de investigación de inversiones que incluirá lo siguiente:

  1. Agente de base de datos orientada a grafos: Ejecuta consultas de Cypher y comprende el esquema de Neo4j
  2. Agente de investigación de inversores: Descubre las relaciones con los inversores y las carteras de inversión.
  3. Agente de investigación de inversiones: Accede a gráficos de conocimiento integrales a través de herramientas de MCP
  4. Agente raíz: Coordina de forma inteligente todos los agentes secundarios

El sistema responderá preguntas complejas como las siguientes:

  • "¿Quiénes son los principales competidores de YouTube?"
  • "¿Qué empresas se mencionan con un sentimiento positivo en enero de 2023?"
  • "¿Quién invirtió en ByteDance y en qué otras empresas invirtió?"

Descripción general de la arquitectura

26c67ab72ef077a4.jpeg

En este codelab, aprenderás los fundamentos conceptuales y la implementación práctica para compilar agentes de GraphRAG de nivel empresarial.

Qué aprenderás

  • Cómo crear sistemas multiagente con el Kit de desarrollo de agentes (ADK) de Google
  • Cómo integrar la base de datos de gráficos de Neo4j con el ADK para aplicaciones de GraphRAG
  • Cómo implementar la caja de herramientas del Protocolo de contexto del modelo (MCP) para consultas de bases de datos validadas previamente
  • Cómo crear herramientas y funciones personalizadas para agentes inteligentes
  • Cómo diseñar jerarquías de agentes y patrones de organización
  • Cómo estructurar las instrucciones del agente para obtener un rendimiento óptimo
  • Cómo depurar las interacciones multiagente de manera eficaz

Requisitos

  • Navegador web Chrome
  • Una cuenta de Gmail
  • Un proyecto de Google Cloud con la facturación habilitada
  • Conocimientos básicos sobre comandos de terminal y Python (son útiles, pero no obligatorios)

Este codelab, diseñado para desarrolladores de todos los niveles (incluidos los principiantes), usa Python y Neo4j en su aplicación de ejemplo. Si bien puede ser útil tener conocimientos básicos de Python y bases de datos de grafos, no se requiere experiencia previa para comprender los conceptos o seguir el curso.

2. Información sobre GraphRAG y los sistemas multiagente

Antes de profundizar en la implementación, comprendamos los conceptos clave que impulsan este sistema.

Neo4j es una base de datos de gráficos nativa líder que almacena datos como una red de nodos (entidades) y relaciones (conexiones entre entidades), lo que la hace ideal para casos de uso en los que es clave comprender las conexiones, como recomendaciones, detección de fraudes, gráficos de conocimiento y mucho más. A diferencia de las bases de datos relacionales o basadas en documentos que dependen de tablas rígidas o estructuras jerárquicas, el modelo de gráfico flexible de Neo4j permite una representación intuitiva y eficiente de datos complejos e interconectados.

En lugar de organizar los datos en filas y tablas como las bases de datos relacionales, Neo4j usa un modelo de gráfico, en el que la información se representa como nodos (entidades) y relaciones (conexiones entre esas entidades). Este modelo hace que sea excepcionalmente intuitivo trabajar con datos que están inherentemente vinculados, como personas, lugares, productos o, en nuestro caso, películas, actores y géneros.

Por ejemplo, en un conjunto de datos de películas:

  • Un nodo puede representar un Movie, un Actor o un Director.
  • Una relación puede ser ACTED_IN o DIRECTED.

b340d5e06fac5f47.jpeg

Esta estructura te permite hacer preguntas fácilmente, como las siguientes:

  • ¿En qué películas apareció este actor?
  • ¿Quiénes trabajaron con Christopher Nolan?
  • ¿Qué son las películas similares basadas en actores o géneros compartidos?

¿Qué es GraphRAG?

La generación aumentada por recuperación (RAG) mejora las respuestas de los LLM recuperando información pertinente de fuentes externas. Por lo general, la RAG tradicional hace lo siguiente:

  1. Incorpora documentos en vectores
  2. Busca vectores similares
  3. Pasa los documentos recuperados al LLM

GraphRAG extiende este proceso con el uso de gráficos de conocimiento:

  1. Incorpora entidades y relaciones
  2. Recorre las conexiones del gráfico
  3. Recupera información contextual de múltiples saltos
  4. Proporciona resultados estructurados y explicables

¿Por qué usar gráficos para los agentes de IA?

Considera esta pregunta: "¿Quiénes son los competidores de YouTube y qué inversores financiaron tanto a YouTube como a sus competidores?".

Qué sucede en un enfoque de RAG tradicional:

  • Busca documentos sobre la competencia de YouTube
  • Busca por separado la información para inversores
  • Tiene dificultades para conectar estas dos partes de la información
  • Es posible que no se detecten las relaciones implícitas.

Qué sucede en un enfoque de GraphRAG:

MATCH (youtube:Company {name: "YouTube"})-[:COMPETES_WITH]->(competitor:Company)
MATCH (investor:Investor)-[:INVESTED_IN]->(youtube)
MATCH (investor)-[:INVESTED_IN]->(competitor)
RETURN youtube, competitor, investor

El gráfico representa las relaciones de forma natural, lo que hace que las consultas de varios saltos sean sencillas y eficientes.

Sistemas multiagente en el ADK

El Kit de desarrollo de agentes (ADK) es el framework de código abierto de Google para compilar e implementar agentes de IA de nivel de producción. Proporciona elementos primitivos intuitivos para la organización de varios agentes, la integración de herramientas y la administración de flujos de trabajo, lo que facilita la composición de agentes especializados en sistemas sofisticados. El ADK funciona sin problemas con Gemini y admite la implementación en Cloud Run, Kubernetes o cualquier infraestructura.

El Kit de desarrollo de agentes (ADK) proporciona elementos básicos para crear sistemas multiagente:

  1. Jerarquía de agentes:
# Root agent coordinates specialized agents
root_agent = LlmAgent(
    name="RootAgent",
    sub_agents=[
        graph_db_agent,
        investor_agent,
        investment_agent
    ]
)
  1. Agentes especializados: Cada agente tiene
  • Herramientas específicas: Funciones a las que puede llamar
  • Instrucciones claras: Su rol y capacidades
  • Experiencia en el dominio: Conocimiento de su área
  1. Patrones de organización:
  • Secuencial: Ejecuta los agentes en orden
  • Paralelo: Ejecuta varios agentes de forma simultánea
  • Condicional: Enruta según el tipo de búsqueda

MCP Toolbox para bases de datos

El Protocolo de contexto del modelo (MCP) es un estándar abierto para conectar sistemas de IA a herramientas y fuentes de datos externas. MCP Toolbox para bases de datos es la implementación de Google que permite la administración declarativa de consultas de bases de datos, lo que te permite definir consultas prevalidadas y creadas por expertos como herramientas reutilizables. En lugar de permitir que los LLM generen búsquedas potencialmente inseguras, MCP Toolbox proporciona búsquedas previamente aprobadas con validación de parámetros, lo que garantiza la seguridad, el rendimiento y la confiabilidad, a la vez que mantiene la flexibilidad para los agentes de IA.

Enfoque tradicional:

# LLM generates query (may be incorrect/unsafe)
query = llm.generate("SELECT * FROM users WHERE...")
db.execute(query)  # Risk of errors/SQL injection

Enfoque de MCP:

# Pre-validated query definition
- name: get_industries
  description: Fetch all industries from database
  query: |
    MATCH (i:Industry)
    RETURN i.name, i.id

Beneficios:

  • Prevalidado por expertos
  • Protección contra ataques de inyección
  • Optimización del rendimiento
  • Administración centralizada
  • Se puede reutilizar en diferentes agentes

Aplica todo lo que aprendiste

La combinación de GraphRAG + Multi-Agent Framework del ADK + MCP crea un sistema potente:

  1. El agente raíz recibe la búsqueda del usuario
  2. Se transfiere a un agente especializado según el tipo de búsqueda
  3. El agente usa herramientas de MCP para recuperar datos de forma segura
  4. La estructura del grafo proporciona un contexto enriquecido
  5. El LLM genera una respuesta fundamentada y explicable

Ahora que comprendemos la arquitectura, comencemos a compilar.

3. Configura el proyecto de Google Cloud

Crea un proyecto

  1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
  2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto .
  3. Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud. Para alternar entre la terminal de Cloud Shell (para ejecutar comandos de Cloud) y el editor (para compilar proyectos), haz clic en el botón correspondiente de Cloud Shell.

Imagen del botón Activar Cloud Shell

  1. Una vez que te hayas conectado a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con tu ID de proyecto con el siguiente comando:
gcloud auth list
  1. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.
gcloud config list project
  1. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:
gcloud config set project <YOUR_PROJECT_ID>

Consulta la documentación para ver los comandos y el uso de gcloud.

¡Excelente! Ahora sí, ya podemos pasar al siguiente paso: comprender el conjunto de datos.

4. Información sobre el conjunto de datos de Companies

En este codelab, usaremos una base de datos de Neo4j de solo lectura que ya se completó con datos de inversión y de empresas del gráfico de conocimiento de Diffbot.

El conjunto de datos contiene lo siguiente:

  • 237,358 nodos que representan lo siguiente:
  • Organizaciones (empresas)
  • Personas (ejecutivos, empleados)
  • Artículos (noticias y menciones)
  • Industrias
  • Tecnologías
  • Inversionistas
  • Relaciones, incluidas las siguientes:
  • INVESTED_IN: Conexiones de inversión
  • COMPETES_WITH: Relaciones competitivas
  • MENTIONS: Referencias de artículos
  • WORKS_AT: Relaciones laborales
  • IN_INDUSTRY: Clasificaciones de la industria

5c5fee2a9823601f.jpeg

Accede a la base de datos de demostración

En este codelab, usaremos una instancia de demostración alojada. Agrega estas credenciales a tus notas:

URI: neo4j+s://demo.neo4jlabs.com
Username: companies
Password: companies
Database: companies

Acceso al navegador:

Puedes explorar los datos de forma visual en: https://demo.neo4jlabs.com:7473

Accede con las mismas credenciales y ejecuta el siguiente comando:

// Sample query to explore the graph
MATCH (o:Organization)-[:HAS_COMPETITOR]->(competitor:Organization)
RETURN o.name, competitor.name
LIMIT 10

Visualiza la estructura del gráfico

Prueba esta consulta en Neo4j Browser para ver patrones de relaciones:

// Find investors and their portfolio companies
MATCH (investor:Organization)-[:HAS_INVESTOR]->(company:Organization)
WITH investor, collect(company.name) as portfolio
RETURN investor.name, size(portfolio) as num_investments, portfolio
ORDER BY num_investments DESC
LIMIT 5

Esta consulta devuelve los 5 inversionistas más activos y sus carteras.

¿Por qué se usa esta base de datos para GraphRAG?

Este conjunto de datos es perfecto para demostrar GraphRAG por los siguientes motivos:

  1. Relaciones enriquecidas: Son conexiones complejas entre entidades.
  2. Datos del mundo real: Empresas, personas y artículos de noticias reales
  3. Consultas de múltiples saltos: Requiere atravesar varios tipos de relaciones
  4. Datos temporales: Artículos con marcas de tiempo para el análisis basado en el tiempo
  5. Análisis de opiniones: Puntuaciones de opiniones precalculadas para artículos

Ahora que comprendes la estructura de datos, configuremos tu entorno de desarrollo.

5. Clona el repositorio y configura el entorno

Clona el repositorio

En la terminal de Cloud Shell, ejecuta el siguiente comando:

# Clone the repository
git clone https://github.com/sidagarwal04/neo4j-adk-multiagents.git

# Navigate into the directory
cd neo4j-adk-multiagents

Explora la estructura del repositorio

Tómate un momento para comprender el diseño del proyecto:

neo4j-adk-multiagents/
├── investment_agent/       # Main agent code
│   ├── agent.py           # Agent definitions
│   ├── tools.py           # Custom tool functions
│   └── .adk/              # ADK configuration
│       └── tools.yaml     # MCP tool definitions
├── main.py                # Application entry point
├── setup_tools_yaml.py    # Configuration generator
├── requirements.txt       # Python dependencies
├── example.env           # Environment template
└── README.md             # Project documentation

Configura el entorno virtual

Antes de crear y activar entornos virtuales de Python, asegúrate de tener el paquete uv ya instalado en tu sistema:

# Install uv if not already installed
pip install uv

Crea y activa un entorno virtual de Python con uv:

# Create virtual environment
uv venv

# Activate the environment
source .venv/bin/activate  # On macOS/Linux
# or
.venv\Scripts\activate  # On Windows

Deberías ver (.venv) antepuesto al mensaje de la terminal.

Instala las dependencias

Instala todos los paquetes obligatorios:

uv pip install -r requirements.txt

Las dependencias clave incluyen las siguientes:

google-adk>=1.21.0          # Agent Development Kit
neo4j>=6.0.3               # Neo4j Python driver
python-dotenv>=1.0.0       # Environment variables

Configura variables de entorno

  1. Crea tu archivo .env:
cp example.env .env
  1. Edita el archivo .env:

Si usas Cloud Shell, haz clic en Abrir editor en la barra de herramientas y, luego, navega a .env y actualiza lo siguiente:

# Neo4j Configuration (Demo Database)
NEO4J_URI=neo4j+ssc://demo.neo4jlabs.com
NEO4J_USERNAME=companies
NEO4J_PASSWORD=companies
NEO4J_DATABASE=companies

# Google AI Configuration
# Choose ONE of the following options:

# Option 1: Google AI API (Recommended)
GOOGLE_GENAI_USE_VERTEXAI=0
GOOGLE_API_KEY=your_api_key_here  # Get from https://aistudio.google.com/app/apikey

# Option 2: Vertex AI (If using GCP)
# GOOGLE_GENAI_USE_VERTEXAI=1
# GOOGLE_CLOUD_PROJECT=your-project-id
# GOOGLE_CLOUD_LOCATION=us-central1

# ADK Configuration
GOOGLE_ADK_MODEL=gemini-3-pro-preview  # or gemini-3-flash-preview

# MCP Toolbox Configuration
MCP_TOOLBOX_URL=https://toolbox-990868019953.us-central1.run.app/mcp/sse
  1. Configuración de MCP Toolbox (preconfigurada, no es necesario ejecutarla):

En este lab, la caja de herramientas de MCP ya está alojada y preconfigurada, por lo que no es necesario que generes ni administres un archivo tools.yaml de forma local.

Normalmente, ejecutarías el siguiente comando para generar tools.yaml a partir de las variables de entorno después de actualizar investment_agent/.adk/tools.yaml.template según sea necesario:

python setup_tools_yaml.py

Esto genera investment_agent/.adk/tools.yaml con tus credenciales de Neo4j configuradas correctamente para la caja de herramientas de MCP.

Ejecutarías la secuencia de comandos anterior solo en los siguientes casos:

  • Estás autoalojando MCP Toolbox
  • Te estás conectando a una base de datos o un conjunto de datos de Neo4j diferente.
  • Quieres definir herramientas o credenciales personalizadas

En esos casos, la URL de la caja de herramientas de MCP y la configuración de tools.yaml deberían actualizarse según corresponda.

Verifica la configuración

Verifica que todo esté configurado correctamente:

# Verify .env file exists
ls -la .env

# Verify tools.yaml was generated
ls -la investment_agent/.adk/tools.yaml

# Test Python environment
python -c "import google.adk; print('ADK installed successfully')"

# Test Neo4j connection
python -c "from neo4j import GraphDatabase; print('Neo4j driver installed')"

Tu entorno de desarrollo ya está completamente configurado. A continuación, analizaremos la arquitectura multiagente.

6. Información sobre la arquitectura de múltiples agentes

El sistema de cuatro agentes

Nuestro sistema de investigación de inversiones utiliza una arquitectura jerárquica multiagente con cuatro agentes especializados que trabajan en conjunto para responder preguntas complejas sobre empresas, inversores y análisis de mercado.

                ┌──────────────┐
                │  Root Agent  │ ◄── User Query
                └──────┬───────┘
                       │
      ┌────────────────┼────────────────┐
      │                │                │
┌─────▼─────┐     ┌────▼─────┐     ┌────▼──────────┐
│ Graph DB  │     │ Investor │     │  Investment   │
│  Agent    │     │ Research │     │  Research     │
└───────────┘     │  Agent   │     │  Agent        │
                  └──────────┘     └───────────────┘
  1. Agente raíz (orquestador):

El agente raíz actúa como coordinador inteligente de todo el sistema. Recibe las preguntas de los usuarios, analiza la intención y enruta las solicitudes al agente especializado más adecuado. Piensa en él como un gerente de proyectos que sabe qué miembro del equipo es el más adecuado para cada tarea. También controla la agregación de respuestas, da formato a los resultados como tablas o gráficos cuando se solicita y mantiene el contexto de la conversación en varias consultas. El agente raíz siempre prefiere los agentes especializados por sobre el agente general de la base de datos, lo que garantiza que las consultas sean controladas por el componente más experto disponible.

  1. Agente de base de datos de grafos:

El agente de base de datos de gráficos es tu conexión directa con las potentes capacidades de gráficos de Neo4j. Comprende el esquema de la base de datos, genera consultas en Cypher a partir del lenguaje natural y ejecuta recorridos complejos de grafos. Este agente se especializa en preguntas estructurales, agregaciones y razonamiento de varios pasos en el gráfico de conocimiento. Es el experto de respaldo cuando las búsquedas requieren una lógica personalizada que las herramientas predefinidas no pueden controlar, por lo que es esencial para el análisis exploratorio y las búsquedas analíticas complejas que no se previeron en el diseño del sistema.

  1. Agente de investigación de inversores:

El agente de investigación de inversores se enfoca exclusivamente en las relaciones de inversión y el análisis de cartera. Puede descubrir quién invirtió en empresas específicas usando la coincidencia exacta de nombres, recuperar carteras completas de inversores que muestren todas sus inversiones y analizar los patrones de inversión en todas las industrias. Esta especialización la hace extremadamente eficiente para responder preguntas como "¿Quién invirtió en ByteDance?" o "¿En qué más invirtió Sequoia Capital?". El agente usa funciones personalizadas de Python que consultan directamente la base de datos de Neo4j para obtener relaciones relacionadas con los inversores.

  1. Agente de investigación de inversiones:

El agente de investigación de inversiones aprovecha la caja de herramientas del Protocolo de contexto del modelo (MCP) para acceder a consultas validadas previamente y creadas por expertos. Puede recuperar todas las industrias disponibles, recuperar empresas dentro de industrias específicas, encontrar artículos con análisis de opinión, descubrir menciones de organizaciones en noticias y obtener información sobre personas que trabajan en empresas. A diferencia del agente de base de datos de grafos, que genera consultas de forma dinámica, este agente usa consultas seguras, optimizadas y predefinidas que se administran y validan de forma centralizada. Esto lo hace seguro y eficiente para los flujos de trabajo de investigación comunes.

7. Ejecuta y prueba el sistema multiagente

Cómo iniciar la aplicación

Ahora que comprendes la arquitectura, ejecutemos el sistema completo y, luego, interactuemos con él.

Inicia la IU web del ADK:

# Make sure you're in the project directory with activated virtual environment
cd ~/neo4j-adk-multiagents
source .venv/bin/activate  # If not already activated

# Launch the application
uv run adk web

Deberías ver un resultado similar a este:

INFO:     Started server process [2542]
INFO:     Waiting for application startup.

+----------------------------------------------------------------+
| ADK Web Server started                                         |
|                                                                |
| For local testing, access at http://127.0.0.1:8000.            |
+----------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Una vez que veas que el servidor se inicia correctamente, abre el navegador y navega a http://127.0.0.1:8000 para acceder a la aplicación.

Prueba de consultas y comportamiento esperado

Exploremos las capacidades del sistema con consultas cada vez más complejas:

Consultas básicas (un solo agente)

Consulta 1: Descubre industrias

What industries are available in the database?

Comportamiento esperado:

  • El agente raíz dirige la solicitud al agente de investigación de inversiones
  • Usa la herramienta de MCP: get_industries()
  • Devuelve una lista con formato de todos los sectores.

Qué observar:

En la IU del ADK, expande los detalles de la ejecución para ver lo siguiente:

  • Decisión de selección del agente
  • Llamada a la herramienta: get_industries()
  • Resultados sin procesar de Neo4j
  • Respuesta con formato

Consulta 2: Busca inversores

Who invested in ByteDance?

Comportamiento esperado:

  • El agente raíz identifica que se trata de una consulta relacionada con el inversor.
  • Rutas al agente de investigación de inversores
  • Herramienta utilizada: find_investor_by_name("ByteDance")
  • Devuelve los inversores con sus tipos (persona/organización).

Qué esperar:

  • Una lista de inversores asociados con ByteDance
  • Cada inversor se devuelve con su nombre y tipo de entidad (persona u organización).
  • Un resumen conciso y legible de los resultados
  • Una instrucción de seguimiento que ofrece explorar inversiones relacionadas o carteras de inversionistas (puede ser)

Consulta 3: Empresas por sector

Show me companies in the Artificial Intelligence industry

Comportamiento esperado:

  • El agente raíz dirige la solicitud al agente de investigación de inversiones
  • Usa la herramienta de MCP: get_companies_in_industry("Artificial Intelligence")
  • Devuelve una lista de empresas de IA con IDs y fechas de fundación

Qué observar:

  • Observa cómo el agente usa la coincidencia exacta del nombre de la industria
  • Los resultados se limitan para evitar una salida abrumadora
  • Los datos tienen un formato claro para facilitar la lectura

Consultas intermedias (varios pasos dentro de un mismo agente)

Pregunta 4: Análisis de opiniones

Find articles with positive sentiment from January 2023

Comportamiento esperado:

  • Rutas al agente de investigación de inversiones
  • Usa la herramienta de MCP: get_articles_with_sentiment(0.7, 2023, 1)
  • Devuelve artículos con títulos, puntuaciones de opiniones y fechas de publicación.

Sugerencia de depuración:

Observa los parámetros de invocación de la herramienta:

  • min_sentiment: 0.7 (el agente interpreta "positivo" como >= 0.7)
  • year: 2023
  • month: 1

Consulta 5: Consulta compleja de base de datos

How many companies are in the database?

Comportamiento esperado:

  • El agente raíz dirige la solicitud al agente de la base de datos de gráficos
  • El agente llama a get_neo4j_schema() primero para comprender la estructura.
  • Genera Cypher: MATCH (c:Company) RETURN count(c)
  • Ejecuta la consulta y devuelve el recuento

Respuesta esperada:

There are 46,088 companies in the database.

Consultas avanzadas (coordinación multiagente)

Consulta 6: Análisis de la cartera

Who invested in ByteDance and what else have they invested in?

Comportamiento esperado:

Esta es una consulta de dos partes que requiere la coordinación del agente:

  • Paso 1: Agente raíz → Agente de investigación de inversores
  • Llamadas find_investor_by_name("ByteDance")
  • Obtiene la lista de inversores: [Rong Yue, Wendi Murdoch]
  • Paso 2: Para cada inversor → Agente de investigación de inversores
  • Llamadas find_investor_by_id(investor_id)
  • Recupera la cartera completa
  • Paso 3: El agente raíz agrega y da formato

Qué esperar:

  • Una lista de los inversores que invirtieron en ByteDance
  • Para cada inversionista, haz lo siguiente:
  • Su nombre y tipo de entidad (persona o organización)
  • Una lista de otras empresas en las que invirtió, según los datos disponibles
  • Un resumen estructurado y fácil de leer agrupado por inversionista

Qué observar:

  • Varias llamadas a herramientas en secuencia
  • Se mantiene el contexto entre los pasos
  • Resultados agregados de forma inteligente

Pregunta 7: Investigación en varios dominios

What are 5 AI companies mentioned in positive articles, and who are their CEOs?

Comportamiento esperado:

Esta consulta compleja requiere varios agentes y herramientas:

  • Paso 1: Agente de investigación de inversiones
  • get_companies_in_industry("Artificial Intelligence")
  • Devuelve la lista de empresas de IA
  • Paso 2: Agente de investigación de inversiones
  • get_articles_with_sentiment(0.8)
  • Devuelve artículos positivos
  • Paso 3: Filtros del agente raíz
  • Identifica qué empresas de IA aparecen en artículos positivos
  • Selecciona los 5 primeros
  • Paso 4: Agente de investigación de inversiones
  • get_people_in_organizations([company_names], "CEO")
  • Devuelve información del CEO
  • Paso 5: El agente raíz formatea la respuesta

Qué esperar:

  • Una lista de cinco empresas de la industria de la inteligencia artificial
  • Solo las empresas que aparecen en artículos con una puntuación positiva
  • Para cada empresa, haz lo siguiente:
  • Nombre de la empresa
  • Sector
  • Nombre del director general
  • Una puntuación de opinión agregada o representativa

Qué observar:

  • Varias llamadas a herramientas en diferentes agentes
  • Lógica de combinación y filtrado de datos

Consulta 8: Análisis de la competencia

Who are YouTube's main competitors?

Comportamiento esperado:

  • El agente raíz dirige la solicitud al agente de base de datos de gráficos (consulta de relación)
  • El agente genera Cypher mejorado con GraphRAG:
MATCH (c:Company {name: "YouTube"})-[:COMPETES_WITH]->(competitor)
RETURN competitor.name as competitor_name
  • Devuelve una lista de empresas de la competencia

Respuesta esperada:

YouTube's main competitors are:

- TikTok (ByteDance)
- Dailymotion
- Twitter
- BuzzFeed
- Mixer
- OpenAI (for video content)

Preguntas de seguimiento adaptadas al contexto

Pregunta 9: Pregunta de seguimiento (después de la pregunta 8)

Which investors funded both YouTube and its competitors?

Comportamiento esperado:

  • El agente raíz recuerda el contexto anterior (YouTube y sus competidores)
  • Rutas al agente de investigación de inversores
  • Para YouTube y cada competidor, busca inversores
  • Identifica a los inversores que aparecen en varias empresas

Qué esperar:

  • El sistema usa el contexto de conversación existente (YouTube y sus competidores).
  • Una lista de los inversores que invirtieron en más de una empresa dentro de este panorama competitivo
  • Para cada inversionista, haz lo siguiente:
  • Nombre del inversionista
  • Una lista agrupada de las empresas relevantes en las que invirtió
  • Un breve resumen interpretativo que destaca las superposiciones o los patrones estratégicos (quizás)

Consulta 10: Resumen de investigación

Summarize our research findings so far

Comportamiento esperado:

  • El agente raíz revisa el historial de conversaciones
  • Sintetiza los hallazgos clave de las búsquedas anteriores
  • Proporciona un resumen coherente

Qué esperar:

  • Un resumen conciso y bien estructurado de las estadísticas recopiladas a partir de búsquedas anteriores
  • Hallazgos clave agrupados por temas (descripción general de la industria, análisis de la empresa, opiniones, competencia y liderazgo)
  • Viñetas claras que destaquen lo siguiente:
  • Sectores explorados
  • Empresas e inversores destacados
  • Patrones de inversión en varias empresas
  • Tendencias del sentimiento del mercado
  • Una narrativa coherente que refleja la síntesis según el contexto en toda la sesión

Cómo comprender las interacciones del agente en la vista de depuración

La interfaz web del ADK proporciona visibilidad detallada de la ejecución. Presta atención a lo siguiente:

  1. Cronograma de eventos

Muestra el flujo cronológico:

[USER] Query received
[ROOT_AGENT] Analyzing query intent
[ROOT_AGENT] Routing to investment_research_agent
[INVESTMENT_RESEARCH_AGENT] Tool call: get_companies_in_industry
[TOOL] Executing with params: {"industry_name": "Artificial Intelligence"}
[TOOL] Returned 47 results
[INVESTMENT_RESEARCH_AGENT] Formatting response
[ROOT_AGENT] Presenting to user
  1. Detalles de la invocación de la herramienta

Haz clic en cualquier llamada a la herramienta para ver lo siguiente:

  • Nombre de la función
  • Parámetros de entrada
  • Valor que se muestra
  • Tiempo de ejecución
  • Cualquier error
  1. Toma de decisiones del agente

Observa el razonamiento del LLM:

  • Por qué eligió un agente específico
  • Cómo interpretó la búsqueda
  • Qué herramientas se consideraron
  • Por qué se formatearon los resultados de una manera determinada

Observaciones y estadísticas comunes

Patrones de enrutamiento de consultas:

  • Palabras clave como "inversor" o "inversión" → Agente de investigación de inversores
  • Palabras clave como "sector", "empresas" y "artículos" → Agente de investigación de inversiones
  • Agregaciones, recuentos y lógica compleja → Agente de base de datos de gráficos

Notas de rendimiento:

  • Las herramientas de MCP suelen ser más rápidas (consultas preoptimizadas)
  • La generación de Cypher compleja lleva más tiempo (tiempo de reflexión del LLM).
  • Varias llamadas a herramientas agregan latencia, pero proporcionan resultados más enriquecidos

Error Handling:

Si falla una consulta, haz lo siguiente:

  • El agente explica qué salió mal
  • Sugerir correcciones (p.ej., "No se encontró el nombre de la empresa. Verifica la ortografía"
  • Es posible que pruebe enfoques alternativos

Sugerencias para realizar pruebas eficaces

  1. Comienza con lo simple: Prueba la funcionalidad principal de cada agente antes de realizar consultas complejas.
  2. Usar seguimientos: Prueba la retención del contexto con preguntas de seguimiento
  3. Observe Routing: Observa qué agente controla cada consulta para comprender la lógica.
  4. Verifica las llamadas a herramientas: Verifica que los parámetros se extraigan correctamente del lenguaje natural.
  5. Prueba casos extremos: Prueba consultas ambiguas, errores ortográficos o solicitudes inusuales.

Ahora tienes un sistema GraphRAG multiagente completamente funcional. Experimenta con tus propias preguntas para explorar sus capacidades.

8. Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta publicación:

  1. En la consola de Google Cloud, ve a la página Administrar recursos.
  2. En la lista de proyectos, elige el proyecto que deseas borrar y haz clic en Borrar.
  3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.

9. Felicitaciones

🎉 ¡Felicitaciones! Creaste con éxito un sistema GraphRAG multiagente de calidad para producción con el Kit de desarrollo de agentes de Google, Neo4j y el kit de herramientas de MCP.

Al combinar las capacidades de organización inteligente del ADK con el modelo de datos enriquecido en relaciones de Neo4j y la seguridad de las consultas de MCP validadas previamente, creaste un sistema sofisticado que va más allá de las simples consultas de bases de datos: comprende el contexto, razona a través de relaciones complejas y coordina agentes especializados para brindar estadísticas integrales y precisas.

En este codelab, completaste las siguientes tareas:

✅ Creaste un sistema multiagente con el Kit de desarrollo de agentes (ADK) de Google con organización jerárquica.

✅ Base de datos de gráficos de Neo4j integrada para aprovechar las consultas que tienen en cuenta las relaciones y el razonamiento de varios saltos

✅ Implementamos MCP Toolbox para consultas de bases de datos seguras y validadas previamente como herramientas reutilizables

✅ Creamos agentes especializados para la investigación de inversores, el análisis de inversiones y las operaciones de bases de datos de gráficos.

✅ Enrutamiento inteligente diseñado que delega automáticamente las preguntas a los agentes expertos más adecuados

✅ Se controlaron tipos de datos complejos con la serialización de tipos de Neo4j adecuada para una integración de Python sin problemas

✅ Se aplicaron las prácticas recomendadas de producción para el diseño de agentes, el control de errores y la depuración del sistema.

Próximos pasos

Esta arquitectura GraphRAG de varios agentes no se limita a la investigación de inversiones, sino que se puede extender a lo siguiente:

  • Servicios financieros: Optimización de la cartera, evaluación de riesgos y detección de fraudes
  • Atención médica: Coordinación de la atención al paciente, análisis de interacciones farmacológicas, investigación clínica
  • Comercio electrónico: Recomendaciones personalizadas, optimización de la cadena de suministro, estadísticas de los clientes
  • Asuntos legales y cumplimiento: Análisis de contratos, supervisión de reglamentaciones, investigación de jurisprudencia
  • Investigación académica: Revisión de literatura, descubrimiento de colaboración, análisis de citas
  • Inteligencia empresarial: Análisis de la competencia, investigación de mercado, gráficos de conocimiento organizacionales

En cualquier lugar donde tengas datos interconectados complejos + experiencia en el dominio + interfaces de lenguaje natural, esta combinación de sistemas multiagente de ADK + gráficos de conocimiento de Neo4j + búsquedas validadas por MCP puede potenciar la próxima generación de aplicaciones empresariales inteligentes.

A medida que el Agent Development Kit de Google y los modelos de Gemini sigan evolucionando, podrás incorporar patrones de razonamiento aún más sofisticados, integración de datos en tiempo real y capacidades multimodales para crear sistemas verdaderamente inteligentes y sensibles al contexto.

Sigue explorando y creando, y lleva tus aplicaciones de agentes inteligentes al siguiente nivel.

Explora más instructivos prácticos sobre gráficos de conocimiento en Neo4j GraphAcademy y descubre patrones de agentes adicionales en el repositorio de muestras del ADK.

🚀 ¿Todo listo para crear tu próximo sistema de agentes inteligentes?

Documentos de referencia