Questa pagina è stata tradotta dall'API Cloud Translation.

Integrare i concetti fondamentali dell'AI nelle app Google Chat

1. Prima di iniziare

Che cosa sono le app di Google Chat con l'AI?

Le app di Google Chat con l'AI svolgono le seguenti operazioni:

Integra i tuoi servizi e le tue risorse in Google Chat, che consente agli utenti di ottenere informazioni e intraprendere azioni senza abbandonare la conversazione.
Integrati con modelli di AI generativa per creare, cercare e modificare dati come testo o immagini.
Supporta un'esperienza di agenzia applicando concetti di AI conversazionale per interazioni più pratiche, naturali, sofisticate e utili.

Perché integrare le app di Google Chat con l'AI?

I casi d'uso tipici rientrano nelle seguenti categorie:

Creazione e modifica di contenuti. Genera testi di marketing, crea post sui social media, crea immagini realistiche, componi musica o aiuta a creare contenuti video.
Ricerca e analisi dei dati. Estrai insight chiave da una knowledge base non strutturata, riassumi testi lunghi, classifica contenuti o traduci lingue con maggiore precisione e velocità.
Conversazione. Partecipa a conversazioni naturali, informative ed efficienti come faresti con un assistente.
Automazione delle attività. Eseguire azioni per conto dell'utente, ad esempio creare un nuovo evento del calendario, inviare un documento o gestire un ticket in un sistema esterno.

La possibilità di integrare queste funzionalità direttamente nell'interfaccia familiare di Google Chat è un'ottima opportunità per chiunque voglia migliorare l'esperienza e la produttività dei propri utenti.

Prerequisiti

Conoscenza di base di Google Cloud e Node.js.
Conoscenza di base delle app Google Chat, inclusi messaggi, schede, autenticazione, API ed endpoint HTTP.

Cosa creerai

In questo codelab, creerai otto app Google Chat minimaliste che integrano concetti fondamentali di AI per mostrare come possono essere applicati in applicazioni reali. Sono tutti creati come componenti aggiuntivi di Google Workspace e si basano sull'architettura HTTP:

Ecco come funziona:

Un utente invia un messaggio in Google Chat a un'app di chat, come messaggio diretto o in uno spazio di Chat.
Una richiesta HTTP viene inviata al server web in esecuzione come funzione Node.js Google Cloud Run che contiene la logica dell'app di chat.
Se vuoi, la logica dell'app Chat può integrarsi con i servizi Google Workspace (come Calendar e Fogli), altri servizi Google (come Maps, YouTube e Vertex AI) o altri servizi web (come un sistema di gestione dei progetti o uno strumento di gestione dei ticket).
Il server web invia una risposta HTTP al servizio dell'app di Chat in Chat.
La risposta viene inviata all'utente.
Se vuoi, l'app di Chat può chiamare l'API Chat per pubblicare messaggi in modo asincrono o eseguire altre operazioni.

La funzione Node.js Google Cloud Run di ogni app Google Chat contiene la propria versione dei seguenti file di origine per eseguire le azioni necessarie nei passaggi 3 e 6 sopra indicati:

package.json: un manifest centrale che funge da progetto per il progetto Node.js. Viene utilizzato per definire i metadati, le dipendenze e gli script.
env.js: uno script che imposta le costanti richieste per l'esecuzione. Deve essere modificato in base all'ambiente e alla configurazione.
index.js: Lo script principale che gestisce la logica per gli eventi di interazione di Google Chat. In questo codelab è implementato solo il tipo di evento messaggio, ma in genere include altri tipi come clic sulla scheda, comando slash e finestra di dialogo nelle applicazioni reali.

App Prompt

Questa app si basa su un modello Gemini per conversare con gli utenti nelle loro lingue naturali utilizzando risposte concise e in testo normale.

App di formattazione

Questa app si basa su Prompt app aggiungendo il supporto per le risposte in formato RTF conformi al formato di testo specifico dei messaggi di Google Chat.

App Ground

Questa app si basa su Format app aggiungendo il supporto dello strumento di Ricerca Google e restituendo le fonti nei messaggi di risposta con le schede.

