Criar um app do Google Chat com um agente Agent2UI

Esta página explica como criar um complemento do Google Workspace que funciona no Google Chat e interage com um agente de IA que usa o protocolo Agent2UI (A2UI). Você desenvolve o agente usando o Kit de Desenvolvimento de Agente (ADK) e o hospeda no Vertex AI Agent Engine.

Os agentes de IA percebem o ambiente, raciocinam e executam ações complexas e de várias etapas de forma autônoma para alcançar uma meta definida. Neste tutorial, você implantará um agente de IA básico que retorna informações de perfil estáticas obtidas por meio de uma ferramenta.

O A2UI permite que agentes de IA gerem interfaces de usuário adaptáveis, ricas e interativas que são renderizadas nativamente. Dessa forma, você pode se concentrar na lógica dos agentes de IA, e não nas interfaces de usuário.

Figura 1. O agente da A2UI responde ao usuário com texto e um card contendo o nome, a imagem e o botão do LinkedIn.
Figura 2. O agente A2UI também foi atualizado para retornar o título do perfil.
Figura 3. O agente da A2UI responde ao usuário com uma mensagem que mostra o nome do perfil no card.

O diagrama a seguir mostra a arquitetura e o padrão de mensagens:

Arquitetura de um app de chat implementado com um agente de IA A2UI.

No diagrama, um usuário interagindo com um app de chat implementado com um agente A2UI tem o seguinte fluxo de informações:

Um usuário envia uma mensagem para um app do Chat em uma mensagem direta ou em um espaço do Chat.
A lógica do app Chat implementada no Apps Script ou como um servidor da Web com endpoints HTTP recebe e processa a mensagem.
O agente A2UI hospedado com o Vertex AI Agent Engine recebe e processa a interação.
Opcionalmente, o app Chat ou o agente de IA podem se integrar aos serviços do Google Workspace, como Agenda ou Planilhas, ou a outros Serviços do Google, como Maps ou YouTube.
O app Chat gera e envia respostas adaptáveis de forma assíncrona, usando a API Google Chat para comunicar o progresso do agente de IA.
As respostas são entregues ao usuário.

Objetivos

Prepare o ambiente.
Implante o agente da A2UI.
Implante o app Chat.
Configure o app Chat.
Teste o app Chat.

Pré-requisitos

Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
Ter um projeto do Google Cloud com o faturamento ativado. Para verificar se um projeto já tem o faturamento ativado, consulte Verificar o status de faturamento dos projetos. Para criar um projeto e configurar o faturamento, consulte Criar um projeto do Google Cloud.
Python 3.11 ou mais recente: para instalação, siga as instruções no site oficial do Python.
Python Poetry: para instalação, siga as instruções no site oficial do Poetry (em inglês).
CLI do Google Cloud: para instalar, siga as instruções no site oficial do Google Cloud.

Configurar o ambiente

Ativar as APIs do Google Cloud

Antes de usar as APIs do Google, é necessário ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

No console do Google Cloud, ative as APIs Google Chat, Vertex AI e Cloud Resource Manager.

Ativar as APIs

Configurar a tela de permissão OAuth

Todos os apps que usam o OAuth 2.0 exigem uma configuração de tela de permissão. Ao configurar a tela de consentimento do OAuth do app, você define o que é mostrado para usuários e revisores de apps e registra o app para que ele possa ser publicado mais tarde.

No console do Google Cloud, acesse Menu > Google Auth platform > Branding.
Acessar Branding
Se você já tiver configurado o Google Auth platform, poderá configurar as seguintes opções da tela de permissão do OAuth em Branding, Público-alvo e Acesso a dados. Se você receber uma mensagem informando que Google Auth platform ainda não foi configurado, clique em Começar:

Em Informações do app, no campo Nome do app, insira um nome para o app.
Em E-mail para suporte do usuário, escolha um endereço de e-mail para que os usuários possam entrar em contato com você se tiverem dúvidas sobre o consentimento deles.
Clique em Próxima.
Em Público-alvo, selecione Interno.
Clique em Próxima.
Em Informações de contato, insira um Endereço de e-mail para receber notificações sobre mudanças no seu projeto.
Clique em Próxima.
Em Concluir, leia a Política de dados do usuário dos serviços de API do Google e, se concordar, selecione Concordo com a Política de dados do usuário dos serviços de API do Google.
Clique em Continuar.
Clique em Criar.

Por enquanto, você pode pular a adição de escopos. No futuro, quando você criar um app para uso fora da sua organização do Google Workspace, mude o Tipo de usuário para Externo. Em seguida, adicione os escopos de autorização necessários para o app. Para saber mais, consulte o guia completo Configurar a permissão OAuth.

Criar uma conta de serviço no console do Google Cloud

Crie uma conta de serviço com o papel Vertex AI User seguindo estas etapas:

Console do Google Cloud

No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.
Acessar a página "Contas de serviço"
Clique em Criar conta de serviço.
Preencha os detalhes da conta de serviço e clique em Criar e continuar.
Observação: por padrão, o Google cria um ID exclusivo de conta de serviço. Se quiser mudar o ID, modifique o campo "ID da conta de serviço".
Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do projeto do Google Cloud. Para mais detalhes, consulte Conceder, alterar e revogar o acesso a recursos.
Clique em Continuar.
Opcional: insira usuários ou grupos que podem gerenciar e realizar ações com essa conta de serviço. Para mais detalhes, consulte Como gerenciar a representação da conta de serviço.
Clique em Concluído. Anote o endereço de e-mail da conta de serviço.

CLI da gcloud

Crie a conta de serviço:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"

Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do projeto do Google Cloud. Para mais detalhes, consulte Conceder, alterar e revogar o acesso a recursos.

A conta de serviço aparece na página de contas de serviço.

Criar uma chave privada

Para criar e fazer o download de uma chave privada para a conta de serviço, siga estas etapas:

No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.
Acessar a página "Contas de serviço"
Selecione sua conta de serviço.
Clique em Chaves > Adicionar chave > Criar nova chave.
Selecione JSON e clique em Criar.
Seu novo par de chave pública/privada é gerado e transferido por download para sua máquina como um novo arquivo. Salve o arquivo JSON baixado como credentials.json no seu diretório de trabalho. Esse arquivo é a única cópia da chave. Para saber como armazenar sua chave com segurança, consulte Como gerenciar chaves de contas de serviço.
Clique em Fechar.

Para mais informações sobre contas de serviço, consulte contas de serviço na documentação do IAM do Google Cloud.

Implantar o agente A2UI

Se ainda não tiver feito isso, autentique-se com sua conta do Google Cloud e configure a Google Cloud CLI para usar seu projeto do Google Cloud.
```
gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID
```
Substitua PROJECT_ID pelo ID do projeto do Cloud.
Faça o download do repositório do GitHub googleworkspace/add-ons-samples usando este botão:

Baixar o repositório
No ambiente de desenvolvimento local de sua preferência, extraia o arquivo baixado e abra o diretório add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui.
```
unzip add-ons-samples-main.zip
cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui
```
Crie um bucket do Cloud Storage dedicado ao agente do ADK.
```
gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION
```
Substitua:
1. CLOUD_STORAGE_BUCKET_NAME com um nome de bucket exclusivo que você quer usar.
2. PROJECT_ID pelo ID do projeto do Cloud.
3. PROJECT_LOCATION com o local do seu projeto do Cloud.
Configure as variáveis de ambiente a seguir:
```
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
```
Substitua:
1. CLOUD_STORAGE_BUCKET_NAME com o nome do bucket que você criou.
2. PROJECT_ID pelo ID do projeto do Cloud.
3. PROJECT_LOCATION com a localização do seu projeto na nuvem.

Instale e implemente o agente ADK a partir de um ambiente virtual.

python3 -m venv myenv
source myenv/bin/activate
poetry install --with deployment
python3 deployment/deploy.py --create

Recupere o ID do agente. Você precisará disso mais tarde, quando configurar o aplicativo de bate-papo.
```
python3 deployment/deploy.py --list
```

Crie e configure o projeto do aplicativo de bate-papo.

Clique no botão a seguir para abrir o projeto A2UI AI Agent Quickstart do Apps Script.

Abrir o projeto
Clique Visão geral > Faça uma cópia.
No seu projeto do Apps Script, clique em Configurações do projeto > Editar propriedades do script > Adicionar propriedade de script Para adicionar as seguintes propriedades de script:
1. REASONING_ENGINE_RESOURCE_NAME com o nome do recurso do agente Vertex AI copiado nas etapas anteriores.
2. SERVICE_ACCOUNT_KEY com a chave JSON da conta de serviço baixada nas etapas anteriores, como { ... }.
Clique em Salvar propriedades do script.
No console do Google Cloud, acesse o Menu. > IAM e Administração > Configurações .

Acesse as Configurações de IAM e Administração
No campo Número do projeto, copie o valor.
No projeto do Apps Script, clique em Configurações do projeto.
Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.
Em Número do projeto GCP, cole o número do projeto do Google Cloud copiado nas etapas anteriores.
Clique em Configurar projeto. O projeto do Cloud e o projeto do Apps Script agora estão conectados.

Criar uma implantação de teste

Você precisa de um ID de implantação para esse projeto do Apps Script, para poder usá-lo na próxima etapa.

Para conseguir o ID da implantação principal, faça o seguinte:

