Como criar agentes do GraphRAG com o ADK

1. Visão geral

Neste codelab, você vai criar um sistema sofisticado de pesquisa de investimentos multiagente que combina o poder do Kit de Desenvolvimento de Agente (ADK) do Google, do banco de dados de gráficos Neo4j e da caixa de ferramentas do Protocolo de Contexto do Modelo (MCP). Este tutorial prático demonstra como criar agentes inteligentes que entendem o contexto dos dados por meio de relações de gráficos e oferecem respostas de consultas altamente precisas.

Por que usar o GraphRAG e sistemas multiagente?

O GraphRAG (geração aumentada de recuperação baseada em gráficos) aprimora as abordagens tradicionais de RAG usando a estrutura de relacionamento avançada dos mapas de informações. Em vez de apenas pesquisar documentos semelhantes, os agentes do GraphRAG podem:

  • Percorrer relações complexas entre entidades
  • Entender o contexto usando a estrutura do gráfico
  • Fornecer resultados explicáveis com base em dados conectados
  • Executar o raciocínio de várias etapas no Mapa de informações

Com os sistemas multiagente, você pode:

  • Decomponha problemas complexos em subtarefas especializadas
  • Crie aplicativos de IA modulares e fáceis de manter
  • Ativar o processamento paralelo e o uso eficiente de recursos
  • Criar padrões de raciocínio hierárquico com orquestração

O que você vai criar

Você vai criar um sistema completo de pesquisa de investimentos com:

  1. Agente de banco de dados de gráficos: executa consultas Cypher e entende o esquema do Neo4j
  2. Agente de pesquisa de investimentos: descobre relacionamentos com investidores e carteiras de investimentos.
  3. Agente de pesquisa de investimentos: acessa mapas de informações abrangentes usando ferramentas do MCP.
  4. Agente raiz: orquestra todos os subagentes de maneira inteligente.

O sistema vai responder a perguntas complexas como:

  • "Quem são os principais concorrentes do YouTube?"
  • "Quais empresas são mencionadas com sentimento positivo em janeiro de 2023?"
  • "Quem investiu na ByteDance e em que mais eles investiram?"

Visão geral da arquitetura

26c67ab72ef077a4.jpeg

Neste codelab, você vai aprender os fundamentos conceituais e a implementação prática da criação de agentes GraphRAG de nível empresarial.

O que você vai aprender

  • Como criar sistemas multiagente usando o Kit de Desenvolvimento de Agente (ADK) do Google
  • Como integrar o banco de dados de gráficos do Neo4j ao ADK para aplicativos GraphRAG
  • Como implementar a caixa de ferramentas do Protocolo de Contexto de Modelo (MCP) para consultas de banco de dados pré-validadas
  • Como criar ferramentas e funções personalizadas para agentes inteligentes
  • Como projetar hierarquias de agentes e padrões de orquestração
  • Como estruturar instruções do agente para uma performance ideal
  • Como depurar interações multiagentes de maneira eficaz

O que é necessário

  • Navegador da Web Google Chrome
  • Uma conta do Gmail
  • Ter um projeto do Google Cloud com o faturamento ativado
  • Conhecimento básico de comandos de terminal e Python (útil, mas não obrigatório)

Este codelab, criado para desenvolvedores de todos os níveis (inclusive iniciantes), usa Python e Neo4j no aplicativo de exemplo. Embora seja útil ter um conhecimento básico de Python e bancos de dados de grafos, não é necessário ter experiência para entender os conceitos ou acompanhar o curso.

2. Entender o GraphRAG e os sistemas multiagentes

Antes de começar a implementação, vamos entender os conceitos principais que impulsionam esse sistema.

O Neo4j é um banco de dados de grafos nativo líder que armazena dados como uma rede de nós (entidades) e relações (conexões entre entidades), o que o torna ideal para casos de uso em que a compreensão das conexões é fundamental, como recomendações, detecção de fraudes, mapas de informações e muito mais. Ao contrário dos bancos de dados relacionais ou baseados em documentos que dependem de tabelas rígidas ou estruturas hierárquicas, o modelo de grafo flexível do Neo4j permite uma representação intuitiva e eficiente de dados complexos e interconectados.

