Integrar conceitos fundamentais de IA aos apps do Google Chat

1. Antes de começar

O que são os apps do Google Chat com IA?

Os apps do Google Chat com IA fazem o seguinte:

  • Transferem seus serviços e recursos para o Google Chat para que os usuários recebam informações e realizem ações sem sair da conversa.
  • Integrar com modelos de IA generativa para criar, pesquisar e editar dados como texto ou imagens.
  • Ofereça uma experiência de agente aplicando conceitos de IA de conversação para interações mais práticas, naturais, sofisticadas e úteis.

Por que integrar os apps do Google Chat à IA?

Os casos de uso típicos se enquadram nas seguintes categorias:

  • Criação e edição de conteúdo. Gere textos de marketing, elabore postagens para redes sociais, produza imagens realistas, escreva músicas ou contribua para a criação de conteúdo em vídeo.
  • Pesquisa e análise de dados. Extraia insights importantes de uma base de conhecimento não estruturada, resuma textos longos, classifique conteúdos ou traduza idiomas com maior precisão e velocidade.
  • Conversa. Participe de conversas naturais, informativas e eficientes como se estivesse falando com um assistente.
  • Automação de tarefas. Realizar ações em nome do usuário, como criar um evento na agenda, enviar um documento ou gerenciar um tíquete em um sistema externo.

A capacidade de integrar esses recursos direto na interface fácil de usar do Google Chat é uma grande oportunidade para quem quer melhorar a experiência e a produtividade dos usuários.

Pré-requisitos

O que você vai criar

Neste codelab, você vai criar oito apps minimalistas do Google Chat que integram conceitos fundamentais de IA para mostrar como eles podem ser aplicados em aplicativos do mundo real. Todos são criados como complementos do Google Workspace e dependem da arquitetura HTTP:

2f1e2c66f6e2e2f0.png

Isso funciona da seguinte maneira:

  1. Um usuário envia uma mensagem no Google Chat para um app do Chat, seja como uma mensagem direta ou em um espaço do Chat.
  2. Uma solicitação HTTP é enviada ao servidor da Web em execução como uma função do Node.js Google Cloud Run que contém a lógica do app Chat.
  3. Opcionalmente, a lógica do app Chat pode ser integrada aos serviços do Google Workspace (como Agenda e Planilhas), a outros Serviços do Google (como Maps, YouTube e Vertex AI) ou a outros serviços da Web (como um sistema de gerenciamento de projetos ou uma ferramenta de emissão de tíquetes).
  4. O servidor da Web envia uma resposta HTTP de volta ao serviço do app Chat no Chat.
  5. A resposta é enviada ao usuário.
  6. Se quiser, o app Chat pode chamar a API Chat para postar mensagens de forma assíncrona ou realizar outras operações.

Cada função do Node.js Google Cloud Run do app do Google Chat contém a própria versão dos seguintes arquivos de origem para realizar as ações necessárias nas etapas 3 e 6 acima:

  • package.json: um manifesto central que funciona como um modelo para o projeto Node.js. Ele é usado para definir metadados, dependências e scripts.
  • env.js: um script que define as constantes necessárias para a execução. Ele precisa ser editado com base no ambiente e na configuração.
  • index.js: O script principal que processa a lógica dos eventos de interação do Google Chat. Neste codelab, apenas o tipo de evento de mensagem é implementado, mas normalmente ele incluiria outros tipos, como clique em card, comando de barra e caixa de diálogo em aplicativos da vida real.

App de comandos

Esse app usa um modelo do Gemini para conversar com os usuários em linguagem natural usando respostas concisas e em texto simples.

5975b36968ab597a.gif

App Format

Esse app se baseia no Prompt app ao adicionar suporte a respostas em rich text compatíveis com o formato de texto específico das mensagens do Google Chat.

bc49e0acf0838f28.gif

App Ground

Esse app usa como base o Format app, adicionando suporte à ferramenta da Pesquisa Google e retornando fontes em mensagens de resposta com cards.

3cf232bf153f6abc.gif

app MCP

Esse app se baseia no Format app ao adicionar suporte ao Protocolo de Contexto de Modelo (MCP) do Google Workspace Developer Assist.

8219c29366e9120e.gif

App multiturno

Esse app se baseia no Format app ao adicionar suporte à memória conversacional com um banco de dados do Google Cloud Firestore.

a819c274ce586451.gif

App de ferramenta personalizada

Esse app se baseia no Multi-turn app ao adicionar suporte a uma ferramenta personalizada de chamada de função que chama a API Google Workspace Calendar com base nas informações fornecidas pelo usuário.

a1c4f586b7ab2e24.gif

Transmissão do app

Esse app usa um modelo do Gemini para gerar contos com base em temas fornecidos pelos usuários. A API Google Chat é usada para enviar resultados e status em mensagens à medida que o progresso é feito.

fd347ba03fe86e22.gif

App multimodal

Esse app usa um modelo do Gemini para editar imagens com base em instruções textuais dos usuários. As APIs do Google Chat são usadas para fazer o download e o upload das imagens como anexos de mensagens.

57574be33474bbc.gif

O que você vai aprender

  • Os conceitos fundamentais de IA são relevantes para os apps do Google Chat e para a aplicação deles.
  • Para acessar a Vertex AI usando o SDK da IA generativa do Google.
  • Para usar as APIs do Google Workspace e desenvolver recursos incríveis e eficientes.
  • Aproveitar o Cloud Run para criar apps escalonáveis do Google Chat.

