1. Giriş
Bu codelab'de, Google'ın Agent Development Kit'ini (ADK) ve Gemini'ı kullanarak ilk yapay zeka aracınızı adım adım oluşturacaksınız. Muhakeme ve hareket etme ile ilgili temel kavramları gösteren, içerik planlayıp yazan temel bir blog yazma aracını oluşturacaksınız.
Yapacaklarınız
- ADK için geliştirme ortamınızı ayarlayın.
- Planlayıcı ve Yazıcı ile çoklu temsilci sistemi oluşturun.
- Ajanı yerel olarak çalıştırın ve ADK web arayüzü üzerinden ajanla etkileşimde bulunun.
İhtiyacınız olanlar
- Chrome gibi bir web tarayıcısı
- Makinenizde Python 3.10 veya sonraki bir sürüm yüklü olmalıdır.
- Google AI Studio API anahtarı.
Bu codelab, yeni başlayanlar da dahil olmak üzere her seviyeden geliştiriciye yöneliktir.
Tahmini süre: 30 dakika.
2. Görsel rehber: Yapay zeka aracısı nedir?
Geliştirmeye başlamadan önce yapay zeka aracıların ne olduğunu ve izledikleri yaygın kalıpları kısaca anlayalım.
Yapay zeka ajanı nedir?
En basit düzeyde, ajan yalnızca yanıt vermekle kalmayıp karar verebilen ve işlem yapabilen bir yazılımdır. Geleneksel bir chatbot gibi tek bir yanıt oluşturmak yerine, isteğinize bakar, hangi adımların atılacağını belirler, API çağırabilir, kod çalıştırabilir, sonucu inceler ve ardından bir sonraki adımda ne yapacağına karar verir.
En net açıklamalardan biri ReAct: Synergizing Reasoning and Acting in Language Models (ReAct: Dil Modellerinde Muhakeme ve Eylemi Sinerjiye Katma) adlı araştırma makalesinde yer alıyor. Bu makaledeki fikir basit ama etkiliydi: Dil modelleri yalnızca tek seferde metin oluşturmamalı. Aslında adım adım muhakeme edebilir, bir aracı veya API'yi çağırma gibi bir işlem yapabilir, sonucu gözlemleyebilir ve ardından bir sonraki adımda ne yapacağına karar verebilir.
Bu muhakeme, hareket etme, gözlemleme ve ayarlama döngüsü, modern yapay zeka aracıların çalışma şeklinin temelini oluşturur. Ayrıca, Google Cloud'un bu araçları tanımlama şekliyle de uyumludur: Muhakeme, planlama ve hafıza özelliklerine sahip, kullanıcının adına uyum sağlayıp karar verebilecek kadar özerk sistemler.
Üç Ajan Davranış Kalıbı
Tüm aracıların davranışı aynı değildir. Bu türleri üç geniş kalıpla düşünebilirsiniz:
- Sıralı temsilciler: Bunlar, montaj hattı gibi adım adım çalışır: 1. adım, ardından 2. adım ve 3. adım. Öngörülebilir ancak katıdırlar.
- Tepkisel ajanlar: Bunlar anlık olarak karar verir. Mevcut duruma bakıp "Bir sonraki adımda ne yapmalıyım?" diye sorarlar. Bir seferinde A aracını, bir sonraki seferde B aracını kullanabilirler. Esnektirler ancak önceden plan yapmazlar.
- Düşünceli veya planlama temsilcileri: Bunlar, bir plan taslağı oluşturmak için duraklatır ve ardından planı uygular. Seyahat rezervasyonu yapmayı düşünün. Rastgele bir uçuş satın almazsınız. Tarihleri ve otelleri seçer, adımları sıralar ve ardından işlemi tamamlarsınız.
Hangisi "doğru" olanıdır? Bu durum soruna bağlıdır. Basit ve öngörülebilir akışlar için sıralı akış uygundur. Dinamik görevlerde tepkisel yaklaşım daha iyi sonuç verir. Bağımlılıkları olan çok adımlı hedefler için planlama aracıları istersiniz.
Bu laboratuvarda, önce bir ana hat oluşturup ardından blog yayını yazan bir Deliberative/Planning (Düşünceli/Planlama) temsilcisi oluşturacağız.
3. Başlamadan önce
Google Cloud hesabı ve projesi oluşturma
Bu laboratuvarın ilerleyen bölümlerinde aracı Google Cloud Run'a dağıtmak için Google Cloud hesabınızın ve faturalandırmanın etkin olduğu bir projenizin olması gerekir.
- Google Cloud Console'da oturum açın. Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanın. Google Hesabınız yoksa hesap oluşturmanız gerekir.
- Ardından, Cloud kaynaklarını kullanmak için Cloud Console'da faturalandırmayı etkinleştirmeniz gerekir. Bu codelab'i tamamlamak birkaç sentten daha az maliyetlidir. Yeni Google Cloud kullanıcıları 300 ABD doları değerinde ücretsiz deneme programından da yararlanabilir.
- Proje kimliğinizi (tüm Google Cloud projelerinde benzersiz bir ad) not edin. Temsilciyi yapılandırmak ve dağıtmak için bu bilgiye ihtiyacınız vardır.
Google AI Studio API anahtarı edinme
Gemini modellerini kullanmak için Google AI Studio'dan bir API anahtarı almanız gerekir.
- Google AI Studio'ya gidin.
- Get API Key'i (API anahtarı al) tıklayın.
- Yeni bir anahtar oluşturun veya mevcut bir anahtarı kullanın. Anahtarı daha sonra kullanmak için kopyalayın.
4. Blog Yazarı Aracısı Proje Yapısını Oluşturma
Bu adımda, blog yazma aracınızın kodunu yerel makinenizde barındıracak dizini ve dosyaları ayarlayacaksınız.
1. Blog yazma temsilcisi çalışma alanını oluşturma
Terminalinizi açın ve aşağıdaki komutları çalıştırarak blog yazarı aracınız için özel bir dizin oluşturup bu dizine gidin:
mkdir bloggeragent
cd bloggeragent
2. Aracı dosyalarını başlatın
Google ADK çerçevesi, aracı iş akışlarını doğrudan proje dizininizden yükler. Gerekli dosyaları doğrudan bloggeragent kök dizininde oluşturun:
touch requirements.txt .env __init__.py agent.py
5. Bağımlılıkları yükleme ve ortamı ayarlama
Bu adımda, Python sanal ortamı oluşturacak, Google ADK çerçevesini yükleyecek ve blog aracınızın Gemini modeliyle kimliğini doğrulayacak ortam değişkenlerini yapılandıracaksınız.
1. Aracı gereksinimlerini yapılandırma
bloggeragent dizinindeki requirements.txt dosyasını açın ve aşağıdaki kodu ekleyerek blog yazma aracısı için gereken paketleri belirtin:
google-adk==2.2.0
python-dotenv
2. Ajan için sanal ortam oluşturma
Aracı paketlerini izole etmek için bloggeragent dizininden bir Python sanal ortamı oluşturun ve etkinleştirin:
python3 -m venv .venv
source .venv/bin/activate
3. ADK çerçevesini yükleme
Yerel çalışma alanınızı Google ADK ile donatmak için requirements.txt dosyanızda tanımlanan bağımlılıkları yükleyin:
pip install -r requirements.txt
4. Aracı API kimlik bilgilerini yapılandırma
Proje kök dizininde oluşturduğunuz .env dosyasını açın ve Gemini API anahtarınızı ekleyin:
GOOGLE_API_KEY=your_api_key
your_api_key kısmını, Google AI Studio'dan kopyaladığınız anahtarla değiştirin.
6. Çok Temsilcili Blog Yazarı'nı oluşturma
Bu adımda, blog yazma ajanı sisteminizin temel iş akışını uygulayacaksınız.
Basit bir tek istemli chatbot yerine, yüksek kaliteli teknik gönderiler yazmak için kendi kendini düzelten döngüler ve taslak doğrulaması kullanan karmaşık bir çok agent'lı sistem oluşturacaksınız. Bu, daha önce bahsettiğimiz Deliberative/Planning (Düşünceli/Planlama) kalıbını takip eder.
Mimariye Genel Bakış
Sisteminizdeki uzman aracılar şu şekilde etkileşime girer:
init.py dosyasını yapılandırma
Metin düzenleyicinizde __init__.py dosyasını açın ve aracı iş akışını çalıştırıcıya göstermek için aşağıdaki içe aktarma işlemini ekleyin:
from . import agent
Blog yazma aracısı iş akışını yazma
Kod düzenleyicinizde agent.py dosyasını açın ve Planlayıcı, Yazar, Doğrulama Denetleyicileri ve ana Blogger aracısını tanımlayan aşağıdaki kodu ekleyin:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Aracı mimarisini anlama
Çoklu aracı planlama ve yazma iş akışının nasıl uygulandığını anlamak için agent.py bölümünde eklediğiniz kodun ana bileşenlerini inceleyelim:
1. BlogPlanner Alt Temsilcisi
blog_planner aracısı, içerik planlamadan sorumludur. Kullanıcının sağladığı konuyu alır ve Markdown biçiminde yapılandırılmış bir taslak (başlık, giriş, 4-6 bölüm ve sonuç ile) oluşturur. Ana hat, "blog_outline" anahtarı altında paylaşılan durum sözlüğüne kaydedilir.
2. The OutlineValidationChecker
OutlineValidationChecker aracısı, kalite kontrolü görevi görür. Durumda oluşturulan "blog_outline" öğesini inceler. Plan geçerliyse "ok" ile yanıt verir. Aksi takdirde, eksik olanların listesiyle birlikte "retry" döndürülür.
3. The RobustBlogPlanner Loop
Aracının kötü planlar üretmesini önlemek için planlayıcıyı ve doğrulama denetleyicisini LoopAgent adlı bir robust_blog_planner içine yerleştiririz. Doğrulama başarısız olursa ve "retry" döndürülürse döngü, planlayıcıyı otomatik olarak 3 kez daha çalıştırır. Böylece bir sonraki aşamaya geçmeden önce kendi kendini düzeltme sağlanır.
4. BlogWriter Alt Temsilcisi
Plan kesinleştikten sonra blog_writer aracısı, durumdan "blog_outline" okur ve planın yapısına uygun, yazılım mühendislerine yönelik tam teknik makaleyi Markdown biçiminde oluşturur.
5. BlogPostValidationChecker ve RobustBlogWriter Döngüsü
Tıpkı taslakta olduğu gibi, nihai makale de tüm önemli bölümlerin mevcut ve net olduğundan emin olmak için BlogPostValidationChecker tarafından doğrulanır. Yazıcı ve kontrolcü, robust_blog_writer döngüsüne dahil edilir. Kontrolcü sorun bulursa döngü, kendi kendini 3 kez düzeltebilir.
6. Döngüleri Araç Olarak Kullanıma Sunma
AgentTool kullanarak planlayıcı döngüsünü (robust_blog_planner) ve yazıcı döngüsünü (robust_blog_writer) araçlar (planner_tool ve writer_tool) olarak sarmalarız. Bu sayede diğer aracıların, bu karmaşık iş akışlarını basit araçlarmış gibi çağırmasına olanak tanınır.
7. Blogger Kök Ajanı
root_agent (Blogger olarak adlandırılır) tüm iş akışını düzenler. Bir konu verildiğinde talimatlar, modelin aşağıdaki işlemleri yapmasını sağlar:
- Doğrulanmış ana hat oluşturmak için
planner_toolnumaralı telefonu arayın. - Bu taslağı, ana hatlara göre yazmak için
writer_toolişlevini çağırın. - 3 alternatif başlık ve 2 tweet kancası oluşturarak işlemi tamamlayın.
Bu çoklu aracı döngüsü mimarisi, çıkışı kullanıcıya göstermeden önce LLM biçimlendirme veya yapısal hatalarını yakalayıp düzelterek güvenilirliği sağlar.
7. Ajanı Çalıştırma ve Test Etme
Şimdi temsilcinizi kullanma zamanı.
1. ADK web kullanıcı arayüzünü başlatma
Terminalinizde bloggeragent proje kök dizininde olduğunuzdan ve sanal ortamınızın etkin olduğundan (source .venv/bin/activate) emin olun, ardından web arayüzünü başlatın:
adk web
2. Ajanla etkileşim kurma
- Tarayıcınızı açıp
http://127.0.0.1:8000(veya belirttiğiniz bağlantı noktası) adresine gidin. Bloggeraracının yüklendiği ve görsel düzeninin (Blogger kök aracının RobustBlogPlanner ve RobustBlogWriter araçlarına işaret ettiğini gösteren) bulunduğu ADK Web kullanıcı arayüzünü görmelisiniz:
- Mesaj kutusuna teknik bir konu yazıp Enter tuşuna basın. Aracınızı değerlendirmek için kullanabileceğiniz bazı ilginç test istemleri:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- Kullanıcı arayüzünde yürütme izini izleyin.
BlogPlannertaslağı oluşturur,OutlineValidationCheckertaslağı doğrular veBlogWritertaslağa göre son taslağı yazar:
8. Cloud Run'a dağıt
Ajanın yerel olarak çalıştığını doğruladığınıza göre şimdi Google Cloud Run'a dağıtalım, böylece diğer kullanıcılar da kullanabilir.
Google Cloud Run, web istekleri veya Pub/Sub etkinlikleri ile çağrılabilen durum bilgisiz container'lar çalıştırmanıza olanak tanıyan bir yönetilen işlem platformudur.
1. Dağıtım için ön koşullar
Blog yazma aracısını Cloud Run'a dağıtmak için Google Cloud KSA'yı (gcloud) yerel makinenize yükleyip kimlik doğrulamanız gerekir:
- Google Cloud CLI'yı yükleyin: Yüklü değilse işletim sisteminize (macOS, Windows veya Linux) yönelik Google Cloud CLI Kurulum Kılavuzu'ndaki talimatları uygulayın.
- Yerel terminalinizin kimliğini doğrulayın: Yükleme tamamlandıktan sonra terminalinizde aşağıdaki komutu çalıştırarak Google Cloud hesabınıza giriş yapın:
gcloud auth login - Kimlik doğrulamayı doğrulayın: Hesabınızda başarıyla oturum açıldığını ve Google Cloud kaynaklarınıza erişebildiğinizi onaylayın:
gcloud auth list
2. Google Cloud projesi oluşturma
Terminalde etkin projenizi ayarlayın:
gcloud config set project <YOUR_PROJECT_ID>
Container'a alınmış aracınızı oluşturmak ve dağıtmak için gereken Google Cloud hizmetlerini etkinleştirin:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
ADK dağıtım komutu, derleme işlemini otomatikleştirmek için Google Cloud Build'ü kullandığından varsayılan Compute hizmet hesabına Cloud Build'ü kullanma izni vermeniz gerekir.
Aşağıdaki komutu çalıştırarak proje numaranızı bulun:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Gerekli IAM rollerini bağlamak için aşağıdaki komutları çalıştırın (
- Cloud Build'e kapsayıcınızı oluşturma izni verin:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Dağıtılan ajanın, API anahtarı gerektirmeden Gemini modellerini çağırabilmesi için Gemini Enterprise erişim izni verin:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Yerel ortam değişkenlerini ayarlama
Dağıtım komutunu basitleştirmek ve yazım hatalarını önlemek için proje kimliğinizi terminal oturumunuzda ortam değişkeni olarak ayarlayın:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. ADK KSA'yı kullanarak dağıtma
ADK CLI, aracınızı Cloud Run'a dağıtmak için kolaylaştırılmış bir komut sağlar.
Sanal ortamınızın etkin olduğundan ve bloggeragent proje dizininde bulunduğunuzdan emin olun, ardından dağıtım komutunu çalıştırın:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
Dağıtım işlemi sırasında terminalinizde aşağıdaki iki soru sorulur:
- Depo oluşturmayı onaylayın:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yyazıp Enter tuşuna basın. - Kimliği doğrulanmamış erişime izin ver:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
yyazın ve Enter tuşuna basın (bu işlem, tarayıcınızda ADK Web kullanıcı arayüzüne herkese açık olarak erişmenizi sağlar).
5. Dağıtılan aracınıza erişme
Dağıtım tamamlandığında komut bir URL çıkışı verir. Herkese açık ve canlı ADK Web Kullanıcı Arayüzü'ne erişmek için bu URL'yi tarayıcınızda açın.
9. Temizleme
Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu codelab sırasında oluşturulan kaynakları silin.
1. Cloud Run hizmetini silme
Dağıtılan bloggeragent hizmetini silin:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Artifact Registry deposunu silme
Oluşturulan container görüntülerini depolamak için oluşturulan Docker deposunu silin:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Yerel sunucuyu durdurma
Yerel ADK sunucusunu durdurmak için çalıştığı terminalde CTRL+C tuşuna basın ve sanal ortamı devre dışı bırakın:
deactivate
10. Tebrikler
Tebrikler! Google'ın ADK'sını ve Gemini'ı kullanarak ilk yapay zeka aracınızı oluşturdunuz.
Öğrendikleriniz
- Yapay zeka ajanlarının temel kavramları (Akıl Yürütme ve İşlem Yapma).
- Çoklu temsilci sistemi oluşturmak için Google ADK'yı kullanma
- Web kullanıcı arayüzünü kullanarak aracınızı çalıştırma ve test etme
Sonraki adımlar
- Ajanınıza araç eklemeyi deneyin (ör. web araması veya API çağrıları).
- MCP sunucusunu entegre edeceğimiz 2. videoyu kaçırmayın.