1. Başlamadan önce
"ADK ile Yapay Zeka Temsilcileri Oluşturma" serisinin ilk bölümüne hoş geldiniz. Bu uygulamalı codelab serisinde, Google'ın Agent Development Kit'ini (ADK) kullanarak kendi akıllı yapay zeka aracınızı oluşturacağınız heyecan verici bir yolculuğa çıkacaksınız.
Geliştirme ortamınızı ayarlama ve temel bir sohbet aracısı oluşturma konusunda size yol göstererek en temel bilgilerle başlayacağız. Bu codelab'in sonunda, ilk etkileşimli yapay zekanızı oluşturmuş olacaksınız. Bu yapay zeka, bu serinin sonraki bölümlerinde çoklu aracı sistemine (MAS) dönüştürülürken geliştirilmeye hazır olacak.
Bu codelab'i yerel ortamınızda veya Google Cloud'da tamamlayabilirsiniz. En tutarlı deneyim için Google Cloud ortamındaki Cloud Shell'i kullanmanızı öneririz. Cloud Shell, $HOME dizininde 5 GB kalıcı depolama alanı da sağlar. Bu, komut dosyalarını, yapılandırma dosyalarını veya klonlanmış depoları depolamak için kullanışlıdır.
Ön koşullar
- Üretken yapay zeka kavramları hakkında bilgi sahibi olmak
- Python programlama konusunda temel düzeyde yeterlilik
- Komut satırı / terminal hakkında bilgi sahibi olma
Neler öğreneceksiniz?
- Python ortamı oluşturma
- ADK'yı kullanarak basit bir kişisel asistan aracısı oluşturma
- Aracıyı çalıştırma, test etme ve hata ayıklama
Gerekenler
- Çalışan bir bilgisayar ve güvenilir kablosuz bağlantı
- Google Cloud Console'a erişmek için Chrome gibi bir tarayıcı
- Faturalandırmanın etkin olduğu bir Google Cloud projesi
- Meraklı bir zihin ve öğrenme isteği
2. Giriş
Üretken yapay zeka dünyası hızla gelişiyor ve yapay zeka aracıları şu anda popüler bir konu. Yapay zeka aracısı, kişisel asistan gibi sizin adınıza hareket etmek üzere tasarlanmış akıllı bir bilgisayar programıdır. Dijital ortamını algılayabilir, kararlar verebilir ve doğrudan insan kontrolü olmadan belirli hedeflere ulaşmak için eylemlerde bulunabilir. Bunu, işleri halletmek için öğrenebilen ve uyum sağlayabilen proaktif, bağımsız bir varlık olarak düşünebilirsiniz.
Bir yapay zeka aracısı, temel olarak anlamak ve akıl yürütmek için "beyin" olarak büyük bir dil modelini (LLM) kullanır. Bu sayede metin, resim ve ses gibi çeşitli kaynaklardan gelen bilgileri işleyebilir. Ardından, bu anlayışı kullanarak bir plan oluşturur ve önceden tanımlanmış bir hedefe ulaşmak için bir dizi görevi yerine getirir.
Artık Agent Development Kit (ADK) gibi kullanıma hazır çerçeveler sayesinde derin bir uzmanlığa sahip olmasanız bile kendi yapay zeka aracılarınızı kolayca oluşturabilirsiniz. Bu yolculuğa, görevlerinizde size yardımcı olacak kişisel asistan aracısı oluşturarak başlayacağız. Başlayalım!
3. Google Cloud Hizmetlerini Yapılandırma
Deneme Faturalandırma Hesabını Kullanma
Google Cloud hizmetlerini kullanmak için etkin bir faturalandırma hesabınızın olması gerekir. Henüz bir faturalandırma hesabınız yoksa bu codelab'i tamamlayabilmeniz için size deneme faturalandırma hesabı sağladık.
Faturalandırma hesabını kullanmak için aşağıdaki adımları uygulayın:
- Bu ödül alma portalına gidin.
- Kişisel Gmail hesabınızı kullanarak giriş yapın.
- Adım adım talimatları uygulayın.
Faturalandırma hesabını kullanıp projeyi başarıyla oluşturabilirseniz Cloud Shell'i yapılandırma bölümüne geçebilirsiniz.
Sağlanan deneme faturalandırma hesabını zaten kullandıysanız yeni bir faturalandırma hesabı oluşturmanız gerekir. Bu işlemi yapmak için aşağıdaki talimatları uygulayabilirsiniz:
Google Cloud projesi seçme veya oluşturma
- Google Cloud Console'a gidin.
- En üstte, proje seçici açılır listesini (Google Cloud logosunun yanında) tıklayın.
- Mevcut bir projeyi seçin veya yeni bir proje oluşturun.
Projeniz İçin Faturalandırmayı Etkinleştirme
- Projenizde faturalandırmayı etkinleştirmek için Google Cloud Faturalandırma belgelerindeki talimatları uygulayın.
Cloud Shell'i yapılandırma
Şimdi de doğrudan Google Cloud Console'da yer alan kullanışlı bir komut satırı arayüzü olan Cloud Shell'de doğru şekilde ayarlandığınızdan emin olalım.
Cloud Shell'i başlatma
Google Cloud Console'unuzun sağ üst köşesinde terminale benzeyen bir simge (>_) görürsünüz. Cloud Shell'i etkinleştirmek için bu simgeyi tıklayın.
Erişim Yetkisi Ver
İstenirse Cloud Shell'e Google Cloud projenizle etkileşim kurması için gerekli izinleri vermek üzere Yetkilendir'i tıklayın.
Hesabınızı doğrulama:
Cloud Shell yüklendikten sonra doğru Google Cloud hesabını kullandığınızı onaylayalım. Aşağıdaki komutu çalıştırın:
gcloud auth list
Terminalde benzer bir komut çıkışı görmeniz gerekir:
Credentialed Accounts
ACTIVE: *
ACCOUNT: current_account@example.com
To set the active account, run:
$ gcloud config set account `ACCOUNT`
Hesapları Değiştirme (Gerekirse):
Etkin hesap doğru değilse your_username@example.com yerine gerçek e-posta adresinizi girerek aşağıdaki komutu kullanarak doğru hesaba geçin:
gcloud config set account your_username@example.com
Projenizi Onaylama
Ardından, Cloud Shell'in doğru Google Cloud projesini kullanacak şekilde yapılandırıldığını doğrulayalım. Çalıştır:
gcloud config list project
Yapılandırma listesini görürsünüz. [core] bölümünü bulun ve proje değerinin, bu Codelab için kullanmak istediğiniz Google Cloud projesinin kimliğiyle eşleştiğinden emin olun:
[core] project = <current-project-id>
Projenizi ayarlama (gerekirse)
project ID değeri yanlışsa aşağıdaki komutu kullanarak istediğiniz projeye ayarlayın:
gcloud config set project <your-desired-project-id>
Gerekli API'leri etkinleştirme
Google Cloud hizmetlerini kullanmak için önce projenizde ilgili API'leri etkinleştirmeniz gerekir. Cloud Shell terminalinde aşağıdaki komutları çalıştırarak bu Codelab için ihtiyacınız olacak tüm hizmetleri etkinleştirebilirsiniz:
gcloud services enable aiplatform.googleapis.com
İşlem başarılı olursa terminalinizde Operation/... finished successfully ifadesi gösterilir.
4. Python sanal ortamı oluşturun
Herhangi bir Python projesine başlamadan önce sanal ortam oluşturmak iyi bir uygulamadır. Bu, projenin bağımlılıklarını yalıtarak diğer projelerle veya sistemin genel Python paketleriyle çakışmaları önler. Agent Development Kit (ADK) için Python 3.9 veya daha yeni bir sürüm gerektiğinden hem sanal ortamı yönetmek hem de doğru Python sürümünün kullanılmasını sağlamak için uv gibi bir araç kullanacağız.
uv, Python projelerini ve ortamlarını yönetmek için modern, hızlı ve verimli bir araçtır. Geleneksel olarak pip, venv, pip-tools ve pipx gibi araçlarda bulunan işlevleri birleştirir. Hızlı olması için Rust ile yazılmıştır.
Cloud Shell'de uv zaten mevcut olduğundan hemen başlayabiliriz. Terminalde aşağıdaki komutları satır satır çalıştırın.
uv'nin doğru şekilde yüklenip yüklenmediğini doğrulayın
uv --version
Temsilciniz için yeni bir proje klasörü oluşturma
uv init ai-agents-adk
Proje klasörüne gitme
cd ai-agents-adk
Python 3.12 ile sanal ortam oluşturma
uv venv --python 3.12
Google ADK kitaplığını sanal ortamınıza yükleyin
uv add google-adk
google-adk paketini başarıyla yükleyip yüklemediğinizi kontrol edin
uv pip list | grep google-adk
google-adk ve sürümünü içeren bir çıkış satırı görüyorsanız bir sonraki adıma geçebilirsiniz.
5. Temsilci oluşturun
Geliştirme ortamınız ayarlanıp hazır hâle geldiğine göre artık yapay zeka temsilcinizin temelini oluşturabilirsiniz. Aracı Geliştirme Kiti (ADK), bu süreci basitleştirerek aracınızın temel mantığını ve yapılandırmasını tanımlamak için yalnızca birkaç temel dosya gerektirir.
Bu üç dosya, aracınızın bulunabilir, çalıştırılabilir ve yapılandırılabilir olması için birlikte çalışır:
agent.py: Bu, temsilcinizin kalbidir. Bu dosya, aracınızın davranışını tanımlayan birincil Python kodunu içerir. Bu kod, aracınızın adını,"beyin" olarak kullandığı büyük dil modelini (LLM) ve yanıtlarını yönlendiren temel talimatları içerir.__init__.py: Python'da__init__.pydosyası, bir dizini Python paketi olarak işaretler. ADK için bu çok önemlidir. Çünkü bu, çerçeveninagent.pykonumundaki aracı tanımınızı keşfetmesine ve yüklemesine yardımcı olur. Basit ADK projelerinde, genellikleagentmodülünüzü içe aktarmak için tek bir satır içerir. Bu sayede, temsilciniz ADK çalıştırıcısına erişebilir..env: Bu dosya ("ortam"ın kısaltması) API anahtarları, proje kimlikleri ve coğrafi konumlar gibi aracılarınızın ihtiyaç duyduğu hassas bilgileri ve yapılandırma değişkenlerini depolamak için kullanılır. Bu ayrıntıları ayrı bir.envdosyada tutmak, hassas verilerin doğrudan kodunuza yerleştirilmesini önlediği için güvenlik ve taşınabilirlik açısından en iyi uygulamadır. Ayrıca, ana aracı mantığınızı değiştirmeden yapılandırmaları kolayca değiştirmenize olanak tanır.
Bu dosyaları kişisel asistan aracınız için ayrılmış bir klasörde oluşturmak üzere aşağıdaki komutları kullanın:
uv run adk create personal_assistant
Komut yürütüldükten sonra, aracınızı yapılandırmak için birkaç seçenek belirlemeniz istenir. İlk adımda, gemini-2.5-flash modelini kullanmak için 1. seçeneği belirleyin. Bu model, sohbet görevleri için ideal olan hızlı ve verimli bir modeldir.
Choose a model for the root agent: 1. gemini-2.5-flash 2. Other models (fill later) Choose model (1, 2): 1
İkinci adımda, arka uç hizmet sağlayıcı olarak Google Cloud'un güçlü ve yönetilen yapay zeka platformu Vertex AI'ı (2. seçenek) seçin.
1. Google AI 2. Vertex AI Choose a backend (1, 2): 2
Ardından, parantez [...] içinde gösterilen proje kimliğinin doğru olduğunu doğrulamanız gerekir. Bu durumda Enter tuşuna basmanız yeterlidir. Doğru değilse buraya doğru proje kimliğini girin.
Enter Google Cloud project ID [project-id]:
Son olarak, köşeli parantezlerin [...] içinde gösterilen proje bölgesinin doğru olduğunu doğrulamanız gerekir. Bu durumda Enter tuşuna basmanız yeterlidir. Aksi takdirde, kullanılabilir Google Cloud bölgeleri için bu belgelere bakın ve doğru olanı girin.
Enter Google Cloud region [project-region]:
Terminalinizde benzer bir çıkış görmeniz gerekir.
Agent created in /home/<your-username>/ai-agent-adk/personal_assistant: - .env - __init__.py - agent.py
Şimdi Cloud Shell pencerenizin üst kısmındaki Open Editor (Düzenleyiciyi Aç) düğmesini tıklayın. Bu düğmeyi tıkladığınızda Düzenleyici penceresine yönlendirilirsiniz. Bu pencerede dosyalarınızın içeriğini çok daha kolay bir şekilde keşfedebilirsiniz.
Geçiş işlemi biraz zaman alabilir. Birkaç dakikadan uzun süre yükleme ekranında kalırsanız tarayıcınızı yenilemeyi deneyin.
Düzenleyici penceresi tamamen yüklendikten sonra personal-assistant klasörüne gidin. Yukarıda belirtilen gerekli dosyaları (agent.py, __init__.py ve .env) görürsünüz. İçeriği inceleyelim.
Klasörde .env dosyasını görmüyorsanız üstteki menü çubuğuna gidin, Görünüm'ü tıklayın ve Gizli Dosyaları Aç/Kapat'ı seçin. .env dosyaları, yanlışlıkla gösterilmelerini önlemek için genellikle varsayılan olarak gizlendiğinden bu ayar yaygın olarak kullanılır.
Her dosyanın içeriğini inceleyelim.
agent.py
Bu dosya, google.adk.agents kitaplığındaki Agent sınıfını kullanarak aracınızı oluşturur.
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
from google.adk.agents import Agent: Bu satır, ADK kitaplığından gerekliAgentsınıfını içe aktarır.root_agent = Agent(...): Burada, yapay zeka temsilcinizin bir örneğini oluşturuyorsunuz.name="root_agent": Aracınızın benzersiz tanımlayıcısı. ADK, temsilcinizi bu şekilde tanır ve ona bu şekilde atıfta bulunur.model="gemini-2.5-flash": Bu önemli parametre, aracınızın anlama, akıl yürütme ve yanıt oluşturma için temel "beyin" olarak hangi büyük dil modelini (LLM) kullanacağını belirtir.gemini-2.5-flash, sohbet görevleri için uygun olan hızlı ve verimli bir modeldir.description="...": Bu, aracının amacının veya özelliklerinin kısa bir özetini sağlar. Açıklama, daha çok insanların anlaması veya çoklu temsilci sistemindeki diğer temsilcilerin bu temsilcinin ne yaptığını anlaması için kullanılır. Genellikle günlük kaydı, hata ayıklama veya aracıyla ilgili bilgileri gösterme için kullanılır.instruction="...": Bu, aracınızın davranışını yönlendiren ve kişiliğini tanımlayan sistem istemidir. Bu talimat, LLM'ye nasıl davranması gerektiğini ve asıl amacının ne olduğunu söyler. Bu örnekte, aracı "faydalı bir asistan" olarak tanımlar. Bu talimat, aracının sohbet tarzını ve yeteneklerini şekillendirmek için çok önemlidir.
init.py
Bu dosya, Python'ın personal-assistant dosyasını paket olarak tanıması için gereklidir. Böylece ADK, agent.py dosyanızı doğru şekilde içe aktarabilir.
from . import agent
from . import agent: Bu satır, göreli bir içe aktarma işlemi gerçekleştirerek Python'a geçerli paket (personal-assistant) içindeagentadlı bir modül (agent.py'ye karşılık gelir) aramasını söyler. Bu basit satır, ADK'nınpersonal-assistantaracınızı yüklemeye çalıştığındaagent.pyiçinde tanımlananroot_agent'yi bulup başlatabilmesini sağlar. Boş olsa bile, dizinin Python paketi olmasını sağlayan__init__.pydosyasıdır.
.env
Bu dosya, ortama özel yapılandırmaları ve hassas kimlik bilgilerini içerir.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
GOOGLE_GENAI_USE_VERTEXAI: Bu, ADK'ya üretken yapay zeka işlemleriniz için Google'ın Vertex AI hizmetini kullanmayı planladığınızı bildirir. Bu, Google Cloud'un yönetilen hizmetlerinden ve gelişmiş modellerinden yararlanmak için önemlidir.GOOGLE_CLOUD_PROJECT: Bu değişken, Google Cloud projenizin benzersiz tanımlayıcısını tutar. ADK, aracınızı bulut kaynaklarınızla doğru şekilde ilişkilendirmek ve faturalandırmayı etkinleştirmek için bu bilgiye ihtiyaç duyar.GOOGLE_CLOUD_LOCATION: Bu, Vertex AI kaynaklarınızın bulunduğu Google Cloud bölgesini belirtir (ör.us-central1). Doğru konumu kullanmak, aracınızın o bölgedeki Vertex AI hizmetleriyle etkili bir şekilde iletişim kurmasını sağlar.
6. Terminalde aracıyı çalıştırma
Üç dosya da yerinde olduğunda aracıyı doğrudan terminalden çalıştırmaya hazırsınız demektir. Bunu yapmak için Terminal penceresini açmanız gerekir. Menü çubuğunda Terminal'i tıklayıp Yeni Terminal'i seçmeniz yeterlidir.
Terminal kullanıma sunulduktan sonra adk run komutunu kullanarak aracıyı başlatabilirsiniz. Bu yeni bir terminal penceresi olduğundan ve uv kullandığımızdan önce ai-agent-adk klasörüne gitmeniz, ardından adk run komutunun başına uv run eklemeniz gerekir.
Terminale şu komutları yazın:
cd ai-agents-adk
uv run adk run personal_assistant
Her şey doğru şekilde ayarlanmışsa terminalinizde benzer bir çıktı görürsünüz.
... Running agent personal_assistant, type exit to exit. [user]: hello. What can you do for me? [personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as: ...
Temsilciyle sohbet etmeye başlayabilirsiniz. Çıktının bazen Markdown ile biçimlendirildiğini fark edebilirsiniz. Bu biçimlendirme, terminalde okunmayı zorlaştırabilir. Bir sonraki adımda, çok daha zengin ve sohbet uygulamasına benzer bir deneyim için Geliştirme kullanıcı arayüzünü kullanacağız.
7. Temsilciyi geliştirme web kullanıcı arayüzünde çalıştırma
Aracı Geliştirme Kiti, geliştirme kullanıcı arayüzünü kullanarak aracınızı sohbet uygulaması olarak başlatmanın kolay bir yolunu da sunar. adk run. yerine adk web komutunu kullanmanız yeterlidir.
Önceki oturumdaysanız kapatmak için terminale exit yazmanız yeterlidir. Önceki oturum kapatıldıktan sonra terminale aşağıdaki komutu yazın:
uv run adk web
Terminalde benzer bir çıkış görmeniz gerekir:
... INFO: Started server process [4978] INFO: Waiting for application startup. +------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Geliştirme kullanıcı arayüzüne erişmek için iki seçeneğiniz vardır:
- Terminal üzerinden açma
- Bağlantıyı Ctrl + tıklayın veya Cmd + tıklayın (ör.
http://localhost:8000) terminalde gösterildiği gibi.
- Web Önizlemesi ile açma
- Web Önizlemesi düğmesini tıklayın.
- Bağlantı Noktasını Değiştir'i seçin.
- Bağlantı noktası numarasını girin (ör. 8000)
- Değiştir ve Önizle'yi tıklayın.
Ardından, tarayıcınızda sohbet uygulamasına benzer bir kullanıcı arayüzü görünür. Bu arayüzü kullanarak kişisel asistanınızla sohbet edebilirsiniz. Markdown biçimlendirmesinin artık doğru şekilde görüntülendiğini fark edeceksiniz. Bu kullanıcı arayüzü, her mesajlaşma etkinliğini, temsilcinin durumunu, kullanıcı isteklerini ve daha fazlasını hata ayıklamanıza ve incelemenize de olanak tanır. Keyifli sohbetler!
8. Temizleme (isteğe bağlı)
Bu codelab'de uzun süren ürünler yer almadığından, terminalde Ctrl + C veya Cmd + C tuşlarına basarak etkin aracı oturumlarınızı (ör. terminalinizdeki adk web örneği) durdurmanız yeterlidir.
Aracı Proje Klasörlerini ve Dosyalarını Silme
Yalnızca kodu Cloud Shell ortamınızdan kaldırmak istiyorsanız aşağıdaki komutları kullanın:
cd ~
rm -rf ai-agents-adk
Vertex AI API'yi devre dışı bırakma
Daha önce etkinleştirilen Vertex AI API'yi devre dışı bırakmak için şu komutu çalıştırın:
gcloud services disable aiplatform.googleapis.com
Google Cloud projesinin tamamını kapatma
Google Cloud projenizi tamamen kapatmak istiyorsanız ayrıntılı talimatlar için resmi kılavuza bakın.
9. Sonuç
Tebrikler! Aracı Geliştirme Kitini (ADK) kullanarak basit bir kişisel asistan aracısı oluşturmayı başardınız. Artık bir ADK aracısının temel bileşenleri hakkında sağlam bir temel ve anlayışa sahipsiniz.
Bir sonraki adım olarak, aracınıza gerçek zamanlı bilgilere erişme ve harici hizmetlerle etkileşim kurma araçları vererek yeteneklerini önemli ölçüde genişletebilirsiniz. Yolculuğunuza devam etmek istiyorsanız bu serideki bir sonraki codelab olan ADK ile Yapay Zeka Aracı Geliştirme: Araçlarla Güçlendirme, bu süreçte size rehberlik edecektir.