O que é preciso

  • Já ter concluído o guia de início rápido Criar um app HTTP do Google Chat com Node.js. Este codelab se baseia no projeto do Google Cloud, no app do Google Chat e na função do Google Cloud Run resultantes.

2. Começar a configuração

Inicializar e acessar recursos

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

Configuração da API Google Chat

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

  1. Selecione o projeto.
  2. No campo de pesquisa do Google Cloud, procure "API Google Chat", clique em API Google Chat, em Gerenciar e em Configuração.

  1. Defina o Nome do app e a Descrição como Gen AI App.
  2. Clique em Salvar.

9a06649cf9285b99.png

Espaço do Google Chat

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

  1. Se ainda não tiver feito isso, abra um espaço de mensagem direta com o app Chat.
  2. Digite Hello e pressione enter. O app Chat vai responder com seu nome e imagem do avatar.

e3b195c7b7b8e2af.png

Serviço de função do Google Cloud Run

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

  1. Selecione o projeto.
  2. Clique em Menu ☰ > Cloud Run > Serviços.

  1. Na lista de serviços, clique em addonchatapp e abra a guia Origem.

b69df34ea0dc48a5.png

Fazer o download do código-fonte e dos recursos no local

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

  1. No ambiente de desenvolvimento local de sua preferência, abra o diretório node/chat/gen-ai-apps.

3c57c15db4ebfddb.png

3. Comando do app

Esse app pede ao Gemini na Vertex AI para conversar com os usuários em linguagem natural usando respostas concisas e em texto simples. A implementação depende do SDK da IA generativa do Google para Node.js.

Revisar conceitos

Linguagem natural

Qualquer linguagem falada ou escrita por humanos para a comunicação cotidiana, em contraste com linguagens artificiais ou de computador.

Funções do Cloud Run

As funções do Cloud Run são ótimas para criar back-ends sem servidor, processar dados em tempo real e criar apps inteligentes. Não há servidores para provisionar, gerenciar, corrigir ou atualizar. Eles têm escalonamento automático, são altamente disponíveis e tolerantes a falhas.

Comandos

Comando é a técnica de criar entradas (comandos) para orientar um modelo de IA generativa a produzir uma saída desejada. Isso geralmente envolve formular perguntas com cuidado, fornecer contexto, dar instruções ou exemplos para obter respostas específicas e relevantes do modelo.

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.

c9e9c7a1945b22ac.png

Gemini

O Gemini é um LLM multimodal do Google que pode ser acessado pela Vertex AI. 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.

SDK da IA generativa do Google

O SDK da IA generativa do Google foi projetado para que os desenvolvedores criem aplicativos com tecnologia do Gemini. Ele oferece uma interface unificada compatível com a API Gemini para desenvolvedores e a Vertex AI. Ela vem com bibliotecas de cliente em Python, Go, Node.js e Java.

Fluxo de análise

c625fdcc8b4a27f4.png

Revisar o código-fonte

env.js

...
// Replace with your GCP project ID.
projectID: process.env.PROJECT_ID || 'your-google-cloud-project-id',

// Replace with your GCP project location.
location: process.env.LOCATION || 'your-google-cloud-project-location',

// Replace with the Gemini model to use.
model: process.env.MODEL || 'gemini-2.5-flash-lite',
...

index.js

// Import the Google Gen AI SDK.
import { GoogleGenAI } from '@google/genai';
...
// Use Vertex AI.
const genAI = new GoogleGenAI({vertexai: true, project: env.projectID, location: env.location});

http('gen-ai-app', async (req, res) => {
 // Send a new Chat message with the generated answer
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: await generateAnswer(req.body.chat.messagePayload.message.text)
 }}}}});
});

async function generateAnswer(message) {
 // The prompt is made of the user's message and specific instructions for the model.
 const prompt = 'In a consice and with plain text only (no formatting), '
                 + 'answer the following message in the same language: ' + message;
 const aiResponse = await genAI.models.generateContent({model: env.model, contents: prompt});
 return aiResponse.candidates[0].content.parts[0].text;
};
...

package.json

...
"main": "index.js",
"type": "module",
"scripts": {
  "start": "node index.js"
},
"dependencies": {
  "@google-cloud/functions-framework": "^4.0.0",
  "@google/genai": "1.15.0"
},
...

Ative a API Vertex AI

  1. No console do Google Cloud, ative a API Vertex AI:

  1. Clique em Menu ☰ > APIs e serviços > APIs e serviços ativados e confirme se a API Vertex AI está na lista.

Atualizar a função do Node.js no Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/1-prompt. Ele contém todo o código-fonte e os recursos.
  2. Abra env.js em um editor e defina o seguinte:
  3. projectID: o ID do seu projeto do Google Cloud. Ele pode ser recuperado na página de boas-vindas do console do Google Cloud.

  1. location: a região do serviço de função do Google Cloud Run. Ele pode ser recuperado na página de detalhes do serviço de função do Google Cloud Run.

  1. model: o modelo a ser usado. Consulte todos os modelos disponíveis na documentação da Vertex AI. O modelo definido por padrão é o Flash para uma execução rápida e barata.

