ADK ve Google Haritalar ile temellendirme kullanarak bir seyahat planı oluşturma ajanı geliştirme

1. Giriş

Bu codelab'de, Agent Development Kit'i (ADK) kullanarak bir seyahat planlama ajanı oluşturacak ve Google Haritalar ile temellendireceksiniz. Google Haritalar'daki gerçek dünya verilerinden yararlanarak aracıdan manzaralı rotalar ve restoran önerileri oluşturmasını isteyeceksiniz.

Yapacaklarınız

  • Temsilci Başlangıç Paketi'ni kullanarak bir temsilci projesi başlatma
  • Aracı, Google Haritalar Temellendirme aracını kullanacak şekilde yapılandırın.
  • Elde edilen aracı bir web arayüzüyle yerel olarak test etme

İhtiyacınız olanlar

  • Chrome gibi bir web tarayıcısı
  • Faturalandırmanın etkin olduğu bir Google Cloud projesi

Bu codelab, Python ve Google Cloud hakkında bilgi sahibi olan ancak uzman olmayan orta düzey geliştiriciler içindir.

2. Başlamadan önce

Google Cloud projesi oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i Başlatma

  1. Kimlik doğrulamayı doğrulayın:
gcloud auth list
  1. Projenizi onaylayın:
gcloud config get project
  1. Gerekirse ayarlayın:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

API'leri etkinleştir

Gerekli tüm API'leri etkinleştirmek için bu komutu çalıştırın:

gcloud services enable \
  aiplatform.googleapis.com

3. Aracı Başlangıç Paketini yükleme

ADK projesine başlamanın en kolay yolu Agent Starter Pack'i kullanmaktır. Google Cloud Agent Starter Pack, Google Cloud'da üretime hazır üretken yapay zeka aracı geliştirme ve dağıtımını hızlandırmak için tasarlanmış açık kaynaklı bir komut satırı arayüzü (KSA) aracıdır.

  1. uv'nın yüklendiğinden emin olun, ardından yeni bir aracı projesi başlatmak için oluşturma komutunu çalıştırın:
uvx agent-starter-pack create
  1. İstendiğinde, projenizi React ön ucuyla yerel geliştirme için yapılandırmak üzere aşağıdaki seçenekleri belirtin:
  • Aracı Şablonu: adk (Basit React Aracı)
  • Dağıtım: none (Cloud Deployment şu anda devre dışı)
  • Bölge: us-central1

Bu işlem, ana aracı mantığınızı, testlerinizi ve bir GEMINI.md kılavuzunu içeren bir proje dizini yapısı oluşturur. Yeni dizininize gidin:

cd my-agent

4. Temellendirmeyi yapılandırma

Agent Starter Pack, yapay zeka destekli kodlama araçlarına projenizi nasıl yönetecekleri konusunda talimat veren bir GEMINI.md dosyası oluşturur. Bu dokümanı, Google Haritalar Grounding dokümanını içerecek şekilde güncelleyeceğiz.

  1. GEMINI.md dosyasını düzenleyicinizde açın.
  2. ## Reference Documentation bölümüne aşağıdaki referans bağlantısını ekleyin:
- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps

Bu bağlam, tüm yapay zeka kodlama asistanlarının temellendirme özelliğini anlamasına yardımcı olur.

5. Ajanı güncelleme

Şimdi, Google Haritalar Temellendirme aracıyla birlikte seyahat planlayıcısı olarak hareket edecek şekilde aracıyı yapılandıracağız.

  1. Dosyayı açın app/agent.py.
  2. app/agent.py dosyasının tüm içeriğini aşağıdaki kodla değiştirin:
"""Agent application for the itinerary planner codelab."""

import os
import google.auth
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools import google_maps_grounding
from google.genai import types

# Authenticate and set environment variables
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

# Define the root agent
root_agent = Agent(
    name="itinerary_planner_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are an itinerary planner agent. Help users plan their trips by"
        " recommending restaurants and scenic routes. Use the"
        " google_maps_grounding tool to get both restaurant recommendations and"
        " route recommendations based on user preferences. When calling for"
        " restaurant recommendation, prompt the tool to tell you about the vibe"
        " of the place. When calling for routes with multiple legs, describe"
        " each of those legs with a brief sentence. Always describe the key"
        " landmarks along the route in one brief sentence."
    ),
    # Add the Google Maps Grounding tool to the agent
    tools=[google_maps_grounding],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Bu kod, yerler ve rotalarla ilgili güncel bilgileri almak için google_maps_grounding aracını kullanan gemini-2.5-flash tabanlı bir temsilciyi yapılandırır.

Kullanılabilen tüm modelleri görüntülemek için Vertex AI belgelerine bakın.

6. Temsilciyi çalıştırma

Aracı mantığınızı oluşturduktan sonra yerel web arayüzünüzde test etmeyi deneyin.

  1. Web uygulamasını başlatmak için my-agent dizininizin kökünden aşağıdaki komutu çalıştırın:
uv run adk web

veya sanal ortam kullanıyorsanız:

adk web
  1. Terminal çıkışında sağlanan URL'yi tarayıcınızda açın.
  2. Temsilciye soru sorarak test edin. Örneğin:
  • San Francisco'da iyi bir İtalyan restoranının da yer aldığı 1 günlük bir seyahat planı yap.
  • Tokyo'yu ziyaret ediyorum. Bana ilginç tarihi önemli noktaları ve rahat bir atmosfere sahip, yüksek puanlı bir ramen restoranını içeren bir seyahat planı verebilir misin?

Doğrudan Google Haritalar'dan alınan gerçek yorumlar ve rota açıklamalarıyla zenginleştirilmiş ayrıntılı bir seyahat planına benzer bir çıktı görmeniz gerekir.

Örnek Seyahat Planı Çıkışı

7. Kodda Temellendirmeyi Doğrulama

Aracınızın Haritalar temellendirmeyi başarıyla kullandığını programatik olarak doğrulamak için yanıttaki etkinlikleri Haritalar'a özgü meta veriler açısından inceleyebilirsiniz.

Temsilcinizi çalıştırdığınızda (örneğin, bir test komut dosyasında) temsilci, grounding_metadata içeren etkinlikler oluşturur. Bu meta verilerdeki grounding_chunks öğelerini inceleyebilir ve maps özelliğini kontrol edebilirsiniz.

Aşağıda, otomatik testte kullanabileceğinize benzer şekilde maps özelliğinin nasıl kontrol edileceğini gösteren bir örnek verilmiştir:

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Check for the maps attribute to confirm maps grounding
                if hasattr(chunk, "maps") and chunk.maps:
                    print("SUCCESS: Maps grounding chunks detected in the response!")

8. Kodlanmış Çoklu Çizgileri Ayıklama

Temellendirmenin gerçekleştiğini doğrulamanın yanı sıra rota yolları gibi belirli verileri de ayıklamak isteyebilirsiniz. Haritalar temellendirme aracı rota bilgilerini döndürdüğünde, genellikle rotayı bir harita ön ucunda oluşturmak için kullanılabilecek bir "Kodlanmış Çoklu Çizgi" içerir.

Bu çoklu çizgiye, grounding_chunks öğesinin maps özelliğindeki metni kontrol ederek ulaşabilirsiniz. Bunu nasıl tespit edebileceğinize dair bir örneği aşağıda bulabilirsiniz:

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Extract the encoded polyline from the maps chunk text
                if (
                    hasattr(chunk, "maps")
                    and chunk.maps
                    and hasattr(chunk.maps, "text")
                    and chunk.maps.text
                    and "Encoded Polyline" in chunk.maps.text
                ):
                    print("SUCCESS: Encoded Polyline detected in the response!")

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. Bu codelab için özel bir proje oluşturduysanız projeyi tamamen silin:
gcloud projects delete $PROJECT_ID

Mevcut bir projeyi kullandıysanız ve bu projeyi tutmak istiyorsanız, aracı yerel olarak çalıştığı ve kullanılan API'ler sunucusuz olduğu için silmeniz gereken belirli bir kaynak yoktur.

10. Tebrikler

Tebrikler! Google Haritalar analizlerini kullanarak bir seyahat planı oluşturma aracısı oluşturup temelini başarıyla oluşturdunuz.

Öğrendikleriniz

  • Ajan Başlangıç Paketi'ni kullanarak yeni bir ajan oluşturma
  • ADK Agent tanımına temellendirme araçları ekleme
  • Yerleşik web çalıştırıcıyı kullanarak ADK aracısını test etme

Sonraki adımlar

  • Diğer ADK araçlarını ve entegrasyon kalıplarını keşfedin

Referans belgeleri