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 de 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 + sistemas multiagente?
O GraphRAG (geração aumentada por recuperação baseada em gráficos) aprimora as abordagens tradicionais de RAG usando a estrutura de relacionamento detalhada 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 de gráficos
- 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 a utilização 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:
- Agente de banco de dados de gráficos: executa consultas Cypher e entende o esquema do Neo4j.
- Agente de pesquisa de investimentos: descobre relacionamentos com investidores e carteiras de investimentos.
- Agente de pesquisa de investimentos: acessa mapas de informações abrangentes usando ferramentas do MCP.
- 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 essa pessoa investiu?"
Visão geral da arquitetura
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 prévia para entender os conceitos ou acompanhar.
2. Entender o GraphRAG e os sistemas multiagente
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 entender as 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,ActorouDirector. - Uma relação pode ser
ACTED_INouDIRECTED
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 por recuperação (RAG) melhora as respostas do LLM ao recuperar informações relevantes de fontes externas. A RAG tradicional geralmente:
- Incorpora documentos em vetores
- Pesquisa vetores semelhantes
- Transmite os documentos recuperados ao LLM
O GraphRAG estende isso usando mapas de informações:
- Incorpora entidades e relacionamentos
- Percorre conexões de gráficos
- Recupera informações contextuais de várias etapas
- 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 separadamente informações para investidores
- Tem dificuldade em conectar essas duas informações
- Pode perder relações implícitas
O que acontece em uma abordagem do 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
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 primitivos intuitivos 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:
- Hierarquia de agentes:
# Root agent coordinates specialized agents
root_agent = LlmAgent(
name="RootAgent",
sub_agents=[
graph_db_agent,
investor_agent,
investment_agent
]
)
- 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
- 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. Assim, você pode definir 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, performance 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 poderoso:
- O agente raiz recebe a consulta do usuário
- Encaminha para um agente especializado com base no tipo de consulta
- O agente usa ferramentas do MCP para buscar dados com segurança
- A estrutura de grafo oferece um contexto avançado
- 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
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .
- 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. É possível alternar entre o terminal do Cloud Shell (para executar comandos da nuvem) e o editor (para criar projetos) clicando no botão correspondente no Cloud Shell.
- Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com o ID do seu projeto usando o seguinte comando:
gcloud auth list
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
- 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 Mapa de informações 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:
HAS_INVESTOR: conexões de investimentoHAS_COMPETITOR: relações competitivasMENTIONS: referências de artigosHAS_CEO- Relações de trabalhoHAS_CATEGORY: classificações do setor
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 (c:Organization)-[:HAS_COMPETITOR]-(competitor:Organization)
RETURN c.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 (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
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:
- Relações avançadas: conexões complexas entre entidades
- Dados do mundo real: empresas, pessoas e artigos de notícias reais
- Consultas de vários saltos: exigem a travessia de vários tipos de relacionamento.
- Dados temporais: artigos com carimbos de data/hora para análise baseada em tempo
- 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
Crie e ative um ambiente virtual Python usando 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
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:
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
Configurar variáveis de ambiente
- Crie seu arquivo **
.env**:
cp example.env .env
- Edite o arquivo **
.env** **:**
Se estiver usando o Cloud Shell, clique em "Abrir editor" na barra de ferramentas, navegue até .env e atualize:
Para revelar o arquivo .env oculto:
Clique em View > Toggle Hidden files no editor do 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
- Gere a configuração da MCP Toolbox:
Execute o script de configuração para criar o arquivo tools.yaml com base nas variáveis de ambiente:
python setup_tools_yaml.py
Isso gera investment_agent/.adk/tools.yaml com suas credenciais do Neo4j configuradas corretamente para as ferramentas do MCP.
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 │
└──────────┘ └───────────────┘
- 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.
- Agente de banco de dados de gráficos:
O agente do 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. Ele é especializado em perguntas estruturais, agregações e raciocínio de várias etapas no mapa de informações. Ele é o especialista substituto 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.
- 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 o torna 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.
- 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 grafo, 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. Como 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)
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 conferir:
- 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).
Resposta 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 setor**
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"
Comportamento esperado:
- O agente raiz encaminha para o agente de pesquisa de investimentos
- Usa a ferramenta MCP:
get_companies_in_industry("Artificial Intelligence") - Retorna a lista de empresas de IA com IDs e datas de fundação.
O que observar:
- Observe como o agente usa a correspondência exata do nome 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 "positivo" como >= 0,7)year: 2023month: 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 8,064 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:
Essa é uma consulta em duas partes que exige coordenação do agente:
- Etapa 1: agente raiz → agente de pesquisa de investimentos
- Chama
find_investor_by_name("ByteDance") - Mostre 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
Resposta 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)
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 agente raiz é formatado como uma tabela
Resposta 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 |
| ... | ... | ... | ... |
O que observar:
- Várias chamadas de ferramentas em diferentes agentes
- Lógica de combinação e filtragem de dados
- Formatação profissional de tabelas
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
Resposta 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: 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
Resposta 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.
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:
- 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
- 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
- Tomada de decisões do agente
Observe o raciocínio do LLM:
- Por que ele escolheu um agente específico
- Como ele 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 complexo leva mais tempo (tempo de raciocínio do LLM)
- Várias chamadas de ferramentas aumentam a 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
- Comece com o básico: teste a funcionalidade principal de cada agente antes de fazer consultas complexas.
- Use acompanhamentos: teste a retenção de contexto com perguntas complementares
- Observar o roteamento: veja qual agente processa cada consulta para entender a lógica
- Verificar chamadas de ferramentas: confira se os parâmetros foram extraídos corretamente da linguagem natural.
- Teste casos extremos: tente consultas ambíguas, erros de ortografia ou solicitações incomuns.
Agora você tem um sistema GraphRAG multiagente totalmente funcional. Experimente com suas próprias perguntas para explorar os recursos dele.
8. Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta postagem, siga estas etapas:
- No console do Google Cloud, acesse a página Gerenciar recursos.
- Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
- Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.
9. Parabéns
🎉 Parabéns! Você criou 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árias etapas
✅ Implementamos a MCP Toolbox para consultas de banco de dados seguras e pré-validadas como ferramentas reutilizáveis.
✅ Criamos 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 serialização de tipo Neo4j adequada para integração perfeita com Python
✅ Práticas recomendadas de produção aplicadas para design de agentes, tratamento de erros e depuração de sistemas
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 complexos interconectados + especialização no domínio + interfaces de linguagem natural, essa combinação de sistemas multiagente do ADK + grafos 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 nível!
Confira mais tutoriais práticos sobre mapas 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?