6c2fb9f554f53a4a.png

  1. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Defina o Ponto de entrada da função como gen-ai-app.
  3. Clique em ➕, digite env.js e clique em ✔️ para criar o arquivo de origem ausente.
  4. Substitua todo o conteúdo dos arquivos index.js, env.js e package.json pelos do seu ambiente de desenvolvimento local.
  5. Clique em Salvar e reimplantar.
  6. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite Hello, how are you? e pressione enter. O app precisa responder de forma concisa em texto simples, conforme nossas instruções no comando.

3cc1fd1de2a9e239.png

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite Bonjour comment allez-vous? e pressione enter. O app precisa responder em francês, conforme nossas instruções no comando.

77010f4ad0bde5da.png

4. Formatar app

Esse app se baseia no Prompt app ao adicionar suporte para respostas em rich text compatíveis com o formato de mensagem de texto do Google Chat. As instruções no comando são atualizadas com uma descrição detalhada das diferentes opções que o modelo pode usar.

Revisar conceitos

Mensagens de texto do Google Chat

As mensagens de texto do Google Chat oferecem várias opções de formatação para que você possa escrever mensagens mais claras e expressivas diretamente na interface do Google Chat. Elas são baseadas em regras específicas de Markdown para aplicar negrito, itálico, tachado, criar hiperlinks etc.

Fluxo de análise

c625fdcc8b4a27f4.png

Revisar o código-fonte

index.js

...
async function generateAnswer(message) {
 // Specify formatting options that are compatible with Google Chat messages
 // https://developers.google.com/workspace/chat/format-messages#format-texts
 const prompt = `Use simple text for concise answers. The only formatting options you can use is to
(1) surround some text with a single star for bold such as *text* for strong emphasis
(2) surround some text with a single underscore for italic such as _text_ for gentle emphasis
(3) surround some text with a single tild for strikethrough such as ~text~ for removal
(4) use a less than before followed by a URL followed by a pipe followed by a link text followed
    by a more than for a hyperlink such as <https://example.com|link text> for resource referencing
(5) use a backslash followed by the letter n for a new line such as \n for readibility
(6) surround some text with a single backquote such as \`text\` for quoting code
(7) surround an entire paragraph with three backquotes in dedicated lines such as
    \`\`\`\nparagraph\n\`\`\` for quoting code
(8) prepend lines with list items with a single star or hyphen followed by a single space
    such as * list item or - list item for bulleting ;
DO NOT USE ANY OTHER FORMATTING OTHER THAN THOSE.
Answer the following message in the same language: ${message}`;
...
};
...

Atualizar a função do Node.js do Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/2-format. Ele contém todo o código-fonte e os recursos.
  2. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Substitua todo o conteúdo do arquivo index.js pelo conteúdo do seu ambiente de desenvolvimento local.
  3. Clique em Salvar e reimplantar.
  4. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite Showcase all formatting options you have with one paragraph each e pressione enter. O app precisa responder com exemplos de formatação com base nas instruções do comando.

cc7f7101d9f7c10.png

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite What are Google Chat apps? What's great about them? e pressione enter. O app precisa responder com formatação quando for útil.

83557d4c7071aac8.png

5. App de embasamento

Esse app usa o Format app e adiciona suporte para embasamento e retorno de fontes. Ele executa a ferramenta da Pesquisa Google e anexa cards com links para respostas.

Revisar conceitos

Embasamento

Embasamento é a técnica de conectar modelos a fontes de informações. Ele é usado com frequência em aplicações práticas para melhorar a precisão e a relevância do conteúdo gerado, fazendo referência a dados do mundo real. Assim, o modelo não alucina nem produz informações factualmente incorretas.

Ferramenta da Pesquisa Google

A ferramenta da Pesquisa Google melhora o embasamento porque permite que os modelos pesquisem informações em tempo real na Web, garantindo que as respostas sejam precisas e atuais.

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

Fluxo de revisão

b72d69a6e79858d6.png

Revisar o código-fonte

index.js

...
const aiResponse = await genAI.models.generateContent({
 model: env.model,
 contents: prompt,
 // Google Search tool is enabled
 config: { tools: [{ googleSearch: {}}]}
});

let groundingCardsV2 = undefined;
const grounding = aiResponse.candidates[0].groundingMetadata;
// Go through the grounding metadata if any
if (grounding && grounding.groundingChunks && grounding.groundingChunks.length > 0) {
 let linkButtons = [];
 grounding.groundingChunks.forEach(groundingChunk => {
   if (groundingChunk.web) {
     // Create one link button per web URL returned
     linkButtons.push({
       text: groundingChunk.web.domain,
       onClick: { openLink: { url: groundingChunk.web.uri}}
     });
   }
 });
 // Create a card with link buttons
 groundingCardsV2 = [{
   cardId: "sourcesCard",
   card: { sections: [{
     header: "Sources",
     widgets: [{ buttonList: { buttons: linkButtons}}]
   }]}
 }];
}

// Send a Chat message with the generated answer
return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
 text: aiResponse.candidates[0].content.parts[0].text,
 // The sources are referenced in the card
 cardsV2: groundingCardsV2
}}}}});
...

