Criar um app do Google Chat com um agente Agent2Agent

Prévia da Vertex AI Agent Builder:o desenvolvimento e o uso de um agente Agent2Agent (A2A) estão em prévia. Consulte a documentação completa.

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 Agent2Agent (A2A). Você desenvolve o agente usando o Kit de Desenvolvimento de Agente (ADK) e o hospeda no Vertex AI Agent Engine.

Observação:no Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Você também pode criar seu app do Chat usando eventos de interação da API Google Chat. Para saber mais, consulte a Visão geral da extensão do Google Chat.

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 a amostra multiagente do LLM Auditor que critica e revisa fatos usando o embasamento do Gemini e da Pesquisa Google.

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

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

1. Um usuário envia uma mensagem para um app do Chat em uma mensagem direta ou em um espaço do Chat.
2. A lógica do app Chat implementada no Apps Script ou como um servidor da Web com endpoints HTTP recebe e processa a mensagem.
3. O agente A2A hospedado com o Vertex AI Agent Engine recebe e processa a interação.
4. 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.
5. O app Chat envia respostas de forma assíncrona, usando a API Google Chat para comunicar o progresso do agente de IA.
6. As respostas são entregues ao usuário.

Objetivos

• Prepare o ambiente.
• Implante o agente A2A.
• 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.
• Pré-requisitos do agente do ADK do LLM Auditor
  • Python 3.11 ou mais recente: para instalar, 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. Configurar a tela de consentimento do 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.

1. No console do Google Cloud, acesse Menu > Google Auth platform > Branding.

   Acessar a página "Branding"

2. Se você já tiver configurado o Google Auth platform, poderá definir as seguintes configuraçõ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:
1. Em Informações do app, no campo Nome do app, insira um nome para o app.
2. 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.
3. Clique em Próxima.
4. Em Público-alvo, selecione Interno.
5. Clique em Próxima.
6. Em Informações de contato, insira um Endereço de e-mail para receber notificações sobre mudanças no seu projeto.
7. Clique em Próxima.
8. 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.
9. Clique em Continuar.
10. Clique em Criar.
3. 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

1. No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.

   Acessar a página "Contas de serviço"

2. Clique em Criar conta de serviço.
3. 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".
4. 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.
5. Clique em Continuar.
6. 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.
7. Clique em Concluído. Anote o endereço de e-mail da conta de serviço.

CLI da gcloud

1. Crie a conta de serviço:

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

2. 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

Aviso : este exemplo usa uma chave de conta de serviço exportada para simplificar. Não é recomendável exportar uma chave privada em produção porque ela não deve ser armazenada em um local inseguro, como o controle de origem.

Para saber mais sobre implementações seguras de contas de serviço e práticas recomendadas, consulte Escolher quando usar contas de serviço.

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

1. No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.

   Acessar a página "Contas de serviço"

2. Selecione sua conta de serviço.
3. Clique em Chaves > Adicionar chave > Criar nova chave.
4. 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.

5. 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 A2A

1. 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.

2. Faça o download do repositório do GitHub de amostras do ADK usando este botão:

   Fazer o download de adk-samples

3. No ambiente de desenvolvimento local de sua preferência, extraia o arquivo baixado e abra o diretório adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Atualize a implementação para implantar o agente do ADK como um agente remoto A2A:

   1. pyproject.toml: adicione dependências do ADK e do SDK A2A no grupo de implantação.

      apps-script/chat/a2a-ai-agent/llm-auditor/pyproject.toml

      Ver no GitHub
      [project]
      name = "llm-auditor"
      version = "0.1.0"
      description = "The LLM Auditor evaluates LLM-generated answers, verifies actual accuracy using the web, and refines the response to ensure alignment with real-world knowledge."
      authors = [
          { name = "Chun-Sung Ferng", email = "[e-mail]" },
          { name = "Cyrus Rashtchian", email = "[e-mail]" },
          { name = "Da-Cheng Juan", email = "[e-mail]" },
          { name = "Ivan Kuznetsov", email = "[e-mail]" },
      ]
      license = "Apache License 2.0"
      readme = "README.md"
      
      [tool.poetry.dependencies]
      python = "^3.10"
      google-adk = "^1.0.0"
      google-cloud-aiplatform = { extras = [
          "adk",
          "agent-engines",
      ], version = "^1.93.0" }
      google-genai = "^1.9.0"
      pydantic = "^2.10.6"
      python-dotenv = "^1.0.1"
      
      [tool.poetry.group.dev]
      optional = true
      
      [tool.poetry.group.dev.dependencies]
      google-adk = { version = "^1.0.0", extras = ["eval"] }
      pytest = "^8.3.5"
      pytest-asyncio = "^0.26.0"
      
      [tool.poetry.group.deployment]
      optional = true
      
      [tool.poetry.group.deployment.dependencies]
      absl-py = "^2.2.1"
      google-adk = "^1.0.0"
      a2a-sdk = "^0.3.0"
      
      [build-system]
      requires = ["poetry-core>=2.0.0,<3.0.0"]
      build-backend = "poetry.core.masonry.api"

   2. deployment/deploy.py: substitua a implantação do app ADK por um agente e um card A2A.

      apps-script/chat/a2a-ai-agent/llm-auditor/deployment/deploy.py

      Ver no GitHub
      # Copyright 2025 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.
      
      """Deployment script for LLM Auditor."""
      
      import os
      
      from absl import app
      from absl import flags
      from dotenv import load_dotenv
      from llm_auditor.agent import root_agent
      import vertexai
      from vertexai import agent_engines
      
      # A2A wrapping
      from a2a.types import AgentSkill
      from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
      from google.adk.runners import InMemoryRunner
      from vertexai.preview.reasoning_engines.templates.a2a import create_agent_card
      from vertexai.preview.reasoning_engines import A2aAgent
      
      FLAGS = flags.FLAGS
      flags.DEFINE_string("project_id", None, "GCP project ID.")
      flags.DEFINE_string("location", None, "GCP location.")
      flags.DEFINE_string("bucket", None, "GCP bucket.")
      flags.DEFINE_string("resource_id", None, "ReasoningEngine resource ID.")
      
      flags.DEFINE_bool("list", False, "List all agents.")
      flags.DEFINE_bool("create", False, "Creates a new agent.")
      flags.DEFINE_bool("delete", False, "Deletes an existing agent.")
      flags.mark_bool_flags_as_mutual_exclusive(["create", "delete"])
      
      
      def create() -> None:
          """Creates an agent engine for LLM Auditor."""
          agent_card = create_agent_card(
              agent_name=root_agent.name,
              description=root_agent.description,
              skills=[AgentSkill(
                  id='audit_llm_output',
                  name='Audit LLM Output',
                  description='Critiques and revises outputs from large language models.',
                  tags=['LLM', 'Audit', 'Revision'],
                  examples=[
                      'The earth is flat.',
                      'The capital of France is Berlin.',
                      'The last winner of the Super Bowl was the New England Patriots in 2020.',
                  ],
              )]
          )
          a2a_agent = A2aAgent(
              agent_card=agent_card,
              agent_executor_builder=lambda: A2aAgentExecutor(
                  runner=InMemoryRunner(
                      app_name=root_agent.name,
                      agent=root_agent,
                  )
              )
          )
          a2a_agent.set_up()
      
          remote_agent = agent_engines.create(
              a2a_agent,
              display_name=root_agent.name,
              requirements=[
                      "google-adk (>=0.0.2)",
                      "google-cloud-aiplatform[agent_engines] (>=1.88.0,<2.0.0)",
                      "google-genai (>=1.5.0,<2.0.0)",
                      "pydantic (>=2.10.6,<3.0.0)",
                      "absl-py (>=2.2.1,<3.0.0)",
                      "a2a-sdk>=0.3.22",
                      "uvicorn",
              ],
              # In-memory runner
              max_instances=1,
              env_vars ={
                  "NUM_WORKERS": "1"
              },
              extra_packages=["./llm_auditor"],
          )
          print(f"Created remote agent: {remote_agent.resource_name}")
      
      
      def delete(resource_id: str) -> None:
          remote_agent = agent_engines.get(resource_id)
          remote_agent.delete(force=True)
          print(f"Deleted remote agent: {resource_id}")
      
      
      def list_agents() -> None:
          remote_agents = agent_engines.list()
          TEMPLATE = '''
      {agent.name} ("{agent.display_name}")
      - Create time: {agent.create_time}
      - Update time: {agent.update_time}
      '''
          remote_agents_string = '\n'.join(TEMPLATE.format(agent=agent) for agent in remote_agents)
          print(f"All remote agents:\n{remote_agents_string}")
      
      def main(argv: list[str]) -> None:
          del argv  # unused
          load_dotenv()
      
          project_id = (
              FLAGS.project_id
              if FLAGS.project_id
              else os.getenv("GOOGLE_CLOUD_PROJECT")
          )
          location = (
              FLAGS.location if FLAGS.location else os.getenv("GOOGLE_CLOUD_LOCATION")
          )
          bucket = (
              FLAGS.bucket if FLAGS.bucket
              else os.getenv("GOOGLE_CLOUD_STORAGE_BUCKET")
          )
      
          print(f"PROJECT: {project_id}")
          print(f"LOCATION: {location}")
          print(f"BUCKET: {bucket}")
      
          if not project_id:
              print("Missing required environment variable: GOOGLE_CLOUD_PROJECT")
              return
          elif not location:
              print("Missing required environment variable: GOOGLE_CLOUD_LOCATION")
              return
          elif not bucket:
              print(
                  "Missing required environment variable: GOOGLE_CLOUD_STORAGE_BUCKET"
              )
              return
      
          vertexai.init(
              project=project_id,
              location=location,
              staging_bucket=f"gs://{bucket}",
          )
      
          if FLAGS.list:
              list_agents()
          elif FLAGS.create:
              create()
          elif FLAGS.delete:
              if not FLAGS.resource_id:
                  print("resource_id is required for delete")
                  return
              delete(FLAGS.resource_id)
          else:
              print("Unknown command")
      
      
      if __name__ == "__main__":
          app.run(main)

5. 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.

6. 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.

7. 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

8. 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

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

   Abrir o projeto

2. Clique em Visão geral > Fazer uma cópia.

3. 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 { ... }.

4. Clique em Salvar propriedades do script.

5. No console do Google Cloud, acesse Menu > IAM e administrador > Configurações.

   Acessar as configurações do IAM e do administrador

6. No campo Número do projeto, copie o valor.

7. No projeto do Apps Script, clique em Configurações do projeto.

8. Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.

9. Em Número do projeto do GCP, cole o número do projeto do Google Cloud copiado nas etapas anteriores.

10. Clique em Configurar projeto. O projeto do Google 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:

1. No projeto do Apps Script do app Chat, clique em Implantar > Testar implantações.
2. Em ID da implantação principal, clique em Copiar.
3. 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:

1. No console, pesquise Google Chat API e clique em API Google Chat.
2. Clique em Gerenciar.

3. Clique em Configuração e configure o app Chat:

   1. No campo Nome do app, digite A2A 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 A2A 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.

4. 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:

1. 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

2. Clique em Novo chat.
3. No campo Adicionar uma ou mais pessoas, digite o nome do seu app Chat.

4. 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 do Google Cloud.

5. Na nova mensagem direta com o app, digite The Eiffel Tower was completed in 1900 e pressione enter.

   O app Chat responde com as respostas dos subagentes Crítico e Revisor.

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 Solucionar 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.

Cuidado:excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para seguir este tutorial, a exclusão dele incluirá quaisquer outras ações feitas no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL em appspot.com, exclua os recursos selecionados dentro do projeto em vez de todo o projeto.

Se você planeja explorar vários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. No console do Google Cloud, acesse a página Gerenciar recursos. Clique em Menu > IAM e administrador > Gerenciar recursos.

   Acesse o Resource Manager

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Temas relacionados

• Criar um app do Google Chat com um agente de IA do ADK
• Cheque a veracidade de declarações com um agente de IA do ADK e um modelo do Gemini
• Planejar viagens com um agente de IA acessível em todo o Google Workspace
• Integrar conceitos fundamentais de IA aos apps do Chat
• Responda perguntas com base em conversas do Chat usando um app do Chat com IA do Gemini
• Responde a incidentes com o Google Chat, a Vertex AI, o Apps Script e a autenticação de usuários
• Gerenciar projetos com o Google Chat, a Vertex AI e o Firestore