Em vez de organizar dados em linhas e tabelas como bancos de dados relacionais, o Neo4j usa um modelo de grafo, em que as informações são representadas como nós (entidades) e relações (conexões entre essas entidades). Esse modelo torna excepcionalmente intuitivo o trabalho com dados inerentemente vinculados, como pessoas, lugares, produtos ou, no nosso caso, filmes, atores e gêneros.

Por exemplo, em um conjunto de dados de filmes:

  • Um nó pode representar um Movie, Actor ou Director.
  • Uma relação pode ser ACTED_IN ou DIRECTED

b340d5e06fac5f47.jpeg

Essa estrutura permite que você faça perguntas com facilidade, como:

  • Em quais filmes esse ator apareceu?
  • Quem já trabalhou com Christopher Nolan?
  • Quais filmes são semelhantes com base em atores ou gêneros compartilhados?

O que é o GraphRAG?

A geração aumentada de recuperação (RAG) melhora as respostas do LLM ao recuperar informações relevantes de fontes externas. A RAG tradicional normalmente:

  1. Incorpora documentos em vetores
  2. Pesquisa vetores semelhantes
  3. Transfere os documentos recuperados para o LLM

O GraphRAG estende isso usando mapas de informações:

  1. Incorpora entidades e relacionamentos
  2. Percorre conexões de gráficos.
  3. Recupera informações contextuais de várias etapas
  4. Fornece resultados estruturados e explicáveis

Por que usar gráficos para agentes de IA?

Considere esta pergunta: "Quem são os concorrentes do YouTube e quais investidores financiaram o YouTube e os concorrentes dele?"

O que acontece em uma abordagem tradicional de RAG:

  • Pesquisa documentos sobre concorrentes do YouTube
  • Pesquisa informações para investidores separadamente
  • Tem dificuldade para conectar essas duas informações
  • Pode perder relações implícitas

O que acontece em uma abordagem do 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

O gráfico representa naturalmente as relações, tornando as consultas de várias etapas simples e eficientes.

Sistemas multiagentes no ADK

O Kit de Desenvolvimento de Agente (ADK) é o framework de código aberto do Google para criar e implantar agentes de IA de nível de produção. Ele oferece primitivas intuitivas para orquestração multiagente, integração de ferramentas e gerenciamento de fluxo de trabalho, facilitando a composição de agentes especializados em sistemas sofisticados. O ADK funciona perfeitamente com o Gemini e oferece suporte à implantação no Cloud Run, no Kubernetes ou em qualquer infraestrutura.

O Kit de Desenvolvimento de Agente (ADK) oferece primitivos para criar sistemas multiagente:

  1. Hierarquia de representantes:
# Root agent coordinates specialized agents
root_agent = LlmAgent(
    name="RootAgent",
    sub_agents=[
        graph_db_agent,
        investor_agent,
        investment_agent
    ]
)
  1. Agentes especializados: cada agente tem
  • Ferramentas específicas: funções que podem ser chamadas
  • Instruções claras: função e recursos
  • Conhecimento do domínio: conhecimento da área
  1. Padrões de orquestração:
  • Sequencial: executa agentes em ordem
  • Paralelo: execute vários agentes simultaneamente
  • Condicional: roteamento com base no tipo de consulta

MCP Toolbox para bancos de dados

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto para conectar sistemas de IA a fontes de dados e ferramentas externas. A MCP Toolbox for Databases é a implementação do Google que permite o gerenciamento declarativo de consultas de banco de dados, permitindo que você defina consultas pré-validadas e criadas por especialistas como ferramentas reutilizáveis. Em vez de permitir que os LLMs gerem consultas potencialmente inseguras, a MCP Toolbox oferece consultas pré-aprovadas com validação de parâmetros, garantindo segurança, desempenho e confiabilidade, além de manter a flexibilidade para agentes de IA.

Abordagem tradicional:

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

Abordagem do MCP:

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

Benefícios:

  • Pré-validados por especialistas
  • Proteção contra ataques de injeção
  • Desempenho otimizado
  • Gerenciamento centralizado
  • Reutilizável em vários agentes

Como tudo funciona em conjunto