Atualizar a função do Node.js do Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/3-ground. Ele contém todo o código-fonte e os recursos.
  2. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Substitua todo o conteúdo do arquivo index.js pelo conteúdo do seu ambiente de desenvolvimento local.
  3. Clique em Salvar e reimplantar.
  4. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

No espaço de mensagem direta com o app Chat no Google Chat, digite What's the world population? e pressione enter. O app deve responder anexando links de origem em um card.

cff461da29c05873.png

6. App MCP

Esse app se baseia no Format app ao adicionar suporte para ferramentas fornecidas por um servidor do Protocolo de Contexto de Modelo (MCP) hospedado remotamente. Ele se conecta ao MCP do Google Workspace Developer Assist, que oferece ferramentas para acessar e pesquisar a documentação para desenvolvedores do Google Workspace.

Revisar conceitos

Protocolo de Contexto de Modelo (MCP)

O Protocolo de Contexto de Modelo é um framework de código aberto que integra modelos a serviços externos de maneira padronizada. Os modelos podem descobrir, entender e interagir de forma programática com várias ferramentas, expandindo os recursos, realizando ações no mundo real e acessando informações atualizadas.

SDK do MCP TypeScript

O SDK do TypeScript implementa a especificação completa do MCP, simplificando a criação de clientes MCP que se conectam a qualquer servidor MCP. Ele também permite o desenvolvimento de servidores MCP que oferecem acesso a recursos, comandos e ferramentas.

Fluxo de análise

e0b324e2cca21915.png

Revisar o código-fonte

index.js

// Import the MCP TypeScript SDK.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
...
// Create and connect the MCP client from the URL.
const mcpServerUrl = new URL("https://workspace-developer.goog/mcp");
const client = new Client({ name: "gen-ai-app-mcp", version: "1.0.0" });
// Try Streamable HTTP first (new) and SSE (old) as fallback for transport
try {
 await client.connect(new StreamableHTTPClientTransport(mcpServerUrl));
} catch (error) {
 await client.connect(new SSEClientTransport(mcpServerUrl));
}

http('gen-ai-app', async (req, res) => {
 ...
 const aiResponse = await genAI.models.generateContent({
   model: env.model,
   contents: prompt,
   // MCP tools are enabled
   config: { tools: [mcpToTool(client)]}
 });
 ...
}
...

package.json

...
"dependencies": {
  ...
  "@modelcontextprotocol/sdk": "^1.18.1"
},
...

Atualizar a função do Node.js do Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/4-mcp. Ele contém todo o código-fonte e os recursos.
  2. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Substitua todo o conteúdo dos arquivos index.js e package.json pelos do seu ambiente de desenvolvimento local.
  3. Clique em Salvar e reimplantar.
  4. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite What can you do for me? e pressione enter. O app precisa descrever o que ele pode fazer (ferramentas do MCP).

13535bfd31d85a50.png

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite I would like to get the latest official documentation for the Google Sheets API append values e pressione enter. O app precisa responder com a documentação solicitada (usando ferramentas do MCP).

8a6f4ac5b7d5fa4a.png

7. App com várias interações

Esse app se baseia no Format app ao adicionar suporte à memória conversacional, rastreando o histórico de interações de chat. Ela permite uma experiência mais natural, inteligente e personalizada. O app usa o banco de dados padrão do Google Cloud Firestore associado ao projeto do Google Cloud para armazenamento.

Revisar conceitos

Multiturno

O conceito multiturno se refere à capacidade de um modelo manter contextos e continuidade em várias trocas e conversas. É um recurso essencial para oferecer suporte a conversas complexas, funcionalidades sofisticadas baseadas em IA e uma experiência do usuário natural.

Google Cloud Firestore

O Google Cloud Firestore é um banco de dados NoSQL na nuvem, flexível e escalonável para desenvolvimento de aplicativos para dispositivos móveis, Web e servidores. Ele armazena dados em documentos, organizados em coleções, e permite sincronização em tempo real e suporte off-line.

Fluxo de análise

52920a2227467218.png

Revisar o código-fonte

index.js

// Import the Google Cloud Firestore client library.
import { Firestore } from '@google-cloud/firestore';
...
// Configure DB
const USERS_PREFIX = 'users/';
const CHATS_COLLECTION = 'chats';
const db = new Firestore();
...
// Create or update data for a given user
async function createOrUpdateChatHistory(userId, data) {
 await db.collection(CHATS_COLLECTION).doc(userId.replace(USERS_PREFIX, '')).set(data);
};

// Retrieve data snapshot for a given user
async function getChatHistory(userId) {
 return await db.collection(CHATS_COLLECTION).doc(userId.replace(USERS_PREFIX, '')).get();
};
...

...
http('gen-ai-app', async (req, res) => {
 // Retrieve the chat history of the user
 const chatHistory = await getChatHistory(userId);
 const chat = genAI.chats.create({
   model: env.model,
   // Initiate the model with chat history for context
   history: chatHistory.exists ? chatHistory.data().contents : []
 });
 // If no history, send a first message to the model with instructions on how to behave
 if(!chatHistory.exists) {
   const preambule = 'The only formatting options you can use is to '
                   + ...
                   + 'DO NOT USE ANY OTHER FORMATTING OTHER THAN THOSE. '
                   + 'Answer in the same language that I use.';
   // The answer to this message is ignored
   await chat.sendMessage({message: preambule});
 }

 // Send the user's message to the model to generate the answer
 const aiResponse = await chat.sendMessage({message: userMessage});

 // Persist the updated chat history of the user
 await createOrUpdateChatHistory(userId, {contents: chat.getHistory({curated: true})});

 // Send a Chat message with the generated answer
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: aiResponse.candidates[0].content.parts[0].text
 }}}}});
});
...

