ADK ile GraphRAG Temsilcileri Oluşturma

1. Genel Bakış

Bu codelab'de, Google'ın Agent Development Kit (ADK), Neo4j Graph Database ve Model Context Protocol (MCP) Toolbox'ın gücünü birleştiren gelişmiş bir çoklu aracı yatırım araştırma sistemi oluşturacaksınız. Bu uygulamalı eğitimde, grafik ilişkileri aracılığıyla veri bağlamını anlayan ve son derece doğru sorgu yanıtları veren akıllı temsilcilerin nasıl oluşturulacağı gösterilmektedir.

Neden GraphRAG + Çoklu Aracı Sistemleri?

GraphRAG (Grafik Tabanlı Almayla Artırılmış Üretim), bilgi grafiklerinin zengin ilişki yapısından yararlanarak geleneksel RAG yaklaşımlarını geliştirir. GraphRAG aracıları, yalnızca benzer dokümanları aramak yerine şunları yapabilir:

  • Varlıklar arasındaki karmaşık ilişkilerde gezinme
  • Grafik yapısı aracılığıyla bağlamı anlama
  • Bağlı verilere dayalı olarak açıklanabilir sonuçlar sunma
  • Bilgi grafiğinde çok adımlı akıl yürütme gerçekleştirme

Çoklu aracı sistemleri şunları yapmanıza olanak tanır:

  • Karmaşık sorunları özelleşmiş alt görevlere ayırma
  • Modüler ve bakımı kolay yapay zeka uygulamaları oluşturma
  • Paralel işlemeyi ve verimli kaynak kullanımını etkinleştirme
  • Orkestrasyon ile hiyerarşik akıl yürütme kalıpları oluşturma

Ne oluşturacaksınız?

Aşağıdakileri içeren eksiksiz bir yatırım araştırma sistemi oluşturacaksınız:

  1. Graph Database Agent: Cypher sorgularını yürütür ve Neo4j şemasını anlar.
  2. Yatırımcı Araştırma Aracısı: Yatırımcı ilişkilerini ve yatırım portföylerini keşfeder.
  3. Yatırım Araştırması Asistanı: MCP araçları aracılığıyla kapsamlı bilgi grafiklerine erişir.
  4. Kök Temsilci: Tüm alt temsilcileri akıllıca yönetir.

Sistem, aşağıdaki gibi karmaşık soruları yanıtlar:

  • "YouTube'un başlıca rakipleri kimler?"
  • "Ocak 2023'te hangi şirketlerden olumlu bir şekilde bahsedildi?"
  • "ByteDance'e kim yatırım yaptı ve başka nerelere yatırım yaptı?"

Mimariye Genel Bakış

26c67ab72ef077a4.jpeg

Bu codelab'de, kurumsal düzeyde GraphRAG aracı oluşturmanın hem kavramsal temellerini hem de pratik uygulamasını öğreneceksiniz.

Neler öğreneceksiniz?

  • Google'ın Agent Development Kit'ini (ADK) kullanarak çok agent'lı sistemler oluşturma
  • Neo4j grafik veritabanını GraphRAG uygulamaları için ADK ile entegre etme
  • Önceden doğrulanmış veritabanı sorguları için Model Context Protocol (MCP) Toolbox'ı uygulama
  • Akıllı temsilciler için özel araçlar ve işlevler oluşturma
  • Aracı hiyerarşilerini ve düzenleme kalıplarını tasarlama
  • Optimum performans için aracı talimatlarını yapılandırma
  • Çoklu aracı etkileşimlerinde etkili bir şekilde hata ayıklama

Gerekenler

  • Chrome web tarayıcısı
  • Gmail hesabı
  • Faturalandırmanın etkinleştirildiği bir Google Cloud projesi
  • Terminal komutları ve Python hakkında temel bilgi (faydalı ancak zorunlu değil)

Her seviyeden geliştirici (yeni başlayanlar dahil) için tasarlanan bu codelab'de, örnek uygulamada Python ve Neo4j kullanılır. Python ve grafik veritabanları hakkında temel bilgi sahibi olmak faydalı olsa da kavramları anlamak veya takip etmek için önceden deneyim sahibi olmanız gerekmez.

2. GraphRAG ve Çoklu Aracı Sistemleri Anlama

Uygulamaya geçmeden önce bu sistemi destekleyen temel kavramları anlayalım.

