Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Criar um app do Google Chat com um agente Agent2UI

Nesta página, explicamos 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ê vai implantar um agente de IA básico que retorna informações estáticas de perfil recuperadas de uma ferramenta.

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

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 da A2UI hospedado com o Vertex AI Agent Engine recebe e processa a interação.
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 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 seus projetos. Para criar um projeto e configurar o faturamento, consulte Criar um projeto do Google Cloud.
Python 3.11 ou mais recente: para instalar, siga as instruções no site oficial do Python.
Python Poetry: para instalar, 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. Configurar a tela de permissão OAuth do app define o que é mostrado aos usuários e revisores de apps, além de registrar o app para que você possa publicá-lo mais tarde.

No console de APIs do Google, acesse Menu > Plataforma de autenticação do Google > Branding.
Acessar Branding
Se você já tiver configurado a plataforma de autenticação do Google, poderá configurar as seguintes opções da tela de permissão OAuth em Branding, Público-alvo e Acesso a dados. Se aparecer a mensagem A plataforma de autenticação do Google ainda não está configurada, 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 Avançar.
Em Público-alvo, selecione Interno.
Clique em Avançar.
Em Informações de contato, insira um Endereço de e-mail para receber notificações sobre mudanças no seu projeto.
Clique em Avançar.
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"

As etapas restantes aparecem no console do Google Cloud.
Selecione um projeto do Google Cloud.
Clique em Criar conta de serviço.
Insira um nome de conta de serviço a ser exibido no Console do Google Cloud.
Observação: por padrão, o Google cria um ID exclusivo de conta de serviço com base no nome dela. É possível modificar o ID no campo "ID da conta de serviço". Não será possível mudar o ID depois.
Se você não quiser definir controles de acesso agora, clique em Concluído para terminar a criação da conta de serviço. Para definir os controles de acesso agora, clique em Criar e continuar e avance para a próxima etapa.
Observação:conceder controle de acesso aqui afeta apenas os recursos do Google Cloud. Os recursos do Google Workspace (como Planilhas Google e Google Drive) são compartilhados e configurados separadamente.
Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do seu projeto do Google Cloud, além dos recursos do Google Workspace. Para mais detalhes, consulte Gerenciar o acesso a projetos, pastas e organizações.
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 identidade temporária de conta de serviço.
Clique em Concluído para terminar a criação da conta de serviço.
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 seu projeto do Google Cloud, além dos recursos do Google Workspace. Para mais detalhes, consulte Gerenciar o acesso a projetos, pastas e organizações.

A conta de serviço aparece na página "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"

As etapas restantes aparecem no console do Google Cloud.
Selecione um projeto do Google Cloud.
Clique no endereço de e-mail da conta de serviço para a qual você quer criar uma chave.
Clique na guia Chaves.
Clique no menu suspenso Adicionar chave e selecione Criar nova chave.
Selecione JSON como o Tipo de chave e clique em Criar.
Seu novo par de chave pública/privada é gerado e baixado para sua máquina como um arquivo de chave de conta de serviço. Salve o arquivo JSON baixado como credentials.json no seu diretório de trabalho. Esse arquivo é a única cópia da chave. Após fazer o download do arquivo de chave, não será possível fazer o download novamente. Para saber como armazenar sua chave com segurança, consulte Práticas recomendadas para gerenciar chaves de contas de serviço.

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 o local do seu projeto do Cloud.

Instale e implante o agente do ADK no 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ê vai precisar dele mais tarde, ao configurar o app Chat.
```
python3 deployment/deploy.py --list
```

Criar e configurar o projeto do app do Chat

Clique no botão a seguir para abrir o projeto do Apps Script Início rápido do agente de IA da A2UI.

Abrir o projeto
Clique em Visão geral > Fazer uma cópia.
No projeto do Apps Script, clique em Configurações do projeto > Editar propriedades do script > Adicionar propriedade do script para adicionar as seguintes propriedades:
1. REASONING_ENGINE_RESOURCE_NAME com o nome do recurso do agente da 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 das APIs do Google, acesse Menu > IAM e administrador > Configurações.

Acessar as configurações do IAM e do administrador
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 do 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 receber 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 de APIs, 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 uma mensagem direta com o app 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 uma ou mais pessoas, digite o nome do seu app Chat.
Selecione seu app de chat nos resultados. Uma mensagem direta é aberta.

Observação:se o app de chat não aparecer na lista de resultados, verifique se você incluiu sua conta do Google Workspace nas configurações de Visibilidade da página Configuração da API Chat no Console de APIs do Google.
Na nova mensagem direta com o app, digite Hello! e pressione enter.

O app Chat responde com uma mensagem de texto de saudação e um card com o nome do perfil, a imagem e o botão do LinkedIn.

Atualize a implementação do agente A2UI para começar a retornar também 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 implantado anteriormente 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 da Vertex AI copiado nas etapas anteriores.
Na mensagem direta com o app, digite Hello again! e pressione enter.

O app Chat responde a uma mensagem com um texto e um card contendo o título do perfil.

Para adicionar testadores de confiança e saber mais sobre como testar recursos interativos, consulte Testar recursos interativos para apps 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 não apareça 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 apps do Chat está ativado. Para ajuda com a visualização, depuração e correção de erros, consulte Resolver e corrigir erros do Google Chat.

Limpar

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

No Console de APIs do Google, 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 Desligar para excluí-lo.