package.json

...
"dependencies": {
  ...
  "@google-cloud/firestore": "^7.11.5"
},
...

Ativar a API Google Cloud Firestore

  1. No console do Google Cloud, ative a API Cloud Firestore:

  1. Clique em Menu ☰ > APIs e serviços > APIs e serviços ativados e confirme se a API Cloud Firestore está na lista.

Criar um banco de dados do Cloud Firestore

  1. No console do Google Cloud, clique em Menu ☰ > Firestore.

  1. Clique em Criar um banco de dados do Firestore.
  2. Mantenha a configuração padrão e clique em Criar banco de dados.

Atualizar a função do Node.js do Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/5-multi-turn. Ele contém todo o código-fonte e os recursos.
  2. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Substitua todo o conteúdo dos arquivos index.js e package.json pelos do seu ambiente de desenvolvimento local.
  3. Clique em Salvar e reimplantar.
  4. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite Can you speak with the English from the 80's for now on? e pressione enter. O app deve responder de forma positiva.

b273beda7e203b23.png

  1. No espaço de mensagem direta com o app Chat no Google Chat, digite Define what Google Chat apps are in one sentence e pressione enter. O app precisa continuar respondendo com o inglês dos anos 80.

9156f563c369f186.png

8. App de ferramenta personalizada

Esse app se baseia no Multi-turn app ao adicionar suporte a uma ferramenta personalizada de chamada de função que depende da API Google Workspace Calendar para recuperar o próximo evento de uma agenda pública. O modelo gerencia todas as interações do usuário, incluindo o recebimento de entradas e a entrega de saídas da ferramenta. No entanto, o aplicativo ainda é responsável por executar as chamadas de API necessárias e fornecer resultados ao modelo quando solicitado. O app usa uma chave de API do Google porque não é necessário ter credenciais de usuário para buscar dados públicos da agenda.

Revisar conceitos

Chamadas de função

A chamada de função permite que um modelo detecte quando uma solicitação do usuário pode ser atendida por uma ferramenta ou API externa. Em seguida, o modelo fornece os parâmetros necessários para chamar essa ferramenta, integrando funcionalidades externas às respostas.

APIs do Google Workspace

As APIs do Google Workspace permitem que os desenvolvedores integrem os aplicativos deles a vários serviços do Google Workspace. Essas APIs oferecem acesso programático a funcionalidades em produtos como Gmail, Chat, Agenda, Drive, Documentos, Planilhas e muito mais, permitindo automação, sincronização de dados e criação de fluxos de trabalho personalizados.

Fluxo de análise

ed866ca369a4512f.png

Revisar o código-fonte

env.js

...
// Replace with your Google API key.
googleApiKey: process.env.GOOGLE_API_KEY || 'your-google-api-key',
...

index.js

// Import parameter type definitions from Google Gen AI SDK.
import { GoogleGenAI, Type } from '@google/genai';
// Import Google APIs that include the Google Calendar API.
import { google } from 'googleapis';
...
// Create a Google Calendar API client using a Google API key.
const calendar = google.calendar({version: 'v3', auth: env.googleApiKey});
...
// Define the tool used for function calling
const getNextPublicCalendarEventTitleFunctionDeclaration = {
 name: 'getNextPublicCalendarEventTitle',
 parameters: {
   type: Type.OBJECT,
   description: 'Get the title of the next event of a public calendar.',
   properties: {
     calendarId: {
       type: Type.STRING,
       description: 'ID of the public calendar to get the next event title.',
     }
   },
   required: ['calendarId']
 }
};

// The function referenced in the tool definition
async function getNextPublicCalendarEventTitle(calendarId) {
 // Use Calendar API to retrieve the next event in the given calendar
 const response = await calendar.events.list({
   calendarId: calendarId,
   timeMin: new Date().toISOString(),
   maxResults: 1,
   singleEvents: true,
   orderBy: 'startTime',
 });
 const events = response.data.items;
 if (!events || events.length === 0) {
   return null;
 }
 return `${events[0].summary}`;
};
...

...
http('gen-ai-app', async (req, res) => {
 ...
 // Send the user's message to the model to generate the answer
 let aiResponse = await chat.sendMessage({
   message: userMessage,
   // The tool used for function calling is enabled
   config: { tools: [{ functionDeclarations: [getNextPublicCalendarEventTitleFunctionDeclaration]}]}
 });

 // Handle the function calling turn with the model if any
 const functionCall = aiResponse.candidates[0].content.parts[0].functionCall;
 if (functionCall) {
   let functionResult = null;
   switch(functionCall.name) {
     case 'getNextPublicCalendarEventTitle':
       // Make the function call as per model request
       functionResult = await getNextPublicCalendarEventTitle(functionCall.args['calendarId']);
       break;
     default:
   }
   // Finish the function calling turn by sending the execution result to the model
   aiResponse = await chat.sendMessage({ message: { functionResponse: {
     name: functionCall.name,
     response: { output: functionResult }
   }}});
 }
 ...
 // Send a Chat message with the generated answer
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: aiResponse.candidates[0].content.parts[0].text
 }}}}});
});
...