No projeto do Apps Script do app Chat, clique em Implantar > Testar implantações.
Em ID da implantação principal, clique em Copiar.
Clique em Concluído.

Configurar o app do Chat

Usando a implantação do Apps Script, siga estas etapas para implantar o app do Google Chat para teste:

No console, pesquise Google Chat API e clique em API Google Chat.
Clique em Gerenciar.
Clique em Configuração e configure o app Chat:
1. No campo Nome do app, digite A2UI Quickstart.
2. No campo URL do avatar, insira https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
3. No campo Descrição, use A2UI Quickstart.
4. Em Funcionalidade, selecione Participar de espaços e conversas em grupo.
5. Em "Configurações de conexão", selecione Projeto do Apps Script.
6. No campo ID da implantação, cole o ID da implantação principal que você copiou antes.
7. Em "Visibilidade", selecione Pessoas e grupos específicos do seu domínio e digite seu e-mail.
Clique em Salvar.

O app Chat está pronto para responder a mensagens.

Teste o app do Chat

Para testar o app do Chat, abra um espaço de mensagem direta com o app do Chat e envie uma mensagem:

Abra o Google Chat usando a conta do Google Workspace que você informou ao se tornar um testador de confiança.

Acessar o Google Chat
Clique em Novo chat.
No campo Adicionar 1 ou mais pessoas, digite o nome do seu aplicativo de bate-papo.
Selecione seu aplicativo de bate-papo nos resultados. Uma mensagem direta é aberta.

Nota: Se você não vir seu aplicativo Chat na lista de resultados, verifique se incluiu sua conta do Google Workspace nas configurações de Visibilidade da página de Configuração da API do Chat no console do Google Cloud.
Na nova mensagem direta com o aplicativo, digite Hello! e pressione enter.

O aplicativo Chat responde à mensagem com uma saudação e um cartão contendo o nome do perfil, a imagem e o botão do LinkedIn.

Atualize a implementação do agente A2UI para que ele também retorne o título do perfil.

No seu ambiente de desenvolvimento local, abra o arquivo a2ui/agent.py e remova o comentário da linha na ferramenta que adiciona o título aos dados retornados.

apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

Ver no GitHub

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""A2UI agent."""

from google.adk.agents import LlmAgent
from google.adk.tools.tool_context import ToolContext
import json

# The schema for any A2UI message. This never changes.
from .a2ui_schema import A2UI_SCHEMA

def get_user_profile(tool_context: ToolContext) -> str:
    """Call this tool to get the current user profile."""
    return json.dumps({
        "name": "Pierrick Voulet",
        # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
        "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
        "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
    })

AGENT_INSTRUCTION="""
You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.

To achieve this, you MUST follow these steps to answer user requests:

1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""

A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""

To generate a valid a2ui UI JSON, you MUST follow these rules:
1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
2.  The first part is your conversational text response.
3.  The second part is a single, raw JSON object which is a list of A2UI messages.
4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.

To represent the user profile, you MUST use the following A2UI message types:
1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
2.  Image MUST be used to represent the user's profile picture.

---BEGIN A2UI JSON SCHEMA---
{A2UI_SCHEMA}
---END A2UI JSON SCHEMA---
"""

root_agent = LlmAgent(
    name="user_profile",
    model="gemini-2.5-flash",
    instruction=A2UI_AND_AGENT_INSTRUCTION,
    description="An agent that returns the current user profile.",
    tools=[get_user_profile]
)

Atualize o ADK previamente implantado com a nova versão da implementação.
```
python3 deployment/deploy.py --update --resource_id=RESOURCE_ID
```
Substitua RESOURCE_ID pelo nome do recurso do agente Vertex AI copiado nas etapas anteriores.
Na mensagem direta com o aplicativo, digite Hello again! e pressione enter.

O aplicativo Chat responde a uma mensagem com um texto e um cartão contendo o título do perfil.

Para adicionar testadores confiáveis e saber mais sobre como testar recursos interativos, consulte Testar recursos interativos para aplicativos do Google Chat.

Resolver problemas

Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra a mensagem "Algo deu errado". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não mostra nenhuma mensagem de erro, mas o app ou card do Chat produz um resultado inesperado. Por exemplo, uma mensagem do card pode não aparecer.

Embora uma mensagem de erro possa não ser exibida na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar você a corrigir erros quando o registro de erros para aplicativos de Chat está ativado. Para obter ajuda na visualização, depuração e correção de erros, consulte Solucionar problemas e corrigir erros do Google Chat.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, exclua o projeto do Cloud.

No console do Google Cloud, acesse a página Gerenciar recursos. Clique em Menu > IAM e administrador > Gerenciar recursos.
Acesse o Resource Manager
Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.