ADK ile Yapay Zeka Ajanları Geliştirme: Temel

1. Genel Bakış

Yapay zeka ajanı, büyük dil modelini (LLM) talimatlar, durum ve araçlarla birleştirerek kullanıcı istekleri üzerinde akıl yürütebilir ve çok adımlı görevleri otonom olarak yürütebilir. Yapılandırılmış bir temsilci çerçevesi olmadığında geliştiriciler, tek bir istemi test etmeden önce model istemcilerini, ortam yapılandırmasını, görüşme oturumlarını ve yerel hata ayıklama arayüzlerini manuel olarak bağlamak zorunda kalır.

ADK ile Yapay Zeka Ajanları Oluşturma serisinin bu ilk bölümünde, Google Cloud'da bir Python geliştirme ortamı oluşturacak ve Agent Development Kit (ADK 2) ile gemini-3.8-flash kullanarak Agent Platform'da bir personal_assistant yapay zeka ajanı oluşturacaksınız. Oluşturulan temsilci paketini inceler ve temsilcinizi hem etkileşimli terminal CLI (adk run) hem de tarayıcı tabanlı ADK Web Kullanıcı Arayüzü (adk web) üzerinden test edersiniz. Bu codelab'i doğrudan goo.gle/adk-foundation adresinden de açabilirsiniz.

ADK ile Yapay Zeka Ajanları Oluşturma Serisi: Bu temel laboratuvarı tamamladıktan sonra Araçlarla Güçlendirme, Temsilci İş Akışlarını Yönetme ve Grafik İş Akışlarını Yönetme ile devam edin.

Ön koşullar

• Üretken yapay zeka kavramlarını anlama
• Python programlama konusunda temel düzeyde yeterlilik
• Komut satırı/terminal ve gcloud KSA hakkında bilgi sahibi olma

Öğrenecekleriniz

• Google Cloud Shell'i ve uv ile izole bir Python 3.12 ortamını yapılandırma
• Agent Platform'da gemini-3.8-flash tarafından desteklenen başlangıç seviyesindeki bir ADK 2 temsilci paketi nasıl oluşturulur?
• ADK 2'nin temsilci kodunu agent.py, __init__.py ve .env genelinde nasıl düzenlediği
• adk run ve adk web'da etkinlikleri, izleri ve SQLite destekli oturumları çalıştırma, test etme ve inceleme

İhtiyacınız olanlar

• Google Hesabı (Atölye kredisi talep ediyorsanız kişisel @gmail.com hesabı kullanın)
• Eğitmeninizden aldığınız atölye kredisi bağlantısı (ve QR kodunu taramak için telefon kamerası) veya etkin bir Cloud Faturalandırma Hesabı
• Google Chrome (Kişisel hesaplar ile iş hesaplarının karışmaması için gizli pencere kullanılması önerilir.)

Gizli pencere ipucu: Bu codelab'i gizli pencerede açın. Böylece her Cloud Console ve Cloud Shell bağlantısı aynı oturumda açılır.

2. Google Cloud kredilerini kullanma (isteğe bağlı)

Etkinlik kredisi bağlantısı içeren bir atölyeye katılıyorsanız kredi kartı olmadan faturalandırma hesabı oluşturmak için Google Developer Program kredinizi kullanın.

Kendi faturalandırma hesabınızı mı kullanıyorsunuz? Google Cloud projesi oluşturma (İsteğe bağlı) bölümüne (veya zaten bir projeniz varsa Ortamınızı ayarlama bölümüne) geçin. Etkinlik kredisi içermeyen yeni bir faturalandırma hesabına ihtiyacınız varsa Cloud Faturalandırma Hesabı oluşturma veya Google Cloud Ücretsiz Deneme başlıklı makaleyi inceleyin.

Etkinlik kredinizi alma

⚠️ Kişisel Gmail hesabı kullanın: Kurumsal veya okul Google Workspace hesapları, atölye etkinliği kredileri için hak talebinde bulunamaz.

1. Atölye kredisi bağlantısını gizli pencerede açın ve @gmail.com hesabınızla oturum açın.
2. Avantajınızı Kullanın sayfasında Krediyi Kullan'ı tıklayın:

3. Google Developer Program profili oluşturmanız istenirse formu doldurun.
4. Gerçek Kişi Olduğunuzu Doğrulamak İçin Tarayın ifadesi göründüğünde QR kodunu telefonunuzla tarayın ve doğrulamayı tamamlayın (QR kodu görünmüyorsa sayfayı yenileyip Krediyi Al'ı tekrar tıklayın):

5. Etkinlik kredinizi başarıyla kullandınız ifadesinin göründüğünü onaylayın, ardından Faturalandırma Hesabını Aç'ı tıklayın:

🔍 Çalışmanızı kontrol edin

Faturalandırma hesabı kurulumu 3 dakika kadar sürer:

1. Google Cloud Billing'i açın (veya URL'yi gizli pencerenize kopyalayın) ve Faturalandırma hesaplarınız'ı seçin:

https://console.cloud.google.com/billing

2. GDP Credit hesabınızın durumu Etkin olarak gösterilene kadar sayfayı yenileyin:

3. Google Cloud projesi oluşturma (isteğe bağlı)

Bu codelab'deki tüm kaynakların izole kalması ve kolayca temizlenebilmesi için özel bir Google Cloud projesi oluşturun.

Zaten bir projeniz var mı? Faturalandırmanın etkinleştirildiği bir projeniz veya önceden temel hazırlığı yapılmış bir atölye projeniz varsa Ortamınızı ayarlama bölümüne geçin.

1. Proje Oluşturma sayfasını açın (veya URL'yi gizli pencerenize kopyalayın):

https://console.cloud.google.com/projectcreate

2. Proje ayrıntılarınızı girin:
   • Proje adı: Örneğin, google-cloud-workshop
   • Faturalandırma hesabı (gösteriliyorsa): GDP Credit (veya etkin faturalandırma hesabınızı) seçin.
   • Üst kaynak: Kuruluş yok (veya gerekirse kuruluşunuz)
3. Proje adının altında oluşturulan Proje Kimliği'ni not edin ve Oluştur'u tıklayın:

🔍 Çalışmanızı kontrol edin

Sağ üstteki araç çubuğunda Bildirimler'i tıklayın ve proje oluşturma işlemi tamamlandığında Proje Seç'i tıklayın:

4. Ortamınızı ayarlama

Google Cloud Shell'i yapılandırın, Agent Platform API'yi etkinleştirin ve uv ile izole bir Python 3.12 sanal ortamı oluşturun.

Yerel terminal ipucu: Cloud Shell yerine yerel bir makinede mi çalışıyorsunuz? gcloud auth application-default login komutunu bir kez çalıştırın, cloudshell edit filename komutlarını tercih ettiğiniz düzenleyiciyle (ör. code veya nano) değiştirin ve http://localhost:8000 dosyasını doğrudan tarayıcınızda açın.

Cloud Shell'i yapılandırma

1. Google Cloud konsolu araç çubuğunda Cloud Shell'i etkinleştir'i (>_) tıklayın veya doğrudan Google Cloud Shell'i açın (ya da URL'yi gizli pencerenize kopyalayın):

https://shell.cloud.google.com/?show=ide,terminal

2. İstenirse Authorize'ı (Yetkilendir) tıklayın:

3. Terminalinizdeki numaralı menüden etkin Google Cloud proje kimliğinizi seçin:

unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

Aşağıdakine benzer bir çıkış görürsünüz (etiketlenmemiş projeler de bilgilendirici bir [environment: untagged] satırı yazdırır):

1) google-cloud-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].

Seçtiğiniz proje kimliğinin Cloud Shell isteminde sarı renkle vurgulandığını doğrulayın:

Gerekli API'leri etkinleştirme

ADK temsilcinizin Gemini modellerini çağırabilmesi için Agent Platform API'yi etkinleştirin:

gcloud services enable aiplatform.googleapis.com

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

Operation "operations/acat.p2-..." finished successfully.

Python sanal ortamı oluşturma ve ADK'yi yükleme

Neden uv? Rust ile yazılan uv, Python ortamları oluşturur ve paketleri saniyeler içinde yükler. Daha fazla bilgiyi uv belgelerinde bulabilirsiniz.

~/ai-agents-adk çalışma alanı dizinini oluşturun ve Python 3.12 sanal ortamını etkinleştirin:

cd ~
mkdir -p ai-agents-adk && cd ~/ai-agents-adk

which uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

uv venv .venv --python 3.12
source .venv/bin/activate

Terminal isteminizin başında (.venv) ön ekinin göründüğünü doğrulayın:

ADK'yi etkin sanal ortama yükleyin:

uv pip install --no-cache "google-adk==2.14.0"

🔍 Çalışmanızı kontrol edin

Yüklü adk CLI sürümünü doğrulayın:

adk --version

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

adk, version 2.14.0

Oturum kurtarma ipucu: Cloud Shell sekmenizin bağlantısı daha sonra kesilirse çalışma alanınıza dönün ve cd ~/ai-agents-adk && source .venv/bin/activate ile ortamı yeniden etkinleştirin.

5. Temsilciyi yapılandırma

adk create ile başlangıç personal_assistant temsilci paketini oluşturun. ADK, personal_assistant/ içinde dört dosya oluşturur:

• agent.py: root_agent modelini, adını, açıklamasını ve sistem talimatını tanımlar.
• __init__.py: personal_assistant dizinini Python paketi olarak işaretler. Böylece ADK, agent.py modülünü bulup içe aktarabilir.
• .env: Arka uç işaretinizi (GOOGLE_GENAI_USE_ENTERPRISE=1), proje kimliğinizi ve konumunuzu (global) depolar.
• .gitignore: .env ve yerel .adk/ SQLite oturum dosyalarını sürüm denetiminden hariç tutar.

adk create çalıştırma

~/ai-agents-adk kaynağından personal_assistant paketinin iskeletini oluşturun:

cd ~/ai-agents-adk
adk create personal_assistant

İstendiğinde aşağıdaki seçenekleri belirleyin (ilk çalıştırmada Enable telemetry? [Y/n]: ile istenirse Enter tuşuna basın veya n yazıp Enter tuşuna basın):

1. Kök temsilci için bir model seçin: gemini-3.8-flash modelini seçmek için 2 yazın (1 seçeneği gemini-3.5-flash modelini seçer) ve Enter tuşuna basın.
2. Arka uç seçin: Google Cloud Agent Platform arka ucunu seçmek için 2 yazın (aşağıdaki CLI menüsünde 2 seçeneği) ve Enter tuşuna basın.
3. Enter Google Cloud project ID (Google Cloud proje kimliğini girin): Parantez içinde algılanan proje kimliğinizi kabul etmek için Enter tuşuna basın (veya farklıysa proje kimliğinizi yazın).
4. Enter Google Cloud region (Google Cloud bölgesini girin): global (Agent Platform'da gemini-3.8-flash hizmeti sunmak için gereklidir) yazın ve Enter tuşuna basın.

🔍 Çalışmanızı kontrol edin

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

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [google-cloud-workshop-4210]:
Enter Google Cloud region [us-central1]: global

Agent created in /home/your_username/ai-agents-adk/personal_assistant:
- .env
- .gitignore
- __init__.py
- agent.py

⚠️  WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env.

Next steps:
- Chat with your agent in the terminal: adk run personal_assistant
- Or in the browser: adk web .
- Have your coding agent evaluate and deploy it: uvx google-agents-cli setup
  (other install options: https://adk.dev/get-started/agents-cli/)

6. Oluşturulan kodu inceleme

Oluşturulan dosyaları terminalinizle birlikte inceleyebilmek için Cloud Shell Düzenleyici'de ~/ai-agents-adk dizinini açın:

which cloudshell >/dev/null 2>&1 && cloudshell workspace ~/ai-agents-adk || true

Terminali Yeniden Başlatma Notu: cloudshell workspace komutunu çalıştırdığınızda Cloud Shell penceresi yeniden yüklenir ve kabuğunuz yeniden başlatılır. Terminal bölmesi yeniden yüklendikten sonra .venv uzantısını yeniden etkinleştirin.

Yeniden yüklenen terminalde sanal ortamınızı yeniden etkinleştirin:

cd ~/ai-agents-adk
source .venv/bin/activate

Çalışma alanını Cloud Shell Düzenleyici'de manuel olarak açmak için Gezgin simgesini (veya Dosya > Klasör Aç...) tıklayıp ai-agents-adk klasörünü de seçebilirsiniz:

.env gibi nokta dosyaları, Gezgin ağacında varsayılan olarak gizlenir. personal_assistant/.env dosyasını görmek için üst menü çubuğunda View > Toggle Hidden Files'ı (Görünüm > Gizli Dosyaları Aç/Kapat) tıklayın:

agent.py adlı videoyu inceleyin

Cloud Shell Düzenleyici'de ~/ai-agents-adk/personal_assistant/agent.py dosyasını açın:

cloudshell edit ~/ai-agents-adk/personal_assistant/agent.py

Oluşturulan dosyayı inceleyin (düzenleme gerekmez):

from google.adk.agents.llm_agent import Agent

root_agent = Agent(
    model='gemini-3.8-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.llm_agent import Agent: ADK'nın Agent sınıfını (LlmAgent sınıfının takma adı; ADK 2, özel kod yazarken from google.adk import Agent sınıfını üst düzey kısaltma olarak da gösterir) içe aktarır.
• model='gemini-3.8-flash': Akıl yürütme ve yanıtlar için gemini-3.8-flash modelini seçer.
• name='root_agent': ADK'nin günlüklerde, izlerde ve çoklu temsilci grafiklerinde kullandığı tanımlayıcıyı atar.
• description='...': Üst koordinatör, temsilciye görev verip vermeyeceğine karar verirken temsilcinin ne yaptığını özetler.
• instruction='...': Temsilcinin üslubunu ve davranışını belirleyen sistem istemini ayarlar.

__init__.py ve .env belgelerini inceleyin

personal_assistant/__init__.py uygulamasını açarak agent öğesini yeniden dışa aktardığını onaylayın. Böylece adk run ve adk web, root_agent öğesini keşfedebilir:

from . import agent as agent

Çalışma zamanı yapılandırmanızı incelemek için personal_assistant/.env uygulamasını açın:

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global

• GOOGLE_GENAI_USE_ENTERPRISE=1: API anahtarı yerine Google Cloud kimlik bilgilerinizi kullanarak ADK model çağrılarını Agent Platform üzerinden yönlendirir.
• GOOGLE_CLOUD_PROJECT: Model isteklerini ve faturalandırmayı Google Cloud projenizle ilişkilendirir.
• GOOGLE_CLOUD_LOCATION=global: gemini-3.8-flash hizmetinin sunulduğu global uç noktayı hedefler.

🔍 Çalışmanızı kontrol edin

Terminalden personal_assistant/agent.py öğesinin sorunsuz bir şekilde içe aktarıldığını ve .env öğesinin global değerini gösterdiğini doğrulayın:

cd ~/ai-agents-adk && source .venv/bin/activate
python3 -c "from personal_assistant.agent import root_agent; print(root_agent.name, root_agent.model)"
cat ~/ai-agents-adk/personal_assistant/.env

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

root_agent gemini-3.8-flash
GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global

7. Temsilciyi terminalde çalıştırma

personal_assistant temsilcinizi adk run kullanarak doğrudan komut satırından test edin:

cd ~/ai-agents-adk && source .venv/bin/activate
adk run personal_assistant

[user]: isteminde hello. What can you do for me? gibi bir mesaj gönderin ve temsilcinin yanıt verdiğini doğrulayın.

🔍 Çalışmanızı kontrol edin

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

Running agent root_agent, type exit to exit.
[user]: hello. What can you do for me?
[root_agent]: Hello! I can help answer questions, explain concepts, summarize text, brainstorm ideas, and assist with writing or coding tasks. How can I help you today?
[user]: exit

Devam etmeden önce etkileşimli CLI oturumunu kapatıp kabuk isteminize dönmek için exit yazıp Enter tuşuna basın.

Sorun giderme

• This API method requires billing to be enabled: personal_assistant/.env içindeki GOOGLE_CLOUD_PROJECT değerinin etkin projenizle eşleştiğini onaylayın, ardından Bağlı Faturalandırma Hesabı'nı açın (veya aşağıdaki URL'yi kopyalayıp gizli pencerenize yapıştırın) ve etkin GDP Credit veya Cloud Faturalandırma Hesabınızı bağlayın:

https://console.cloud.google.com/billing/linkedaccount

• API has not been used in project: Terminalinizde Agent Platform API'yi etkinleştirin ve birkaç saniye sonra tekrar deneyin:

gcloud services enable aiplatform.googleapis.com

8. Temsilciyi ADK web kullanıcı arayüzünde çalıştırma

Markdown yanıtları, etkinlik yükleri ve çok turlu durum, ADK 2'nin yerleşik tarayıcı oyun alanında çok daha kolay incelenebilir. Üst ~/ai-agents-adk dizininden (personal_assistant/ üstünde) ADK Web kullanıcı arayüzünü başlatın:

cd ~/ai-agents-adk && source .venv/bin/activate
adk web --allow_origins "*"

Neden --allow_origins "*"? --allow_origins "*" parametresini ilettiğinizde Cloud Shell web önizleme alanınız (*.cloudshell.dev) üzerinden proxy ile gönderilen isteklere izin verilir.

Tarayıcınızda ADK Web kullanıcı arayüzünü açın:

1. Cloud Shell araç çubuğunun sağ üst kısmındaki Web Preview (Web Önizlemesi) simgesini tıklayın ve Change port'u (Bağlantı noktasını değiştir) seçin.
2. 8000 bağlantı noktasını girin ve Change and Preview'u (Değiştir ve Önizle) tıklayın:

3. Sol üstteki temsilci açılır listesinde personal_assistant öğesinin seçili olduğunu onaylayın, "Hello. What can you do?" öğesini gönderin ve meta verilerini incelemek için temsilci yanıt etkinliğini tıklayın:

ADK 2'nin web kullanıcı arayüzü, Etkinlikler ve İzler akış açma/kapatma düğmesini Bilgi, Durum, Yapılar ve Değerlendirmeler denetleyici sekmeleriyle (ve üst araç çubuğundaki Temsilci Yapısı grafik simgesiyle) eşler ve yerel oturumları personal_assistant/.adk/session.db dizininde otomatik olarak saklar.

🔍 Çalışmanızı kontrol edin

Cloud Shell terminalinizde şuna benzer bir çıkış görürsünüz:

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)

Testi tamamladığınızda terminalinizde Ctrl + C tuşlarına basarak adk web sunucusunu durdurun ve komut istemine dönün.

9. Temizleme (isteğe bağlı)

⚠️ Seriye devam mı ediyorsunuz? Doğrudan ~/ai-agents-adk/personal_assistant üzerine inşa edilen ADK ile Yapay Zeka Ajanları Oluşturma: Araçlarla Güçlendirme bölümüne devam ediyorsanız bu adımı atlayın.

Bu codelab, istek başına ödeme yapılan Gemini çağrıları dışında kalıcı faturalandırılabilir altyapı oluşturmaz. adk web uygulamasının durdurulduğundan (Ctrl + C) emin olun.

Yerel çalışma alanı dosyalarını kaldırma

~/ai-agents-adk dizinini Cloud Shell'den silmek için:

cd ~
rm -rf ~/ai-agents-adk

Özel bir projeyi silme (isteğe bağlı)

⚠️ Zarar Verici İşlem: Projeyi yalnızca bu codelab için özel olarak oluşturduysanız ve seriye devam etmiyorsanız silin. Paylaşılan veya önceden temel hazırlığı yapılmış bir atölye projesini hiçbir zaman silmeyin.

gcloud projects delete "$(gcloud config get-value project)" --quiet

10. Tebrikler

Google Cloud'da ADK 2 Python ortamı oluşturdunuz, Agent Platform'da gemini-3.8-flash tarafından desteklenen bir personal_assistant temsilcisi oluşturdunuz, oluşturulan paket yapısını incelediniz ve hem terminal KSA'da hem de ADK Web kullanıcı arayüzünde test ettiniz.

Başarılarınız

• Google Cloud Shell'i yapılandırdınız, Agent Platform API'yi etkinleştirdiniz ve uv ile bir Python 3.12 ortamı oluşturdunuz.
• personal_assistant ile adk create için iskele oluşturuldu ve agent.py, __init__.py ve .env'nin birlikte nasıl çalıştığı incelendi.
• adk run üzerinden çok turlu görüşmeler test edildi ve adk web içindeki etkinlikler, izler ve SQLite destekli oturumlar incelendi.

Sonraki adımlar

• 2. bölüme devam edin: ADK ile Yapay Zeka Ajanları Oluşturma: Araçlarla Güçlendirme
• 3. bölüme devam edin: ADK ile Yapay Zeka Ajanları Oluşturma: Ajan İş Akışlarını Yönetme
• 4. bölüme devam edin: ADK ile Yapay Zeka Ajanları Oluşturma: Grafik İş Akışlarını Yönetme
• Agent Development Kit belgelerini ve GEAR öğrenme programını inceleyin.