Guia do desenvolvedor: como enriquecer agentes com interfaces dinâmicas usando A2UI e Gemini Enterprise

Se você já construiu um chatbot, conhece este diálogo:

Usuário: "Reserve uma mesa para dois amanhã às 19h."
Agente: "Ok, para qual dia?"
Usuário: "Amanhã."
Agente: "Que horário?"

Um date picker teria resolvido isso em um toque. Mas, até recentemente, os agentes não tinham uma forma padronizada de renderizar um date picker — ou um mapa, ou uma lista de múltipla seleção — dentro da superfície de chat onde eles vivem. Só conseguiam retornar texto ou Markdown para uso genérico.

Hoje, vamos mostrar como resolver isso com o A2UI, um protocolo aberto para interfaces de usuário controladas por agentes, e como integrar um agente habilitado para A2UI com o Gemini Enterprise (GE), para que seu agente renderize UI rica e interativa nativamente na superfície de chat do GE — e também no seu próprio frontend customizado, se desejar. Usaremos como referência um agente de busca de restaurantes funcional, construído com o Google Agent Development Kit (ADK), o protocolo A2A e o Gemini. O código-fonte completo está no GitHub e há um vídeo de demonstração de 2 minutos.

Assista ao vídeo de demonstração (2 min)

Por que agentes que só falam texto são um problema?

A maioria dos frameworks de agentes hoje retorna strings. Isso funciona para respostas curtas, mas quebra rapidamente:

• Preenchimento de slots multi-turn (data, hora, número de pessoas) queima turnos e paciência.
• Escolhas entre opções (qual restaurante? qual plano de seguro?) viram longas listas com bullets que o usuário precisa copiar e colar de volta.
• Informação espacial (localizações, rotas, plantas baixas) é reduzida a endereços.

Desenvolvedores tentaram contornar isso enviando fragmentos de HTML ou JavaScript, mas isso introduz riscos reais: cross-site scripting, injeção de UI de um agente remoto que você não controla totalmente e desalinhamento visual com o design system da aplicação hospedeira. O que se precisa é de uma forma de transmitir UI que seja segura como dados e expressiva como código.

O que é A2UI e como resolve isso?

A2UI é um protocolo aberto, introduzido pelo Google e co-desenvolvido com a equipe do Flutter e os times de produto por trás do Gemini Enterprise. Em vez de retornar texto ou HTML, um agente retorna um payload JSON que descreve uma UI: uma árvore de componentes (Card, Text, Button, ChoicePicker, Image, …) e um modelo de dados separado contendo os valores que esses componentes exibem.

Três propriedades tornam isso útil na prática:

• Declarativo, não executável. O payload é dado. O cliente só renderiza componentes de um catálogo pré-aprovado, então um agente remoto não pode injetar código arbitrário ou roubar credenciais através de um widget de UI.
• Amigável para streaming. O formato é uma lista plana de pequenas mensagens JSON, então o LLM pode emiti-las incrementalmente e o cliente pode renderizar conforme chegam.
• Independente de framework. A mesma resposta do agente renderiza via Lit, Angular, Flutter ou mobile nativo. O agente não sabe — nem se importa — o que está do outro lado.

A2UI também é independente de transporte. As mensagens viajam dentro de qualquer pipe que você já usa: A2A JSON-RPC, AG-UI, WebSockets, SSE. Em nossa implementação de referência, o A2UI viaja dentro do protocolo A2A como objetos DataPart com o MIME type application/json+a2ui.

Onde o A2UI se encaixa na stack?

A2UI é uma peça de uma stack de quatro camadas. A confusão geralmente vem de misturar essas camadas — cada uma faz um trabalho diferente:

Camada	Responsabilidade	Exemplos
App experience	Shell do cliente e estado da conversa — janela de chat, caixa de entrada, histórico de mensagens	CopilotKit, AG-UI
Pixel drawing	Transformar descrições de componentes em UI renderizada	Lit, Flutter, Angular
Conversation pipeline	Transporte cliente-servidor — enviar mensagens, receber respostas	Protocolo A2A
Cargo (formato de dados)	A coisa que flui pelo pipeline e descreve a UI	A2UI

Lendo de cima para baixo: CopilotKit/AG-UI é responsável pela experiência do app. Lit/Flutter/Angular pela renderização. Enquanto CopilotKit e AG-UI oferecem abstrações valiosas, eles são estritamente opcionais para implementar A2UI. Nessa arquitetura, A2A serve como o pipeline de conversação subjacente, enquanto A2UI representa a carga estruturada que realmente trafega por esse pipe.

Essa separação é a razão pela qual o mesmo payload A2UI renderiza identicamente em três formatos de implantação muito diferentes:

• Aplicação web sob medida — um shell customizado (como o frontend/ Lit do repositório de referência) mais um renderizador A2UI customizado.
• App CopilotKit / AG-UI — CopilotKit gerencia o shell de chat, um renderizador A2UI é registrado dentro dele para cards ricos.
• Gemini Enterprise — o GE é o shell, o renderizador e o cliente de transporte. Você só constrói o agente.

Portanto, para o caminho GE, a stack se reduz a duas camadas que você controla: o endpoint A2A (seu agente) e a carga A2UI que ele emite. As outras duas camadas são responsabilidade do GE. CopilotKit e AG-UI são ótimos se você está construindo um produto de UI standalone em outro lugar — mas estão fora do escopo para incorporar um agente dentro do Gemini Enterprise.

Quais padrões de revisão existem?

O protocolo evolui rapidamente, e diferentes clientes suportam diferentes revisões. Dois padrões são comuns hoje:

• Inline pattern — o agente envia uma árvore de componentes com os dados embutidos em cada componente (o padrão que o Gemini Enterprise renderiza atualmente).
• Decoupled pattern — o agente envia a árvore de componentes e o modelo de dados como mensagens separadas, permitindo que turnos subsequentes atualizem um sem reenviar o outro. Isso reduz tokens e latência em conversas longas e é a direção para onde o protocolo está caminhando.

O repositório de referência atende ambos os padrões a partir de um backend, escolhendo qual emitir por requisição com base no cabeçalho X-A2A-Extensions do cliente. Conforme novas revisões forem lançadas, você adiciona outro catálogo e o mesmo padrão de negociação continua funcionando.

Como o A2UI funciona dentro do Gemini Enterprise?

O Gemini Enterprise já vem com um renderizador A2UI embutido. Para o desenvolvedor, a história de integração é curta:

1. Construa seu agente A2A, incorporando um catálogo A2UI e payloads de exemplo junto com as definições de ferramentas regulares.
2. Registre o agente no Gemini Enterprise como um endpoint A2A. (Use make register-gemini-enterprise no repositório de referência.)
3. Um administrador do GE compartilha o agente com os colaboradores, como qualquer outro agente no catálogo do GE.

Em runtime, o fluxo é o seguinte:

1. O usuário digita uma requisição no chat do GE. O GE chama o endpoint A2A do seu agente e envia junto o próprio catálogo A2UI do GE — a lista de componentes de UI que o GE sabe renderizar.
2. Seu agente decide se um widget de UI é a resposta certa. Se sim, ele emite uma mensagem JSON A2UI (ex.: um ChoicePicker de opções de restaurante). Se não, cai para texto. Ambos podem coexistir na mesma resposta.
3. O GE recebe o JSON, valida contra seu catálogo e renderiza o widget nativamente no próprio design language do GE — então ele visualmente se alinha ao resto da superfície de chat.
4. Quando o usuário interage com o widget (seleciona três opções, escolhe uma data), o GE serializa a interação de volta em JSON e envia para seu agente como o próximo turno. Seu agente processa entrada estruturada, não texto livre.

Um ponto importante: como seu agente não envia seu próprio renderizador para o GE, você não precisa escolher um framework frontend para começar. Seu endpoint A2A pode rodar em qualquer lugar — Cloud Run, GKE, on-prem — e o GE cuida da renderização.

Exemplo de arquitetura de alto nível

A implementação de referência é um backend ADK no Cloud Run projetado para se conectar perfeitamente ao Gemini Enterprise.

• O Gemini Enterprise conecta-se diretamente ao seu agente usando chamadas A2A JSON-RPC padrão.
• O agente atende ao padrão de mensagem inline esperado pela UI gerenciada do Gemini Enterprise.
• Componentes customizados como GoogleMap renderizam via iframes do Google Maps Embed, com a chave de API injetada no servidor para que o LLM nunca a veja.

A demonstração a seguir ilustra como o Google Maps funciona como um componente interativo e vivo dentro do Gemini Enterprise, em vez de uma imagem estática. Aproveitando a arquitetura amigável para streaming do A2UI, o agente atualiza a visualização do mapa em tempo real — colocando pins e ajustando coordenadas incrementalmente à medida que os resultados chegam da API Maps.

Veja funcionando e construa o seu

• Guia de implementação detalhado aqui.
• Vídeo de demonstração (2 minutos, ponta a ponta com o shell Lit e o Gemini Enterprise): https://youtu.be/_5AaYwyqVio
• Especificação A2UI e referência de componentes: a2ui.org
• Atualizações do Gemini Enterprise, incluindo o renderizador A2UI: What's new in Gemini Enterprise
• Anúncio do A2UI generativo: Introducing A2UI generative UI

Se você já está construindo agentes no Google Cloud, o caminho mais rápido é clonar o repositório de referência, executar make local-backend para um teste local e depois make register-gemini-enterprise para conectá-lo ao GE. A partir daí, troque seu próprio catálogo, suas próprias ferramentas e seu próprio domínio. Da próxima vez que um usuário pedir ao seu agente "uma mesa para dois amanhã às 19h", a resposta pode ser um date picker em vez de outra pergunta.

Perguntas Frequentes

• O que é A2UI e como ele difere de enviar HTML ou JavaScript diretamente?
  A2UI é um protocolo declarativo que envia um payload JSON descrevendo componentes de UI (como ChoicePicker, Map, Button). Diferente de HTML/JS, ele não é executável: o cliente renderiza apenas componentes de um catálogo pré-aprovado, eliminando riscos de XSS e injeção de código.

• Quais são os requisitos técnicos para integrar um agente A2UI com Gemini Enterprise?
  Você precisa construir um agente A2A (pode usar Google ADK) que emita mensagens A2UI no formato JSON com MIME type application/json+a2ui. O agente deve expor um endpoint A2A e ser registrado no Gemini Enterprise como um agente. O GE já possui um renderer A2UI embutido.

• A2UI funciona apenas com Google Cloud ou pode ser usado em ambientes multi-cloud?
  O protocolo A2UI é transport-agnostic e framework-agnostic — pode rodar em qualquer stack (Cloud Run, GKE, on-prem) e ser consumido por qualquer cliente que implemente o renderer (Lit, Flutter, Angular). A integração nativa com Gemini Enterprise é um dos caminhos, mas não o único.

• Quais riscos de segurança o A2UI mitiga em comparação com o envio de fragmentos de HTML ou JavaScript?
  Como o payload A2UI é declarativo e não executável, um agente remoto não pode injetar scripts, roubar credenciais ou causar visual drift. O cliente só renderiza componentes de um catálogo aprovado, garantindo que a UI esteja sempre alinhada ao design system da aplicação hospedeira.

---

Artigo originalmente publicado por Yuan Tian, Software Engineer, Google Cloud AI em Cloud Blog.