Next '26 Geliştirici Açılış Konuşması: Beceriler ve Araçlarla ADK Ajanları Oluşturma

1. Giriş

Bu codelab'de, Agent Development Kit'i (ADK) kullanarak gelişmiş bir Maraton Planlayıcı Ajanı oluşturacaksınız. İyi yapılandırılmış bir sistem isteminden dinamik beceri yüklemeye ve MCP araçlarını eşlemeye kadar, aracının özelliklerini aşamalı olarak inceleyeceksiniz. Son olarak, aracıyı yerel olarak test edecek ve Agent Runtime'a (Agent Engine) dağıtacaksınız.

Yapacaklarınız

  • Yeni bir ADK aracısı projesi başlatma
  • Yapılandırılmış bir oluşturucu kullanarak güçlü bir sistem istemi oluşturma
  • Gerçek dünya konum bağlamı için Google Haritalar MCP araçlarını ekleyin.
  • Ajanın araç setine becerileri dinamik olarak yükleme
  • Temsilci yürütmesini yerel olarak test etme
  • Aracıyı Agent Engine'e (Cloud Run) dağıtın.

İhtiyacınız olanlar

  • Chrome gibi bir web tarayıcısı
  • Faturalandırmanın etkin olduğu bir Google Cloud projesi
  • Python'a dair temel bilgiler

Bu codelab, uzmanlaşmış üretken yapay zeka aracıları oluşturmak isteyen orta düzey geliştiriciler içindir.

Tahmini süre: 45 dakika

Bu codelab'de oluşturulan kaynakların maliyeti 2 ABD dolarından az olmalıdır.

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

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

  1. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
  2. Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
    gcloud auth list
  3. Projenizin yapılandırıldığını onaylayın:
    gcloud config get project
  4. Projeniz beklendiği gibi ayarlanmamışsa şu şekilde ayarlayın:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Kimlik doğrulamayı doğrulayın:

gcloud auth list

Projenizi onaylayın:

gcloud config get project

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 \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

Google Haritalar API anahtarı oluşturma

Google Haritalar MCP araçlarını kullanmak için Haritalar API anahtarı oluşturmanız gerekir.

  1. Google Cloud Console'da arama çubuğunu kullanarak Google Haritalar Platformu > Kimlik Bilgileri'ne gidin.
  2. İstenirse Google Cloud projenizi onaylayın.
  3. Kimlik bilgisi oluştur'u tıklayın ve API anahtarı'nı seçin.
  4. Oluşturulan API anahtarını kopyalayın. Bu bilgiye bir sonraki adımda ihtiyacınız olacak.

3. Ortamınızı ayarlama

Bu codelab'deki kod GitHub'da barındırılır. Dizin yapısını ve gerekli alt bileşenleri (ör. skills/ dizini) içeren depoyu klonlarsınız.

  1. Depoyu klonlayın ve proje klasörüne gidin:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Python sanal ortamı oluşturun ve ADK'yı yükleyin:
uv venv
source .venv/bin/activate
uv sync
  1. Haritalar API anahtarınızı ayarlayın. Uygulama, bunu bir ortam değişkeninden okur:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Ortam değişkenlerini yapılandırma

Simülasyon Aracı, yapılandırma için .env dosyasını kullanır. Örnek dosyayı kopyalayın ve proje kimliğinizle güncelleyin.

  1. Örnek ortam dosyasını kopyalayın:
cp planner_agent/sample.env planner_agent/.env
  1. planner_agent/.env dosyasını açın, GOOGLE_CLOUD_PROJECT alanını gerçek Google Cloud proje kimliğinizle ve GOOGLE_MAPS_API_KEY alanını oluşturduğunuz Google Haritalar API anahtarınızla güncelleyin.

Dosya aşağıdaki gibi görünmelidir:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4. Yeni bir ADK aracısı oluşturma

Aracı tanımlayan temel dosyayı inceleyin: planner_agent/agent.py.

build-agents-with-skills deposunda, aracı ADK'nın Agent sınıfı kullanılarak başlatılır. Temel modeli ve kimlik adını belirtir, diğer modüllerde tanımlanan talimatları ve araçları kullanır.