App MCP

Questa app si basa su Format app aggiungendo il supporto per il Model Context Protocol (MCP) di Google Workspace Developer Assist.

App multi-turn

Questa app si basa su Format app aggiungendo il supporto della memoria conversazionale con un database Google Cloud Firestore.

App personalizzata per gli attrezzi

Questa app si basa su Multi-turn app aggiungendo il supporto per uno strumento personalizzato di chiamata di funzioni che chiama l'API Google Workspace Calendar in base alle informazioni fornite dall'utente.

App Stream

Questa app si basa su un modello Gemini per generare racconti brevi basati su temi forniti dagli utenti. L'API Google Chat viene utilizzata per inviare risultati e stati nei messaggi man mano che vengono eseguiti progressi.

App multimodale

Questa app si basa su un modello Gemini per modificare le immagini in base alle istruzioni testuali degli utenti. Le API Google Chat vengono utilizzate per scaricare e caricare le immagini come allegati dei messaggi.

Cosa imparerai a fare

I concetti fondamentali dell'AI sono pertinenti per le app Google Chat e per il modo in cui vengono applicati.
Per accedere a Vertex AI utilizzando Google Gen AI SDK.
Per utilizzare le API Google Workspace per sviluppare funzionalità potenti e piacevoli.
Per sfruttare Cloud Run per creare app Google Chat scalabili.

Cosa ti serve

Completamento della guida rapida Crea un'app Google Chat HTTP con Node.js. Questo codelab si basa sul progetto Google Cloud, sull'app Google Chat e sulla funzione Google Cloud Run risultanti.

2. Configurazione

Inizializzare le risorse e accedervi

In questa sezione, accedi e configura le seguenti risorse dal tuo browser web preferito.

Configurazione dell'API Google Chat

Apri la console Google Cloud in una nuova scheda, quindi segui questi passaggi:

Seleziona il progetto.
Nel campo di ricerca di Google Cloud, cerca "API Google Chat", quindi fai clic su API Google Chat, su Gestisci e su Configurazione.

Imposta Nome app e Descrizione su Gen AI App.
Fai clic su Salva.

Spazio Google Chat

Apri Google Chat in una nuova scheda, poi segui questi passaggi:

Se non l'hai ancora fatto, apri uno spazio di messaggi diretti con l'app di Chat.
Digita Hello e premi enter. L'app Chat dovrebbe rispondere con il tuo nome e la tua immagine dell'avatar.

Servizio di funzioni Google Cloud Run

Apri la console Google Cloud in una nuova scheda, quindi segui questi passaggi:

Seleziona il progetto.
Fai clic su Menu ☰ > Cloud Run > Servizi.

Nell'elenco dei servizi, fai clic su addonchatapp, poi apri la scheda Origine.

Scarica localmente il codice sorgente e le risorse

Scarica questo repository GitHub.

Nell'ambiente di sviluppo locale che preferisci, apri la directory node/chat/gen-ai-apps.

3. Prompt app

Questa app chiede a Gemini su Vertex AI di conversare con gli utenti nelle loro lingue naturali utilizzando risposte concise e in formato di testo normale. L'implementazione si basa sull'SDK Google Gen AI per Node.js.

Concetti sulle recensioni

Linguaggio naturale

Qualsiasi lingua parlata o scritta dagli esseri umani per la comunicazione quotidiana, in contrasto con le lingue artificiali o basate su computer.

Cloud Run Functions

Le funzioni Cloud Run sono ideali per creare backend serverless, elaborare dati in tempo reale e creare app intelligenti. Non ci sono server di cui eseguire il provisioning, la gestione, l'applicazione di patch o l'aggiornamento. Vengono scalati automaticamente e sono ad alta disponibilità e a tolleranza di errore.

Prompt

Il prompting si riferisce alla tecnica di creazione di input (prompt) per guidare un modello di AI generativa a produrre l'output desiderato. Di solito, consiste nel formulare con attenzione le domande, fornire il contesto, dare istruzioni o fornire esempi per ottenere risposte specifiche e pertinenti dal modello.

Vertex AI