Neo4j, verileri bir düğüm (varlık) ve ilişki (varlıklar arasındaki bağlantılar) ağı olarak depolayan, önde gelen yerel bir grafik veritabanıdır. Bu nedenle, bağlantıları anlamanın önemli olduğu kullanım alanları (ör. öneriler, sahtekarlık tespiti, bilgi grafikleri vb.) için idealdir. Neo4j'nin esnek grafik modeli, katı tablolara veya hiyerarşik yapılara dayanan ilişkisel ya da belge tabanlı veritabanlarının aksine, karmaşık ve birbirine bağlı verilerin sezgisel ve verimli bir şekilde gösterilmesine olanak tanır.

Neo4j, verileri ilişkisel veritabanları gibi satırlar ve tablolar halinde düzenlemek yerine grafik modeli kullanır. Bu modelde bilgiler düğümler (varlıklar) ve ilişkiler (bu varlıklar arasındaki bağlantılar) olarak gösterilir. Bu model, doğası gereği bağlantılı olan verilerle (ör. kişiler, yerler, ürünler veya bizim durumumuzda filmler, aktörler ve türler) çalışmayı son derece kolaylaştırır.

Örneğin, bir film veri kümesinde:

  • Bir düğüm Movie, Actor veya Director öğesini temsil edebilir.
  • İlişki ACTED_IN veya DIRECTED olabilir.

b340d5e06fac5f47.jpeg

Bu yapı, aşağıdaki gibi soruları kolayca sormanıza olanak tanır:

  • Bu oyuncu hangi filmlerde rol aldı?
  • Christopher Nolan ile kimler çalıştı?
  • Ortak oyunculara veya türlere göre benzer filmler nelerdir?

GraphRAG nedir?

Veriyle Artırılmış Üretim (RAG), harici kaynaklardan alakalı bilgileri alarak LLM yanıtlarını geliştirir. Geleneksel RAG genellikle:

  1. Dokümanları vektörlere yerleştirir.
  2. Benzer vektörler için aramalar
  3. Alınan belgeleri LLM'ye iletir.

GraphRAG, bilgi grafikleri kullanarak bu özelliği genişletir:

  1. Varlıkları ve ilişkileri yerleştirir.
  2. Grafik bağlantılarını geçme
  3. Çok adımlı bağlam bilgilerini alır.
  4. Yapılandırılmış ve açıklanabilir sonuçlar sunar

Yapay Zeka Temsilcileri İçin Neden Grafikler?

Şu soruyu ele alalım: "YouTube'un rakipleri kimler ve hem YouTube'u hem de rakiplerini hangi yatırımcılar finanse etti?"

Geleneksel RAG yaklaşımında neler olur?

  • YouTube'un rakipleriyle ilgili belgeler için yapılan aramalar
  • Yatırımcı bilgilerini ayrı ayrı arar
  • Bu iki bilgiyi birleştirmekte zorlanıyor
  • Örtülü ilişkileri kaçırabilir.

GraphRAG yaklaşımında ne olur?

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

Grafik, ilişkileri doğal olarak temsil ettiğinden çok adımlı sorgular kolay ve verimli bir şekilde yapılabilir.

ADK'daki Çok Temsilcili Sistemler

Agent Development Kit (ADK), Google'ın üretime hazır yapay zeka aracıları oluşturmak ve dağıtmak için kullandığı açık kaynaklı çerçevedir. Çoklu aracı düzenleme, araç entegrasyonu ve iş akışı yönetimi için sezgisel temel öğeler sunarak uzmanlaşmış aracıları gelişmiş sistemlere dahil etmeyi kolaylaştırır. ADK, Gemini ile sorunsuz bir şekilde çalışır ve Cloud Run, Kubernetes veya herhangi bir altyapıya dağıtımı destekler.

Aracı Geliştirme Kiti (ADK), çoklu aracı sistemleri oluşturmak için temel öğeler sağlar:

  1. Temsilci Hiyerarşisi:
# Root agent coordinates specialized agents
root_agent = LlmAgent(
    name="RootAgent",
    sub_agents=[
        graph_db_agent,
        investor_agent,
        investment_agent
    ]
)
  1. Uzman Temsilciler: Her temsilcinin
  • Belirli araçlar: Çağırabileceği işlevler
  • Net talimatlar: Rolü ve özellikleri
  • Alan uzmanlığı: Alanıyla ilgili bilgi
  1. Düzenleme Kalıpları:
  • Sıralı: Aracılar sırayla yürütülür.
  • Paralel: Aynı anda birden fazla aracı çalıştırın
  • Koşullu: Sorgu türüne göre yönlendirme

Veritabanları için MCP Araç Kutusu

