1. Visão geral
A maioria dos agentes de IA responde com texto. Neste codelab, você vai usar a A2UI para que o agente responda com uma interface do usuário. O agente descreve cards, listas, botões e formulários em JSON, usando um catálogo de componentes padrão, e o cliente os renderiza com os próprios widgets nativos. Assim, novos layouts não precisam de um novo código de front-end.
Você vai criar o agente com o Kit de Desenvolvimento de Agente (ADK).
O que você vai criar
Um painel simulado de infraestrutura em nuvem em três estágios:
- Um agente padrão que retorna dados de recursos como texto simples.
- Um agente A2UI que retorna os mesmos dados que o JSON estruturado da A2UI
- Um agente renderizado que mostra o JSON A2UI como componentes interativos da interface na interface de desenvolvimento do ADK.

O que você vai aprender
- Como a A2UI funciona: 18 primitivas, as mensagens que criam uma interface e o modelo de componente simples
- Como usar o SDK A2UI para solicitar que um agente do ADK gere JSON A2UI
- Como renderizar componentes da A2UI em
adk web
O que é necessário
- Tenha um projeto do Google Cloud com o faturamento ativado.
- Um navegador da web, como o Chrome
- Python 3.12+ e uv, se você executar o código na sua própria máquina em vez do Cloud Shell
Este codelab é destinado a desenvolvedores intermediários que têm alguma familiaridade com Python e o Google Cloud.
Este codelab leva aproximadamente 20 minutos para ser concluído.
Os recursos criados neste codelab custam menos de US $5.
2. Configurar o ambiente
Criar um projeto do Google Cloud
- No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
- Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
Iniciar o editor do Cloud Shell
Para iniciar uma sessão do Cloud Shell no console do Google Cloud, clique em Ativar o Cloud Shell.
Isso inicia uma sessão no painel inferior do console do Google Cloud.
Para iniciar o editor, clique em Abrir editor na barra de ferramentas da janela do Cloud Shell.
Ativar APIs
Na barra de ferramentas do Editor do Cloud Shell, clique em Terminal e Novo terminal. Em seguida, execute o comando a seguir para ativar as APIs necessárias:
gcloud services enable aiplatform.googleapis.com
Instalar dependências
No terminal, execute os seguintes comandos para criar uma pasta para este codelab, com uma pasta a2ui_agent dentro dela para o código do agente, e instale o Kit de Desenvolvimento de Agente (ADK) e o SDK A2UI:
mkdir -p ~/adk-a2ui/a2ui_agent cd ~/adk-a2ui uv init --bare uv add google-adk a2ui-agent-sdk
O uv cria um ambiente Python isolado para este codelab, então você não precisa ativar nada. Adicione o prefixo uv run aos comandos do Python.
3. Criar o agente
Comece com um agente padrão do ADK que retorne texto simples. É assim que a maioria dos apps de agente se parece hoje.
Configurar as definições do projeto
No terminal, execute o comando a seguir para criar a2ui_agent/.env com seu projeto e local e para que o ADK chame o Gemini pelo seu projeto na nuvem do Google Cloud. O ADK carrega esse arquivo automaticamente, então as configurações também funcionam em novos terminais.
cat > ~/adk-a2ui/a2ui_agent/.env <<EOF GOOGLE_CLOUD_PROJECT=$(gcloud config get project) GOOGLE_CLOUD_LOCATION=global GOOGLE_GENAI_USE_ENTERPRISE=True EOF
Definir ferramenta e dados simulados
Crie a2ui_agent/resources.py com este conteúdo: Essa ferramenta retorna uma lista de recursos da nuvem com o status deles.
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
Definir o agente
Crie a2ui_agent/agent.py com o conteúdo abaixo:
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. Testar o agente
O ADK inclui uma interface de desenvolvimento que pode ser usada para interagir e enviar comandos ao agente em um navegador para teste.
Iniciar a interface de desenvolvimento do ADK
No terminal do editor do Cloud Shell, execute o comando a seguir para iniciar a interface de desenvolvimento do ADK:
uv run adk web --port 8080 --allow_origins "*" --reload_agents
Você verá uma mensagem semelhante a esta:
+-----------------------------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://127.0.0.1:8080. | +-----------------------------------------------------------------------------+
Abrir a interface de desenvolvimento do ADK
Para abrir a interface de desenvolvimento do ADK no navegador, pressione Ctrl ou Cmd e clique no URL de teste local. Outra opção é clicar no botão Visualização na Web e selecionar Visualizar na porta 8080.
Depois de abrir a interface de desenvolvimento do ADK, selecione a2ui_agent no menu suspenso.
Enviar exemplos de comandos
Envie um exemplo de comando para o agente:
What's running in my project?
Agora tente outro comando de exemplo para receber mais texto:
Does anything need my attention?
Sua conversa será parecida com esta:

A resposta está correta, mas é um texto muito longo.
5. Gerar JSON A2UI
Em seguida, mude o agente de texto simples para A2UI.
O SDK Python A2UI inclui um gerador de comandos que escreve comandos do sistema para você. Ele ensina ao LLM o catálogo completo de componentes da A2UI, os nomes e tipos de propriedades corretos e a estrutura JSON.
Atualizar o agente
Substitua os conteúdos de a2ui_agent/agent.py pelo seguinte:
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,
)
O show_raw_json mostra o JSON do A2UI como texto para que você possa ler. Você vai remover isso mais tarde para ver a renderização da interface.
O método prompt_generator.generate() combina sua descrição de função com o esquema JSON completo da A2UI e exemplos com poucos exemplos (few-shot) para que o LLM saiba exatamente como formatar a saída. Não é preciso escrever o catálogo de componentes manualmente.
Este codelab usa a versão 0.8 do A2UI (version="0.8"), que é a versão compatível com o renderizador adk web do A2UI.
6. Testar a saída JSON
Se você ainda tiver a interface de desenvolvimento do ADK em execução, ela vai recarregar automaticamente as mudanças feitas no seu agente.
Selecione a2ui_agent, inicie uma nova sessão clicando em +Nova sessão no canto superior direito da interface de desenvolvimento do ADK e envie o mesmo comando de antes:
What's running in my project?
Desta vez, o agente responde com JSON A2UI em vez de texto simples. Você vai encontrar mensagens estruturadas, como beginRendering e surfaceUpdate (e às vezes dataModelUpdate), na saída do chat, em um bloco de código JSON.

O JSON descreve uma interface avançada com cards, ícones e botões, mas o show_raw_json mantém o texto para que você possa ler. Em seguida, você vai analisar a estrutura desse JSON e remover show_raw_json para renderizar como componentes reais da interface.
7. Entender o A2UI
Confira o JSON que o agente acabou de gerar. A A2UI tem três tipos de mensagens para criar uma interface. A saída do seu agente pode não usar os três sempre:
1. beginRendering
Cria uma superfície de renderização e nomeia o componente raiz:
{"beginRendering": {"surfaceId": "default", "root": "main-column"}}
2. surfaceUpdate
Envia a árvore de componentes como uma lista simples com referências de ID (não aninhadas):
{"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
Envia os dados separadamente da estrutura:
{"dataModelUpdate": {"surfaceId": "default", "contents": [
{"key": "service_name", "valueString": "auth-service"},
{"key": "status", "valueString": "healthy"}
]}}
Os componentes são vinculados aos dados usando {"path": "key"}. É possível atualizar os dados sem reenviar a árvore de componentes.
Os 18 primitivos
Categoria | Componentes |
Layout | Card, Column, Row, List, Tabs, Divider, Modal |
Display | Texto, imagem, ícone, vídeo, AudioPlayer |
Entrada | TextField, DateTimeInput, MultipleChoice, CheckBox, Slider |
Ação | Botão |
O agente cria layouts diferentes, como uma visualização de navegação, um painel de prioridade ou um formulário de configuração, com esses mesmos componentes. Consulte a referência de componentes para mais detalhes sobre cada um deles.
8. Renderizar componentes A2UI
O SDK encapsula a A2UI em tags padrão. O adk web os reconhece e renderiza os componentes com o renderizador A2UI integrado. Para conferir, remova show_raw_json.
Atualizar o agente
Substitua o conteúdo de a2ui_agent/agent.py pelo seguinte: As únicas mudanças da etapa anterior são que a função show_raw_json, o parâmetro after_model_callback e as duas importações usadas foram removidos:
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. Testar a interface renderizada
Se você ainda tiver a interface de desenvolvimento do ADK em execução, ela vai recarregar automaticamente as mudanças feitas no seu agente.
Atualize a guia do navegador, selecione a2ui_agent e inicie uma nova sessão clicando em +Nova sessão no canto superior direito da interface de desenvolvimento do ADK. Envie o mesmo comando de antes:
What's running in my project?
Desta vez, o adk web renderiza os componentes da A2UI como uma interface real: cards com indicadores de status, detalhes de recursos e botões de ação.

Tente um comando diferente para ver como o agente cria uma interface diferente com o mesmo conjunto de primitivos:
Does anything need my attention?
Por fim, tente outro comando para gerar uma interface diferente e implantar um novo serviço:
I need to deploy a new service
Todos os três comandos usam o mesmo agente, ferramenta e componentes, mas cada um produz uma interface diferente que se adapta ao que você pediu.
10. Limpeza
Para evitar deixar servidores locais em execução, limpe os recursos:
- No terminal que executa
adk web, pressione Ctrl+C para interromper o servidor do agente.
Se você criou um projeto especificamente para este codelab, exclua o projeto inteiro:
gcloud projects delete <YOUR_PROJECT_ID>
11. Parabéns
Você criou um agente do ADK que gera uma interface interativa e avançada usando o A2UI.
O que você aprendeu
- O A2UI é um protocolo com 18 primitivos declarativas e algumas mensagens simples que criam uma interface.
- O SDK A2UI gera comandos do sistema que ensinam o catálogo de componentes ao LLM.
- O mesmo agente, ferramenta e primitivas compõem diferentes interfaces do usuário para diferentes objetivos.
- Os componentes A2UI podem ser renderizados diretamente em
adk webdurante o desenvolvimento.
Criar um front-end de produção
Neste codelab, você renderizou a A2UI em adk web para desenvolvimento e testes.
Para produção, crie um front-end usando um dos renderizadores oficiais da A2UI:
Plataforma | Renderizador | Instalar |
Web (React) |
|
|
Web (Lit) |
|
|
Web (Angular) |
|
|
Dispositivo móvel/computador | SDK GenUI do Flutter |
Documentos de referência
- Especificação e documentos da A2UI
- Repositório do GitHub do A2UI
- Renderizadores A2UI
- Documentação do ADK
- Integração do ADK A2UI
A seguir
Conheça os recursos de aprendizado para criar e implantar agentes de nível empresarial com o Gemini Enterprise Agent Ready (GEAR).