A combinação de GraphRAG + framework multiagente do ADK + MCP cria um sistema eficiente:

  1. O agente raiz recebe a consulta do usuário
  2. Encaminha para um agente especializado com base no tipo de consulta
  3. O agente usa ferramentas do MCP para buscar dados com segurança
  4. A estrutura de grafo oferece um contexto avançado
  5. O LLM gera uma resposta embasada e explicável

Agora que entendemos a arquitetura, vamos começar a criar!

3. Configurar projeto do Google Cloud

Criar um projeto

  1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
  2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .
  3. Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud. Clique no botão correspondente no Cloud Shell para alternar entre o terminal do Cloud Shell (para executar comandos da nuvem) e o editor (para criar projetos).

Imagem do botão "Ativar o Cloud Shell"

  1. Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com seu ID do projeto usando o seguinte comando:
gcloud auth list
  1. Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
  1. Se o projeto não estiver definido, use este comando:
gcloud config set project <YOUR_PROJECT_ID>

Consulte a documentação para ver o uso e os comandos gcloud.

Ótimo! Agora estamos prontos para passar para a próxima etapa: entender o conjunto de dados.

4. Noções básicas sobre o conjunto de dados "Empresas"

Neste codelab, vamos usar um banco de dados Neo4j somente leitura pré-preenchido com dados de investimento e de empresas do grafo de conhecimento da Diffbot.

O conjunto de dados contém:

  • 237.358 nós representando:
  • Organizações (empresas)
  • Pessoas (executivos, funcionários)
  • Artigos (notícias e menções)
  • Setores
  • Tecnologias
  • Investidores
  • Relações, incluindo:
  • INVESTED_IN: conexões de investimento
  • COMPETES_WITH: relações competitivas
  • MENTIONS: referências de artigos
  • WORKS_AT - Relações de trabalho
  • IN_INDUSTRY: classificações do setor

5c5fee2a9823601f.jpeg

Acessar o banco de dados de demonstração

Neste codelab, vamos usar uma instância de demonstração hospedada. Adicione estas credenciais às suas anotações:

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

Acesso ao navegador:

Acesse: https://demo.neo4jlabs.com:7473 para explorar os dados visualmente.

Faça login com as mesmas credenciais e tente executar:

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

Como visualizar a estrutura do gráfico

Teste esta consulta no navegador Neo4j para ver padrões de relacionamento:

// 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

Essa consulta retorna os cinco investidores mais ativos e os portfólios deles.

Por que esse banco de dados para o GraphRAG?

Esse conjunto de dados é perfeito para demonstrar o GraphRAG porque:

  1. Relações avançadas: conexões complexas entre entidades
  2. Dados do mundo real: empresas, pessoas e artigos de notícias reais
  3. Consultas de vários hops: exigem a travessia de vários tipos de relacionamento.
  4. Dados temporais: artigos com carimbos de data/hora para análise baseada no tempo
  5. Análise de sentimento: pontuações de sentimento pré-calculadas para artigos

Agora que você entende a estrutura de dados, vamos configurar seu ambiente de desenvolvimento.

5. Clonar repositório e configurar ambiente

Clone o repositório

No terminal do Cloud Shell, execute:

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

# Navigate into the directory
cd neo4j-adk-multiagents

Conhecer a estrutura do repositório

Reserve um momento para entender o layout do projeto:

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

Configurar o ambiente virtual

Antes de criar e ativar ambientes virtuais do Python, verifique se o pacote uv já está instalado no seu sistema:

# Install uv if not already installed
pip install uv

Crie e ative um ambiente virtual Python usando uv:

# Create virtual environment
uv venv

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

Você vai ver (.venv) adicionado ao início do prompt do terminal.

Instalar dependências

Instale todos os pacotes necessários:

uv pip install -r requirements.txt

As principais dependências incluem:

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

Configurar variáveis de ambiente

  1. Crie seu arquivo .env:
cp example.env .env
  1. Edite o arquivo .env:

Se estiver usando o Cloud Shell, clique em "Abrir editor" na barra de ferramentas, navegue até .env e atualize:

# 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. Configuração da MCP Toolbox (pré-configurada, não é necessário executar):

Neste laboratório, a caixa de ferramentas do MCP já está hospedada e pré-configurada. Portanto, não é necessário gerar ou gerenciar um arquivo tools.yaml localmente.