İlk kullanıma hazırlama kodunu incelemek için planner_agent/agent.py dosyasını açın:

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

Agent sınıfı, mesaj geçmişini, araç düzenlemesini ve LLM iletişimini soyutlayarak aracının davranışına odaklanmanızı sağlar.

Şu anda temsilci çok genel bir yanıt veriyor. Bu modelle diğer büyük dil modelleriyle etkileşim kurduğunuz gibi etkileşim kurabilirsiniz.

uv run adk run planner_agent

Bu komut, temsilciyle sohbet başlatır. Model olarak gemini-3-flash-preview'ı kullanır ve temel soruları yanıtlayabilir.

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

Temsilci, maratonlarla ilgili bazı bilgileri zaten biliyor. Ancak bu, kurallar ve rota planlamasıyla uygun bir maraton planlamak için yeterli değildir.

5. Sistem istemi oluşturma

Sistem istemleri (talimatlar), temsilcinin davranışını belirler. Bu proje, tek bir devasa dize yerine talimatları dinamik olarak oluşturmak için PromptBuilder (planner_agent/utils.py) kullanır.

İstemlerin nasıl mantıksal bölümler halinde yapılandırıldığını görmek için planner_agent/prompts.py simgesini açın:

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

planner_agent/agent.py'da bu zaten içe aktarılmış.

TODO: Replace Instruction and Description içeren bölümü bulun ve instruction ile description değişken yeniden atamasını yorumdan çıkarın.

Kodun bu bölümü şu şekilde görünmelidir:

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

Aracı için herhangi bir araca referans vermeyen bir istem sürümünü içe aktarıyorsunuz. Araçları daha sonraki bir adımda ekleyeceksiniz.

Temsilcinin bu sürümünü test edebilirsiniz:

uv run adk run planner_agent

Sohbet penceresinde aşağıdaki istemi gönderin:

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Birkaç dakika sonra şuna benzer bir yanıt alırsınız:

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

İyi tanımlanmış bir istemle, çıktı zaten beklenen sonuca çok daha yakın. Sonraki adımda, temsilciyi bir sonraki seviyeye taşıyacak araçlar ekleyeceksiniz.

6. Beceri ve araç ekleme

planner_agent/agent.py'da becerileri ve araçları etkinleştirmek için TODO: Replaces Tools içeren bölümü bulun ve sonraki iki satırın yorumunu kaldırın. Kodunuz aşağıdaki gibi görünmelidir:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

Bu adımda yapılması gereken tek kod değişikliği budur. Bu bölümün geri kalanında beceri ve araçların arkasındaki kavramlar açıklanmaktadır.

Beceri

Bir temsilci becerisi, ADK temsilcisinin belirli bir görevi yerine getirmek için kullanabileceği bağımsız bir işlev birimidir. Bir temsilci becerisi, Temsilci Becerisi spesifikasyonuna göre bir görev için gerekli talimatları, kaynakları ve araçları kapsar. Beceri yapısı, aracının işletim bağlamı penceresi üzerindeki etkiyi en aza indirmek için becerinin artımlı olarak yüklenmesine olanak tanır.

Maraton planlama aracısı için tanımlanmış 3 beceri vardır:

  1. gis-spatial-engineering: Maraton rotasını oluşturmak için GeoJSON verilerini işlemekten sorumludur.
  2. Harita: Yerleri ve hava durumu bilgilerini aramak için Google Haritalar araçlarını kullanın.
  3. race-director: Maraton rotasının planlama kurallarına uygun olduğunu doğrulayın.

Becerilerde komut dosyaları, ek öğeler ve referanslar olabilir.

Uygulama, tüm becerileri yükler ve planner_agent/tools.py'da araç olarak sunar. Bunun get_tools() işlevinde nasıl yapıldığına dikkat edin:

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

En ilgi çekici kısım, ADK'daki load_skill_from_dir yöntemidir. ADK'da beceri oluşturmanın bir başka yolu da satır içi oluşturmadır. Bu codelab'de kullanılmasa da şu şekilde görünür:

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

Eşleme araçları ekleme

Maraton planlayıcının rota oluşturmak için mekansal bağlama ihtiyacı vardır. Google Haritalar MCP (Model Context Protocol) sunucusunu entegre ederek bunu sağlayabilirsiniz.

planner_agent/tools.py bölümünde, MCP sunucusunun ApiRegistry aracıyla nasıl kaydedildiğine dikkat edin:

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

MCP araç setini ekleyen aracı, rota, yükseklik ve konum ayrıntıları için Google Haritalar'ı otomatik olarak sorgulama olanağı kazanır.

7. Aracıyı yerel olarak çalıştırma

Artık aracı, istemi ve araçları birbirine bağladığınıza göre aracı yerel olarak çalıştırın. Bu kez, adk web kullanacaksınız. Böylece Skill Load ve Tool Call etkinliklerini görebilirsiniz.

uv run adk web

Aşağıdakine benzer bir şey görmeniz gerekir.

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. Tarayıcınızı açın ve terminalde gösterilen URL'ye (genellikle http://localhost:8000) gidin.
  2. Sol üstteki açılır listede planner_agent simgesini seçin.
  3. Sohbet penceresinde aşağıdaki istemi gönderin:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Becerilerin yüklendiğini ve araçların çağrıldığını görmelisiniz. Birkaç dakika sonra ajan, maraton planı oluşturur.

Kullanıcı arayüzünüz aşağıdaki gibi görünmelidir:

ADK Web Kullanıcı Arayüzü

8. Aracıyı dağıtma

Aracının yerel olarak performansından memnun kaldığınızda, aracı Cloud Run'da güvenli bir şekilde barındıran Agent Engine'e dağıtabilirsiniz.

Aracı dağıtmak için ADK CLI dağıtım komutunu kullanın:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  planner_agent

Dağıtım tamamlandığında CLI, aracınız için güvenli bir şekilde barındırılan uç nokta çıkarır. Artık bu uç noktayı ön uç uygulamalarına, chatbot'lara veya diğer arka uç sistemlerine entegre edebilirsiniz. Ayrıca, aracı test etmek için Agent Runtime Playground'u da kullanabilirsiniz.

Çıkış şu şekilde görünür:

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

Aracıyla iletişim kurmak için sağlanan Python komut dosyasını kullanabilirsiniz.

  1. Örnek ortam dosyasını kopyalayın:
cp sample.env .env
  1. .env dosyasını açın ve GOOGLE_CLOUD_PROJECT alanını gerçek Google Cloud projesi kimliğinizle güncelleyin.

Dosya aşağıdaki gibi görünmelidir:

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. Projenizdeki temsilcileri listeleyebilirsiniz.
python main.py list

Aşağıdakine benzer bir şey görmeniz gerekir.

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Dağıtılan aracı kimliğine sahip olduğunuzda istem gönderebilirsiniz:

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

Aşağıdakine benzer bir çıkış alırsınız:

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

9. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu codelab sırasında oluşturulan kaynakları silin.

Dağıtım tarafından oluşturulan Cloud Run hizmetini silin:

python main.py delete --agent-id ${AGENT_ID}

Maps API anahtarını Secret Manager'da sakladıysanız gizli anahtarı silin:

gcloud secrets delete maps-api-key --project=$PROJECT_ID

Bu codelab için yeni bir Google Cloud projesi oluşturduysanız projeyle ilişkili tüm kaynakları ve API'leri kaldırmak için projenin tamamını silebilirsiniz:

gcloud projects delete $PROJECT_ID

10. Tebrikler

Tebrikler! ADK'yı kullanarak gelişmiş bir Maraton Planlayıcı Temsilcisi oluşturdunuz.

Öğrendikleriniz

  • Agent Development Kit (ADK) projesini başlatma
  • Modüler sistem istemleri için PromptBuilder'ı kullanma
  • MCP araçlarını ve ApiRegistry kullanarak harita oluşturma özelliklerini entegre etme
  • SkillToolset kullanarak becerileri koşullu olarak yükleme
  • Yerel olarak test etme ve Agent Engine'e dağıtma

Referans belgeleri