ADK ve A2UI ile Ön Uç Deneyimleri

1. Genel Bakış

Çoğu yapay zeka temsilcisi metinle yanıt verir. Bu codelab'de, aracınızın kullanıcı arayüzüyle yanıt vermesini sağlamak için A2UI'yı kullanacaksınız. Aracı, standart bileşenler kataloğunu kullanarak kartları, listeleri, düğmeleri ve formları JSON biçiminde açıklar. İstemci bunları kendi yerel widget'larıyla oluşturur. Bu nedenle, yeni düzenler için yeni ön uç kodu gerekmez.

Ajanı Agent Development Kit (ADK) ile oluşturacaksınız.

Ne oluşturacaksınız?

Üç aşamada bulut altyapısı kontrol paneli örneği:

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

ADK A2UI Temsilcisi

Neler öğreneceksiniz?

  • A2UI'nin işleyiş şekli: 18 temel öğe, kullanıcı arayüzü oluşturan mesajlar ve düz bileşen modeli
  • A2UI SDK'yı kullanarak bir ADK aracısı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ı
  • Cloud Shell yerine kodu kendi makinenizde çalıştırıyorsanız Python 3.12+ ve uv

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

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

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

2. Ortamınızı ayarlama

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ı nasıl kontrol edeceğinizi öğ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.

API'leri etkinleştir

Cloud Shell Düzenleyici araç çubuğunda Terminal ve Yeni Terminal'i tıklayın, ardından 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 aşağıdaki komutları çalıştırarak bu codelab için bir klasör oluşturun. Bu klasörün içinde, ajan kodunuz için a2ui_agent klasörü yer almalıdır. Ayrıca Agent Development Kit (ADK) ve A2UI SDK'yı yükleyin:

mkdir -p ~/adk-a2ui/a2ui_agent
cd ~/adk-a2ui
uv init --bare
uv add google-adk a2ui-agent-sdk

uv, bu codelab için izole bir Python ortamı oluşturur. Bu nedenle herhangi bir şeyi etkinleştirmeniz gerekmez. Python komutlarının önüne uv run ekleyin.

3. Ajanı oluşturma

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

Proje ayarlarınızı yapılandırma

Terminalde aşağıdaki komutu çalıştırarak projeniz ve konumunuzla a2ui_agent/.env oluşturun ve ADK'nın Google Cloud projeniz üzerinden Gemini'ı çağırmasını sağlayın. ADK bu dosyayı otomatik olarak yüklediğinden ayarlar yeni terminallerde de çalışır.

cat > ~/adk-a2ui/a2ui_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF

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 google.adk.models import Gemini
from google.genai import types
from .resources import get_resources

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    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. Ajanı 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ştirme 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:

uv run 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 Önizleme'yi seçerek tarayıcınızda ADK geliştirici kullanıcı arayüzünü 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. Bu kez daha fazla metin çıktısı alacaksınız:

Does anything need my attention?

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

ADK Text Agent

Yanıt doğru ancak çok uzun.

5. A2UI JSON'u oluşturma

Ardından, aracıyı düz metinden A2UI'ye geçirin.

A2UI Python SDK, sizin için sistem istemleri yazan bir istem oluşturucu içerir. Bu görev, LLM'ye A2UI bileşen kataloğunun tamamını, doğru özellik adlarını ve türlerini, ayrıca JSON yapısını öğretir.

Ajanı güncelleme

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

from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from google.adk.models.llm_response import LlmResponse
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    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,
)


def show_raw_json(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Show the A2UI JSON as text so you can read it, instead of rendering it."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if part.text:
            part.text = (
                part.text
                .replace("<a2ui-json>", "```json\n")
                .replace("</a2ui-json>", "\n```")
            )
    return llm_response


root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=show_raw_json,
)

show_raw_json, A2UI JSON'unu metin olarak gösterir. Böylece, bu JSON'u okuyabilirsiniz. Kullanıcı arayüzü oluşturmayı görmek için daha sonra kaldıracaksınız.

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

Bu codelab'de, adk web A2UI oluşturucunun desteklediği sürüm olan A2UI 0.8 sürümü (version="0.8") kullanılmaktadır.

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ştirici 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 aynı istemi gönderin:

What's running in my project?

Bu kez aracı, düz metin yerine A2UI JSON ile yanıt veriyor. Sohbet çıktısında, JSON kodu bloğunda beginRendering ve surfaceUpdate gibi yapılandırılmış mesajlar (bazen de dataModelUpdate) 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 show_raw_json, okunabilmesi için bunu metin olarak tutuyor. Ardından, bu JSON'un nasıl yapılandırıldığına bakacak ve gerçek kullanıcı arayüzü bileşenleri olarak oluşturmak için show_raw_json öğesini kaldıracaksınız.

7. A2UI'yi anlama

Ajanınızın az önce oluşturduğu JSON'a bakın. A2UI, kullanıcı arayüzü oluşturmak için üç tür mesaj kullanır. Ajanınızın çıkışında her zaman üçü de kullanılmayabilir:

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ı içeren (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 şekil

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, AudioPlayer

Giriş

TextField, DateTimeInput, MultipleChoice, CheckBox, Slider

İşlem

Düğme

Aracı, aynı bileşenlerden farklı düzenler (ör. göz atma görünümü, öncelikli kontrol paneli veya yapılandırma formu) oluşturur. Her biriyle ilgili ayrıntılar için bileşen referansına bakın.

8. A2UI bileşenlerini oluşturma

SDK, A2UI'yi standart etiketleriyle sarmalar. adk web bunları tanır ve bileşenleri yerleşik A2UI oluşturucusuyla oluşturur. Görmek için show_raw_json simgesini kaldırın.

Ajanı güncelleme

a2ui_agent/agent.py dosyasının içeriğini aşağıdakiyle değiştirin. Önceki adımdan farklı olarak show_raw_json işlevi, after_model_callback parametresi ve kullandığı iki içe aktarma işlemi kaldırıldı:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    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(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

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 daha önce gönderdiğiniz istemi tekrar 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 Temsilcisi

Ajanın aynı temel öğelerle 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

Üç istemde de aynı aracı, araç ve bileşenler kullanılır ancak her biri, istediğiniz şeye uygun farklı bir kullanıcı arayüzü oluşturur.

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 <YOUR_PROJECT_ID>

11. Tebrikler

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

Öğrendikleriniz

  • A2UI, 18 bildirimsel temel ve kullanıcı arayüzü oluşturan birkaç basit mesaj içeren bir protokoldür.
  • A2UI SDK, LLM'ye bileşen kataloğunu öğreten sistem istemleri oluşturur.
  • Aynı aracı, aracı ve temel öğeleri kullanarak farklı amaçlar için farklı kullanıcı arayüzleri oluşturma
  • 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

Referans belgeleri

Sonraki Adımlar

Gemini Enterprise Agent Ready (GEAR) ile kurumsal düzeyde ajanlar oluşturup dağıtmak için eğitim kaynaklarını inceleyin.