Model Context Protocol (MCP), yapay zeka sistemlerini harici veri kaynaklarına ve araçlara bağlamak için kullanılan açık bir standarttır. Veritabanları için MCP Araç Kutusu, Google'ın bildirim temelli veritabanı sorgu yönetimini etkinleştiren uygulamasıdır. Bu sayede, önceden doğrulanmış ve uzmanlar tarafından oluşturulmuş sorguları yeniden kullanılabilir araçlar olarak tanımlayabilirsiniz. MCP Toolbox, büyük dil modellerinin potansiyel olarak güvenli olmayan sorgular oluşturmasına izin vermek yerine, önceden onaylanmış ve parametre doğrulaması yapılmış sorgular sunar. Böylece, yapay zeka aracı esnekliğini korurken güvenlik, performans ve güvenilirlik sağlanır.

Geleneksel Yaklaşım:

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

MCP Yaklaşımı:

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

Avantajları

  • Uzmanlar tarafından önceden doğrulanmış
  • Enjeksiyon saldırılarına karşı güvenli
  • Performansı optimize edilmiş
  • Merkezi olarak yönetilen
  • Farklı temsilcilerde yeniden kullanılabilir

Parçaları Birleştirme

GraphRAG + ADK'nın Multi-Agent Framework'ü + MCP kombinasyonu güçlü bir sistem oluşturur:

  1. Root Agent, kullanıcı sorgusunu alır.
  2. Sorgu türüne göre uzman temsilciye yönlendirme
  3. Temsilci, verileri güvenli bir şekilde getirmek için MCP araçlarını kullanır.
  4. Grafik yapısı zengin bağlam sağlar.
  5. LLM, temellendirilmiş ve açıklanabilir bir yanıt oluşturur.

Artık mimariyi anladığımıza göre geliştirmeye başlayabiliriz.

3. Google Cloud projesi oluşturma

Proje oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Faturalandırmanın projede etkin olup olmadığını kontrol etmeyi öğrenin .
  3. Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın. Cloud Shell'deki ilgili düğmeyi tıklayarak Cloud Shell Terminali (bulut komutlarını çalıştırmak için) ile Düzenleyici (projeleri oluşturmak için) arasında geçiş yapabilirsiniz.

Cloud Shell'i etkinleştir düğmesinin resmi

  1. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanmış olduğunu ve projenin proje kimliğinize ayarlandığını kontrol edin:
gcloud auth list
  1. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
  1. Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>

gcloud komutları ve kullanımı için belgelere bakın.

Harika! Şimdi bir sonraki adıma, yani veri kümesini anlamaya geçebiliriz.

4. Şirketler veri kümesini anlama

Bu codelab'de, Diffbot'un Bilgi Grafiği'nden alınan yatırım ve şirket verileriyle önceden doldurulmuş salt okunur bir Neo4j veritabanı kullanıyoruz.

Veri kümesi şunları içerir:

  • Şunları temsil eden 237.358 düğüm:
  • Kuruluşlar (şirketler)
  • Kullanıcılar (yöneticiler, çalışanlar)
  • Makaleler (haberler ve bahsetmeler)
  • Sektörler
  • Teknolojiler
  • Yatırımcılar
  • Aşağıdakiler dahil ilişkiler:
  • INVESTED_IN - Yatırım bağlantıları
  • COMPETES_WITH - Rekabete dayalı ilişkiler
  • MENTIONS - Makale referansları
  • WORKS_AT - İstihdam ilişkileri
  • IN_INDUSTRY - Sektör sınıflandırmaları

5c5fee2a9823601f.jpeg

Demo veritabanına erişme

Bu codelab'de, barındırılan bir demo örneği kullanacağız. Notlarınıza şu kimlik bilgilerini ekleyin:

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

Tarayıcı Erişimi:

Verileri görsel olarak incelemek için: https://demo.neo4jlabs.com:7473

Aynı kimlik bilgileriyle giriş yapın ve aşağıdaki kodu çalıştırmayı deneyin:

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

Grafik Yapısını Görselleştirme

İlişki kalıplarını görmek için Neo4j Browser'da şu sorguyu deneyin:

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

Bu sorgu, en aktif 5 yatırımcıyı ve portföylerini döndürür.

GraphRAG için Neden Bu Veritabanı?

Bu veri kümesi, GraphRAG'i göstermek için idealdir. Bunun nedeni:

  1. Zengin İlişkiler: Öğeler arasındaki karmaşık bağlantılar
  2. Gerçek Dünya Verileri: Gerçek şirketler, kişiler ve haber makaleleri
  3. Çok adımlı sorgular: Birden fazla ilişki türünün geçilmesini gerektirir.
  4. Zamana Dayalı Veriler: Zamana dayalı analiz için zaman damgaları içeren makaleler
  5. Yaklaşım analizi: Makaleler için önceden hesaplanmış yaklaşım puanları

Veri yapısını anladığınıza göre şimdi geliştirme ortamınızı ayarlayalım.

5. Depoyu Klonlama ve Ortamı Yapılandırma

Depoyu Klonlama

Cloud Shell terminalinizde şu komutu çalıştırın:

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

# Navigate into the directory
cd neo4j-adk-multiagents

Depo Yapısını Keşfetme

Proje düzenini anlamak için bir dakikanızı ayırın:

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

Sanal Ortamı Ayarlama

Python sanal ortamlarını oluşturup etkinleştirmeden önce sisteminizde uv paketinin yüklü olduğundan emin olun:

# Install uv if not already installed
pip install uv

uv'yi kullanarak Python sanal ortamı oluşturun ve etkinleştirin:

# Create virtual environment
uv venv

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

Terminal isteminizin başına (.venv) eklenir.

Bağımlılıkları yükleme

Gerekli tüm paketleri yükleyin:

uv pip install -r requirements.txt

Temel bağımlılıklar şunlardır:

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

Ortam değişkenlerini yapılandırma

  1. .env dosyanızı oluşturun:
cp example.env .env
  1. .env dosyasını düzenleyin:

Cloud Shell kullanıyorsanız araç çubuğunda Düzenleyiciyi Aç'ı tıklayın, ardından .env bölümüne gidin ve güncelleyin:

# 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. MCP Toolbox Yapılandırması (Önceden yapılandırılmıştır, çalıştırmanıza gerek yoktur):

Bu laboratuvarda MCP Araç Kutusu zaten barındırılıyor ve önceden yapılandırılmış durumda. Bu nedenle, yerel olarak bir tools.yaml dosyası oluşturmanız veya yönetmeniz gerekmez.

Normalde, investment_agent/.adk/tools.yaml.template değerini gerektiği gibi güncelledikten sonra ortam değişkenlerinden tools.yaml oluşturmak için aşağıdaki komutu çalıştırırsınız:

python setup_tools_yaml.py

Bu işlem, MCP Toolbox için Neo4j kimlik bilgileriniz doğru şekilde yapılandırılmış olarak investment_agent/.adk/tools.yaml oluşturur.

Yukarıdaki komut dosyasını yalnızca şu durumlarda çalıştırırsınız:

  • MCP Toolbox'ı kendiniz barındırıyorsunuz
  • Farklı bir Neo4j veritabanına veya veri kümesine bağlanıyorsunuz
  • Özel araçlar veya kimlik bilgileri tanımlamak istiyorsanız

Bu durumlarda, MCP Toolbox URL'si ve tools.yaml yapılandırmasının buna göre güncellenmesi gerekir.

Yapılandırmayı doğrulama

Her şeyin doğru şekilde ayarlandığını kontrol edin:

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

Geliştirme ortamınız artık tamamen yapılandırıldı. Ardından, çoklu aracı mimarisine geçeceğiz.

6. Çoklu aracı mimarisini anlama

Dört Aracılı Sistem

Yatırım araştırma sistemimiz, şirketler, yatırımcılar ve pazar bilgileriyle ilgili karmaşık sorguları yanıtlamak için birlikte çalışan dört uzman aracının bulunduğu hiyerarşik bir çoklu aracı mimarisi kullanır.

                ┌──────────────┐
                │  Root Agent  │ ◄── User Query
                └──────┬───────┘
                       │
      ┌────────────────┼────────────────┐
      │                │                │
┌─────▼─────┐     ┌────▼─────┐     ┌────▼──────────┐
│ Graph DB  │     │ Investor │     │  Investment   │
│  Agent    │     │ Research │     │  Research     │
└───────────┘     │  Agent   │     │  Agent        │
                  └──────────┘     └───────────────┘
  1. Kök Aracı (Düzenleyici):

Kök aracı, tüm sistemin akıllı koordinatörü olarak görev yapar. Kullanıcı sorgularını alır, amacı analiz eder ve istekleri en uygun uzmanlaşmış aracıya yönlendirir. Bu özelliği, hangi ekip üyesinin hangi görev için en uygun olduğunu bilen bir proje yöneticisi olarak düşünebilirsiniz. Ayrıca yanıtları toplar, istendiğinde sonuçları tablo veya grafik olarak biçimlendirir ve birden fazla sorguda sohbet bağlamını korur. Kök Ajan, sorguların mevcut en uzman bileşen tarafından işlenmesini sağlamak için her zaman genel veritabanı ajanı yerine uzmanlaşmış ajanları tercih eder.

  1. Graph Database Agent:

Graph Database Agent, Neo4j'nin güçlü grafik özelliklerine doğrudan bağlanmanızı sağlar. Veritabanı şemasını anlar, doğal dilden Cypher sorguları oluşturur ve karmaşık grafik geçişlerini yürütür. Bu aracı, bilgi grafiğindeki yapısal sorular, toplama işlemleri ve çok adımlı akıl yürütme konusunda uzmanlaşmıştır. Sorgular, önceden tanımlanmış araçların işleyemediği özel mantık gerektirdiğinde yedek uzman olarak kullanılır. Bu nedenle, sistem tasarımında öngörülmeyen keşif analizi ve karmaşık analitik sorgular için vazgeçilmezdir.

  1. Yatırımcı Araştırması Aracısı:

Yatırımcı Araştırma Aracısı yalnızca yatırım ilişkilerine ve portföy analizine odaklanır. Tam ad eşleştirme özelliğini kullanarak belirli şirketlere kimlerin yatırım yaptığını bulabilir, tüm yatırımlarını gösteren yatırımcı portföylerini alabilir ve sektörler genelindeki yatırım modellerini analiz edebilir. Bu uzmanlık, "ByteDance'e kim yatırım yaptı?" veya "Sequoia Capital başka hangi şirketlere yatırım yaptı?" gibi soruları yanıtlamayı son derece verimli hale getirir. Aracı, yatırımcılarla ilgili ilişkiler için doğrudan Neo4j veritabanını sorgulayan özel Python işlevlerini kullanır.

  1. Yatırım Araştırması Temsilcisi:

Yatırım Araştırması Asistanı, önceden doğrulanmış ve uzmanlar tarafından yazılmış sorgulara erişmek için Model Context Protocol (MCP) Araç Kutusu'ndan yararlanır. Mevcut tüm sektörleri getirebilir, belirli sektörlerdeki şirketleri alabilir, duygu analizi içeren makaleleri bulabilir, haberlerdeki kuruluşlardan bahsedilen kısımları keşfedebilir ve şirketlerde çalışan kişiler hakkında bilgi edinebilir. Sorguları dinamik olarak oluşturan Graph Database Agent'ın aksine bu aracı, merkezi olarak yönetilen ve doğrulanan güvenli, optimize edilmiş, önceden tanımlanmış sorgular kullanır. Bu sayede, yaygın araştırma iş akışları için hem güvenli hem de yüksek performanslıdır.

7. Çok Temsilcili Sistemi Çalıştırma ve Test Etme

Uygulamayı başlatma

Mimariyi anladığınıza göre şimdi sistemi tamamen çalıştıralım ve sistemle etkileşim kuralım.

ADK web arayüzünü başlatın:

# 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

Şuna benzer bir çıkış alırsınız:

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)

Sunucunun başarıyla başlatıldığını gördüğünüzde tarayıcınızı açın ve uygulamaya erişmek için http://127.0.0.1:8000 adresine gidin.

Test Sorguları ve Beklenen Davranış

Sistemin özelliklerini giderek karmaşıklaşan sorgularla keşfedelim:

Temel Sorgular (Tek Temsilci)

1. Sorgu: Sektörleri Keşfetme

What industries are available in the database?

Beklenen Davranış:

  • Root Agent, Investment Research Agent'a yönlendirir.
  • MCP aracını kullanır: get_industries()
  • Tüm sektörlerin biçimlendirilmiş bir listesini döndürür.

Gözlemlenecekler:

ADK kullanıcı arayüzünde, yürütme ayrıntılarını genişleterek şunları görebilirsiniz:

  • Aracı seçimi kararı
  • Araç çağrısı: get_industries()
  • Neo4j'den alınan işlenmemiş sonuçlar
  • Biçimlendirilmiş yanıt

2. Sorgu: Yatırımcı Bulma

Who invested in ByteDance?

Beklenen Davranış:

  • Kök temsilci, bunu yatırımcıyla ilgili bir sorgu olarak tanımlar.
  • Yatırımcı Araştırma Temsilcisi'ne yönlendirme
  • Kullanılan araç: find_investor_by_name("ByteDance")
  • Yatırımcıları türleriyle (Kişi/Kuruluş) birlikte döndürür.

Sürecin işleyiş şekli:

  • ByteDance ile ilişkili yatırımcıların listesi
  • Her yatırımcı, adı ve tüzel kişi türüyle (Şahıs veya Kuruluş) birlikte döndürülür.
  • Sonuçların kısa ve kullanıcılar tarafından okunabilir özeti
  • İlgili yatırımları veya yatırımcı portföylerini keşfetmeyi teklif eden bir takip istemi (olabilir)

3. Sorgu: Sektöre Göre Şirketler

Show me companies in the Artificial Intelligence industry

Beklenen Davranış:

  • Root Agent, Investment Research Agent'a yönlendirir.
  • MCP aracını kullanır: get_companies_in_industry("Artificial Intelligence")
  • Kimlikleri ve kuruluş tarihleriyle birlikte yapay zeka şirketlerinin listesini döndürür.

Gözlemlenecekler:

  • Aracının, sektör adını tam olarak eşleştirme yöntemini inceleyin.
  • Sonuçlar, aşırı çıktı oluşmasını önlemek için sınırlandırılır.
  • Veriler, okunabilirlik için net bir şekilde biçimlendirilir.

Orta Düzey Sorgular (Tek Aracıda Çok Adımlı)

4. Sorgu: Yaklaşım Analizi

Find articles with positive sentiment from January 2023

Beklenen Davranış:

  • Yatırım Araştırması Temsilcisi'ne yönlendirme
  • MCP aracını kullanır: get_articles_with_sentiment(0.7, 2023, 1)
  • Başlıkları, duygu puanları ve yayınlanma tarihleri olan makaleleri döndürür.

Hata Ayıklama İpucu:

Araç çağırma parametrelerine bakın:

  • min_sentiment: 0,7 (temsilci, "olumlu"yu >= 0,7 olarak yorumluyor)
  • year: 2023
  • month: 1

5. Sorgu: Karmaşık Veritabanı Sorgusu

How many companies are in the database?

Beklenen Davranış:

  • Kök temsilci, Grafik Veritabanı Temsilcisi'ne yönlendirir
  • Yapıyı anlamak için önce aracı çağrıları get_neo4j_schema()
  • Cypher oluşturur: MATCH (c:Company) RETURN count(c)
  • Sorguyu yürütür ve sayımı döndürür.

Beklenen Yanıt:

There are 46,088 companies in the database.

Gelişmiş Sorgular (Çoklu Aracı Koordinasyonu)

6. Sorgu: Portföy Analizi

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

Beklenen Davranış:

Bu, temsilci koordinasyonu gerektiren iki bölümlü bir sorgudur:

  • 1. adım: Root Agent → Investor Research Agent
  • Aramalar find_investor_by_name("ByteDance")
  • Yatırımcı listesini al: [Rong Yue, Wendi Murdoch]
  • 2. adım: Her yatırımcı için → Yatırımcı Araştırma Aracısı
  • Aramalar find_investor_by_id(investor_id)
  • Portföyün tamamını alır.
  • 3. adım: Root Agent, toplama ve biçimlendirme işlemlerini yapar

Sürecin işleyiş şekli:

  • ByteDance'e yatırım yapan yatırımcıların listesi
  • Her yatırımcı için:
  • Adı ve tüzel kişi türü (Kişi veya Kuruluş)
  • Mevcut verilere göre yatırım yaptıkları diğer şirketlerin listesi
  • Yatırımcıya göre gruplandırılmış, okunması kolay ve yapılandırılmış bir özet

Gözlemlenecekler:

  • Sırayla birden fazla araç çağrısı
  • Adımlar arasında bağlam korunur.
  • Sonuçlar akıllıca toplanır

7. Sorgu: Çok Alanlı Araştırma

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

Beklenen Davranış:

Bu karmaşık sorgu için birden fazla aracı ve araç gerekir:

  • 1. adım: Yatırım Araştırması Aracısı
  • get_companies_in_industry("Artificial Intelligence")
  • Yapay zeka şirketlerinin listesini döndürür.
  • 2. adım: Yatırım Araştırması Aracısı
  • get_articles_with_sentiment(0.8)
  • Olumlu makaleler döndürür.
  • 3. adım: Root Agent filtreleri
  • Hangi yapay zeka şirketlerinin olumlu makalelerde yer aldığını belirler.
  • İlk 5 öğeyi seçer
  • 4. adım: Yatırım Araştırması Temsilcisi
  • get_people_in_organizations([company_names], "CEO")
  • CEO bilgilerini döndürür.
  • 5. adım: Root Agent, yanıtı biçimlendirir

Sürecin işleyiş şekli:

  • Yapay zeka sektöründeki beş şirketin listesi
  • Yalnızca olumlu puan alan makalelerde görünen şirketler
  • Her şirket için:
  • Şirket adı
  • Sektör
  • CEO adı
  • Toplu veya temsili bir yaklaşım puanı

Gözlemlenecekler:

  • Farklı aracılarda birden fazla araç çağrısı
  • Veri filtreleme ve birleştirme mantığı

8. Sorgu: Rekabet Analizi

Who are YouTube's main competitors?

Beklenen Davranış:

  • Root Agent, Graph Database Agent'a yönlendirir (ilişki sorgusu).
  • Temsilci, GraphRAG ile geliştirilmiş Cypher oluşturur:
MATCH (c:Company {name: "YouTube"})-[:COMPETES_WITH]->(competitor)
RETURN competitor.name as competitor_name
  • Rakip şirketlerin listesini döndürür.

Beklenen Yanıt:

YouTube's main competitors are:

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

Bağlama Duyarlı Takip Sorguları (Context-Aware Follow-Up Queries)

9. Sorgu: Takip Sorusu (8. Sorgudan Sonra)

Which investors funded both YouTube and its competitors?

Beklenen Davranış:

  • Root Agent, önceki bağlamı (YouTube ve rakipleri) hatırlar.
  • Yatırımcı Araştırma Temsilcisi'ne yönlendirme
  • YouTube ve her rakip için yatırımcı bulur.
  • Birden fazla şirkette görünen yatırımcıları tanımlar

Sürecin işleyiş şekli:

  • Sistem, mevcut etkileşimli bağlamı (YouTube ve rakipleri) kullanır.
  • Bu rekabet ortamında birden fazla şirkete yatırım yapan yatırımcıların listesi
  • Her yatırımcı için:
  • Yatırımcı adı
  • Yatırım yaptıkları alakalı şirketlerin gruplandırılmış listesi
  • Stratejik örtüşmeyi veya kalıpları vurgulayan kısa bir yorumlayıcı özet (belki)

10. Sorgu: Araştırma Özeti

Summarize our research findings so far

Beklenen Davranış:

  • Root Agent, görüşme geçmişini inceler.
  • Önceki sorgulardaki temel bulguları sentezler.
  • Tutarlı bir özet sunar.

Sürecin işleyiş şekli:

  • Önceki sorgulardan toplanan analizlerin kısa ve iyi yapılandırılmış bir özeti
  • Temalara (sektöre genel bakış, şirket analizi, duygu, rekabet, liderlik) göre gruplandırılmış temel bulgular
  • Aşağıdakileri vurgulayan net madde işaretleri:
  • İncelenen sektörler
  • Önemli şirketler ve yatırımcılar
  • Şirketler arası yatırım kalıpları
  • Pazar duyarlılığı trendleri
  • Oturum genelinde bağlama duyarlı sentezi yansıtan tutarlı bir anlatı

Hata Ayıklama Görünümünde Temsilci Etkileşimlerini Anlama

ADK web arayüzü, ayrıntılı yürütme görünürlüğü sağlar. Aşağıdaki özelliklere dikkat edin:

  1. Etkinlik Zaman Çizelgesi

Kronolojik akışı gösterir:

[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. Araç Çağırma Ayrıntıları

Şunları görmek için herhangi bir araç çağrısını tıklayın:

  • İşlev adı
  • Giriş parametreleri
  • Döndürülen değer
  • Yürütme süresi
  • Tüm hatalar
  1. Temsilci Karar Alma (Agent Decision Making)

LLM'nin muhakemesini gözlemleyin:

  • Neden belirli bir aracı seçtiği
  • Sorguyu nasıl yorumladığı
  • Hangi araçların dikkate alındığı
  • Sonuçları neden belirli bir şekilde biçimlendirdiği

Sık Karşılaşılan Gözlemler ve Analizler

Sorgu Yönlendirme Kalıpları:

  • "Yatırımcı", "yatırım yaptı" gibi anahtar kelimeler → Yatırımcı Araştırma Aracısı
  • "Sektör", "şirketler", "makaleler" gibi anahtar kelimeler → Yatırım Araştırması Aracısı
  • Toplamalar, sayımlar, karmaşık mantık → Graph Database Agent

Performans Notları:

  • MCP araçları genellikle daha hızlıdır (önceden optimize edilmiş sorgular).
  • Karmaşık şifre oluşturma daha uzun sürer (LLM düşünme süresi).
  • Birden fazla araç çağrısı gecikmeye neden olur ancak daha zengin sonuçlar sağlar.

Hata İşleme:

Bir sorgu başarısız olursa:

  • Temsilci, neyin yanlış gittiğini açıklıyor
  • Düzeltme önerir (ör. "Şirket adı bulunamadı, yazımı kontrol edin")
  • Alternatif yaklaşımları deneyebilir.

Etkili test için ipuçları

  1. Basit Başlayın: Karmaşık sorgulardan önce her aracının temel işlevini test edin.
  2. Takip soruları kullanma: Takip sorularıyla bağlamı koruma özelliğini test etme
  3. Yönlendirmeyi İzleme: Mantığı anlamak için her sorguyu hangi temsilcinin işlediğini izleyin.
  4. Araç Çağrılarını Kontrol Etme: Parametrelerin doğal dilden doğru şekilde çıkarıldığını doğrulayın.
  5. Sınır Durumları Test Etme: Belirsiz sorguları, yazım hatalarını veya sıra dışı istekleri deneyin.

Artık tamamen işlevsel bir çoklu aracı GraphRAG sisteminiz var. Özelliklerini keşfetmek için kendi sorularınızla denemeler yapın.

8. Temizleme

Bu yayında kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:

  1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin.
  2. Proje listesinde silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
  3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.

9. Tebrikler

🎉 Tebrikler! Google'ın Agent Development Kit'ini, Neo4j'yi ve MCP Toolbox'ı kullanarak üretim kalitesinde bir çoklu aracı GraphRAG sistemini başarıyla oluşturdunuz.

ADK'nın akıllı düzenleme özelliklerini Neo4j'nin ilişki açısından zengin veri modeli ve önceden doğrulanmış MCP sorgularının güvenliğiyle birleştirerek basit veritabanı sorgularının ötesine geçen gelişmiş bir sistem oluşturdunuz. Bu sistem, bağlamı anlar, karmaşık ilişkilerdeki nedenleri değerlendirir ve kapsamlı, doğru analizler sunmak için uzmanlaşmış aracıları koordine eder.

Bu codelab'de şunları yaptınız:

✅ Google'ın Agent Development Kit'ini (ADK) kullanarak hiyerarşik düzenlemeye sahip çoklu aracı sistemi oluşturma

✅ İlişki odaklı sorgulardan ve çok adımlı akıl yürütmeden yararlanmak için entegre Neo4j grafik veritabanı

✅ Yeniden kullanılabilir araçlar olarak güvenli, önceden doğrulanmış veritabanı sorguları için MCP Toolbox'ı uyguladık.

✅ Yatırımcı araştırması, yatırım analizi ve grafik veritabanı işlemleri için uzman temsilciler oluşturdu.

✅ Sorguları otomatik olarak en uygun uzman temsilciye yönlendiren akıllı yönlendirme tasarlandı.

✅ Sorunsuz Python entegrasyonu için uygun Neo4j türü serileştirme ile karmaşık veri türleri işlendi.

✅ Aracı tasarımı, hata işleme ve sistem hata ayıklama için üretimle ilgili en iyi uygulamalar uygulandı.

Sırada ne var?

Bu çoklu aracı GraphRAG mimarisi yatırım araştırmasıyla sınırlı değildir. Aşağıdaki alanlarda da kullanılabilir:

  • Finansal hizmetler: Portföy optimizasyonu, risk değerlendirmesi, sahtekarlık tespiti
  • Sağlık hizmetleri: Hasta bakım koordinasyonu, ilaç etkileşimi analizi, klinik araştırma
  • E-ticaret: Kişiselleştirilmiş öneriler, tedarik zinciri optimizasyonu, müşteri analizleri
  • Yasal konular ve uygunluk: Sözleşme analizi, yönetmelik izleme, içtihat araştırması
  • Akademik araştırma: Edebiyat incelemesi, ortak çalışma keşfi, alıntı analizi
  • Kurumsal zeka: Rekabet analizi, pazar araştırması, kurumsal bilgi grafikleri

Karmaşık bir şekilde birbirine bağlı veriler + alan uzmanlığı + doğal dil arayüzlerinin olduğu her yerde, ADK çoklu aracı sistemleri + Neo4j bilgi grafikleri + MCP onaylı sorgular kombinasyonu, yeni nesil akıllı kurumsal uygulamalara güç verebilir.

Google'ın Agent Development Kit'i ve Gemini modelleri gelişmeye devam ettikçe daha da karmaşık akıl yürütme kalıpları, gerçek zamanlı veri entegrasyonu ve çok formatlı özellikler ekleyerek gerçekten akıllı, bağlama duyarlı sistemler oluşturabileceksiniz.

Keşfetmeye ve geliştirmeye devam edin, akıllı aracı uygulamalarınızı bir sonraki seviyeye taşıyın.

Neo4j GraphAcademy'de daha fazla uygulamalı bilgi grafiği eğitimi keşfedin ve ADK Örnekleri Deposu'nda ek aracı kalıplarını inceleyin.

🚀 Bir sonraki akıllı aracı sisteminizi oluşturmaya hazır mısınız?

Referans belgeleri