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:
- 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ştirici kullanıcı arayüzünde A2UI JSON'ı etkileşimli kullanıcı arayüzü bileşenleri olarak gösteren bir oluşturulmuş ajan

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
- 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ı 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:

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.

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.

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 webkomutunun ç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 webiç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) |
|
|
Web (Lit) |
|
|
Web (Angular) |
|
|
Mobil/Masaüstü | Flutter GenUI SDK'sı |
Referans belgeleri
- A2UI spesifikasyonu ve dokümanları
- A2UI GitHub deposu
- A2UI oluşturucular
- ADK belgeleri
- ADK A2UI entegrasyonu
Sonraki Adımlar
Gemini Enterprise Agent Ready (GEAR) ile kurumsal düzeyde ajanlar oluşturup dağıtmak için eğitim kaynaklarını inceleyin.