Normalmente, você executa o seguinte comando para gerar tools.yaml das variáveis de ambiente depois de atualizar investment_agent/.adk/tools.yaml.template conforme necessário:

python setup_tools_yaml.py

Isso gera investment_agent/.adk/tools.yaml com suas credenciais do Neo4j configuradas corretamente para a caixa de ferramentas do MCP.

Execute o script acima somente se:

  • Você está fazendo a autohospedagem da MCP Toolbox
  • Você está se conectando a um banco de dados ou conjunto de dados do Neo4j diferente
  • Você quer definir ferramentas ou credenciais personalizadas

Nesses casos, o URL da caixa de ferramentas do MCP e a configuração tools.yaml precisam ser atualizados de acordo.

Verificar configuração

Verifique se tudo está configurado corretamente:

# 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')"

Seu ambiente de desenvolvimento está totalmente configurado. Em seguida, vamos analisar a arquitetura multiagente.

6. Noções básicas sobre a arquitetura multiagente

O sistema de quatro agentes

Nosso sistema de pesquisa de investimentos usa uma arquitetura hierárquica multiagente com quatro agentes especializados trabalhando juntos para responder a consultas complexas sobre empresas, investidores e inteligência de mercado.

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

O agente raiz funciona como o coordenador inteligente de todo o sistema. Ele recebe consultas do usuário, analisa a intenção e encaminha solicitações ao agente especializado mais adequado. Pense nele como um gerente de projetos que entende qual membro da equipe é mais adequado para cada tarefa. Ele também processa a agregação de respostas, formata os resultados como tabelas ou gráficos quando solicitado e mantém o contexto da conversa em várias consultas. O agente raiz sempre prefere agentes especializados em vez do agente de banco de dados geral, garantindo que as consultas sejam processadas pelo componente mais especializado disponível.

  1. Agente de banco de dados de gráficos:

O agente de banco de dados de gráficos é sua conexão direta com os recursos avançados de gráficos do Neo4j. Ele entende o esquema do banco de dados, gera consultas Cypher em linguagem natural e executa travessias de gráficos complexas. Esse agente é especializado em perguntas estruturais, agregações e raciocínio de várias etapas no gráfico de conhecimento. É o especialista de substituição quando as consultas exigem uma lógica personalizada que as ferramentas predefinidas não conseguem processar. Isso o torna essencial para análises exploratórias e consultas analíticas complexas que não foram previstas no design do sistema.

  1. Agente de pesquisa de investidores:

O agente de pesquisa de investimentos se concentra exclusivamente em relacionamentos de investimento e análise de portfólio. Ele pode descobrir quem investiu em empresas específicas usando a correspondência exata de nomes, recuperar carteiras completas de investidores mostrando todos os investimentos e analisar padrões de investimento em vários setores. Essa especialização torna o modelo extremamente eficiente para responder a perguntas como "Quem investiu na ByteDance?" ou "Em que mais a Sequoia Capital investiu?". O agente usa funções personalizadas do Python que consultam diretamente o banco de dados Neo4j para encontrar relacionamentos relacionados a investidores.

  1. Agente de pesquisa de investimentos:

O agente de pesquisa de investimentos usa a caixa de ferramentas do Protocolo de Contexto de Modelo (MCP) para acessar consultas pré-validadas e criadas por especialistas. Ele pode buscar todos os setores disponíveis, recuperar empresas em setores específicos, encontrar artigos com análise de sentimentos, descobrir menções a organizações em notícias e obter informações sobre pessoas que trabalham em empresas. Ao contrário do agente de banco de dados de gráficos, que gera consultas dinamicamente, esse agente usa consultas seguras, otimizadas e predefinidas que são gerenciadas e validadas de forma centralizada. Isso o torna seguro e eficiente para fluxos de trabalho de pesquisa comuns.

7. Executar e testar o sistema multiagente

Iniciar o aplicativo

Agora que você entende a arquitetura, vamos executar o sistema completo e interagir com ele.

Inicie a interface da Web do 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

Você verá uma saída como:

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)

Quando o servidor for iniciado, abra o navegador e acesse http://127.0.0.1:8000 para acessar o aplicativo.

Testar consultas e comportamento esperado

Vamos conhecer as funcionalidades do sistema com consultas cada vez mais complexas:

Consultas básicas (agente único)

Consulta 1: descobrir setores

What industries are available in the database?

Comportamento esperado:

  • O agente raiz encaminha para o agente de pesquisa de investimentos
  • Usa a ferramenta MCP: get_industries()
  • Retorna uma lista formatada de todos os setores.

O que observar:

Na interface do ADK, expanda os detalhes da execução para ver:

  • Decisão de seleção de agente
  • Chamada de ferramenta: get_industries()
  • Resultados brutos do Neo4j
  • Resposta formatada

Consulta 2: encontrar investidores

Who invested in ByteDance?

Comportamento esperado:

  • O agente raiz identifica isso como uma consulta relacionada a investidores
  • Rotas para o agente de pesquisa de investidores
  • Usa a ferramenta: find_investor_by_name("ByteDance")
  • Retorna investidores com os respectivos tipos (pessoa/organização).

O que esperar:

  • Uma lista de investidores associados à ByteDance
  • Cada investidor é retornado com o nome e o tipo de entidade (pessoa ou organização).
  • Um resumo conciso e legível dos resultados
  • Um comando de acompanhamento oferecendo a opção de explorar investimentos relacionados ou carteiras de investidores (pode ser)

Consulta 3: empresas por setor

Show me companies in the Artificial Intelligence industry

Comportamento esperado:

  • O agente raiz encaminha para o agente de pesquisa de investimentos
  • Usa a ferramenta MCP: get_companies_in_industry("Artificial Intelligence")
  • Retorna uma lista de empresas de IA com IDs e datas de fundação.

O que observar:

  • Observe como o agente usa a correspondência exata de nomes do setor
  • Os resultados são limitados para evitar uma saída excessiva
  • Os dados são formatados de maneira clara para facilitar a leitura

Consultas intermediárias (várias etapas em um único agente)

Consulta 4: análise de sentimento

Find articles with positive sentiment from January 2023

Comportamento esperado:

  • Rotas para o agente de pesquisa de investimentos
  • Usa a ferramenta MCP: get_articles_with_sentiment(0.7, 2023, 1)
  • Retorna artigos com títulos, pontuações de sentimento e datas de publicação

Dica de depuração:

Confira os parâmetros de invocação da ferramenta:

  • min_sentiment: 0,7 (o agente interpreta "positiva" como >= 0,7)
  • year: 2023
  • month: 1

Consulta 5: consulta complexa de banco de dados

How many companies are in the database?

Comportamento esperado:

  • O agente raiz encaminha para o agente de banco de dados de gráficos
  • O agente chama get_neo4j_schema() primeiro para entender a estrutura
  • Gera Cypher: MATCH (c:Company) RETURN count(c)
  • Executa a consulta e retorna a contagem

Resposta esperada:

There are 46,088 companies in the database.

Consultas avançadas (coordenação de vários agentes)

Consulta 6: análise de portfólio

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

Comportamento esperado:

Esta é uma consulta dividida em duas partes que exige coordenação do agente:

  • Etapa 1: agente raiz → agente de pesquisa de investimentos
  • Chama find_investor_by_name("ByteDance")
  • Recebe a lista de investidores: [Rong Yue, Wendi Murdoch]
  • Etapa 2: para cada investidor → agente de pesquisa de investidores
  • Chama find_investor_by_id(investor_id)
  • Recupera o portfólio completo
  • Etapa 3: o agente raiz agrega e formata

O que esperar:

  • Uma lista de investidores que investiram na ByteDance
  • Para cada investidor:
  • O nome e o tipo de entidade (pessoa ou organização)
  • Uma lista de outras empresas em que investiram, com base nos dados disponíveis
  • Um resumo estruturado e fácil de ler agrupado por investidor

O que observar:

  • Várias chamadas de ferramentas em sequência
  • Contexto mantido entre as etapas
  • Resultados agregados de forma inteligente

Consulta 7: pesquisa em vários domínios

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

Comportamento esperado:

Essa consulta complexa exige vários agentes e ferramentas:

  • Etapa 1: agente de pesquisa de investimentos
  • get_companies_in_industry("Artificial Intelligence")
  • Retorna a lista de empresas de IA
  • Etapa 2: agente de pesquisa de investimentos
  • get_articles_with_sentiment(0.8)
  • Retorna artigos positivos
  • Etapa 3: filtros do agente raiz
  • Identifica quais empresas de IA aparecem em artigos positivos
  • Seleciona os cinco principais
  • Etapa 4: agente de pesquisa de investimentos
  • get_people_in_organizations([company_names], "CEO")
  • Retorna informações do CEO
  • Etapa 5: o Root Agent formata a resposta

O que esperar:

  • Uma lista de cinco empresas do setor de inteligência artificial
  • Apenas empresas que aparecem em artigos com pontuação positiva
  • Para cada empresa:
  • Nome da empresa
  • Setor
  • Nome do CEO
  • Uma pontuação de sentimento agregada ou representativa

O que observar:

  • Várias chamadas de ferramentas em diferentes agentes
  • Lógica de combinação e filtragem de dados

Consulta 8: análise da concorrência

Who are YouTube's main competitors?

Comportamento esperado:

  • O agente raiz encaminha para o agente de banco de dados de grafos (consulta de relacionamento)
  • O agente gera Cypher aprimorado com GraphRAG:
MATCH (c:Company {name: "YouTube"})-[:COMPETES_WITH]->(competitor)
RETURN competitor.name as competitor_name
  • Retorna uma lista de empresas concorrentes.

Resposta esperada:

YouTube's main competitors are:

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

Consultas de acompanhamento baseadas no contexto

Consulta 9: pergunta de acompanhamento (depois da consulta 8)

Which investors funded both YouTube and its competitors?

Comportamento esperado:

  • O agente raiz lembra o contexto anterior (YouTube e concorrentes)
  • Rotas para o agente de pesquisa de investidores
  • Para o YouTube e cada concorrente, encontre investidores
  • Identifica investidores que aparecem em várias empresas

O que esperar:

  • O sistema usa o contexto conversacional atual (YouTube e concorrentes)
  • Uma lista de investidores que investiram em mais de uma empresa nesse cenário competitivo
  • Para cada investidor:
  • Nome do investidor
  • Uma lista agrupada de empresas relevantes em que investiram
  • Um breve resumo interpretativo destacando a sobreposição ou os padrões estratégicos (talvez)

Consulta 10: resumo da pesquisa

Summarize our research findings so far

Comportamento esperado:

  • O agente raiz analisa o histórico de conversas
  • Sintetiza as principais descobertas de consultas anteriores
  • Fornece um resumo coerente

O que esperar:

  • Um resumo conciso e bem estruturado de insights coletados em consultas anteriores
  • Principais descobertas agrupadas por temas (visão geral do setor, análise da empresa, sentimento, concorrência, liderança)
  • Marcadores claros destacando:
  • Setores analisados
  • Empresas e investidores importantes
  • Padrões de investimento entre empresas
  • Tendências de sentimento do mercado
  • Uma narrativa coerente que reflete a síntese com reconhecimento de contexto em toda a sessão

Como entender as interações do agente na visualização de depuração

A interface da Web do ADK oferece visibilidade detalhada da execução. Confira o que você precisa observar:

  1. Linha do tempo de eventos

Mostra o fluxo 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. Detalhes da invocação da ferramenta

Clique em qualquer chamada de função para ver:

  • Nome da função
  • Parâmetros de entrada
  • Valor de retorno
  • Tempo de execução
  • Qualquer erro
  1. Tomada de decisões do agente

Observe o raciocínio do LLM:

  • Por que ele escolheu um agente específico
  • Como ela interpretou a consulta
  • Quais ferramentas foram consideradas
  • Por que ele formatou os resultados de uma determinada maneira

Observações e insights comuns

Padrões de encaminhamento de consultas:

  • Palavras-chave como "investidor", "investido" → Agente de pesquisa de investidores
  • Palavras-chave como "setor", "empresas", "artigos" → Agente de pesquisa de investimentos
  • Agregações, contagens, lógica complexa → agente do banco de dados de gráficos

Observações sobre a performance:

  • As ferramentas do MCP geralmente são mais rápidas (consultas pré-otimizadas)
  • A geração de Cypher complexa leva mais tempo (tempo de raciocínio do LLM)
  • Várias chamadas de função adicionam latência, mas oferecem resultados mais completos

