Integrar agentes do Gemini Enterprise ao Google Workspace

1. Antes de começar

O que é o Gemini Enterprise?

O Gemini Enterprise é uma plataforma agêntica avançada que oferece o melhor da IA do Google para todos os funcionários, em todos os fluxos de trabalho. Ele permite que as equipes descubram, criem, compartilhem e executem agentes de IA em um ambiente seguro.

Acesso a modelos avançados:os usuários têm acesso imediato à IA multimodal mais poderosa do Google, incluindo o Gemini, para enfrentar desafios de negócios complexos.
Use agentes especializados:o pacote inclui agentes do Google prontos para uso em pesquisa, programação e anotações, oferecendo valor imediato.
Capacite todos os funcionários:as opções sem código e com código permitem que funcionários de todos os departamentos criem e gerenciem os próprios agentes personalizados para automação de fluxos de trabalho.
Baseie os agentes em dados:os agentes podem ser conectados com segurança a dados internos da empresa e aplicativos de terceiros para garantir que as respostas sejam contextualmente precisas.
Governança centralizada:os administradores podem visualizar e auditar toda a atividade do agente para garantir que a organização atenda a padrões rigorosos de segurança e compliance.
Expansão com ecossistemas:a plataforma se integra a uma ampla rede de aplicativos parceiros e provedores de serviços para estender a automação a diferentes sistemas.

O que é o Google Workspace?

O Google Workspace é um conjunto de soluções de produtividade e colaboração baseadas na nuvem projetadas para pessoas, escolas e empresas:

Comunicação:serviços de e-mail profissional (Gmail), videoconferências (Meet) e mensagens em grupo (Chat).
Criação de conteúdo:ferramentas para escrever documentos (Documentos), criar planilhas (Planilhas) e design de apresentações (Apresentações).
Organização:agendas compartilhadas (Agenda) e anotações digitais (Keep).
Armazenamento:espaço centralizado na nuvem para salvar e compartilhar arquivos com segurança (Drive).
Gerenciamento:controles administrativos para gerenciar usuários e configurações de segurança (Admin Console do Workspace).

Que tipo de integrações personalizadas?

O Google Workspace e o Gemini Enterprise criam um poderoso ciclo de feedback em que o Workspace fornece dados em tempo real e contexto de colaboração, enquanto o Gemini Enterprise oferece os modelos, o raciocínio agêntico e a organização necessários para automatizar fluxos de trabalho inteligentes.

Conectividade inteligente:os repositórios de dados, as APIs e os servidores MCP gerenciados pelo Google (gerenciados pelo Google e personalizados) permitem que os agentes acessem os dados do Workspace com segurança e facilidade e realizem ações em nome dos usuários.
Agentes personalizados:usando designers sem código ou estruturas de programação, as equipes podem criar agentes especializados com base em dados e ações do Workspace gerenciados pelo administrador.
Integração nativa:os complementos do Workspace preenchem a lacuna entre os sistemas de IA e aplicativos como o Chat e o Gmail, seja por componentes dedicados da interface ou por processos em segundo plano. Assim, os atendentes podem ajudar os usuários de forma instantânea e contextualizada.

Ao combinar o ecossistema de produtividade robusto do Google Workspace com o poder agêntico avançado do Gemini Enterprise, as organizações podem transformar as operações com agentes de IA personalizados e baseados em dados que automatizam fluxos de trabalho complexos diretamente nas ferramentas que as equipes já usam todos os dias.

Pré-requisitos

Se quiser seguir todas as etapas no seu próprio ambiente, você vai precisar do seguinte:

Conhecimento básico do Google Cloud e do Python.
Um projeto do Google Cloud em que você é proprietário com faturamento. 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. Para mudar a propriedade do projeto, consulte Gerenciar membros ou mudar a propriedade do projeto.
Edições Gemini Enterprise Standard / Plus ativadas. Para comparar as edições do Gemini Enterprise, consulte Comparar as edições do Gemini Enterprise. Se você não tiver uma licença do Gemini Enterprise, poderá criar uma licença de teste na próxima etapa.
Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat e aos recursos inteligentes ativados.
A Google Cloud CLI instalada e inicializada para seu projeto do Google Cloud.
Python 3.11 ou mais recente instalado. Consulte as instruções no site oficial do Python.

O que você vai criar

Neste codelab, vamos criar três soluções com agentes de IA do Gemini Enterprise totalmente integrados ao Google Workspace. Eles vão demonstrar padrões arquitetônicos que podem ser usados para interagir com dados, ações e interfaces.

Agente personalizado sem código

Com ele, os usuários podem pesquisar dados e realizar ações no Workspace em linguagem natural. Ele depende dos seguintes elementos:

Modelo:Gemini.
Dados e ações:repositórios de dados do Gemini Enterprise para Google Workspace (Agenda, Gmail, Drive, NotebookLM) e Pesquisa Google.
Ferramentas de criação de agentes:Agent Designer do Gemini Enterprise.
Host do agente:Gemini Enterprise.
Interface:web app do Gemini Enterprise.

Agente personalizado de programação avançada

Com ele, os usuários podem pesquisar dados e realizar ações no Workspace em linguagem natural usando ferramentas e regras personalizadas. Ele depende dos seguintes elementos:

Modelo:Gemini.
Dados e ações:repositórios de dados do Gemini Enterprise para o Google Workspace (Agenda, Gmail, Drive, NotebookLM), Pesquisa Google, servidor do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) da Pesquisa da Vertex AI gerenciado pelo Google, função de ferramenta personalizada para enviar mensagens do Google Chat (pela API do Google Chat).
Ferramentas de criação de agentes:Kit de Desenvolvimento de Agente (ADK).
Host do agente:Vertex AI Agent Engine.
Interface:web app do Gemini Enterprise.

Agente padrão como complemento do Google Workspace

Com ele, os usuários podem pesquisar dados do Workspace em linguagem natural no contexto das interfaces dos apps do Workspace. Ele depende dos seguintes elementos:

Modelo:Gemini.
Dados:repositórios de dados do Gemini Enterprise para Google Workspace (Agenda, Gmail, Drive, NotebookLM), Pesquisa Google.
Host do agente:Gemini Enterprise.
Interface:complemento do Google Workspace para Chat e Gmail (facilmente extensível para Agenda, Drive, Documentos, Planilhas e Apresentações).
Complemento do Google Workspace:Apps Script, APIs do Gemini Enterprise e da Vertex AI, contextuais (metadados do usuário, mensagem selecionada do Gmail).

O que você vai aprender

Os pontos de integração entre o Gemini Enterprise e o Google Workspace que permitem dados e ações.
As opções sem código e com código para criar agentes personalizados hospedados no Gemini Enterprise.
As formas como os usuários podem acessar agentes no web app Gemini Enterprise e nos aplicativos do Google Workspace.

2. Começar a configuração

Revisar conceitos

App Gemini Enterprise

Um app do Gemini Enterprise fornece resultados de pesquisa, ações e agentes para seus usuários finais. O termo "app" pode ser usado de forma intercambiável com o termo "engine" no contexto das APIs. Um app precisa estar conectado a um repositório de dados para usar as informações dele e veicular resultados da pesquisa, respostas ou ações.

Web app do Gemini Enterprise

Um web app do Gemini Enterprise está associado a um app do Gemini Enterprise. Ele funciona como uma base de IA centralizada em que os funcionários usam uma única interface de chat para pesquisar dados isolados da empresa, executar agentes de IA especializados para fluxos de trabalho complexos e gerar conteúdo de nível profissional com privacidade empresarial.

Inicializar e acessar recursos

Nesta seção, você vai acessar e configurar os seguintes recursos no navegador da Web de sua preferência.

App do Gemini Enterprise

Abra o console do Google Cloud em uma nova guia e siga estas etapas:

Selecione o projeto.
No campo de pesquisa do Google Cloud, procure e selecione Gemini Enterprise e clique em + Criar app. Se você não tiver uma licença do Gemini Enterprise, será solicitado que ative uma licença de teste sem custo financeiro de 30 dias.

Defina o Nome do app como codelab.
Um ID é gerado com base no nome e exibido abaixo do campo. Copie-o.
Defina a Multirregião como global (Global).
Clique em Criar.

O app é criado, e você é redirecionado automaticamente para Gemini Enterprise > Visão geral.
Em Tenha acesso total, clique em Configurar identidade.
Na nova tela, selecione Usar o Google Identity e clique em Confirmar a identidade de colaboradores.

A configuração é salva, e você é redirecionado automaticamente para Gemini Enterprise > Visão geral.
Acesse Configurações.
Na guia Gerenciamento de recursos, ative a opção Ativar o designer de agentes e clique em Salvar.

Web app do Gemini Enterprise

Abra o Gemini Enterprise no console do Cloud em uma nova guia e siga estas etapas:

Clique no app chamado codelab.
Copie o URL que aparece, porque vamos usá-lo para navegar até o web app do Gemini Enterprise nas próximas etapas.

3. Agente personalizado sem código

Com ele, os usuários podem pesquisar dados e realizar ações no Workspace em linguagem natural. Ele depende dos seguintes elementos:

Modelo:Gemini.
Dados e ações:repositórios de dados do Gemini Enterprise para Google Workspace (Agenda, Gmail, Drive, NotebookLM) e Pesquisa Google.
Ferramentas de criação de agentes:Agent Designer do Gemini Enterprise.
Host do agente:Gemini Enterprise.
Interface:web app do Gemini Enterprise.

Revisar conceitos

Gemini

O Gemini é um LLM multimodal do Google. Essa ferramenta ajuda as pessoas a aproveitar todo o potencial humano para que possam dar asas à imaginação, ampliar a curiosidade e aumentar a produtividade.

Repositório de dados do Gemini Enterprise

Um repositório de dados do Gemini Enterprise é uma entidade que contém os dados ingeridos de uma fonte de dados própria, como o Google Workspace, ou de aplicativos de terceiros, como o Jira ou o Salesforce. Os repositórios de dados que contêm dados de aplicativos de terceiros também são chamados de conectores de dados.

Designer de agentes do Gemini Enterprise