Vertex AI offre tutto ciò di cui hai bisogno per creare e utilizzare l'AI generativa, tra cui soluzioni AI, ricerca e conversazione, oltre 130 modelli di base e una piattaforma AI unificata.

Gemini

Gemini è un LLM multimodale di Google accessibile tramite Vertex AI. Aiuta le persone a liberare il proprio potenziale umano in modo da aumentare la loro immaginazione, espandere la loro curiosità e migliorare la loro produttività.

SDK Google Gen AI

L'SDK Google Gen AI è progettato per consentire agli sviluppatori di creare applicazioni basate su Gemini e fornisce un'interfaccia unificata compatibile sia con l'API Gemini Developer sia con Vertex AI. È dotato di librerie client in Python, Go, Node.js e Java.

Flusso di revisione

Esaminare il codice sorgente

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"
},
...

Abilita l'API Vertex AI

Nella console Google Cloud, abilita l'API Vertex AI:

Fai clic su Menu ☰ > API e servizi > API e servizi abilitati e poi verifica che API Vertex AI sia presente nell'elenco.

Aggiorna la funzione Google Cloud Run Node.js

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/1-prompt. Contiene l'intero codice sorgente e le risorse.
Apri env.js in un editor e imposta quanto segue:
projectID: l'ID del tuo progetto Google Cloud. Può essere recuperato dalla pagina di benvenuto della console Google Cloud.

location: la regione del servizio di funzioni Google Cloud Run. Può essere recuperato dalla pagina dei dettagli del servizio della funzione Google Cloud Run.

model: il modello da utilizzare. Puoi trovare tutti i modelli disponibili nella documentazione di Vertex AI. Il modello impostato per impostazione predefinita è Flash per un'esecuzione rapida ed economica.

Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Imposta Entry point della funzione su gen-ai-app.
Fai clic su ➕, digita env.js e fai clic su ✔️ per creare il file di origine mancante.
Sostituisci l'intero contenuto dei file index.js, env.js e package.json con quelli dell'ambiente di sviluppo locale.
Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita Hello, how are you? e premi enter. L'app deve rispondere in modo conciso in testo normale, come indicato nelle istruzioni del prompt.

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita Bonjour comment allez-vous? e premi enter. L'app deve rispondere in francese, come indicato nelle istruzioni del prompt.

4. Formatta app

Questa app si basa su Prompt app aggiungendo il supporto per le risposte in formato RTF conformi al formato dei messaggi di testo di Google Chat. Le istruzioni nel prompt vengono aggiornate con una descrizione esaustiva delle diverse opzioni che il modello può utilizzare.

Concetti sulle recensioni

Messaggi di Google Chat

I messaggi di testo di Google Chat supportano varie opzioni di formattazione per consentire messaggi più chiari ed espressivi direttamente all'interno dell'interfaccia di Google Chat. Si basano su regole di markdown specifiche per applicare il grassetto, il corsivo, la sbarratura, creare collegamenti ipertestuali e così via.

Flusso di revisione