Tratamento de erros:

Se uma consulta falhar:

  • O agente explica o que deu errado
  • Sugere correções (por exemplo, "Nome da empresa não encontrado, verifique a ortografia")
  • Pode tentar abordagens alternativas

Dicas para testes eficazes

  1. Comece com o básico: teste a funcionalidade principal de cada agente antes de consultas complexas.
  2. Use complementos: teste a retenção de contexto com perguntas complementares
  3. Observar o roteamento: assista qual agente processa cada consulta para entender a lógica.
  4. Verificar chamadas de ferramentas: confira se os parâmetros foram extraídos corretamente da linguagem natural.
  5. Teste casos extremos: tente consultas ambíguas, erros de ortografia ou solicitações incomuns.

Agora você tem um sistema GraphRAG multiagente totalmente funcional. Teste suas próprias perguntas para conhecer os recursos dele.

8. Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta postagem, siga estas etapas:

  1. No console do Google Cloud, acesse a página Gerenciar recursos.
  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

9. Parabéns

🎉 Parabéns! Você criou com sucesso um sistema GraphRAG multiagente de qualidade de produção usando o Kit de Desenvolvimento de Agente do Google, o Neo4j e a caixa de ferramentas do MCP.

Ao combinar os recursos de orquestração inteligente do ADK com o modelo de dados avançado do Neo4j e a segurança das consultas MCP pré-validadas, você criou um sistema sofisticado que vai além de consultas simples de banco de dados. Ele entende o contexto, os motivos em relações complexas e coordena agentes especializados para fornecer insights abrangentes e precisos.

Neste codelab, você fez o seguinte:

✅ Criou um sistema multiagente usando o Kit de Desenvolvimento de Agente (ADK) do Google com orquestração hierárquica

✅ Banco de dados de gráficos Neo4j integrado para aproveitar consultas com reconhecimento de relacionamento e raciocínio de vários saltos

✅ Implementamos a MCP Toolbox para consultas de banco de dados seguras e pré-validadas como ferramentas reutilizáveis.

✅ Criou agentes especializados para pesquisa de investidores, análise de investimentos e operações de banco de dados de gráficos

✅ Projetou um roteamento inteligente que delega automaticamente as consultas ao agente especialista mais adequado.

✅ Processamento de tipos de dados complexos com a serialização adequada de tipos do Neo4j para uma integração perfeita com Python

✅ Práticas recomendadas de produção aplicadas para design de agente, tratamento de erros e depuração do sistema

A seguir

Essa arquitetura GraphRAG multiagente não se limita à pesquisa de investimentos. Ela pode ser estendida para:

  • Serviços financeiros: otimização de portfólio, avaliação de riscos, detecção de fraudes
  • Saúde: coordenação do atendimento ao paciente, análise de interação medicamentosa, pesquisa clínica
  • E-commerce: recomendações personalizadas, otimização da cadeia de suprimentos, insights dos clientes
  • Jurídico e compliance: análise de contratos, monitoramento regulatório, pesquisa de jurisprudência
  • Pesquisa acadêmica: revisão de literatura, descoberta de colaboração, análise de citações
  • Inteligência empresarial: análise da concorrência, pesquisa de mercado, mapas de informações organizacionais

Em qualquer lugar em que você tenha dados interconectados complexos + especialização no domínio + interfaces de linguagem natural, essa combinação de sistemas multiagentes do ADK + gráficos de conhecimento do Neo4j + consultas validadas pelo MCP pode impulsionar a próxima geração de aplicativos empresariais inteligentes.

À medida que o Kit de desenvolvimento de agentes do Google e os modelos do Gemini evoluem, você poderá incorporar padrões de raciocínio ainda mais sofisticados, integração de dados em tempo real e recursos multimodais para criar sistemas verdadeiramente inteligentes e sensíveis ao contexto.

Continue explorando e criando para levar seus aplicativos de agente inteligente a um novo patamar!

Confira mais tutoriais práticos sobre gráficos de conhecimento na Neo4j GraphAcademy (em inglês) e descubra outros padrões de agentes no repositório de amostras do ADK (em inglês).

🚀 Tudo pronto para criar seu próximo sistema de agente inteligente?

Documentos de referência