package.json

...
"dependencies": {
  ...
   "googleapis": "^160.0.0"
},
...

Ativar a API Calendar

  1. No console do Google Cloud, ative a API Google Calendar:

  1. Clique em Menu ☰ > APIs e serviços > APIs e serviços ativados e confirme se a API Google Agenda está na lista.

Criar chave de API do Google

No console do Google Cloud, siga estas etapas:

  1. Clique em Menu ☰ > APIs e serviços > Credenciais.

  1. Clique em + Criar credenciais e selecione Chave de API.
  2. Aguarde a conclusão da operação.
  3. Na caixa de diálogo de confirmação, localize o campo de texto Sua chave de API e clique em Copiar para a área de transferência.

Atualizar a função do Node.js do Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/6-custom-tool. Ele contém todo o código-fonte e os recursos.
  2. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Substitua todo o conteúdo dos arquivos index.js e package.json pelos do seu ambiente de desenvolvimento local.
  3. Abra o arquivo env.js e faça o seguinte:
  4. Adicione googleApiKey aos campos exportados
export const env = {
 ...
 googleApiKey: 'your-google-api-key',
};
  1. Substitua your-google-api-key pela chave da API do Google copiada na etapa anterior. Para acessar a chave, clique em Mostrar chave na página de credenciais do Google Cloud.

  1. Clique em Salvar e reimplantar.
  2. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

  1. No Google Agenda, siga estas etapas:
  2. Em Outras agendas, clique em + e em Criar nova agenda.
  3. Defina o Nome como My Public Calendar.
  4. Clique em Criar agenda.
  5. Aguarde a conclusão da operação.
  6. Em Configurações das minhas agendas, selecione a agenda recém-criada Minha agenda pública.
  7. Em Permissões de acesso a eventos, selecione Disponibilizar ao público e clique em OK na caixa de diálogo Aviso.
  8. Em Autorizações de acesso a eventos, selecione Ver todos os detalhes de eventos no menu suspenso ao lado da opção Disponibilizar ao público.
  9. Em Integrar agenda, copie o valor do campo ID da agenda para a área de transferência.
  10. Clique na seta para a esquerda no canto superior esquerdo para sair das Configurações.
  11. Clique na agenda para criar um evento para amanhã, digite Important meeting, selecione Minha agenda pública no menu suspenso e clique em Salvar.
  12. No espaço de mensagem direta com o app Chat no Google Chat, digite When is the next meeting? e pressione enter. O app precisa solicitar uma precisão porque não está claro a qual agenda o usuário se refere.

40383099311b0813.png

  1. No espaço de mensagem direta com o app Chat no Google Chat, cole o ID da agenda que você copiou anteriormente para a área de transferência e pressione enter. O app deve responder com detalhes sobre o evento criado anteriormente.

4c614c7e444e3b45.png

9. App de streaming

Esse app usa um modelo do Gemini para gerar histórias de dois minutos com base em temas fornecidos pelos usuários. Como leva tempo para gerar respostas completas, o app faz chamadas para o modelo no modo de streaming e usa a API do Google Chat para enviar conteúdos e status em mensagens à medida que o progresso é feito.

Revisar conceitos

API Google Chat

A API Google Chat permite que os desenvolvedores interajam de forma programática com o Google Chat, enviando mensagens, criando espaços, gerenciando participantes e muito mais para criar integrações e bots personalizados.

Streaming

Streaming é o processo de receber dados em um fluxo contínuo, em vez de esperar que toda a resposta seja gerada. Quando se trata de chamadas de modelos de IA, o streaming permite que os aplicativos mostrem resultados parciais aos usuários assim que eles ficam disponíveis, melhorando a performance percebida e a experiência do usuário, especialmente para tarefas de geração mais longas. Isso é particularmente relevante para modelos de IA generativa que podem levar um tempo significativo para produzir uma saída completa.

Fluxo de análise

25f9036eecd9a48b.png

Revisar o código-fonte

index.js

// Import Google Auth library used to create Google Chat API client
import { GoogleAuth } from 'google-auth-library';
...
http('gen-ai-app', async (req, res) => {
 // Use app authentication.
 // Application Default Credentials (ADC) will use the Cloud Run function's
 // default service account, we just need to specify the Chat API app auth scopes.
 const auth = new GoogleAuth({
   // Chat API app authentication scopes
   scopes: ['https://www.googleapis.com/auth/chat.bot']
 });

 // Create Chat service client with application credentials
 const chatClient = google.chat({
   version: 'v1',
   auth: await auth.getClient()
 });

 // Send a server streaming request to generate the answer
 const aiResponse = await genAI.models.generateContentStream({
   model: env.model,
   contents: `Generate a story about a ${userMessage}. `
               + `It should take 2 minutes to read it out loud.`
 });

 // Send a first Chat message to summarize what will be done
 await chatClient.spaces.messages.create({
   parent: spaceName,
   requestBody: { text: `Sure, let me work on generating a short story `
                           + `about a ${userMessage} like you requested.`}
 });

 // Go through the response chunks received from the stream
 let messageName = undefined;
 let answer = "";
 for await (const chunk of aiResponse) {
   const text = chunk.text;
   if (text) {
     // Update the answer by concatenating the response chunks
     answer += text;
     // The Chat message request body is the same for message creation and update
     const responseBody = {
       text: answer,
       accessoryWidgets: [getStatusAccessoryWidget('Generating story...', 'progress_activity')]
     }
     if (!messageName) {
       // Create a Chat message dedicated to the generated content
       const messageResponse = await chatClient.spaces.messages.create({
         parent: spaceName,
         requestBody: responseBody
       });
       messageName = messageResponse.data.name;
     } else {
       // Update the Chat message dedicated to the generated content
       await chatClient.spaces.messages.patch({
         name: messageName,
         updateMask: 'text,accessory_widgets',
         requestBody: responseBody
       });
     }
   }
 }

 // Update the accessory widget with final progress status
 await chatClient.spaces.messages.patch({
   name: messageName,
   updateMask: 'accessory_widgets',
   requestBody: {
     accessoryWidgets: [getStatusAccessoryWidget('Story is fully generated', 'check')]
   }
 });

 // Send a last Chat message to confirm it's done
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: 'All done, I hope you like it!'
 }}}}});
});

