ADK ve A2UI ile Ön Uç Deneyimleri

1. Genel Bakış

Çoğu temsilci uygulaması düz metin döndürür. A2UI bunu değiştiriyor. Bu, aracınızın zengin ve etkileşimli arayüzler oluşturmasına olanak tanıyan 18 bildirime dayalı kullanıcı arayüzü temel öğesi içeren bir protokoldür. Müşteri, bunları yerel olarak oluşturur. Düzen başına yeni ön uç kodu gerekmez.

Bu codelab'de, ajanı oluşturmak için Agent Development Kit (ADK), kullanıcı arayüzünü oluşturmak için ise A2UI kullanılır.

Ne oluşturacaksınız?

Üç aşamada bulut altyapısı kontrol paneli:

Kaynak verilerini düz metin olarak döndüren bir standart aracı
Yapılandırılmış A2UI JSON'u ile aynı verileri döndüren bir A2UI aracısı
ADK geliştirme kullanıcı arayüzünde A2UI JSON'u etkileşimli kullanıcı arayüzü bileşenleri olarak görüntüleyen bir oluşturulmuş aracı

ADK A2UI Aracısı

Neler öğreneceksiniz?

A2UI'nin işleyiş şekli: 18 temel öğe, 3 ileti türü, düz bileşen modeli
A2UI SDK'yı kullanarak bir ADK aracından A2UI JSON oluşturmasını isteme
adk web'da A2UI bileşenleri nasıl oluşturulur?

İhtiyacınız olanlar

Faturalandırmanın etkin olduğu bir Google Cloud projesi
Chrome gibi bir web tarayıcısı
Python 3.12 veya daha yeni sürümler

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

Bu codelab'in tamamlanması yaklaşık 15-20 dakika sürer.

Bu kod laboratuvarında oluşturulan kaynakların maliyeti 5 ABD dolarından az olmalıdır.

2. Ortamınızı ayarlama

Google Cloud projesi oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
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 Düzenleyici'yi başlatma

Google Cloud Console'dan Cloud Shell oturumu başlatmak için Google Cloud Console'da Cloud Shell'i etkinleştir'i tıklayın.

Bu işlem, Google Cloud Console'unuzun alt bölmesinde bir oturum başlatır.

Düzenleyiciyi başlatmak için Cloud Shell penceresinin araç çubuğunda Open Editor'ı (Düzenleyiciyi Aç) tıklayın.

Ortam değişkenlerini ayarlama

Cloud Shell Düzenleyici araç çubuğunda Terminal ve Yeni Terminal'i tıklayın, ardından projenizi ve konumunuzu ayarlamak için aşağıdaki komutları çalıştırın ve ADK'yı Vertex AI'da Gemini'ı kullanacak şekilde yapılandırın.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

API'leri etkinleştir

Terminalde, gerekli API'leri etkinleştirmek için aşağıdaki komutu çalıştırın:

gcloud services enable aiplatform.googleapis.com

Bağımlıları yükleme

Terminalde, Agent Development Kit'in (ADK) en son sürümünü yüklemek için aşağıdaki komutu çalıştırın:

pip install -U google-adk a2ui-agent-sdk
export PATH="$HOME/.local/bin:$PATH"

3. Aracıyı oluşturma

Düz metin döndüren standart bir ADK temsilcisiyle başlayın. Çoğu temsilci uygulaması günümüzde bu şekilde görünür.

Temsilci klasörü oluşturma

Temsilcinizin ve araçlarınızın kaynak kodunu içerecek a2ui_agent adlı bir klasör oluşturun.

Aracı ve sahte verileri tanımlama

Aşağıdaki içeriklerle a2ui_agent/resources.py oluşturun. Bu araç, durumlarıyla birlikte bulut kaynaklarının bir listesini döndürür.

RESOURCES = [
    {
        "name": "auth-service",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "healthy",
        "cpu": "2 vCPU",
        "memory": "1 GiB",
        "instances": 3,
        "url": "https://auth-service-abc123.run.app",
        "last_deployed": "2026-04-18T14:22:00Z",
    },
    {
        "name": "events-db",
        "type": "Cloud SQL",
        "region": "us-east1",
        "status": "warning",
        "tier": "db-custom-8-32768",
        "storage": "500 GB SSD",
        "connections": 195,
        "version": "PostgreSQL 16",
        "issue": "Storage usage at 92%",
    },
    {
        "name": "analytics-pipeline",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "error",
        "cpu": "2 vCPU",
        "memory": "4 GiB",
        "instances": 0,
        "url": "https://analytics-pipeline-ghi789.run.app",
        "last_deployed": "2026-04-10T16:45:00Z",
        "issue": "CrashLoopBackOff: OOM killed",
    },
]

def get_resources() -> list[dict]:
    """Get all cloud resources in the current project.
    Returns a list of cloud infrastructure resources including their
    name, type, region, status, and type-specific details.
    Status is one of: healthy, warning, error. Resources with
    warning or error status include an 'issue' field describing
    the problem.
    """
    return RESOURCES

Temsilciyi tanımlama

Aşağıdaki içeriklerle a2ui_agent/agent.py oluşturun:

from google.adk.agents import Agent
from .resources import get_resources

root_agent = Agent(
    model="gemini-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that reports on project resources.",
    instruction=(
        "You are a cloud infrastructure assistant. When users ask about their "
        "cloud resources, use the get_resources tool to fetch the current state. "
        "Summarize the results clearly in plain text."
    ),
    tools=[get_resources],
)

4. Temsilciyi test etme

ADK, test için tarayıcıda aracınızla etkileşim kurmak ve istem göndermek üzere kullanabileceğiniz bir geliştirici kullanıcı arayüzü içerir.

ADK geliştirici kullanıcı arayüzünü başlatma

Cloud Shell Düzenleyici terminalinizde aşağıdaki komutu çalıştırarak ADK geliştirme kullanıcı arayüzünü başlatın:

adk web --port 8080 --allow_origins "*" --reload_agents

Aşağıdakine benzer bir mesaj görürsünüz:

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

ADK geliştirici kullanıcı arayüzünü açma

Yerel test URL'sini Ctrl veya Cmd tuşunu basılı tutarak tıklayarak ya da Web Önizlemesi düğmesini tıklayıp 8080 bağlantı noktasında önizle'yi seçerek ADK geliştirici kullanıcı arayüzünü tarayıcınızda açabilirsiniz.

ADK geliştirici kullanıcı arayüzünü görüntülerken açılır menüden a2ui_agent simgesini seçin.

Örnek istemler gönderme

Ajana örnek istem gönderin:

What's running in my project?

Şimdi başka bir örnek istem deneyin. Daha fazla metin çıktısı alacaksınız:

Does anything need my attention?

Konuşmanız aşağıdakine benzer şekilde görünmelidir:

ADK Text Agent

Metin duvarı görürsünüz. Doğru ancak iyi bir kullanıcı deneyimi sunmuyor.

5. A2UI JSON'u oluşturma

Ajan, metin dökümü yapmak yerine bir kullanıcı arayüzünü açıklayabilseydi ne olurdu? A2UI, temsilcilerin 18 temel öğeden oluşan bir katalogdan etkileşimli arayüzler oluşturmasına olanak tanıyan bir protokoldür. Müşteri, bunları yerel olarak oluşturur.

A2UI Python SDK, sizin için sistem istemleri oluşturan bir şema yöneticisi içerir. Bu, LLM'ye tam A2UI bileşen kataloğunu, doğru özellik adlarını ve türlerini ve JSON yapısını öğretir.

Ajanı güncelleme

a2ui_agent/agent.py dosyasının içeriğini aşağıdakiyle değiştirin:

from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

schema_manager = A2uiSchemaManager(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = schema_manager.generate_system_prompt(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model="gemini-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

generate_system_prompt() yöntemi, rol açıklamanızı tam A2UI JSON şeması ve birkaç görevli örnekle birleştirir. Böylece LLM, çıkışını nasıl biçimlendireceğini tam olarak bilir. Bileşen kataloğunu elle yazmanız gerekmez.

6. JSON çıkışını test etme

ADK geliştirici kullanıcı arayüzünü daha önce çalıştırdıysanız arayüz, aracınızda yaptığınız değişiklikleri otomatik olarak yeniden yükler.

a2ui_agent simgesini seçin, ADK geliştirme kullanıcı arayüzünün sağ üst kısmındaki +Yeni Oturum'u tıklayarak yeni bir oturum başlatın ve ardından daha önce gönderdiğiniz istemi tekrar gönderin:

What's running in my project?

Bu kez temsilci, düz metin yerine A2UI JSON ile yanıt veriyor. Sohbet çıktısında beginRendering, surfaceUpdate ve dataModelUpdate içeren yapılandırılmış mesajlar görürsünüz.

ADK A2UI JSON

JSON, kartlar, simgeler ve düğmeler içeren zengin bir kullanıcı arayüzünü açıklıyor ancak adk web bunu ham metin olarak gösteriyor. Bir sonraki adımda, bunu gerçek kullanıcı arayüzü bileşenleri olarak oluşturacaksınız.

7. A2UI'yi anlama

Temsilcinizin az önce oluşturduğu JSON'a bakın. Üç tür mesaj içerdiğini fark edeceksiniz. Her A2UI yanıtı aynı yapıyı izler:

1. beginRendering

Bir oluşturma yüzeyi oluşturur ve kök bileşeni adlandırır:

{"beginRendering": {"surfaceId": "default", "root": "main-column"}}

2. surfaceUpdate

Bileşen ağacını, kimlik referanslarıyla (iç içe yerleştirilmemiş) düz liste olarak gönderir:

{"surfaceUpdate": {"surfaceId": "default", "components": [
  {"id": "main-column", "component": {"Column": {"children": {"explicitList": ["title", "card1"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "My Resources"}, "usageHint": "h1"}}},
  {"id": "card1", "component": {"Card": {"child": "card1-content"}}},
  {"id": "card1-content", "component": {"Text": {"text": {"path": "service_name"}}}}
]}}

3. dataModelUpdate

Verileri yapıdan ayrı olarak gönderir:

{"dataModelUpdate": {"surfaceId": "default", "contents": [
  {"key": "service_name", "valueString": "auth-service"},
  {"key": "status", "valueString": "healthy"}
]}}

Bileşenler, {"path": "key"} kullanılarak verilere bağlanır. Bileşen ağacını yeniden göndermeden verileri güncelleyebilirsiniz.

18 temel öğe

Kategori	Bileşenler
Düzen	Kart, Sütun, Satır, Liste, Sekmeler, Ayırıcı, Modal
Görüntülü reklam ağı	Metin, Resim, Simge, Video, Ses Çalar
Giriş	TextField, DateTimeInput, MultipleChoice, CheckBox, Slider
İşlem	Düğme

Aracı, aynı katalogdan farklı düzenler oluşturur. Her birimle ilgili tüm ayrıntılar için bileşen referansına bakın. Göz atma görünümü, öncelikli kontrol paneli ve yapılandırma formu aynı 18 temel öğeyi kullanır. Yeni ön uç bileşenleri gerekmez.

8. A2UI bileşenlerini oluşturma

Ajan, geçerli A2UI JSON'u oluşturuyor ancak adk web bunu ham metin olarak gösteriyor. Bunu gerçek kullanıcı arayüzü bileşenleri olarak oluşturmak için aracının A2UI JSON çıkışını adk web'nın yerleşik oluşturucusunun beklediği biçime dönüştüren küçük bir yardımcı programa ihtiyacınız vardır.

A2UI oluşturma yardımcı programını oluşturun

Aşağıdaki içeriklerle a2ui_agent/a2ui_utils.py oluşturun:

import json
import re
from google.genai import types
from google.adk.agents.callback_context import CallbackContext
from google.adk.models.llm_response import LlmResponse

def _wrap_a2ui_part(a2ui_message: dict) -> types.Part:
    """Wrap a single A2UI message for rendering in adk web."""
    datapart_json = json.dumps({
        "kind": "data",
        "metadata": {"mimeType": "application/json+a2ui"},
        "data": a2ui_message,
    })
    blob_data = (
        b"<a2a_datapart_json>"
        + datapart_json.encode("utf-8")
        + b"</a2a_datapart_json>"
    )
    return types.Part(
        inline_data=types.Blob(
            data=blob_data,
            mime_type="text/plain",
        )
    )

def a2ui_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Convert A2UI JSON in text output to rendered components."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if not part.text:
            continue
        text = part.text.strip()
        if not text:
            continue
        if not any(k in text for k in ("beginRendering", "surfaceUpdate", "dataModelUpdate")):
            continue
        # Strip markdown fences
        if text.startswith("```"):
            text = text.split("\n", 1)[-1]
            if text.endswith("```"):
                text = text[:-3].strip()
        # Find where JSON starts (skip conversational prefix)
        json_start = None
        for i, ch in enumerate(text):
            if ch in ("[", "{"):
                json_start = i
                break
        if json_start is None:
            continue
        json_text = text[json_start:]
        # raw_decode parses JSON and ignores trailing text
        try:
            parsed, _ = json.JSONDecoder().raw_decode(json_text)
        except json.JSONDecodeError:
            # Handle concatenated JSON objects: {"a":1} {"b":2}
            try:
                fixed = "[" + re.sub(r'\}\s*\{', '},{', json_text) + "]"
                parsed, _ = json.JSONDecoder().raw_decode(fixed)
            except json.JSONDecodeError:
                continue
        if not isinstance(parsed, list):
            parsed = [parsed]
        a2ui_keys = {"beginRendering", "surfaceUpdate", "dataModelUpdate", "deleteSurface"}
        a2ui_messages = [msg for msg in parsed if isinstance(msg, dict) and any(k in msg for k in a2ui_keys)]
        if not a2ui_messages:
            continue
        new_parts = [_wrap_a2ui_part(msg) for msg in a2ui_messages]
        return LlmResponse(
            content=types.Content(role="model", parts=new_parts),
            custom_metadata={"a2a:response": "true"},
        )
    return None

Bu yardımcı program iki işlem yapar:

Ajanın metin çıkışından A2UI JSON'u çıkarır.
Her A2UI mesajını, adk web'nın yerleşik A2UI oluşturucusunun beklediği biçimde sarmalar.

Ajanı güncelleme

a2ui_agent/agent.py dosyasının içeriğini aşağıdakiyle değiştirin. Önceki adımdan tek fark, a2ui_callback ve temsilcideki after_model_callback parametresinin içe aktarılmasıdır:

from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources
from .a2ui_utils import a2ui_callback

schema_manager = A2uiSchemaManager(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = schema_manager.generate_system_prompt(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model="gemini-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=a2ui_callback,
)

9. Oluşturulan kullanıcı arayüzünü test etme

ADK geliştirici kullanıcı arayüzünü daha önce çalıştırdıysanız arayüz, aracınızda yaptığınız değişiklikleri otomatik olarak yeniden yükler.

Tarayıcı sekmesini yenileyin, a2ui_agent simgesini seçin, ardından ADK geliştirici kullanıcı arayüzünün sağ üst kısmındaki +Yeni Oturum'u tıklayarak yeni bir oturum başlatın ve aynı istemi gönderin:

What's running in my project?

Bu kez adk web, A2UI bileşenlerini gerçek kullanıcı arayüzü olarak oluşturur: durum göstergeleri, kaynak ayrıntıları ve işlem düğmeleri içeren kartlar.

ADK A2UI Aracısı

Temsilcinin aynı temel öğeler grubundan farklı bir kullanıcı arayüzü oluşturup oluşturmadığını görmek için farklı bir istem deneyin:

Does anything need my attention?

Son olarak, yeni bir hizmet dağıtmak için farklı bir kullanıcı arayüzü oluşturmak üzere başka bir istem deneyin:

I need to deploy a new service

Her istem aynı aracıya, aynı araca ve aynı 18 temel öğeye gider. Ancak her istem, farklı bir amaç için farklı bir kullanıcı arayüzüyle sonuçlanır.

10. Temizleme

Yerel sunucuların çalışır durumda kalmasını önlemek için kaynakları temizleyin:

adk web komutunun çalıştırıldığı terminalde, aracı sunucusunu durdurmak için Ctrl+C tuşlarına basın.

Bu codelab için özel olarak bir proje oluşturduysanız projenin tamamını silebilirsiniz:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

11. Tebrikler

A2UI kullanarak zengin ve etkileşimli kullanıcı arayüzü oluşturan bir ADK temsilcisi oluşturdunuz.

Öğrendikleriniz

A2UI, 18 bildirimsel temel ve 3 mesaj türü içeren bir protokoldür.
A2UI SDK, LLM'ye bileşen kataloğunu öğreten sistem istemleri oluşturur.
Aynı aracı, aracı ve temel öğeler, farklı amaçlar için farklı kullanıcı arayüzleri oluşturur.
A2UI bileşenleri, geliştirme sırasında doğrudan adk web içinde oluşturulabilir.

Üretim ön ucu oluşturma

Bu codelab'de, geliştirme ve test için A2UI'yi adk web içinde oluşturuyorsunuz.

Üretim için resmi A2UI oluşturuculardan birini kullanarak bir ön uç oluşturursunuz:

Platform	Oluşturucu	Yükle
Web (React)	`@a2ui/react`	`npm install @a2ui/react`
Web (Lit)	`@a2ui/lit`	`npm install @a2ui/lit`
Web (Angular)	`@a2ui/angular`	`npm install @a2ui/angular`
Mobil/Masaüstü	Flutter GenUI SDK'sı	Başlarken

ADK ve A2UI ile Ön Uç Deneyimleri

1. Genel Bakış

Ne oluşturacaksınız?

Neler öğreneceksiniz?

İhtiyacınız olanlar

2. Ortamınızı ayarlama

Google Cloud projesi oluşturma

Cloud Shell Düzenleyici'yi başlatma

Ortam değişkenlerini ayarlama

API'leri etkinleştir

Bağımlıları yükleme

3. Aracıyı oluşturma

Temsilci klasörü oluşturma

Aracı ve sahte verileri tanımlama

Temsilciyi tanımlama

4. Temsilciyi test etme

ADK geliştirici kullanıcı arayüzünü başlatma

ADK geliştirici kullanıcı arayüzünü açma

Örnek istemler gönderme

5. A2UI JSON'u oluşturma

Ajanı güncelleme

6. JSON çıkışını test etme

7. A2UI'yi anlama

1. beginRendering

2. surfaceUpdate

3. dataModelUpdate

18 temel öğe

8. A2UI bileşenlerini oluşturma

A2UI oluşturma yardımcı programını oluşturun

Ajanı güncelleme

9. Oluşturulan kullanıcı arayüzünü test etme

10. Temizleme

11. Tebrikler

Öğrendikleriniz

Üretim ön ucu oluşturma

Referans belgeleri