1. Öğrenecekleriniz
ADK Master Class'a hoş geldiniz: Çok Ajanlı Sistemlere Yolculuğunuz
Yapay zeka temsilcilerinin 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)'yı ayrıntılı bir şekilde inceliyoruz.
Bu eğiticiyi tamamladığınızda şunları yapabileceksiniz:
- İ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.
- Özel Araçlarda Uzmanlaşın: Temsilcileri kendi özel işlevlerinize ve API'lerinize bağlayarak gerçek güçlerini ortaya çıkarın. Temsilcinize, anlık hava durumu tahminleri gibi gerçek zamanlı verileri getirmeyi öğreteceksiniz.
- Ç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ı Yönetin: 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.
- Temsilcilerinize Hafıza Kazandırma: Sohbet hafızasının kritik rolünü anlayın. Bu sayede temsilcileriniz ek soruları yanıtlayabilir, geri bildirimlerden ders çıkarabilir ve çok adımlı görevleri sorunsuz bir şekilde yönetebilir.
Haydi, başlayalım. 🚀
2. Kurulum: API Anahtarınızı Alma
Google AI Studio API Anahtarı Kurulumu
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)
- Yeni bir tarayıcı sekmesinde https://aistudio.google.com/app/apikey adresini açın.
- Google hesabınızla oturum açın.
- "Create API key" (API anahtarı oluştur) seçeneğini tıklayın (sağ üstte).
- Proje açılır listesini içeren 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.
- 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: Colab not defterleri ve ADK Web kurulumu (Ek'te) için bu koda ihtiyacınız olacak.
2. adım: API anahtarınızı Colab'e ekleyin (1 dakika)
Her not defterinde, API anahtarınızı yükleyen bir kurulum hücresi bulunur. İki seçeneğiniz vardır. Tercih ettiğinizi seçin:
A seçeneği: Colab Secrets (Önerilir: Anahtar gizli kalır)
- Colab not defterinde, sol kenar çubuğundaki 🔑 anahtar simgesini tıklayın.
- "Yeni gizli anahtar ekle" seçeneğini tıklayın.
- Name'i (Ad)
GOOGLE_API_KEYolarak ayarlayın. - API anahtarınızı (1. adımda) Value (Değer) alanına yapıştırın.
- "Not defteri erişimi" anahtarını AÇIK duruma getirin.
Kurulum hücresini çalıştırdığınızda anahtar otomatik olarak alınır:
✅ API key loaded from Colab Secrets.
B seçeneği: İstendiğinde yapıştırma (hızlı ve kolay)
Colab Secrets'ı atlayıp doğrudan codelab1 ve codelab2'yi çalıştırırsanız not defterinde bir şifre alanı gösterilir:
🔑 Enter your Google AI Studio API key: ••••••••
API anahtarınızı yapıştırıp Enter tuşuna basın. Anahtar ekranda görünmez.
✅ API key entered manually.
API anahtarı hücresi çalıştırıldıktan sonraki hücre, ortamı yapılandırır:
✅ API key configured (starts with 'AIzaSy...')
✅ Using Google AI Studio (not Vertex AI).
✅ Kontrol noktası: Yukarıdaki ✅ iletilerin ikisini de not defterinde görüyorsunuz. API anahtarınız yapılandırıldı ve artık temsilci oluşturmaya hazırsınız.
3. 1. Oturum: Runner ile İlk Temsilciniz
Temel bilgilerle başlayalım. Burada, ilk basit temsilcimizi (day_trip_agent) oluşturuyoruz. Bu temsilcinin amacı, bütçe hususları da dahil olmak üzere kullanıcının isteğine göre tam günlük bir seyahat planı oluşturmaktır. Bu örnekte, ADK'daki tüm aracı etkileşimlerinin üç temel bileşeni tanıtılmaktadır:
- Aracı: İşlemin temel beynidir. Talimatları (kişiliği ve misyonu), kullandığı yapay zeka modeli (ör. Gemini) ve erişebildiği araçlarla tanımlanır.
- Oturum: Sohbetin hafızası. Etkileşim geçmişini (kullanıcı mesajları ve aracı yanıtları) saklayarak kesintisiz bir diyalog kurulmasına olanak tanır.
- Runner: Görevi yürüten motor. Aracı ve oturumu alır, yeni kullanıcı sorgusunu işler ve yanıt oluşturma adımlarını düzenler.
➡️ Not defterinde nerede bulunur?
👉 Bu, 1. Bölüm: İlk Ajanınız - Günübirlik Gezi Ajanı 🧞 altındaki hücrelere karşılık gelir.🌟
- Aracı Tanımı:
create_day_trip_agent()işlevini bulun. Ajan burada tanımlanır. Ayrıntılı talimat dizesine dikkat edin. Bu, temsilciye nasıl davranması gerektiğini söyleyen istemdir. Ayrıca, Google Arama'yı ilk aracı olarak sunuyoruz. - Yardımcı İşlev:
run_agent_query()yardımcı işlevi burada tanımlanmıştır. Sorgu çalıştırmayı basitleştirmek için bu yardımcı programı not defterinde kullanacağız. - Test çalıştırması:
run_day_trip_genie()işlevi, kullanıcının "uygun fiyatlı" ve "dinlendirici" bir günlük gezi istediğini simüle eder. Ajan, uygun yerleri bulmak ve Markdown biçimli bir seyahat planı oluşturmak için talimatlarını ve Google Arama aracını kullanır.
➡️ İşlem: day_trip_agent için talimat istemini inceleyin. Test sorgusundaki "uygun fiyatlı" gezi isteğinin, aracının "Bütçeye Uygun Olma" yönergesiyle nasıl doğrudan ilişkili olduğunu görün.
4. 2. Oturum: Özel Araçlar 🛠️
Google Arama güçlü bir araç olsa da yapay zeka temsilcilerinin gerçek potansiyeli, onları kendi benzersiz veri kaynaklarınıza, API'lerinize veya özel mantığınıza bağladığınızda ortaya çıkar. Bu bölümde, basit bir Python işlevinden özel bir araç oluşturacağız.
Bir işlev aracının en önemli kısmı docstring'idir. ADK, aracın ne yaptığını, hangi parametreleri kabul ettiğini (Args) ve ne döndürdüğünü (Returns) anlamak için docstring'i otomatik olarak ayrıştırır. Büyük dil modeli (LLM), aracı ne zaman ve nasıl kullanacağına karar vermek için bu açıklamayı okur.
➡️ Not defterinde nerede bulunur?
👉 Bu, 2.1 Basit FunctionTool: Anlık Hava Durumu API'sini Çağırma bölümündeki hücrelere karşılık gelir. 🌟
- Araç Tanımı:
get_live_weather_forecast(location: str)işlevi, özel aracımızın temelini oluşturur. Bir şehir adı alır, herkese açık Ulusal Hava Durumu Servisi API'sini çağırır ve sıcaklık ile tahmini içeren bir sözlük döndürür. - Agent Definition: weather_agent, başlatma sırasında
tools=[get_live_weather_forecast]iletilerek yeni aracımızla oluşturulur ve donatılır. Ajanın talimatlarında, açık hava etkinlikleri önermeden önce bu aracı kullanması gerektiği açıkça belirtiliyor. - Test çalıştırması: "Tahoe Gölü yakınlarında yürüyüşe gitmek istiyorum. Hava nasıl?" sorgusu, talimatları gerektirdiği için doğrudan aracının
get_live_weather_forecastaracını kullanmasını tetikliyor.
➡️ İşlem: get_live_weather_forecast işlevinin docstring'ini ve weather_agent ile ilgili talimatı okuyun. İkisi arasındaki doğrudan ilişkiye dikkat edin.
5. 3. Oturum: Araç olarak aracı 🧑🍳
Uzmanlardan oluşan bir ekip oluşturmak varken neden tek bir monolitik ajan oluşturmalısınız? Agent-as-a-Tool kalıbı, genellikle düzenleyici veya yönlendirici olarak adlandırılan birincil aracının görevleri diğer, daha odaklanmış aracılara devrettiği karmaşık sistemler oluşturmak için güçlü bir yöntemdir.
Bu kalıp, modüler ve yeniden kullanılabilir temsilciler oluşturmanıza olanak tanır. Örneğin, bir ajanınız veritabanı sorgularında, bir diğeri yaratıcı yazma konusunda uzman olabilir ve üçüncüsü de samimi bir resepsiyonist gibi davranabilir. Düzenleyicinin görevi, kullanıcının isteğini anlamak ve doğru uzmana yönlendirmektir.
➡️ Not defterinde nerede bulunur?
👉 Bu, 2.2 Araç Olarak Temsilci: Uzmana Danışma 🧑🍳 bölümündeki hücrelere karşılık gelir.🌟
Bu örnekte, gelişmiş ve çok katmanlı bir ajan sistemi oluşturuluyor:
- Uzmanlar:
- food_critic_agent: Yalnızca restoran önerileri sunan, son derece uzmanlaşmış bir aracı.
- db_agent: Otel bilgileri için bir veritabanını sorguluyormuş gibi davranan sahte bir aracı.
- concierge_agent: Kibar bir danışma görevlisi gibi davranan orta düzey bir temsilci. En önemlisi,
food_critic_agentkendi aracı olarak kullanılıyor.
- Düzenleyici (
trip_data_concierge_agent): Kullanıcının etkileşimde bulunduğu üst düzey ajandır. Talimatları sayesinde "uzman seyahat planlayıcı" olan bu ajana, diğer aracıları çağıran iki araç verilir:- call_db_agent:
db_agentişlevini çağıran bir işlev. - call_concierge_agent:
concierge_agentişlevini çağıran bir işlev.
- call_db_agent:
- Akış:
run_trip_data_concierge()içinde çalıştırılan test, tam temsilci zincirini gösterir.- Bir kullanıcı, düzenleyiciden otel ve yakındaki bir restoran hakkında bilgi istiyor.
- Orkestratörün talimatları, otel verilerini almak için önce
call_db_agentaracının kullanılmasını ister. - Ardından düzenleyici, öneri almak için
call_concierge_agentaracını kullanır. concierge_agent, isteği aldıktan sonra restoran önerisi almak için kendi aracı olanfood_critic_agent'ı kullanır.
Yemek eleştirmeninin yanıtı, kibarca biçimlendirip düzenleyiciye geri gönderen konsiyerje iletilir. Düzenleyici de yanıtı kullanıcıya sunar.
➡️ İşlem: run_trip_data_concierge() bölümündeki test çalıştırmasında yürütme akışını izleyin. TOOL CALLED çıktılarının, düzenleyiciden uzmanlara kadar olan yetki devri zincirini nasıl gösterdiğini inceleyin. Bu, sıralı bir komuta zinciridir.
6. 4. Oturum: Aracı Belleği 🧠
Gerçekten akıllı bir temsilcinin, yalnızca tek seferlik sorgulara yanıt vermenin ötesine geçmesi gerekir. Görüşmeyi hatırlaması, bağlamı anlaması ve geri bildirimlere uyum sağlaması gerekir. Bu, uygun oturum yönetimiyle sağlanır. "Döngü ajanı"nı, hafızasıyla desteklenen ve sürekli bir sohbet döngüsüne giren bir ajan olarak düşünebilirsiniz.
Aynı oturum nesnesini birden fazla sıralı sorgu için kullandığınızda aracı, görüşmenin tüm geçmişini "görebilir". Bu sayede ek soruları yanıtlayabilir, geri bildirimlere göre kendini düzeltebilir ve çok adımlı görevleri planlayabilir.
➡️ Not defterinde nerede bulunur?
👉 Bu, Bölüm 3: Hafızalı Ajan - Uyarlanabilir Planlayıcı 🗺️ altındaki hücrelere karşılık gelir. 🌟
- Agent Definition:
create_multi_day_trip_agent()işlevi, bir geziyi aşamalı olarak planlamak için tasarlanmış bir ajanı tanımlar. Talimatlarında bağlamı hatırlama, geri bildirimleri ele alma ve her günü ayrı ayrı planlama vurgulanır.
3a senaryosu: Belleği OLAN ajan (✅)
Bu test, run_adaptive_memory_demonstration() işlevinde çalıştırılır.
- Tek bir
trip_sessionoluşturulur ve üç ardışık dönüş için yeniden kullanılır. - 1. dönüş: Kullanıcı, 2 günlük bir gezi planı başlatır.
- 2. adım: Kullanıcı geri bildirimde bulunuyor ("Kaleleri pek sevmem"). Ajan, 1. dönüşün belleğine sahip olduğundan planın hangi bölümünün değiştirileceğini anlar ve alternatif bir plan sunar.
- 3. tur: Kullanıcı değişikliği onaylar ve sonraki adımı sorar. Ajan her şeyi hatırlıyor ve 2. günü planlamaya devam ediyor.
3b senaryosu: Belleği OLMAYAN aracı (❌)
Bu test, run_memory_failure_demonstration() işlevinde çalıştırılır.
Bu, oturum yönetiminin kritik önemini göstermek için kasıtlı olarak yapılan bir hatadır. Her dönüş için yeni bir oturum oluşturulur.
- 1. oturum: Kullanıcı, oturum_bir'de yolculuğu başlatır. Aracı doğru yanıt veriyor.
- 2. dönüş: Kullanıcı 2. günü planlamayı ister ancak sorgu, yeni bir session_two oturumunda gönderilir. Bu yeni oturumun geçmişi olmadığından temsilci kafası karışıyor. Hafıza kaybı var! Hangi gezi planlandığını bilmiyor.
İşlem: run_adaptive_memory_demonstration() ve run_memory_failure_demonstration()'deki temsilci yanıtlarını karşılaştırın. Not defterindeki en önemli kavram şudur: Kesintisiz bir sohbet için kesintisiz bir oturum gerekir.
7. 5. Oturum: Yönlendirici Aracısı 🚏
Tek bir temsilci belirli miktarda iş yapabilir. Gerçekten karmaşık kullanıcı istekleriyle başa çıkmak için uzman temsilcilerden oluşan bir ekibe ihtiyacımız var. Ancak belirli bir sorgu için hangi aracıyı kullanacağımızı nasıl bilebiliriz? Yönlendirici aracısı bu noktada devreye girer.
Yönlendirici aracısı, "ana" aracı veya dağıtıcı olarak görev yapar. Tek amacı, gelen kullanıcı sorgusunu analiz etmek ve iş için en uygun uzman aracıyı (veya aracı iş akışını) belirlemektir. Sorguyu yanıtlamaz, yalnızca doğru alt akış aracısına yönlendirir.
Örneğin, "en iyi suşi" ile ilgili bir sorgu foodie_agent'a, "bu hafta sonu konserleri" ile ilgili bir soru ise weekend_guide_agent tarafından ele alınmalıdır.
➡️ Not defterinde bu bilgiyi nerede bulabilirsiniz?
👉 Bu kavram, not defterinin tamamı için merkezi bir öneme sahiptir ancak ilk olarak Bölüm 1: Çoklu Ajan Kaosu - Sıralı İş Akışları 🧠→🤖→🤖 bölümünde tanıtılmaktadır. 🌟
- Ajan Tanımları: Kod hücresi, birden fazla uzmanlık alanı ajanı (day_trip_agent, foodie_agent, transportation_agent) ve en önemlisi router_agent'ı tanımlar. router_agent için talimat istemine dikkat edin. Yalnızca iş için en iyi temsilcinin adını döndürmesi açıkça belirtilmiştir.
- Yürütme Mantığı: run_sequential_app işlevi, önce bir karar (chosen_route) almak için router_agent'ı nasıl çağıracağınızı ve ardından uygun uzman aracıyı yürütmek için bu kararı bir
if/elifbloğunda nasıl kullanacağınızı gösterir.
8. 6. Oturum: SequentialAgent ⛓️
Bazı görevler, belirli bir sırayla birden fazla adımın tamamlanmasını gerektirir. Örneğin, "Palo Alto'daki en iyi suşiyi bul ve oraya nasıl gideceğimi söyle." Bu iki adımlı bir işlemdir: Önce restoranı bulmanız, ardından yol tarifi almanız gerekir.
ADK, SequentialAgent ile bunu yönetmek için temiz ve güçlü bir yol sağlar. Bu, önceden tanımlanmış bir sırada bir alt ajan listesini yürüten özel bir iş akışı aracısıdır.
İşin sırrı, paylaşılan durumda yatar. Sıradaki bir aracının çıktısı, paylaşılan bir durum sözlüğüne otomatik olarak kaydedilebilir ve ardından bir sonraki aracı için giriş olarak kullanılabilir. Bu sayede, adımlar arasında bilgi aktarmak için karmaşık manuel kod yazma ihtiyacı ortadan kalkar.
➡️ Not defterinde bu bilgiyi nerede bulabilirsiniz?
👉 Bu konu, Bölüm 2 (ADK Yöntemi): SequentialAgent ile Çoklu Aracı Kaosu 🧠→⛓️→🤖 başlıklı makalede ele alınmaktadır. 🌟
- Aracı Yeniden Düzenleme: Bu bölümün ilk kod hücresinde,
foodie_agentvetransportation_agentile ilgili önemli değişiklikleri inceleyin:foodie_agentartıkoutput_key="destination"sahibi. Bu, ADK'ya son yanıtını paylaşılan durumdakidestinationadlı bir değişkene kaydetmesini söyler.transportation_agentartık talimat isteminde{destination}yer tutucusunu içeriyor. ADK, paylaşılan durumdaki değeri otomatik olarak bu yer tutucuya yerleştirir.
- İş Akışını Tanımlama:
find_and_navigate_agent, SequentialAgent olarak tanımlanır ve sub_agents'ı [foodie_agent,transportation_agent] olarak ayarlanır. Bu sayede, alt aracılar tam olarak bu sırayla çalışır. - Basitleştirilmiş Yürütme: Bu bölümdeki
run_sequential_appişlevine bakın. Karmaşıkif/elifmantığı artık yok.find_and_navigate_agentartık tek bir çağrılabilir birim olarak kabul ediliyor ve ADK, dahili sıralı adımları otomatik olarak işliyor.
9. 7. Oturum: LoopAgent 🔁
Her sorunun basit ve tek seferlik bir çözümü yoktur. Bazen bir çözüm önerip eleştirmemiz ve belirli bir kısıtlamayı karşılayana kadar iyileştirmemiz gerekir.
ADK, bu amaçla LoopAgent sunar. Bu iş akışı aracısı, belirli bir koşul karşılanana kadar bir dizi alt aracıyı tekrar tekrar çalıştırır. Bu, kendi çalışmalarını planlayabilen, eleştirebilen ve iyileştirebilen "mükemmeliyetçi" temsilciler oluşturmak için idealdir.
Şemada önce Planner Agent plan oluşturma gösterilmektedir. Ardından LoopAgent aracına biniyoruz. Critic Agent planı kontrol eder. Kusurluysa Refiner Agent yeni bir sürüm oluşturur ve döngü tekrarlanır. Plan iyi ise Refiner Agent, exit_loop aracını çağırır ve son, doğrulanmış plan döndürülür.
➡️ Not defterinde bu bilgiyi nerede bulabilirsiniz?
👉 Bu durum, LoopAgent ile yinelemeli fikirler 🧠→🔁→🤖 başlıklı makalede açıklanmaktadır. 🌟
- Temel Ajanlar: İş akışında
planner_agent,critic_agentverefiner_agentkullanılır. - Loop Tanımı:
refinement_loop,critic_agent,refiner_agentvesets max_iterations=3'ı düzenleyen bir LoopAgent olarak tanımlanır. - Çıkış koşulu:
critic_agent, planı onayladığında döngü sonlanır verefiner_agent, özelexit_looparacını çağırır.
10. 8. Oturum: ParallelAgent ⚡️
Verimlilik önemlidir. Kullanıcı aynı anda birbiriyle alakasız birden fazla bilgi isterse bu aramaları tek tek yapmak yavaş olur.
ParallelAgent çözümüdür. Bu iş akışı aracısı, bir alt aracılar listesini eşzamanlı olarak yürütür. Tüm paralel görevler tamamlandıktan sonra sonuçları toplanıp tek ve kapsamlı bir yanıtta sentezlenebilir.
Bu diyagramda, ParallelAgent tek bir sorgu alıp işi üç eşzamanlı parçaya ayırıyor. museum_finder, concert_finder ve restaurant_finder aynı anda çalışır. Üç görev de tamamlandıktan sonra, her birinin sonuçları (paylaşılan duruma kaydedilir) birleştirilir ve nihai Synthesis Agent'a iletilir. Bu sonuçlar, tek bir yanıt halinde birleştirilir.
➡️ Not defterinde bu bilgiyi nerede bulabilirsiniz?
👉 Bu iş akışı, ParallelAgent ile Paralel Güç 🧠→⚡️→🤖🤖🤖 bölümünde ayrıntılı olarak açıklanmaktadır. 🌟
- Uzman aracıları: Her biri benzersiz bir output_key'e (ör. museum_result) sahip üç uzman aracı tanımlanır.
- Paralel İş Akışı: parallel_research_agent, ParallelAgent olarak tanımlanır ve üç bulma aracısı, alt aracısı olarak listelenir.
- Sentez adımı: Paralel adımdan sonra nihai bir synthesis_agent, yer tutucuları (
{museum_result},{concert_result}vb.) kullanarak paylaşılan durumdaki tüm bulguları toplar ve düzenli bir özet oluşturur.
11. Ek: ADK Web - 🍎 Mac/Linux için
Bu kılavuzda, ADK Day Trip Planning Agent'ı yerel makinenizde ayarlama ve çalıştırma adımları açıklanmaktadır.
Ön koşullar
- Python 3.8 veya sonraki sürümler
- Python 3.9 veya sonraki sürümler: google-adk==1.5.0 (tam özellikli en son sürüm) yüklenir.
- Python 3.8: google-adk==0.3.0 (uyumlu sürüm) yüklenir.
- Google AI Studio API anahtarı (yukarıdaki Kurulum adımından)
- İnternet bağlantısı
1. adım: Depoyu klonlayın
Terminal'i açıp şu komutu çalıştırın:
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
2. adım: Sanal ortamı ayarlayın ve bağımlılıkları yükleyin
A seçeneği: Otomatik kurulum (önerilir)
# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh
B seçeneği: Manuel kurulum
# Create virtual environment
python3 -m venv .adk_env
# Activate virtual environment
source .adk_env/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
3. adım: 🔥 ÖNEMLİ - Ortam değişkenleri oluşturun
⚠️ Bu adımı atlamayın. agent/ dizininde bir .env dosyası oluşturun:
# Create the .env file
touch agent/.env
# Open it in your default text editor
open agent/.env
Dosyaya şu satırları ekleyin:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 KRİTİK: your_actual_api_key_here yerine Kurulum: API Anahtarınızı Alma adımındaki gerçek API anahtarınızı girin.
4. adım: Sanal ortamı etkinleştirin (henüz etkin değilse)
source .adk_env/bin/activate
Terminal isteminizin başında (.adk_env) simgesini görmeniz gerekir.
5. adım: ADK web arayüzünü çalıştırın
adk web
6. adım: Tarayıcınızı açın
- Tarayıcınızı açıp terminalde gösterilen URL'ye (genellikle
http://localhost:8000) gidin. - Sol üstteki açılır listede
agentsimgesini seçin. - Günübirlik gezi planlama temsilcinizle sohbet etmeye başlayın.
Şuna benzer bir etkileşim görürsünüz: 
Ortamı devre dışı bırakma
Projeyle çalışmayı bitirdiğinizde:
deactivate
Bu komut, hem Mac/Linux hem de Windows'da aynı şekilde çalışır. (.adk_env) önekini terminal isteminizden kaldırıldığını görürsünüz.
Mac'te Sorun Giderme
- Python bulunamadı:
pythonyerinepython3kullanın. - İzin reddedildi: Komut dosyasını çalıştırmadan önce
chmod +x setup_venv.shkomutunu çalıştırın.
12. Ek: ADK Web - 🪟 Windows Kullanıcıları İçin
Bu kılavuzda, ADK Day Trip Planning Agent'ı yerel makinenizde ayarlama ve çalıştırma adımları açıklanmaktadır.
Ön koşullar
- Python 3.8 veya sonraki sürümler
- Python 3.9 veya sonraki sürümler: google-adk==1.5.0 (tam özellikli en son sürüm) yüklenir.
- Python 3.8: google-adk==0.3.0 (uyumlu sürüm) yüklenir.
- Google AI Studio API anahtarı (yukarıdaki Kurulum adımından)
- İnternet bağlantısı
1. adım: Depoyu klonlayın
Komut İstemi'ni veya PowerShell'i açıp şu komutu çalıştırın:
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
2. adım: Sanal ortamı ayarlayın ve bağımlılıkları yükleyin
A seçeneği: Otomatik kurulum (önerilir)
# Run the setup script in Command Prompt
setup_venv.bat
B seçeneği: Manuel kurulum
Komut istemi için:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
PowerShell için:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\Activate.ps1
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
3. adım: 🔥 ÖNEMLİ - Ortam değişkenleri oluşturun
⚠️ Bu adımı atlamayın. agent/ dizininde bir .env dosyası oluşturun:
# Create the .env file
type nul > agent\.env
# Open it in Notepad
notepad agent\.env
Dosyaya şu satırları ekleyin:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 KRİTİK: your_actual_api_key_here yerine Kurulum: API Anahtarınızı Alma adımındaki gerçek API anahtarınızı girin.
4. adım: Sanal ortamı etkinleştirin (henüz etkin değilse)
Komut istemi:
.adk_env\Scripts\activate
PowerShell:
.adk_env\Scripts\Activate.ps1
İsteminizin başında (.adk_env) simgesini görmelisiniz.
5. adım: ADK web arayüzünü çalıştırın
adk web
6. adım: Tarayıcınızı açın
- Tarayıcınızı açıp terminalde gösterilen URL'ye (genellikle
http://localhost:8000) gidin. - Sol üstteki açılır listede
agentsimgesini seçin. - Günübirlik gezi planlama temsilcinizle sohbet etmeye başlayın.
Windows Sorun Giderme
- PowerShell yürütme politikası hatası:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserkomutunu çalıştırın.
Şuna benzer bir etkileşim görürsünüz:
Ortamı devre dışı bırakma
Projeyle çalışmayı bitirdiğinizde:
deactivate
Bu komut, hem Mac/Linux hem de Windows'da aynı şekilde çalışır. (.adk_env) önekini terminal isteminizden kaldırıldığını görürsünüz.