// Create an accessory widget with progress status
function getStatusAccessoryWidget(text, icon) {
 return { buttonList: { buttons: [{
   text: text,
   icon: { materialIcon: { name: icon}},
   // This is a workaround to have the icon shown, it's not clickable
   onClick: { openLink: { url: "https://google.com"}},
   disabled: true
 }]}};
}

package.json

...
"dependencies": {
  ...
   "google-auth-library": "^10.3.0"
},
...

Atualizar a função do Node.js do Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/7-stream. Ele contém todo o código-fonte e os recursos.
  2. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Substitua todo o conteúdo dos arquivos index.js e package.json pelos do seu ambiente de desenvolvimento local.
  3. Clique em Salvar e reimplantar.
  4. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

No espaço de mensagem direta com o app Chat no Google Chat, digite turtle e pressione enter. O app precisa responder com uma mensagem de confirmação, a história gerada com o status à medida que o progresso é feito e uma mensagem de confirmação de conclusão.

17600cd1490972c7.png

26af4b3d442712a5.png

10. App multimodal

Esse app usa um modelo para editar imagens com base em instruções textuais dos usuários. Os usuários e o app adicionam as imagens como anexos de mensagens do Google Chat para troca. O app depende das APIs do Google Chat para fazer o download e upload de imagens de forma programática.

Revisar conceitos

Anexo de mensagem do Google Chat

Os anexos de mensagens do Google Chat são arquivos, como imagens ou vídeos, enviados para uma mensagem do Google Chat. Esses anexos podem ser gerenciados de maneira programática, permitindo que os aplicativos interajam com mídia avançada diretamente nas conversas.

Delegação em todo o domínio (DWD)

A delegação em todo o domínio (DWD) permite que uma conta de serviço represente usuários em um domínio do Google Workspace, permitindo que os aplicativos realizem ações em nome desses usuários sem autorização direta. Isso é útil para apps que precisam acessar dados do usuário ou realizar ações (como fazer upload de anexos para o Google Chat) no contexto do usuário, mesmo quando ele não está presente, concedendo à conta de serviço acesso amplo em todo o domínio.

Fluxo de análise

74295b25761f1682.png

Revisar o código-fonte

env.js

...
// Replace with the Gemini model to use.
model: process.env.MODEL || 'gemini-2.0-flash-preview-image-generation',
...

index.js

...
// Import byte stream management libraries.
import { Buffer } from 'buffer';
import { Readable } from 'stream';
...
// Download a Google Chat attachment as base 64 string.
async function downloadFile(appChatClient, attachmentName) {
 const response = await appChatClient.media.download({
     resourceName: attachmentName,
     alt: 'media'
   }, {
     responseType: 'stream'
 });
 const chunks = [];
 return new Promise((resolve) => {
   response.data.on('data', (chunk) => {
     chunks.push(chunk);
   });
   response.data.on('end', () => {
     const fileBuffer = Buffer.concat(chunks);
     const base64String = fileBuffer.toString('base64');
     resolve(base64String);
   });
 });
}

// Upload a base 64 string as Google Chat attachment of a space.
async function uploadFile(useChatClient, spaceName, data) {
 const filename = 'generated_image.png';
 return await userChatClient.media.upload({
   parent: spaceName,
   requestBody: { filename: filename },
   media: {
     mimeType: 'image/png',
     body: Readable.from(Buffer.from(data, 'base64'))
   }
 });
}
...

