Codelab: 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
  • Ejecuta 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: Organiza de forma inteligente todos los subagentes.

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 (ú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. Explicación de 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 y conectados.

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 (org:Organization {name: "OpenAI"})-[:HAS_COMPETITOR]-(competitor:Organization)
MATCH (org)-[:HAS_INVESTOR]->(investor:Person)
MATCH (competitor)-[:HAS_INVESTOR]->(investor)
RETURN org, 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 primitivas 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 validadas previamente y creadas por expertos como herramientas reutilizables. En lugar de permitir que los LLM generen consultas potencialmente inseguras, MCP Toolbox proporciona consultas 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 del MCP:

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

Beneficios:

  • Validado previamente por expertos
  • Seguro contra ataques de inyección
  • Optimización del rendimiento
  • Administración centralizada
  • Se puede reutilizar en todos los agentes

Aplica todo lo que aprendiste

La combinación de GraphRAG + el framework multiagente del ADK + el MCP crea un sistema potente:

  1. El agente raíz recibe la consulta 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 conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con tu ID del proyecto usando 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, usamos una base de datos de Neo4j de solo lectura que se completó previamente 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:
  • HAS_INVESTOR: Conexiones de inversión
  • HAS_COMPETITOR: Relaciones competitivas
  • MENTIONS: Referencias de artículos
  • HAS_CEO: Relaciones laborales
  • HAS_CATEGORY: 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 (c:Organization)-[:HAS_COMPETITOR]-(competitor:Organization)
RETURN c.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 (company:Organization)-[:HAS_INVESTOR]->(investor:Person)
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

Crea y activa un entorno virtual de Python con uv:

# Install uv if not already installed
pip install 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:

txtgoogle-adk>=1.21.0          # Agent Development Kit
neo4j>=6.0.3               # Neo4j Python driver
python-dotenv>=1.0.0       # Environment variables
google-cloud-aiplatform>=1.30.0  # Vertex AI

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:

Para revelar el archivo .env oculto, haz lo siguiente:

Haz clic en View > Toggle Hidden files en el editor de Google Cloud Shell.

# Neo4j Configuration (Demo Database)
NEO4J_URI=neo4j+s://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.1-flash-lite-preview # or gemini-3-flash-preview

# MCP Toolbox Configuration
MCP_TOOLBOX_URL=https://toolbox-990868019953.us-central1.run.app/mcp/sse
  1. Genera la configuración de MCP Toolbox:

Ejecuta la secuencia de comandos de configuración para crear el archivo tools.yaml a partir de tus variables de entorno:

python setup_tools_yaml.py

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

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 varios 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 de inversores completas 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 interfaz 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)

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 esta consulta como relacionada con inversores.
  • Rutas al agente de investigación de inversores
  • Herramienta utilizada: find_investor_by_name("ByteDance")
  • Devuelve los inversores con sus tipos (persona/organización).

Respuesta esperada:

I found 2 investors in ByteDance:

1. Rong Yue (Person)
2. Wendi Murdoch (Person)

Would you like to know more about their investment portfolios?

Consulta 3: Empresas por sector**

I found 2 investors in ByteDance:

1. Rong Yue (Person)
2. Wendi Murdoch (Person)

Would you like to know more about their investment portfolios?

"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 8,064 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

Respuesta esperada:

I found 2 investors in ByteDance. Here are their portfolios:

1. Rong Yue (Person)
   - ByteDance
   - Inspur
   
2. Wendi Murdoch (Person)
   - ByteDance
   - (No other investments in database)

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 una 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 principales
  • 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 se formatea como una tabla

Respuesta esperada:

Here are 5 AI companies with positive news and their CEOs:

| Company | Industry | CEO | Avg Sentiment |
|---------|----------|-----|---------------|
| OpenAI | Artificial Intelligence | Sam Altman | 0.92 |
| Anthropic | Artificial Intelligence | Dario Amodei | 0.89 |
| ... | ... | ... | ... |

Qué observar:

  • Múltiples llamadas a herramientas en diferentes agentes
  • Lógica de combinación y filtrado de datos
  • Formato de tabla profesional

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

Respuesta esperada:

Based on our previous analysis of YouTube's competitors, I found these 
investors who funded multiple companies in this competitive landscape:

Sequoia Capital invested in:
- YouTube
- TikTok (ByteDance)
- Twitter

Accel Partners invested in:
- YouTube  
- BuzzFeed

This suggests these investors have strategic positions across the video content platform ecosystem.

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

Respuesta esperada:

Here's a summary of our investment research session:

1. Industry Overview: We explored the Artificial Intelligence industry 
   with 150+ companies in the database.

2. ByteDance Analysis: 
   - Investors: Rong Yue, Wendi Murdoch
   - Rong Yue also invested in Inspur

3. Market Sentiment: We analyzed articles from January 2023, finding 
   strong positive sentiment (avg 0.85) for tech companies.

4. Competitive Landscape: YouTube faces competition from TikTok, 
   Dailymotion, and others, with some investors (Sequoia, Accel) holding 
   positions across competing platforms.

5. Key Players: Identified CEOs of major AI companies with positive media coverage.

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 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" y "invertido" → 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 del 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. Comprueba 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 búsqueda 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 MCP Toolbox.

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 previamente validadas 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 al agente experto más adecuado

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

✅ Prácticas recomendadas de producción aplicadas para el diseño de agentes, el control de errores y la depuración del sistema

¿Qué sigue?

Esta arquitectura de GraphRAG con 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 regulatoria, 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 del ADK + gráficos de conocimiento de Neo4j + consultas 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