ADK Agentic Pattern with Memory & MCP

1. Öğrenecekleriniz

ADK Master Class'a hoş geldiniz: Çok Ajanlı Sistemlere Yolculuğunuz

Yapay zeka aracıların heyecan verici dünyasına adım atmak üzeresiniz. Sadece soruları yanıtlayan basit chatbot'ları unutun. Karmaşık görevleri tamamlamak için akıl yürütebilen, plan yapabilen ve araçları kullanabilen gelişmiş, otonom sistemler oluşturmak amacıyla Agent Development Kit (ADK)'nın derinliklerine iniyoruz.

Bu codelab'in tamamı uygulamalı bir yolculuk olacak. Oturumlarımızdaki tüm kodları ve örnekleri içeren 1 GitHub deposu kullanacağız. github deposu

Bu eğiticiyi tamamladığınızda:

• İlk Yapay Zeka Ajanınızı Oluşturun: Kullanıcının ihtiyaçlarını anlayabilen, Google Arama gibi araçları kullanabilen ve ayrıntılı, faydalı yanıtlar üretebilen, tamamen işlevsel bir ajan oluşturun.
• Çok Ajanlı Sistemler Oluşturma: Ajanların görevleri diğer uzmanlaşmış ajanlara devrettiği ve birlikte çalışan bir yapay zeka uzmanları ekibi oluşturduğu devrim niteliğindeki bir kavram olan "Araç Olarak Ajan" modelini öğrenin.
• Karmaşık İş Akışlarını Düzenleme: Basit görevlendirme işlemlerinin ötesine geçin ve Yönlendiriciler, Sıralı Zincirler, Döngüler ve Paralel Yürütme gibi gelişmiş kalıplarda uzmanlaşarak neredeyse tüm istekleri işleyebilen sağlam, verimli ve akıllı uygulamalar oluşturun.
• Ajanlarınıza Hafıza Verme: Sohbet hafızasının kritik rolünü anlayın. Bu sayede ajanlarınız ek soruları yanıtlayabilir, geri bildirimlerden ders çıkarabilir ve çok adımlı görevleri sorunsuz bir şekilde yönetebilir.
• MCP ile bağlanma: MCP Toolbox ile bağlanın.

Haydi, başlayalım. 🚀

2. Kurulum: API Anahtarınızı Alma

Google AI Studio API Anahtarı Kurulumu

Bu codelab tamamen ücretsiz bir Google AI Studio API anahtarıyla çalışır. Google Cloud projesi, faturalandırma hesabı veya kredi gerekmez. Memory (Oturum 6) ve MCP (Oturum 7) dahil her oturum, anahtarınıza karşı yerel olarak çalışır. Her öğrenci kendi anahtarını kullandığından API kotası kişi başına verilir ve paylaşılmaz.

İhtiyacınız olanlar:

• Python 3.9 veya sonraki sürümler (python3 --version ile kontrol edin)
• Google Hesabı (AI Studio anahtarı oluşturmak için)
• Bir terminal (yerel makineniz veya Cloud Shell)
• Yaklaşık 10 dakika

Yapay zeka temsilcilerimizi desteklemek için Google AI Studio'dan bir Gemini API anahtarı almamız gerekir. Bu, başlangıç yapmanın en hızlı yoludur.

1. adım: AI Studio'dan Gemini API anahtarınızı alın (1 dakika)

1. Yeni bir tarayıcı sekmesinde https://aistudio.google.com/app/apikey adresini açın.
2. Google hesabınızla oturum açın.
3. "Create API key" (API anahtarı oluştur) seçeneğini tıklayın (sağ üstte).
4. Proje açılır listesinin bulunduğu bir iletişim kutusu açılır:

• Daha önce oluşturulmuş bir Google projeniz varsa: Projeyi seçin ve "Mevcut projede API anahtarı oluştur"u tıklayın.
• Listede YOKSA: "Proje Oluştur"'u tıklayın.

5. Görünen API anahtarını kopyalayın. AIza... ile başlar ve yaklaşık 40 karakterdir.

✏️ Güvenli bir yere yapıştırın. Bu bilgiye aşağıdaki 4. adımda ihtiyacınız olacaktır.

API anahtarını şifre gibi kullanın. API anahtarını herkese açık sohbetlere, ekran görüntülerine yapıştırmayın veya herkese açık bir GitHub deposuna işlemeyin.

2. adım: Depoyu klonlayın (1 dakika)

👉💻 Terminalinizi (veya Cloud Shell'i) açın ve eğitim deposunu klonlayın:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

3. adım: Sanal ortamı oluşturun ve bağımlılıkları yükleyin

👉💻 .adk_env adlı bir sanal ortam oluşturup etkinleştirin, ardından bağımlılıkları yükleyin:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Terminal isteminizin başında (.adk_env) simgesini görmeniz gerekir.

4. adım: 🔥 ÖNEMLİ: API anahtarınızı ekleyin

⚠️ Bu adımı atlamayın. adk_tutorial klasörünün kökünde bir .env dosyası oluşturun. Bu tek dosya, bu codelab'deki tüm oturumları destekler. ADK Web oturumları (1-5) ile komut satırı bellek ve MCP oturumları (6-7) bu dosyayı otomatik olarak okur.

👉💻 Anahtarınızla .env dosyasını oluşturun (your_actual_api_key_here yerine 1. adımdaki anahtarı kullanın):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

~/adk_tutorial/.env hesabınızda artık şunlar olmalıdır:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 KRİTİK: your_actual_api_key_here yerine 1. adımda aldığınız gerçek API anahtarınızı girin (AIza... ile başlar).

⚠️ GOOGLE_GENAI_USE_VERTEXAI değerinin FALSE olarak ayarlandığından emin olun. Bu, ADK'ya Vertex AI yerine Google AI Studio API anahtarınızla kimlik doğrulama yapmasını söyler.

✅ Kontrol noktası: AIza... anahtarınızı içeren .env dosyanız ~/adk_tutorial/.env konumunda bulunuyor ve terminal isteminizde (.adk_env) gösteriliyor. Artık ajan oluşturmaya hazırsınız.

3. 1. Oturum: ADK Web'deki İlk Temsilciniz

Aşağıdaki komutu çalıştırarak ADK Web'i açın:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Komutları çalıştırdıktan sonra terminalinizde ADK Web Sunucusu'nun başlatıldığını belirten bir çıkış görmelisiniz. Bu çıkış şuna benzer:

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


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

👉 Ardından, ADK Dev UI'ye erişmek için tarayıcınızda http://localhost:8000 adresini açın.

Yerel olarak değil de Cloud Shell'de mi çalıştırıyorsunuz? Cloud Shell araç çubuğunda (genellikle sağ üstte) Web önizlemesi simgesini tıklayın, Bağlantı noktasını değiştir'i seçin, bağlantı noktasını 8000 olarak ayarlayın ve "Değiştir ve Önizle"'yi tıklayın. Cloud Shell, ADK Dev UI'yi yeni bir tarayıcı sekmesinde açar.

👉 Çağırma ritüeliniz tamamlandı ve temsilci çalıştırılıyor. Tarayıcınızdaki ADK Dev UI, Familiar ile doğrudan bağlantınızdır.

İlk temsilcinizi seçin: Kullanıcı arayüzünün üst kısmındaki açılır menüde a_single_agent simgesini seçin.

Buradan a_single_agent seçebilirsiniz:

İzlemeyi buradan görebilirsiniz:

👉 Test istemi:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. 2. Oturum: İş Akışı Aracısı: Sıralı Aracısı, Paralel Aracısı, Döngü Aracısı

1. oturumdaki adımları uygulayarak ADK Web kullanıcı arayüzünüzü açın.

Parallel Agent

Paralel iş akışı aracını seçin: Kullanıcı arayüzünün üst kısmındaki açılır menüden b2_parallel_agent simgesini seçin.

👉 Test istemi:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Buradan b2_parallel_agent seçebilirsiniz:

İzlemeyi buradan görebilirsiniz:

Sıralı Ajan

Sıralı iş akışı aracısını seçin: Kullanıcı arayüzünün üst kısmındaki açılır menüden b1_sequential_agent simgesini seçin.

👉 Test istemi:

Find a good sushi near Standford and tell me how to get there.

Buradan b1_sequential_agent seçebilirsiniz:

İzlemeyi buradan görebilirsiniz:

Loop Agent

Loop iş akışı aracını seçin: Kullanıcı arayüzünün üst kısmındaki açılır menüden b3_loop_agent simgesini seçin.

👉 Test istemi:

Plan a trip from Sunnyvale to San Francisco today.

Buradan b3_loop_agent seçebilirsiniz:

İzlemeyi buradan görebilirsiniz:

5. 3. Oturum: Özel Temsilci

1. oturumdaki adımları uygulayarak ADK Web kullanıcı arayüzünüzü açın.

ADK Web Kullanıcı Arayüzünüz açıldıktan sonra açılır listeden c_custom_agent simgesini seçin.

👉 Test istemi:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Buradan c_custom_agent seçebilirsiniz:

İzlemeyi buradan görebilirsiniz:

6. 4. Oturum: Düzenleyici Kalıbı - Yönlendirme Aracısı

1. oturumdaki adımları uygulayarak ADK Web kullanıcı arayüzünüzü açın.

ADK Web Kullanıcı Arayüzünüz açıldıktan sonra açılır listeden d_routing_agent simgesini seçin.

👉 Test istemi:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Buradan d_routing_agent seçebilirsiniz:

İzlemeyi buradan görebilirsiniz:

7. 5. Oturum: Araç olarak aracı

1. oturumdaki adımları uygulayarak ADK Web kullanıcı arayüzünüzü açın.

ADK Web Kullanıcı Arayüzünüz açıldıktan sonra açılır listeden e_agent_as_tool simgesini seçin.

👉 Test istemi:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Buradan e_agent_as_tool seçebilirsiniz:

İzlemeyi buradan görebilirsiniz:

8. 6. Oturum: Uzun Süreli Belleğe Sahip Ajan

Tamamen yerel olarak çalışır. Bu oturum, sohbet belleğini yerel bir SQLite veritabanında (~/.adk/ altında) depolar. Böylece tercihleriniz, yeniden başlatma işlemlerinde korunur ve Google Cloud, faturalandırma veya kredi gerekmez. Aracı, Kurulum'da oluşturduğunuz ~/adk_tutorial/.env dosyasından AI Studio anahtarınızı okur.

👉💻 Klasöre gidip koşucuyu kullanarak temsilciye güç vererek uzun süreli hafızanızı test edin:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test istemi:

I like Art and Italian food.

Ardından Ctrl+C tuşlarına basarak oturumu sonlandırın. Oturumu yeniden başlatma:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test istemi:

Plan a trip to San Francisco based on my preference.

✅ Ajan, önceki çalıştırmadan "Sanat ve İtalyan yemekleri" bilgisini hatırlamalıdır. Bu, oturumlar arasında çalışan uzun süreli bellektir.

9. 7. Oturum: Ajanınızı MCP ile destekleme

Tamamen yerel olarak çalışır. Bu oturumda, yerel bir SQLite veritabanını (destinations.db) okuyan bir yerel MCP Toolbox sunucusu başlatılır. Google Cloud, faturalandırma veya kredi gerekmez. Tek harici indirme, açık kaynaklı MCP Toolbox ikilisidir.

1. adım: Yerel veritabanını hazırlayın

👉💻 Depo kökünden örnek veritabanını oluşturun:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Bu işlem, ~/adk_tutorial/ konumunda destinations.db adlı tetikleyiciyi oluşturur.

⚠️ Örnek veritabanında yalnızca dört şehir (Paris, Roma, New York ve Tokyo) yer alır (Etkinlik türleri: Önemli nokta, Müze, Park). Diğer şehirlerden (ör. San Francisco veya Sunnyvale) bahseden istemler, bu satırlar mevcut olmadığı için doğru şekilde sonuç döndürmeyecek. Bu oturumu test ederken yukarıdaki dört şehri kullanın.

2. adım: MCP Toolbox Server'ı yükleyin ve çalıştırın

👉💻 İşletim sisteminiz için MCP Araç Kutusu ikilisini indirin:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

indirme işlemi tamamlandıktan sonra çalıştırın.

chmod +x toolbox

Hangi Mac'e sahip olduğunuzdan emin değil misiniz? uname -m çalıştırın. arm64 = Apple Silicon, x86_64 = Intel. Windows'da .../windows/amd64/toolbox.exe dosyasını indirip PowerShell'den çalıştırın.

3. Adım

Bir terminalde aşağıdaki komutu çalıştırın (çalışmaya devam etsin; aracı, http://127.0.0.1:7001 adresinde bu komuta bağlanır):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

Başka bir terminalde aşağıdaki komutu çalıştırın.

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Test istemleri (örnek veritabanında bulunan şehirleri kullanın: Paris, Roma, New York veya Tokyo):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

7. oturumda sorun giderme

• "Bağlantı reddedildi" / ajan hiçbir araç bulamıyor: İlk terminaldeki Toolbox sunucusu çalışmıyor. Sunucuyu yeniden başlatın ve 7001 numaralı bağlantı noktasında dinlediğini doğrulayın.
• Her sorgu boş sonuçlar döndürüyor: ~/adk_tutorial/destinations.db dosyasının mevcut olması için 1. Adım'ı çalıştırdığınızı ve isteminizin dört şehirden birini (Paris, Roma, New York, Tokyo) kullandığını doğrulayın.
• toolbox: cannot execute binary file macOS'te: Linux derlemesini indirdiyseniz OS=darwin/arm64 (Apple Silicon) veya OS=darwin/amd64 (Intel) ile 2. Adım'ı yeniden çalıştırın.