...
http('gen-ai-app', async (req, res) => {
 const userEmail = req.body.chat.user.email;
 const spaceName = req.body.chat.messagePayload.space.name;
 const userMessage = req.body.chat.messagePayload.message.text;
 const attachmentName = req.body.chat.messagePayload.message.attachment[0].attachmentDataRef.resourceName;
 const attachmentContentType = req.body.chat.messagePayload.message.attachment[0].contentType;

 // Set up app authentication used to download the attachment input
 // Application Default Credentials (ADC) will use the Cloud Run function's
 // default service account.
 const appAuth = new GoogleAuth({
   // Specify the Chat API app authentication scopes
   scopes: ['https://www.googleapis.com/auth/chat.bot']
 });
 // Create Chat service client with application credentials
 const appChatClient = google.chat({
   version: 'v1',
   auth: await appAuth.getClient()
 });

 // Send a request to generate the answer with both text and image contents
 const aiResponse = await genAI.models.generateContent({
   model: env.model,
   contents: [{
     role: 'USER',
     parts: [
       // The text content of the message
       { text: userMessage },
       // The attachment of the message is downloaded and added inline
       { inlineData: {
         data: await downloadFile(appChatClient, attachmentName),
         mimeType: attachmentContentType
       }}
     ]
   }],
   config: { responseModalities: ['TEXT', 'IMAGE']}
 });

 // Set up user impersonation authentication used to upload the attachment output
 // and send the response.
 const impersonatedUserAuth = new GoogleAuth({
   // Specify the Chat API user authentication scopes
   scopes: ['https://www.googleapis.com/auth/chat.messages'],
   keyFile: './credentials.json',
   clientOptions: {
     // Impersonate the user who sent the original message
     subject: userEmail
   }
 });
 // Create Chat service client with impersonated user credentials
 const userChatClient = google.chat({
   version: 'v1',
   auth: await impersonatedUserAuth.getClient()
 });

 let responseText = undefined;
 let responseAttachment = undefined;
 // Go through the response parts received
 for (const part of aiResponse.candidates[0].content.parts) {
   if (part.inlineData) {
     // The resulting image is retrieved inline and uploaded
     const mediaResponse = await uploadFile(userChatClient, spaceName, part.inlineData.data);
     responseAttachment = mediaResponse.data;
   } else {
     responseText = part.text;
   }
 }

 // Create a Chat message dedicated to the generated content
 await userChatClient.spaces.messages.create({
   parent: spaceName,
   requestBody: {
     text: responseText ? responseText : 'Here it is!',
     // The uploaded image is referenced as attachment
     attachment: responseAttachment ? [responseAttachment] : undefined
   }
 });

 // Send a last Chat message to confirm it's done
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: 'Done, feel free to let me know if you need anything else!'
 }}}}});
});
...

Configurar a conta de serviço e exportar a chave privada

  1. Delegue a conta de serviço padrão do Cloud Run para gerenciar mensagens do Google Chat para usuários. Siga as instruções com o escopo https://www.googleapis.com/auth/chat.messages. Para recuperar o ID do cliente da conta de serviço padrão do Cloud Run, siga estas etapas:
  2. Clique em Menu ☰ > IAM e administrador > Contas de serviço.

  1. Clique na conta de serviço com o nome Conta de serviço padrão do Compute.
  2. Expanda a seção Configurações avançadas.
  3. Copie o ID do cliente para a área de transferência.
  4. Crie e faça o download de uma nova chave privada para a conta de serviço padrão do Cloud Run
  5. Clique em Menu ☰ > IAM e administrador > Contas de serviço.

  1. Clique na conta de serviço com o nome Conta de serviço padrão do Compute.
  2. Selecione a guia Chaves, clique em Adicionar chave e em Criar nova chave.
  3. Selecione JSON e clique em Criar.
  4. 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 e copie o conteúdo dele para a área de transferência. 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.

Atualizar a função do Node.js do Google Cloud Run

  1. No ambiente de desenvolvimento local, mude o diretório atual para node/chat/gen-ai-apps/8-multimodal. Ele contém todo o código-fonte e os recursos.
  2. Acesse a guia Origem da página de detalhes do serviço de função do Google Cloud Run.

  1. Clique em Editar origem.
  2. Clique em ➕, digite credentials.json e clique em ✔️ para criar o arquivo de recurso ausente.
  3. Cole o conteúdo do arquivo JSON baixado na etapa anterior no arquivo credentials.json recém-criado.
  4. Substitua todo o conteúdo do arquivo index.js pelo conteúdo do seu ambiente de desenvolvimento local.
  5. Abra o arquivo env.js e defina o valor de model como gemini-2.0-flash-preview-image-generation.
...
model: 'gemini-2.0-flash-preview-image-generation',
...
  1. Clique em Salvar e reimplantar.
  2. Aguarde a conclusão da implantação da revisão.

487b64f2d3b1a104.png

Testar

No espaço de mensagem direta com o app Chat no Google Chat, faça upload de uma foto de rosto sua no formato PNG, digite Change the background color to blue e pressione enter. O app vai responder com uma versão da imagem com um plano de fundo azul e uma mensagem de confirmação da conclusão.

270547e7a83c1841.png

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

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

  1. Clique em Encerrar.
  2. Digite o ID do projeto.
  3. Clique em Encerrar mesmo assim.

407699a4e03afea6.png

12. Parabéns

Parabéns! Você criou apps do Google Chat como complementos do Google Workspace que integram conceitos fundamentais de IA.

A seguir

Mostramos apenas casos de uso minimalistas neste codelab, mas existem muitas áreas de expansão que você pode querer considerar nos seus apps do Google Chat, como estas:

  • Oferecer suporte a outros tipos de mídia, como áudio e vídeo.
  • Integrar com outros modelos de IA, incluindo os personalizados, hospedados em plataformas dedicadas, como a Vertex AI.
  • Integração com agentes, incluindo personalizados, hospedados em plataformas dedicadas, como o Agentspace e o Dialogflow CX.
  • Use loops de feedback e classificações para monitorar e melhorar a performance.
  • Publique no 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: