Experiências de front-end com ADK e A2UI

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:

  1. Um agente padrão que retorna dados de recursos como texto simples.
  2. Um agente A2UI que retorna os mesmos dados que o JSON estruturado da A2UI
  3. Um agente renderizado que mostra o JSON A2UI como componentes interativos da interface na interface de desenvolvimento do ADK.

Agente A2UI 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

  1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
  2. 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:

Agente de texto do ADK

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.

JSON do ADK A2UI

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.

Agente A2UI do ADK

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 web durante 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)

@a2ui/react

npm install @a2ui/react

Web (Lit)

@a2ui/lit

npm install @a2ui/lit

Web (Angular)

@a2ui/angular

npm install @a2ui/angular

Dispositivo móvel/computador

SDK GenUI do Flutter

Primeiros passos

Documentos de referência

A seguir

Conheça os recursos de aprendizado para criar e implantar agentes de nível empresarial com o Gemini Enterprise Agent Ready (GEAR).