O Agent Designer do Gemini Enterprise é uma plataforma interativa sem código e com pouco código para criar, gerenciar e lançar agentes de uma ou várias etapas no Gemini Enterprise.

Analisar a arquitetura da solução

Ativar APIs

Os repositórios de dados do Gemini Enterprise Workspace exigem a ativação das seguintes APIs:

No console do Google Cloud, ative as APIs Calendar, Gmail e People:

Clique em Menu ☰ > APIs e serviços > APIs e serviços ativados e confirme se a API Google Agenda, a API Gmail e a API People estão na lista.

As ações do Gemini Enterprise no Workspace Calendar e no Gmail exigem uma configuração de tela de consentimento:

No console do Google Cloud, clique em Menu ☰ > Plataforma de autenticação do Google > Branding.

Clique em Primeiros passos.
Em Informações do app, defina o Nome do app como Codelab .
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 e em Criar.

A configuração é salva, e você é redirecionado automaticamente para Plataforma de autenticação do Google > Visão geral.
Navegue até Acesso a dados.
Clique em Adicionar ou remover escopos.
Copie os escopos a seguir e cole no campo Adicionar escopos manualmente.

https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.readonly

Clique em Adicionar à tabela, Atualizar e Salvar.

Para saber mais, consulte o guia completo Configurar a permissão OAuth.

Criar credenciais de cliente OAuth

Crie um cliente OAuth para o Gemini Enterprise autenticar usuários:

No console do Google Cloud, clique em Menu ☰ > Plataforma de autenticação do Google > Clientes.

Clique em + Criar cliente.
Em Tipo de aplicativo, selecione Aplicativo da Web.
Defina o Nome como codelab.
Pule Origens JavaScript autorizadas.
Na seção URIs de redirecionamento autorizados, clique em Adicionar URI e insira https://vertexaisearch.cloud.google.com/oauth-redirect.
Clique em Criar.
Uma caixa de diálogo vai aparecer com o ID e a chave secreta do cliente OAuth recém-criados. Salve essas informações em um local seguro.

Criar repositórios de dados

Abra o Gemini Enterprise no console do Cloud em uma nova guia e siga estas etapas:

Clique no app chamado codelab.
No menu de navegação, clique em Repositórios de dados conectados.
Clique em + Novo repositório de dados.
Em Origem, pesquise Google Agenda e clique em Selecionar.
Na seção Ações, insira o ID do cliente e a chave secreta do cliente salvos nas etapas anteriores. Em seguida, clique em Verificar autenticação e siga as etapas para autenticar e autorizar o cliente OAuth.
Ative as ações Criar evento da agenda e Atualizar evento da agenda.
Clique em Continuar.

Na seção Configuração, defina o Nome do conector de dados como calendar.
Clique em Criar.
Você vai ser redirecionado automaticamente para Repositórios de dados conectados, onde é possível ver o repositório de dados recém-adicionado.

Crie o repositório de dados do Google Gmail:

Clique em + Novo repositório de dados.
Em Origem, pesquise Google Gmail e clique em Selecionar.
Na seção Ações, insira o ID do cliente e a chave secreta do cliente salvos nas etapas anteriores e clique em Verificar autenticação.
Ative a ação Enviar e-mail.
Clique em Continuar.
Na seção Configuração, defina o Nome do conector de dados como gmail.
Clique em Criar.
Você vai ser redirecionado automaticamente para Repositórios de dados conectados, onde é possível ver o repositório de dados recém-adicionado.

Crie o repositório de dados do Google Drive:

Clique em + Novo repositório de dados.
Em Origem, pesquise Google Drive e clique em Selecionar.
Na seção Dados, selecione Todos e clique em Continuar.
Na seção Configuração, defina o Nome do conector de dados como drive.
Clique em Criar.
Você vai ser redirecionado automaticamente para Repositórios de dados conectados, onde é possível ver o repositório de dados recém-adicionado.

Crie o repositório de dados do NotebookLM:

Clique em + Novo repositório de dados.
Em Origem, pesquise NotebookLM e clique em Selecionar.
Na seção Configuração, defina o Nome do conector de dados como notebooklm.
Clique em Criar.
Você vai ser redirecionado automaticamente para Repositórios de dados conectados, onde é possível ver o repositório de dados recém-adicionado.

Após alguns minutos, o status de todos os repositórios de dados conectados (exceto o NotebookLM) será Ativo. Se houver erros, clique na fonte de dados para ver os detalhes.

Repositórios de dados de teste

Abra o URL do web app Gemini Enterprise que copiamos antes:

Clique em Menu ☰ > Novo chat.
No rodapé do novo campo de mensagem de chat, clique no ícone Conectores e ative todos os conectores.
Agora você pode testar comandos relacionados aos conectores. Por exemplo, no chat, digite Do I have any meetings today? e pressione enter.
Em seguida, digite How many emails did I receive today? e pressione enter.
Por fim, digite Give me the title of the last Drive file I created e pressione enter.

Criar um agente personalizado

No web app Gemini Enterprise, crie um agente usando o Designer de agentes:

Clique em Menu ☰ > + Novo agente.
No chat, digite An agent that always sends pirate-themed emails but use normal English otherwise e pressione enter.

O Agent Designer cria um rascunho do agente com base no comando e o abre no editor.
Clique em Criar.

Testar agente personalizado

No web app Gemini Enterprise, converse com o agente recém-criado:
Clique em Menu ☰ > Agentes.
Selecione o agente em Seus agentes.
No rodapé do novo campo de mensagem do chat, clique no ícone Connectors e em Ativar ações para E-mail. Siga as instruções para autorizar o agente.
No chat, digite Send an email to someone@example.com saying I'll see them at Cloud Next, generate some subject and body yourself e pressione enter. Você pode substituir o e-mail de exemplo pelo seu endereço de e-mail.
Clique em ✔️ para enviar o e-mail.

4. Agente personalizado de programação profissional

Com ele, os usuários podem pesquisar dados e realizar ações no Workspace em linguagem natural usando ferramentas e regras personalizadas. Ele depende dos seguintes elementos:

Modelo:Gemini.
Dados e ações:repositórios de dados do Gemini Enterprise para o Google Workspace (Agenda, Gmail, Drive, NotebookLM), Pesquisa Google, servidor do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) da Pesquisa da Vertex AI gerenciado pelo Google, função de ferramenta personalizada para enviar mensagens do Google Chat (pela API do Google Chat).
Ferramentas de criação de agentes:Kit de Desenvolvimento de Agente (ADK).
Host do agente:Vertex AI Agent Engine.
Interface:web app do Gemini Enterprise.

Ele será integrado ao Gemini Enterprise usando o recurso de trazer seu próprio. Por isso, precisamos seguir as etapas de implantação, registro e configuração.

Revisar conceitos

Vertex AI

A Vertex AI oferece tudo o que você precisa para criar e usar a IA generativa, como soluções de IA, pesquisa e conversa, mais de 130 modelos de fundação e uma plataforma de IA unificada.

Kit de Desenvolvimento de Agente (ADK)

O Kit de Desenvolvimento de Agente (ADK) é um conjunto especializado de ferramentas e frameworks projetados para simplificar a criação de agentes autônomos de IA. Ele oferece módulos pré-criados para raciocínio, gerenciamento de memória e integração de ferramentas.

Protocolo de Contexto de Modelo (MCP)

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto criado para permitir a integração perfeita e segura entre aplicativos de IA e várias fontes de dados ou ferramentas por meio de uma interface universal "plug-and-play".

Ferramenta de função

Uma ferramenta de função é uma rotina executável predefinida que um modelo de IA pode acionar para realizar ações específicas ou recuperar dados em tempo real de sistemas externos, estendendo suas capacidades além da simples geração de texto.

Analisar a arquitetura da solução

Revisar o código-fonte

agent.py

...
MODEL = "gemini-2.5-flash"

# Gemini Enterprise authentication injects a bearer token into the ToolContext state.
# The key pattern is "GE_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
GE_AUTH_NAME = "enterprise-ai"

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Helper method to dynamically parse the intercepted bearer token from the context state."""
    escaped_name = re.escape(GE_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    # Handle ADK varying state object types (Raw Dict vs ADK State)
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

def send_direct_message(email: str, message: str, tool_context: ToolContext) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=_get_access_token_from_context(tool_context))
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT
    ),
    tool_filter=['search'],
    # The auth_header_provider dynamically injects the bearer token from the ToolContext
    # into the MCP call for authentication.
    header_provider=auth_header_provider
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

Ativar APIs

A solução exige a ativação de outras APIs:

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

Clique em Menu ☰ > APIs e serviços > APIs e serviços ativados e confirme se a API Vertex AI, a API Cloud Resource Manager e a API Google Chat estão na lista.

A solução exige mais acesso a dados:

No console do Google Cloud, clique em Menu ☰ > Plataforma de autenticação do Google > Acesso a dados.

Clique em Adicionar ou remover escopos.
Copie os escopos a seguir e cole no campo Adicionar escopos manualmente.
Clique em Adicionar à tabela, Atualizar e Salvar.

https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/chat.messages.create
https://www.googleapis.com/auth/chat.spaces.create

Clique em Adicionar à tabela, Atualizar e Salvar.

Atualizar credenciais de cliente OAuth

A solução exige um URI de redirecionamento autorizado adicional:

No console do Google Cloud, clique em Menu ☰ > Plataforma de autenticação do Google > Clientes.

Clique no nome do cliente codelab.
Na seção URIs de redirecionamento autorizados, clique em Adicionar URI e insira https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
Clique em Salvar.

Ativar o MCP da Vertex AI para Pesquisa

Em um terminal, execute:

gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

Configurar o app Chat

No console do Google Cloud, pesquise Google Chat API no campo de pesquisa do Google Cloud, clique em API Google Chat, em Gerenciar e em Configuração.

Defina o Nome do app e a Descrição como Gemini Enterprise.
Defina o URL do avatar como https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
Desmarque a opção Ativar recursos interativos e clique em Desativar na caixa de diálogo modal que aparece.
Selecione Registrar erros no Logging.
Clique em Salvar.

Implantar um agente no Vertex AI Agent Engine

Faça o download deste repositório do GitHub.

Em um terminal, abra o diretório solutions/enterprise-ai-agent e execute:

# 1. Create and activate a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install poetry and project dependencies
pip install poetry
poetry install

# 3. Deploy the agent
adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Enterprise AI" \
  enterprise_ai

Quando a linha Deploying to agent engine... aparecer nos registros, abra um novo terminal e execute o comando a seguir para adicionar as permissões necessárias ao agente de serviço do Reasoning Engine da Vertex AI:

# 1. Get the current Project ID
PROJECT_ID=$(gcloud config get-value project)

# 2. Extract the Project Number for that ID
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# 3. Construct the Service Account name
SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# 4. Apply the IAM policy binding
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT" \
     --role="roles/discoveryengine.viewer"

Aguarde a conclusão do comando adk deploy e copie o nome do recurso do agente recém-implantado da saída do comando em verde.

Registrar agente no Gemini Enterprise

Abra o Gemini Enterprise no console do Cloud em uma nova guia e siga estas etapas:

Clique no app chamado codelab.
No menu de navegação, clique em Agentes.
Clique em + Adicionar agente.
Clique em Adicionar para Agente personalizado via Agent Engine. A seção Autorizações é exibida.
Clique em Adicionar autorização.
Defina o Nome da autorização como enterprise-ai. Um ID é gerado com base no nome e exibido abaixo do campo. Copie-o.
Defina o ID do cliente com o mesmo valor do cliente OAuth criado e atualizado nas etapas anteriores.
Defina a Chave secreta do cliente com o mesmo valor do cliente OAuth criado e atualizado nas etapas anteriores.
Defina o URI do token como https://oauth2.googleapis.com/token.
Defina o URI de autorização com o valor a seguir depois de substituir <CLIENT_ID> pelo ID do cliente OAuth criado e atualizado nas etapas anteriores.

https://accounts.google.com/o/oauth2/v2/auth?client_id=<CLIENT_ID>&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.messages.create%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.spaces.create&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

Clique em Concluído e em Próxima. A seção Configuração é exibida.
Defina o Nome do agente e a Descrição do agente como Enterprise AI.
Defina o mecanismo de inferência do Agent Engine como o nome do recurso do mecanismo de inferência copiado nas etapas anteriores. Ele tem o seguinte formato:

projects/<PROJECT_ID>/locations/<LOCATION>/reasoningEngines/<REASONING_ENGINE_ID>

Clique em Criar. O agente recém-adicionado agora está listado em Agentes.

Testar agente

No web app Gemini Enterprise, converse com o agente recém-registrado:
Clique em Menu ☰ > Agentes.
Selecione o agente em Da sua organização.
No chat, digite Please find my meetings for today, I need their titles and links e pressione enter.
Clique em Autorizar e siga o fluxo de autorização.

O agente responde com uma lista de eventos da Agenda (dependendo da conta do usuário).
No chat, digite Please send a Chat message to someone@example.com with the following text: Hello! e pressione enter.
O agente responde com uma mensagem de confirmação.

5. Agente padrão como complemento do Google Workspace

Com ele, os usuários podem pesquisar dados do Workspace em linguagem natural no contexto das interfaces dos apps do Workspace. Ele depende dos seguintes elementos:

Modelo:Gemini.
Dados:repositórios de dados do Gemini Enterprise para Google Workspace (Agenda, Gmail, Drive, NotebookLM), Pesquisa Google.
Host do agente:Gemini Enterprise.
Interface:complemento do Google Workspace para Chat e Gmail (facilmente extensível para Agenda, Drive, Documentos, Planilhas e Apresentações).
Complemento do Google Workspace:Apps Script, APIs do Gemini Enterprise e da Vertex AI, contextuais (metadados do usuário, mensagem selecionada do Gmail).

O complemento do Google Workspace será conectado ao Gemini Enterprise usando a API StreamAssist.

Revisar conceitos

Complemento do Google Workspace

Um complemento do Google Workspace é um aplicativo personalizado que estende um ou mais apps do Google Workspace (Gmail, Chat, Agenda, Documentos, Drive, Meet, Planilhas e Apresentações).

Apps Script

O Apps Script é uma plataforma JavaScript baseada na nuvem com tecnologia do Google Drive que permite integrar e automatizar tarefas em vários produtos do Google.

Estrutura de cards do Google Workspace

O framework de card no Google Workspace permite que os desenvolvedores criem interfaces de usuário interativas e avançadas. Ele permite a construção de cards organizados e visualmente atraentes que podem incluir texto, imagens, botões e outros widgets. Esses cards melhoram a experiência do usuário ao fornecer informações estruturadas e permitir ações rápidas diretamente nos aplicativos do Workspace.

Analisar a arquitetura da solução

Revisar o código-fonte

appsscript.json

...
"addOns": {
    "common": {
      "name": "Enterprise AI",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png"
    },
    "chat": {},
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onAddonEvent"
        }
      ]
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/discoveryengine.assist.readwrite",
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
  ]
...

Chat.gs

...
// Service that handles Google Chat operations.

// Handle incoming Google Chat message events, actions will be taken via Google Chat API calls
function onMessage(event) {
  if (isInDebugMode()) {
    console.log(`MESSAGE event received (Chat): ${JSON.stringify(event)}`);
  }
  // Extract data from the event.
  const chatEvent = event.chat;
  setChatConfig(chatEvent.messagePayload.space.name);

  // Request AI agent to answer the message
  requestAgent(chatEvent.messagePayload.message);
  // Respond with an empty response to the Google Chat platform to acknowledge execution
  return null; 
}

// --- Utility functions ---

// The Chat direct message (DM) space associated with the user
const SPACE_NAME_PROPERTY = "DM_SPACE_NAME"

// Sets the Chat DM space name for subsequent operations.
function setChatConfig(spaceName) {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty(SPACE_NAME_PROPERTY, spaceName);
  console.log(`Space is set to ${spaceName}`);
}

// Retrieved the Chat DM space name to sent messages to.
function getConfiguredChat() {
  const userProperties = PropertiesService.getUserProperties();
  return userProperties.getProperty(SPACE_NAME_PROPERTY);
}

// Finds the Chat DM space name between the Chat app and the given user.
function findChatAppDm(userName) {
  return Chat.Spaces.findDirectMessage(
    { 'name': userName },
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

// Creates a Chat message in the configured space.
function createMessage(message) {
  const spaceName = getConfiguredChat();
  console.log(`Creating message in space ${spaceName}...`);
  return Chat.Spaces.Messages.create(
    message,
    spaceName,
    {},
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

...
// Service that handles Gmail operations.

// Triggered when the user opens the Gmail Add-on or selects an email.
function onAddonEvent(event) {
  // If this was triggered by a button click, handle it
  if (event.parameters && event.parameters.action === 'send') {
    return handleSendMessage(event);
  }

  // Otherwise, just render the default initial sidebar
  return createSidebarCard();
}

// Creates the standard Gmail sidebar card consisting of a text input and send button.
// Optionally includes an answer section if a response was generated.
function createSidebarCard(optionalAnswerSection) {
  const card = CardService.newCardBuilder();
  const actionSection = CardService.newCardSection();

  // Create text input for the user's message
  const messageInput = CardService.newTextInput()
    .setFieldName("message")
    .setTitle("Message")
    .setMultiline(true);

  // Create action for sending the message
  const sendAction = CardService.newAction()
    .setFunctionName('onAddonEvent')
    .setParameters({ 'action': 'send' });

  const sendButton = CardService.newTextButton()
    .setText("Send message")
    .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
    .setOnClickAction(sendAction);

  actionSection.addWidget(messageInput);
  actionSection.addWidget(CardService.newButtonSet().addButton(sendButton));

  card.addSection(actionSection);

  // Attach the response at the bottom if we have one
  if (optionalAnswerSection) {
    card.addSection(optionalAnswerSection);
  }

  return card.build();
}

// Handles clicks from the Send message button.
function handleSendMessage(event) {
  const commonEventObject = event.commonEventObject || {};
  const formInputs = commonEventObject.formInputs || {};
  const messageInput = formInputs.message;

  let userMessage = "";
  if (messageInput && messageInput.stringInputs && messageInput.stringInputs.value.length > 0) {
    userMessage = messageInput.stringInputs.value[0];
  }

  if (!userMessage || userMessage.trim().length === 0) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Please enter a message."))
      .build();
  }

  let finalQueryText = `USER MESSAGE TO ANSWER: ${userMessage}`;

  // If we have an email selected in Gmail, append its content as context
  if (event.gmail && event.gmail.messageId) {
    try {
      GmailApp.setCurrentMessageAccessToken(event.gmail.accessToken);
      const message = GmailApp.getMessageById(event.gmail.messageId);

      const subject = message.getSubject();
      const bodyText = message.getPlainBody() || message.getBody();

      finalQueryText += `\n\nEMAIL THE USER HAS OPENED ON SCREEN:\nSubject: ${subject}\nBody:\n---\n${bodyText}\n---`;
    } catch (e) {
      console.error("Could not fetch Gmail context: " + e);
      // Invalidate the token explicitly so the next prompt requests the missing scopes
      ScriptApp.invalidateAuth();

      CardService.newAuthorizationException()
        .setResourceDisplayName("Enterprise AI")
        .setAuthorizationUrl(ScriptApp.getAuthorizationUrl())
        .throwException();
    }
  }

  try {
    const responseText = queryAgent({ text: finalQueryText, forceNewSession: true });

    // We leverage the 'showdown' library to parse the LLM's Markdown output into HTML
    // We also substitute markdown listings with arrows and adjust newlines for clearer rendering in the sidebar
    let displayedText = substituteListingsFromMarkdown(responseText);
    displayedText = new showdown.Converter().makeHtml(displayedText).replace(/\n/g, '\n\n');

    const textParagraph = CardService.newTextParagraph();
    textParagraph.setText(displayedText);

    const answerSection = CardService.newCardSection()
      .addWidget(textParagraph);

    const updatedCard = createSidebarCard(answerSection);

    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();

  } catch (err) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Error fetching response: " + err.message))
      .build();
  }
}
...

AgentHandler.gs

...
// Service that handles Gemini Enterprise AI Agent operations.

// Submits a query to the AI agent and returns the response string synchronously
function queryAgent(input) {
  const isNewSession = input.forceNewSession || !PropertiesService.getUserProperties().getProperty(AGENT_SESSION_NAME);
  const sessionName = input.forceNewSession ? createAgentSession() : getOrCreateAgentSession();

  let systemPrompt = "SYSTEM PROMPT START Do not respond with tables but use bullet points instead.";
  if (input.forceNewSession) {
    systemPrompt += " Do not ask the user follow-up questions or converse with them as history is not kept in this interface.";
  }
  systemPrompt += " SYSTEM PROMPT END\n\n";

  const queryText = isNewSession ? systemPrompt + input.text : input.text;

  const requestPayload = {
    "session": sessionName,
    "userMetadata": { "timeZone": Session.getScriptTimeZone() },
    "query": { "text": queryText },
    "toolsSpec": { "vertexAiSearchSpec": { "dataStoreSpecs": getAgentDataStores().map(ds => { dataStore: ds }) } },
    "agentsSpec": { "agentSpecs": [{ "agentId": getAgentId() }] }
  };

  const responseContentText = UrlFetchApp.fetch(
    `https://${getLocation()}-discoveryengine.googleapis.com/v1alpha/${getReasoningEngine()}/assistants/default_assistant:streamAssist?alt=sse`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${ScriptApp.getOAuthToken()}` },
      contentType: 'application/json',
      payload: JSON.stringify(requestPayload),
      muteHttpExceptions: true
    }
  ).getContentText();

  if (isInDebugMode()) {
    console.log(`Response: ${responseContentText}`);
  }

  const events = responseContentText.split('\n').map(s => s.replace(/^data:\s*/, '')).filter(s => s.trim().length > 0);
  console.log(`Received ${events.length} agent events.`);

  let answerText = "";
  for (const eventJson of events) {
    if (isInDebugMode()) {
      console.log("Event: " + eventJson);
    }
    const event = JSON.parse(eventJson);

    // Ignore internal events
    if (!event.answer) {
      console.log(`Ignored: internal event`);
      continue;
    }

    // Handle text replies
    const replies = event.answer.replies || [];
    for (const reply of replies) {
      const content = reply.groundedContent.content;
      if (content) {
        if (isInDebugMode()) {
          console.log(`Processing content: ${JSON.stringify(content)}`);
        }
        if (content.thought) {
          console.log(`Ignored: thought event`);
          continue;
        }
        answerText += content.text;
      }
    }

    if (event.answer.state === "SUCCEEDED") {
      console.log(`Answer text: ${answerText}`);
      return answerText;
    } else if (event.answer.state !== "IN_PROGRESS") {
      throw new Error("Something went wrong, check the Apps Script logs for more info.");
    }
  }
  return answerText;
}

// Gets the list of data stores configured for the agent to include in the request.
function getAgentDataStores() {
  const responseContentText = UrlFetchApp.fetch(
    `https://${getLocation()}-discoveryengine.googleapis.com/v1/${getReasoningEngine().split('/').slice(0, 6).join('/')}/dataStores`,
    {
      method: 'get',
      // Use the add on service account credentials for data store listing access
      headers: { 'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}` },
      contentType: 'application/json',
      muteHttpExceptions: true
    }
  ).getContentText();
  if (isInDebugMode()) {
    console.log(`Response: ${responseContentText}`);
  }
  const dataStores = JSON.parse(responseContentText).dataStores.map(ds => ds.name);
  if (isInDebugMode()) {
    console.log(`Data stores: ${dataStores}`);
  }
  return dataStores;
}
...

Iniciar conta de serviço

No console do Google Cloud, siga estas etapas:

Clique em Menu ☰ > IAM e administrador > Contas de serviço > + Criar conta de serviço.

Defina o Nome da conta de serviço como ge-add-on.

Clique em Criar e continuar.
Adicione o papel Leitor do Discovery Engine às permissões.

Clique em Continuar e em Concluído. O sistema vai redirecionar você para a página Contas de serviço, onde é possível conferir a conta de serviço que criou.

Selecione a conta de serviço recém-criada e clique na guia Chaves.
Clique em Adicionar chave e em Criar nova chave.
Selecione JSON e clique em Criar.

A caixa de diálogo é fechada, e o par de chaves pública/privada recém-criado é automaticamente transferido por download para o ambiente local como um arquivo JSON.

Criar e configurar um projeto do Apps Script

Clique no botão a seguir para abrir o projeto do Apps Script do complemento de IA empresarial:

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.
Defina REASONING_ENGINE_RESOURCE_NAME como o nome do recurso do aplicativo Gemini Enterprise. Ele tem o seguinte formato:

# 1. Replace PROJECT_ID with the Google Cloud project ID.
# 2. Replace GE_APP_ID with the codelab app ID found in Google Cloud console > Gemini Enterprise > Apps.

projects/<PROJECT_ID>/locations/global/collections/default_collection/engines/<GE_APP_ID>

Defina APP_SERVICE_ACCOUNT_KEY como a chave JSON do arquivo da conta de serviço baixado nas etapas anteriores.
Clique em Salvar propriedades do script.

Implantação no Gmail e no Chat

No seu projeto do Apps Script, siga estas etapas:

Clique em Implantar > Testar implantações e em Instalar. Agora ele está disponível no Gmail.
Clique em Copiar em ID da implantação principal.

No console do Google Cloud, siga estas etapas:

Pesquise Google Chat API no campo de pesquisa do Google Cloud, clique em API Google Chat, em Gerenciar e em Configuração.

Selecione Ativar recursos interativos.
Desmarque a opção Participar de espaços e conversas em grupo.
Em Configurações de conexão, selecione Apps Script.
Defina o ID da implantação como o ID da implantação principal copiado nas etapas anteriores.
Em Visibilidade, selecione Disponibilize o app de chat para pessoas e grupos específicos no seu domínio do Workspace e digite seu endereço de e-mail.
Clique em Salvar.

Testar o complemento

Abra o Google Chat em uma nova guia e siga estas etapas:

Abra um espaço de mensagem direta com o app Chat Gemini Enterprise.

Clique em Configurar e siga o fluxo de autenticação.
Digite What are my meetings for today? e pressione enter. O app de chat do Gemini Enterprise vai responder com os resultados.

Abra o Gmail em uma nova guia e siga estas etapas:

Envie um e-mail para você mesmo com o Assunto definido como We need to talk e o Corpo definido como Are you available today between 8 and 9 AM?.
Abra o e-mail que você acabou de receber.
Abra a barra lateral do complemento IA empresarial.
Defina a Mensagem como Am I?.
Clique em Enviar mensagem.
A resposta aparece depois do botão.

6. Limpar

Excluir projeto do Google Cloud

Para evitar cobranças na conta do Google Cloud pelos recursos usados neste codelab, é recomendável excluir o projeto do Google Cloud.

No console do Google Cloud, siga estas etapas:

Clique em Menu ☰ > IAM e administrador > Configurações.

Clique em Encerrar.
Digite o ID do projeto.
Clique em Encerrar mesmo assim.

7. Parabéns

Parabéns! Você criou soluções que aproveitam o poder de aproximar o Gemini Enterprise e o Google Workspace para os trabalhadores.

A seguir

Mostramos apenas os casos de uso mais típicos neste codelab, mas existem muitas áreas de expansão que você pode querer considerar nas suas soluções, como estas:

Use ferramentas de desenvolvedor com tecnologia de IA, como a CLI do Gemini e a Antigravity.
Integração com outros frameworks e ferramentas de agentes, como MCPs personalizados, chamadas de função personalizadas e UIs generativas.
Integrar com outros modelos de IA, incluindo os personalizados, hospedados em plataformas dedicadas, como a Vertex AI.
Integração com outros agentes hospedados em plataformas dedicadas, como o Dialogflow, ou por terceiros via Cloud Marketplace.
Publique agentes no Cloud Marketplace para capacitar equipes, organizações ou usuários públicos.

Saiba mais

Existem muitos recursos disponíveis para desenvolvedores, como vídeos do YouTube, sites de documentação, exemplos de código e tutoriais:

Integrar agentes do Gemini Enterprise ao Google Workspace

1. Antes de começar

O que é o Gemini Enterprise?

O que é o Google Workspace?

Que tipo de integrações personalizadas?

Pré-requisitos

O que você vai criar

Agente personalizado sem código

Agente personalizado de programação avançada

Agente padrão como complemento do Google Workspace

O que você vai aprender

2. Começar a configuração

Revisar conceitos

App Gemini Enterprise

Web app do Gemini Enterprise

Inicializar e acessar recursos

App do Gemini Enterprise

Web app do Gemini Enterprise

3. Agente personalizado sem código

Revisar conceitos

Gemini

Repositório de dados do Gemini Enterprise

Designer de agentes do Gemini Enterprise

Analisar a arquitetura da solução

Ativar APIs

Configure a tela de consentimento OAuth

Criar credenciais de cliente OAuth

Criar repositórios de dados

Repositórios de dados de teste

Criar um agente personalizado

Testar agente personalizado

4. Agente personalizado de programação profissional

Revisar conceitos

Vertex AI

Kit de Desenvolvimento de Agente (ADK)

Protocolo de Contexto de Modelo (MCP)

Ferramenta de função

Analisar a arquitetura da solução

Revisar o código-fonte

agent.py

Ativar APIs

Atualizar a tela de permissão OAuth

Atualizar credenciais de cliente OAuth

Ativar o MCP da Vertex AI para Pesquisa

Configurar o app Chat

Implantar um agente no Vertex AI Agent Engine

Registrar agente no Gemini Enterprise

Testar agente

5. Agente padrão como complemento do Google Workspace

Revisar conceitos

Complemento do Google Workspace

Apps Script

Estrutura de cards do Google Workspace

Analisar a arquitetura da solução

Revisar o código-fonte

appsscript.json

Chat.gs

Sidebar.gs

AgentHandler.gs

Iniciar conta de serviço

Criar e configurar um projeto do Apps Script

Implantação no Gmail e no Chat

Testar o complemento

6. Limpar

Excluir projeto do Google Cloud

7. Parabéns

A seguir

Saiba mais