Esamina il codice sorgente

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}`;
...
};
...

Aggiorna la funzione Google Cloud Run Node.js

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/2-format. Contiene l'intero codice sorgente e le risorse.
Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Sostituisci l'intero contenuto del file index.js con quello dell'ambiente di sviluppo locale.
Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita Showcase all formatting options you have with one paragraph each e premi enter. L'app deve rispondere con esempi di formattazione basati sulle nostre istruzioni nel prompt.

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita What are Google Chat apps? What's great about them? e premi enter. L'app deve rispondere con la formattazione quando è utile.

5. App Ground

Questa app si basa su Format app aggiungendo il supporto per la fondatezza e la restituzione delle fonti. Esegue lo strumento Ricerca Google e allega schede con link alle risposte.

Rivedere i concetti

Grounding

Il grounding è la tecnica di collegamento dei modelli a fonti di informazioni. Viene spesso utilizzato in applicazioni pratiche per migliorare l'accuratezza e la pertinenza dei contenuti generati facendo riferimento a dati reali, impedendo così al modello di avere allucinazioni o di produrre informazioni oggettivamente errate.

Strumento di Ricerca Google

Lo strumento Ricerca Google migliora la fondatezza consentendo ai modelli di cercare sul web informazioni in tempo reale, garantendo che le risposte siano accurate e aggiornate.

Framework delle schede di Google Workspace

Il framework delle schede in Google Workspace consente agli sviluppatori di creare interfacce utente interattive e avanzate. Consente la creazione di schede organizzate e visivamente accattivanti che possono includere testo, immagini, pulsanti e altri widget. Queste schede migliorano l'esperienza utente fornendo informazioni strutturate e consentendo azioni rapide direttamente all'interno della conversazione.

Flusso di revisione

Esamina il codice sorgente

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
}}}}});
...

Aggiorna la funzione Google Cloud Run Node.js

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/3-ground. Contiene l'intero codice sorgente e le risorse.
Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Sostituisci l'intero contenuto del file index.js con quello dell'ambiente di sviluppo locale.
Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita What's the world population? e premi enter. L'app deve rispondere allegando i link delle fonti in una scheda.

6. App MCP

Questa app si basa su Format app aggiungendo il supporto per gli strumenti forniti da un server Model Context Protocol (MCP) ospitato in remoto. Si connette al MCP di Google Workspace Developer Assist che fornisce strumenti per accedere e cercare la documentazione per gli sviluppatori di Google Workspace.

Concetti sulle recensioni

Model Context Protocol (MCP)

Il Model Context Protocol è un framework open source che integra i modelli con servizi esterni in modo standardizzato. I modelli possono scoprire, comprendere e interagire in modo programmatico con vari strumenti, ampliando le loro capacità, eseguendo azioni nel mondo reale e accedendo a informazioni aggiornate.

SDK TypeScript MCP

L'SDK TypeScript implementa la specifica MCP completa, semplificando la creazione di client MCP che si connettono a qualsiasi server MCP. Consente inoltre lo sviluppo di server MCP che forniscono l'accesso a risorse, prompt e strumenti.

Flusso di revisione

Esamina il codice sorgente

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"
},
...

Aggiorna la funzione Google Cloud Run Node.js

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/4-mcp. Contiene l'intero codice sorgente e le risorse.
Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Sostituisci l'intero contenuto dei file index.js e package.json con quelli nel tuo ambiente di sviluppo locale.
Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita What can you do for me? e premi enter. L'app deve descrivere le sue funzionalità (strumenti MCP).

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita I would like to get the latest official documentation for the Google Sheets API append values e premi enter. L'app deve rispondere con la documentazione richiesta (utilizzando gli strumenti MCP).

7. App multi-turno

Questa app si basa su Format app aggiungendo il supporto della memoria conversazionale monitorando la cronologia delle interazioni di chat. Consente un'esperienza più naturale, intelligente e personalizzata. L'app utilizza il database Google Cloud Firestore predefinito associato al progetto Google Cloud per l'archiviazione.

Rivedere i concetti

Multi-turn

Il concetto di multi-turno si riferisce alla capacità di un modello di mantenere contesti e continuità in più scambi e conversazioni. È una funzionalità indispensabile per supportare conversazioni complesse, funzionalità sofisticate basate sull'AI ed esperienze utente naturali.

Google Cloud Firestore

Google Cloud Firestore è un database cloud NoSQL flessibile e scalabile per lo sviluppo mobile, web e server. Archivia i dati in documenti, organizzati in raccolte, e consente la sincronizzazione in tempo reale e il supporto offline.

Flusso di revisione

Esamina il codice sorgente

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"
},
...

Attiva l'API Google Cloud Firestore

Nella console Google Cloud, abilita l'API Google Cloud Firestore:

Fai clic su Menu ☰ > API e servizi > API e servizi abilitati e poi verifica che API Cloud Firestore sia presente nell'elenco.

Crea il database Cloud Firestore

Nella console Google Cloud, fai clic su Menu ☰ > Firestore.

Fai clic su Crea un database Firestore.
Lascia la configurazione predefinita e fai clic su Crea database.

Aggiorna la funzione Google Cloud Run Node.js

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/5-multi-turn. Contiene l'intero codice sorgente e le risorse.
Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Sostituisci l'intero contenuto dei file index.js e package.json con quelli nel tuo ambiente di sviluppo locale.
Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita Can you speak with the English from the 80's for now on? e premi enter. L'app deve rispondere in modo positivo.

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita Define what Google Chat apps are in one sentence e premi enter. L'app dovrebbe continuare a rispondere con l'inglese degli anni '80.

Nota:questa applicazione si concentra sulla dimostrazione di interazioni multi-turn e non include funzionalità di gestione della cronologia della chat come la rimozione o la modifica dei dati, in quanto non sono fondamentali per il concetto di base.

Per modificare la cronologia della chat utilizzata dal modello, puoi modificare direttamente il documento corrispondente dell'utente all'interno della raccolta chat nel database Google Cloud Firestore (impostazione predefinita).

Se devi cancellare la cronologia dell'utente, segui questi passaggi:

Nella console Google Cloud, fai clic su Menu ☰ > Firestore.

Nell'elenco dei database, fai clic su (predefinito).
Seleziona la raccolta chat, quindi seleziona il documento con l'ID utente.
Fai clic sui tre puntini accanto all'ID documento, quindi fai clic su Elimina documento.
Nella finestra di dialogo di conferma, fai clic su Elimina.

8. App Strumento personalizzato

Questa app si basa su Multi-turn app aggiungendo il supporto per uno strumento personalizzato di chiamata di funzioni che si basa sull'API Google Workspace Calendar per recuperare il prossimo evento da un calendario pubblico. Il modello gestisce tutte le interazioni degli utenti, inclusi la ricezione dell'input e la generazione dell'output dallo strumento. L'applicazione è comunque responsabile dell'esecuzione delle chiamate API necessarie e della fornitura dei risultati al modello su richiesta. L'app utilizza una chiave API di Google perché non sono necessarie credenziali utente per recuperare i dati del calendario pubblico.

Concetti sulle recensioni

Chiamata di funzione

La chiamata di funzioni consente a un modello di rilevare quando la richiesta di un utente può essere soddisfatta da un'API o uno strumento esterno. Il modello fornisce quindi i parametri necessari per chiamare lo strumento, integrando funzionalità esterne nelle sue risposte.

API Google Workspace

Le API Google Workspace consentono agli sviluppatori di integrare le proprie applicazioni con vari servizi Google Workspace. Queste API forniscono l'accesso programmatico alle funzionalità di prodotti come Gmail, Chat, Calendar, Drive, Documenti, Fogli e altri ancora, consentendo l'automazione, la sincronizzazione dei dati e la creazione di flussi di lavoro personalizzati.

Flusso di revisione

Esamina il codice sorgente

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"
},
...

Abilitare l'API Calendar

Nella console Google Cloud, abilita l'API Google Calendar:

Fai clic su Menu ☰ > API e servizi > API e servizi abilitati e poi verifica che API Google Calendar sia presente nell'elenco.

Crea chiave API di Google

Nella console Google Cloud, segui questi passaggi:

Fai clic su Menu ☰ > API e servizi > Credenziali.

Fai clic su + Crea credenziali e poi seleziona Chiave API.
Attendi il completamento dell'operazione.
Nella finestra di dialogo di conferma, individua il campo di testo La tua chiave API e fai clic su Copia negli appunti.

Aggiorna la funzione Node.js di Google Cloud Run

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/6-custom-tool. Contiene l'intero codice sorgente e le risorse.
Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Sostituisci l'intero contenuto dei file index.js e package.json con quelli nel tuo ambiente di sviluppo locale.
Apri il file env.js e procedi nel seguente modo
Aggiungi googleApiKey ai campi esportati

export const env = {
 ...
 googleApiKey: 'your-google-api-key',
};

Sostituisci your-google-api-key con la chiave API di Google copiata nel passaggio precedente. Può essere recuperata dalla pagina delle credenziali Google Cloud facendo clic su Mostra chiave.

Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

In Google Calendar, segui questi passaggi:
Nella sezione Altri calendari, fai clic su +, quindi su Crea nuovo calendario.
Imposta Nome su My Public Calendar
Fai clic su Crea calendario.
Attendi il completamento dell'operazione.
Nella sezione Impostazioni per i miei calendari, seleziona il calendario appena creato Il mio calendario pubblico.
Nella sezione Autorizzazioni di accesso per gli eventi, seleziona Rendi disponibile pubblicamente e poi fai clic su Ok nella finestra di dialogo Avviso.
Nella sezione Autorizzazioni di accesso per gli eventi, seleziona Vedere tutti i dettagli dell'evento dal menu a discesa accanto all'opzione Rendi disponibile pubblicamente.
Nella sezione Integra calendario, copia negli appunti il valore del campo ID calendario.
Fai clic sulla freccia sinistra nell'angolo in alto a sinistra per uscire da Impostazioni.
Fai clic sul calendario per creare un nuovo evento per domani, digita Important meeting, seleziona Il mio calendario pubblico dal menu a discesa, quindi fai clic su Salva.
Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita When is the next meeting? e premi enter. L'app deve richiedere una precisione perché non è chiaro a quale calendario si fa riferimento.

Nello spazio dei messaggi diretti con l'app Chat in Google Chat, incolla l'ID calendario che hai copiato in precedenza negli appunti e premi enter. L'app dovrebbe rispondere con i dettagli dell'evento creato in precedenza.

9. App di streaming

Questa app si basa su un modello Gemini per generare storie di 2 minuti in base ai temi forniti dagli utenti. Poiché la generazione di risposte complete richiede tempo, l'app chiama il modello in modalità di streaming e si basa sull'API Google Chat per inviare contenuti e stati nei messaggi man mano che vengono generati.

Concetti sulle recensioni

API Google Chat

L'API di Google Chat consente agli sviluppatori di interagire in modo programmatico con Google Chat, consentendo loro di inviare messaggi, creare spazi, gestire membri e altro ancora, per creare integrazioni e bot personalizzati.

Streaming

Streaming si riferisce al processo di ricezione dei dati in un flusso continuo anziché attendere la generazione dell'intera risposta. Per quanto riguarda le chiamate ai modelli di AI, lo streaming consente alle applicazioni di mostrare agli utenti risultati parziali non appena diventano disponibili, migliorando le prestazioni percepite e l'esperienza utente, soprattutto per le attività di generazione più lunghe. Ciò è particolarmente importante per i modelli di AI generativa che potrebbero impiegare molto tempo per produrre un output completo.

Flusso di revisione

Esaminare il codice sorgente

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"
},
...

Aggiorna la funzione Google Cloud Run Node.js

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/7-stream. Contiene l'intero codice sorgente e le risorse.
Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Sostituisci l'intero contenuto dei file index.js e package.json con quelli nel tuo ambiente di sviluppo locale.
Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

Nello spazio di messaggi diretti con l'app di Chat in Google Chat, digita turtle e premi enter. L'app dovrebbe rispondere con un messaggio di conferma, la storia generata con lo stato di avanzamento e un messaggio di conferma del completamento.

10. App multimodale

Questa app si basa su un modello per modificare le immagini in base alle istruzioni testuali degli utenti. Sia gli utenti che l'app aggiungono le proprie immagini come allegati dei messaggi di Google Chat da scambiare. L'app si basa sulle API Google Chat per scaricare e caricare immagini in modo programmatico.

Concetti sulle recensioni

Allegato del messaggio di Google Chat

Gli allegati dei messaggi di Google Chat sono file, ad esempio immagini o video, caricati in un messaggio di Google Chat. Questi allegati possono essere gestiti in modo programmatico, consentendo alle applicazioni di interagire con i contenuti multimediali avanzati direttamente all'interno delle conversazioni.

Delega a livello di dominio (DWD)

La delega a livello di dominio (DWD) consente a un service account di rappresentare gli utenti in un dominio Google Workspace, consentendo alle applicazioni di eseguire azioni per conto di questi utenti senza autorizzazione diretta. Ciò è utile per le app che devono accedere ai dati utente o eseguire azioni (come il caricamento di allegati su Google Chat) nel contesto dell'utente, anche quando l'utente non è presente attivamente, concedendo all'account di servizio un ampio accesso al dominio.

Flusso di revisione

Esamina il codice sorgente

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!'
 }}}}});
});
...

Configura il service account ed esporta la chiave privata

Delega l'account di servizio predefinito di Cloud Run per gestire i messaggi di Google Chat per gli utenti. Segui le istruzioni con l'ambito https://www.googleapis.com/auth/chat.messages. Per recuperare l'ID client dell'account di servizio predefinito di Cloud Run, segui questi passaggi:
Fai clic su Menu ☰ > IAM e amministrazione > Service account.

Fai clic sul service account con il nome Service account Compute predefinito.
Espandi la sezione Impostazioni avanzate.
Copia l'ID client negli appunti.
Crea e scarica una nuova chiave privata per il service account predefinito di Cloud Run
Fai clic su Menu ☰ > IAM e amministrazione > Service account.

Fai clic sul service account con il nome Service account Compute predefinito.
Seleziona la scheda Chiavi, fai clic su Aggiungi chiave, quindi su Crea nuova chiave.
Seleziona JSON, quindi fai clic su Crea.
Una nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come nuovo file. Salva il file JSON scaricato e copia i relativi contenuti negli appunti. Questo file è l'unica copia di questa chiave. Per informazioni su come archiviare la chiave in modo sicuro, consulta la sezione Gestire le chiavi degli account di servizio.

Aggiorna la funzione Google Cloud Run Node.js

Nell'ambiente di sviluppo locale, cambia la directory attuale in node/chat/gen-ai-apps/8-multimodal. Contiene l'intero codice sorgente e le risorse.
Vai alla scheda Origine della pagina dei dettagli del servizio della funzione Google Cloud Run.

Fai clic su Modifica origine.
Fai clic su ➕, digita credentials.json e fai clic su ✔️ per creare il file di risorse mancante.
Incolla i contenuti del file JSON scaricato nel passaggio precedente nel file credentials.json appena creato.
Sostituisci l'intero contenuto del file index.js con quello dell'ambiente di sviluppo locale.
Apri il file env.js e imposta il valore di model su gemini-2.0-flash-preview-image-generation.

...
model: 'gemini-2.0-flash-preview-image-generation',
...

Fai clic su Salva e ridistribuisci.
Attendi il completamento del deployment della revisione.

Prova

Nello spazio di messaggi diretti con l'app di chat in Google Chat, carica una tua foto verticale in formato PNG, digita Change the background color to blue e premi enter. L'app dovrebbe rispondere con una versione dell'immagine con uno sfondo blu e un messaggio di conferma del completamento.

11. Esegui la pulizia

Eliminare il progetto Google Cloud

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab, ti consigliamo di eliminare il progetto Google Cloud.

Nella console Google Cloud, segui questi passaggi:

Fai clic su Menu ☰ > IAM e amministrazione > Impostazioni.

Fai clic su Chiudi.
Inserisci l'ID progetto.
Fai clic su Chiudi comunque.

12. Complimenti

Complimenti! Hai creato app Google Chat come componenti aggiuntivi di Google Workspace che integrano i concetti fondamentali dell'AI.

Passaggi successivi

In questo codelab mostriamo solo casi d'uso minimalisti, ma ci sono molte aree di espansione che potresti prendere in considerazione nelle tue app Google Chat, ad esempio:

Supportare altri tipi di contenuti multimediali come audio e video.
Esegui l'integrazione con altri modelli di AI, inclusi quelli personalizzati, ospitati su piattaforme dedicate come Vertex AI.
Esegui l'integrazione con agenti, inclusi quelli personalizzati, ospitati in piattaforme dedicate come Agentspace e Dialogflow CX.
Utilizza cicli di feedback e classificazioni per monitorare e migliorare il rendimento.
Pubblica sul marketplace per consentire a team, organizzazioni o utenti pubblici di utilizzarlo.

Scopri di più

Gli sviluppatori hanno a disposizione molte risorse, come video di YouTube, siti web di documentazione, esempi di codice e tutorial: