Интеграция фундаментальных концепций ИИ в приложения Google Chat

1. Прежде чем начать

Какие приложения Google Chat используют ИИ?

Приложения Google Chat с ИИ выполняют следующие функции:

  • Добавьте свои услуги и ресурсы в Google Chat, который позволит пользователям получать информацию и предпринимать действия, не выходя из беседы.
  • Интеграция с генеративными моделями ИИ для создания, поиска и редактирования данных, таких как текст или изображения.
  • Поддерживайте агентный опыт, применяя концепции разговорного ИИ для более практичного, естественного, сложного и полезного взаимодействия.

Зачем интегрировать приложения Google Chat с ИИ?

Типичные варианты использования можно разделить на следующие категории:

  • Создание и редактирование контента . Создавайте маркетинговые тексты, публикуйте посты в социальных сетях, создавайте реалистичные изображения, сочиняйте музыку или помогайте в создании видеоконтента.
  • Поиск и анализ данных . Извлекайте важную информацию из неструктурированной базы знаний, обобщайте длинные тексты, классифицируйте контент или переводите с других языков с повышенной точностью и скоростью.
  • Разговор . Ведите естественные, информативные и эффективные беседы, как если бы вы общались с помощником.
  • Автоматизация задач. Выполняйте действия от имени пользователя, например, создание нового события в календаре, отправка документа или управление тикетом во внешней системе.

Возможность интегрировать эти возможности непосредственно в привычный интерфейс Google Chat — это огромная возможность для тех, кто хочет улучшить опыт и производительность своих пользователей.

Предпосылки

Что вы будете строить

В этой лабораторной работе вы создадите восемь минималистичных приложений Google Chat, интегрирующих фундаментальные концепции искусственного интеллекта, чтобы продемонстрировать их применение в реальных приложениях. Все они реализованы как дополнения к Google Workspace и используют архитектуру HTTP:

2f1e2c66f6e2e2f0.png

Работает это следующим образом:

  1. Пользователь отправляет сообщение из Google Chat в приложение Chat либо как личное сообщение, либо в чат-пространстве.
  2. HTTP-запрос отправляется на веб-сервер, работающий как функция Node.js Google Cloud Run , которая содержит логику приложения чата.
  3. При желании логику приложения Chat можно интегрировать с сервисами Google Workspace (например, Календарь и Таблицы), другими сервисами Google (например, Карты, YouTube и Vertex AI) или другими веб-сервисами (например, системой управления проектами или инструментом тикетов).
  4. Веб-сервер отправляет HTTP-ответ обратно в службу приложения Chat.
  5. Ответ доставляется пользователю.
  6. При желании приложение чата может вызывать API чата для асинхронной публикации сообщений или выполнения других операций.

Каждая функция Node.js Google Cloud Run приложения Google Chat содержит собственную версию следующих исходных файлов для выполнения необходимых действий на шагах № 3 и № 6 выше:

  • package.json : центральный манифест, служащий основой для проекта Node.js. Он используется для определения метаданных, зависимостей и скриптов.
  • env.js : скрипт, устанавливающий константы, необходимые для выполнения. Его следует редактировать в соответствии с окружением и конфигурацией.
  • index.js: Основной скрипт, обрабатывающий логику событий взаимодействия с Google Chat. В этой лабораторной работе реализован только тип событий «сообщение», но в реальных приложениях он обычно включает и другие типы событий, такие как нажатие карточки, команда «косая черта» и диалог.

Приложение Prompt

Это приложение использует модель Gemini для общения с пользователями на их естественном языке, используя краткие и простые текстовые ответы.

5975b36968ab597a.gif

Форматировать приложение

Это приложение создано на основе Prompt app и добавляет поддержку ответов в формате расширенного текста, соответствующих определенному текстовому формату сообщений Google Chat .

bc49e0acf0838f28.gif

Наземное приложение

Это приложение основано на Format app , добавляя поддержку инструмента поиска Google и возвращая источники в ответных сообщениях с карточками.

3cf232bf153f6abc.gif

приложение MCP

Это приложение создано на основе Format app с добавлением поддержки Google Workspace Developer Assist Model Context Protocol (MCP) .

8219c29366e9120e.gif

Многооборотное приложение

Это приложение создано на основе Format app , с добавлением поддержки разговорной памяти с базой данных Google Cloud Firestore .

a819c274ce586451.gif

Приложение для пользовательских инструментов

Это приложение создано на основе Multi-turn app путем добавления поддержки функции, вызывающей пользовательский инструмент , который вызывает API Календаря Google Workspace на основе информации, предоставленной пользователем.

a1c4f586b7ab2e24.gif

Стрим-приложение

Это приложение использует модель Gemini для создания коротких историй на основе тем, предложенных пользователями. API Google Chat используется для отправки результатов и статусов в сообщениях по мере продвижения.

fd347ba03fe86e22.gif

Мультимодальное приложение

Это приложение использует модель Gemini для редактирования изображений на основе текстовых инструкций пользователей. API Google Chat используются для загрузки и отправки изображений в виде вложений в сообщения.

57574be33474bbc.gif

Чему вы научитесь

  • Фундаментальные концепции искусственного интеллекта актуальны для приложений Google Chat и способов их применения.
  • Для доступа к Vertex AI используйте Google Gen AI SDK.
  • Использовать API Google Workspace для разработки замечательных и мощных функций.
  • Использовать Cloud Run для создания масштабируемых приложений Google Chat.

Что вам понадобится

  • Завершение краткого руководства по созданию HTTP-приложения Google Chat на Node.js. Эта практическая работа основана на получившемся проекте Google Cloud, приложении Google Chat и функции Google Cloud Run.

2. Настройте

Инициализация и доступ к ресурсам

В этом разделе вы получите доступ к следующим ресурсам и настроите их с помощью предпочитаемого вами веб-браузера.

Конфигурация API Google Chat

Откройте консоль Google Cloud в новой вкладке и выполните следующие действия:

  1. Выберите свой проект.
  2. В поле поиска Google Cloud найдите «Google Chat API», затем нажмите Google Chat API , нажмите Управление и нажмите Конфигурация .

  1. Задайте имя приложения и описание Gen AI App .
  2. Нажмите «Сохранить» .

9a06649cf9285b99.png

Пространство Google Чата

Откройте Google Chat в новой вкладке и выполните следующие действия:

  1. Если вы еще этого не сделали, откройте чат-группу для обмена личными сообщениями.
  2. Введите Hello и нажмите enter . Приложение чата должно ответить вашим именем и аватаром.

e3b195c7b7b8e2af.png

Служба функций Google Cloud Run

Откройте консоль Google Cloud в новой вкладке и выполните следующие действия:

  1. Выберите свой проект.
  2. Нажмите Меню ☰ > Cloud Run > Службы .

  1. В списке сервисов нажмите addonchatapp , затем откройте вкладку Источник .

b69df34ea0dc48a5.png

Загрузите исходный код и ресурсы локально

  1. Загрузите этот репозиторий GitHub .

  1. В предпочитаемой вами локальной среде разработки откройте каталог node/chat/gen-ai-apps .

3c57c15db4ebfddb.png

3. Приложение Prompt

Это приложение позволяет Gemini на базе Vertex AI общаться с пользователями на их естественном языке, используя краткие и понятные текстовые ответы. Реализация основана на Google Gen AI SDK для Node.js.

Обзор концепций

Естественный язык

Любой язык, на котором говорят или пишут люди для повседневного общения, в отличие от искусственных или компьютерных языков.

Функции Cloud Run

Функции Cloud Run отлично подходят для создания бессерверных бэкендов, обработки данных в реальном времени и создания интеллектуальных приложений. Не нужно предоставлять серверы, управлять ими, устанавливать исправления или обновлять их. Они автоматически масштабируются, обладают высокой доступностью и отказоустойчивостью.

Подсказка

Подсказки — это метод формирования входных данных (подсказок), помогающих генеративной модели ИИ получить желаемый результат. Обычно это включает в себя тщательное формулирование вопросов, предоставление контекста, предоставление инструкций или примеров для получения конкретных и релевантных ответов от модели.

Вершинный ИИ

Vertex AI предлагает все необходимое для создания и использования генеративного ИИ, включая ИИ-решения, поиск и общение, более 130 базовых моделей и унифицированную ИИ-платформу.

c9e9c7a1945b22ac.png

Близнецы

Gemini — это мультимодальная программа магистратуры права (LLM) от Google, доступная через Vertex AI. Она помогает людям раскрыть свой человеческий потенциал, развить воображение, развить любознательность и повысить производительность.

Google Gen AI SDK

Пакет Google Gen AI SDK предназначен для разработчиков приложений на базе Gemini. Он предоставляет унифицированный интерфейс, совместимый как с Gemini Developer API , так и с Vertex AI . Он включает клиентские библиотеки на Python , Go , Node.js и Java .

Обзор потока

c625fdcc8b4a27f4.png

Просмотреть исходный код

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

пакет.json 

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

Включить API Vertex AI

  1. В консоли Google Cloud включите API Vertex AI :

  1. Нажмите Меню ☰ > API и службы > Включенные API и службы , а затем убедитесь, что API Vertex AI присутствует в списке.

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/1-prompt . Он содержит весь исходный код и ресурсы.
  2. Откройте env.js в редакторе и установите следующее:
  3. projectID : идентификатор вашего проекта Google Cloud. Его можно получить на странице приветствия консоли Google Cloud.

  1. Местоположение : регион вашей службы функции Google Cloud Run. Его можно узнать на странице сведений о службе функции Google Cloud Run.

  1. model : Используемая модель. Все доступные модели можно найти в документации Vertex AI. Модель по умолчанию — Flash для быстрого и экономичного выполнения.

6c2fb9f554f53a4a.png

  1. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Установите точку входа функции на gen-ai-app .
  3. Нажмите ➕ , введите env.js и нажмите ✔️, чтобы создать отсутствующий исходный файл.
  4. Замените все содержимое файлов index.js , env.js и package.json тем, что находится в вашей локальной среде разработки.
  5. Нажмите «Сохранить и повторно развернуть» .
  6. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

  1. В поле для личных сообщений приложения «Чат» в Google Chat введите Hello, how are you? и нажмите enter . Приложение должно ответить кратко и простым текстом, следуя нашим инструкциям в подсказке.

3cc1fd1de2a9e239.png

  1. В поле для личных сообщений приложения «Чат» в Google Chat введите Bonjour comment allez-vous? и нажмите enter . Приложение должно ответить на французском языке, следуя нашим инструкциям в строке запроса.

77010f4ad0bde5da.png

4. Форматировать приложение

Это приложение основано на Prompt app и поддерживает форматированные текстовые ответы, совместимые с форматом текстовых сообщений Google Chat. Инструкции в подсказке дополнены подробным описанием различных опций, которые может использовать модель.

Обзор концепций

Текстовые сообщения Google Chat

Текстовые сообщения Google Chat поддерживают различные варианты форматирования, позволяющие создавать более понятные и выразительные сообщения непосредственно в интерфейсе Google Chat. Они основаны на специальных правилах разметки для применения жирного шрифта, курсива, зачёркивания, создания гиперссылок и т. д.

Обзор потока

c625fdcc8b4a27f4.png

Просмотреть исходный код

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

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/2-format . Он содержит весь исходный код и ресурсы.
  2. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Замените все содержимое файла index.js на содержимое в вашей локальной среде разработки.
  3. Нажмите «Сохранить и повторно развернуть» .
  4. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

  1. В поле для прямых сообщений в приложении «Чат» Google Chat введите Showcase all formatting options you have with one paragraph each и нажмите enter . Приложение должно предоставить примеры форматирования, следуя нашим инструкциям в подсказке.

cc7f7101d9f7c10.png

  1. В поле для личных сообщений приложения «Чат» в Google Chat введите What are Google Chat apps? What's great about them? и нажмите enter . Приложение должно отвечать с форматированием, когда это необходимо.

83557d4c7071aac8.png

5. Наземное приложение

Это приложение дополняет Format app , добавляя поддержку заземлённых и возвращаемых источников. Оно запускает инструмент поиска Google и прикрепляет карточки со ссылками к ответам.

Обзор концепций

Заземление

Заземление — это метод связи моделей с источниками информации. Он часто используется на практике для повышения точности и релевантности создаваемого контента посредством ссылок на реальные данные, тем самым предотвращая появление у модели иллюзий или предоставление фактически некорректной информации.

Инструмент поиска Google

Инструмент поиска Google повышает качество заземления, позволяя моделям искать в Интернете информацию в режиме реального времени, гарантируя точность и актуальность ответов.

Фреймворк Google Workspace Card

Фреймворк карточек в Google Workspace позволяет разработчикам создавать насыщенные интерактивные пользовательские интерфейсы. Он позволяет создавать структурированные и визуально привлекательные карточки, которые могут включать текст, изображения, кнопки и другие виджеты. Эти карточки улучшают пользовательский опыт, предоставляя структурированную информацию и позволяя быстро выполнять действия непосредственно в диалоге.

Обзор потока

b72d69a6e79858d6.png

Просмотреть исходный код

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

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/3-ground . Он содержит весь исходный код и ресурсы.
  2. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Замените все содержимое файла index.js на содержимое в вашей локальной среде разработки.
  3. Нажмите «Сохранить и повторно развернуть» .
  4. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

В поле для личных сообщений приложения «Чат» в Google Chat введите What's the world population? и нажмите enter . Приложение должно ответить, прикрепив ссылки на источники в карточке.

cff461da29c05873.png

6. Приложение MCP

Это приложение основано на Format app , добавляя поддержку инструментов, предоставляемых сервером Model Context Protocol (MCP), размещенным удаленно. Оно подключается к MCP-серверу Google Workspace Developer Assist , который предоставляет инструменты для доступа к документации Google Workspace Developers и поиска в ней.

Обзор концепций

Протокол контекста модели (MCP)

Model Context Protocol — это фреймворк с открытым исходным кодом, стандартизированно интегрирующий модели с внешними сервисами. Модели могут программно обнаруживать, понимать и взаимодействовать с различными инструментами, расширяя свои возможности, выполняя действия, аналогичные реальным, и получая доступ к актуальной информации.

MCP TypeScript SDK

TypeScript SDK реализует полную спецификацию MCP, упрощая создание MCP-клиентов, подключающихся к любому MCP-серверу. Он также позволяет разрабатывать MCP-серверы, предоставляющие доступ к ресурсам, подсказкам и инструментам.

Обзор потока

e0b324e2cca21915.png

Просмотреть исходный код

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

пакет.json 

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

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/4-mcp . Он содержит весь исходный код и ресурсы.
  2. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Замените все содержимое файлов index.js и package.json на содержимое в вашей локальной среде разработки.
  3. Нажмите «Сохранить и повторно развернуть» .
  4. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

  1. В поле для личных сообщений приложения «Чат» в Google Chat введите What can you do for me? и нажмите enter . Приложение должно описать свои возможности (инструменты MCP).

13535bfd31d85a50.png

  1. В поле для личных сообщений приложения «Чат» в Google Chat введите I would like to get the latest official documentation for the Google Sheets API append values и нажмите enter . Приложение должно предоставить запрошенную документацию (с помощью инструментов MCP).

8a6f4ac5b7d5fa4a.png

7. Многооборотное приложение

Это приложение основано на Format app и поддерживает разговорную память, отслеживая историю чат-взаимодействий. Оно обеспечивает более естественный, интеллектуальный и персонализированный опыт взаимодействия. Для хранения данных приложение использует базу данных Google Cloud Firestore по умолчанию, связанную с проектом Google Cloud.

Обзор концепций

Многооборотный

Концепция многооборотности подразумевает способность модели сохранять контекст и преемственность в рамках множества обменов и диалогов. Это необходимая функция для поддержки сложных диалогов, сложных функций на базе искусственного интеллекта и естественного пользовательского опыта.

Google Cloud Firestore

Google Cloud Firestore — это гибкая масштабируемая облачная база данных NoSQL для разработки мобильных, веб- и серверных приложений. Она хранит данные в документах, организованных в коллекции, и обеспечивает синхронизацию в режиме реального времени и офлайн-поддержку.

Обзор потока

52920a2227467218.png

Просмотреть исходный код

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

пакет.json 

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

Включить API Google Cloud Firestore

  1. В консоли Google Cloud включите API Google Cloud Firestore :

  1. Нажмите Меню ☰ > API и службы > Включенные API и службы , а затем убедитесь, что API Cloud Firestore присутствует в списке.

Создать базу данных Cloud Firestore

  1. В консоли Google Cloud нажмите Меню ☰ > Firestore.

  1. Нажмите «Создать базу данных Firestore».
  2. Оставьте конфигурацию по умолчанию и нажмите «Создать базу данных».

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/5-multi-turn . Он содержит весь исходный код и ресурсы.
  2. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Замените все содержимое файлов index.js и package.json на содержимое в вашей локальной среде разработки.
  3. Нажмите «Сохранить и повторно развернуть» .
  4. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

  1. В поле для личных сообщений приложения «Чат» в Google Chat введите Can you speak with the English from the 80's for now on? и нажмите enter . Приложение должно ответить положительно.

b273beda7e203b23.png

  1. В поле для личных сообщений приложения «Чат» в Google Chat введите Define what Google Chat apps are in one sentence и нажмите enter . Приложение должно продолжить отвечать на английском языке, как в 80-х.

9156f563c369f186.png

8. Пользовательское приложение-инструмент

Это приложение основано на Multi-turn app , добавляя поддержку функции, вызывающей пользовательский инструмент, который использует API Календаря Google Workspace для получения следующего события из публичного календаря. Модель управляет всеми взаимодействиями с пользователем, включая получение входных данных и отправку выходных данных инструмента. При этом приложение по-прежнему отвечает за выполнение необходимых вызовов API и предоставление результатов модели по запросу. Приложение использует ключ API Google, поскольку для получения данных публичного календаря учётные данные пользователя не требуются.

Обзор концепций

Вызов функции

Вызов функций позволяет модели определить, может ли запрос пользователя быть выполнен внешним инструментом или API. Затем модель предоставляет параметры, необходимые для вызова этого инструмента, интегрируя внешние функции в свои ответы.

API Google Workspace

API Google Workspace позволяют разработчикам интегрировать свои приложения с различными сервисами Google Workspace. Эти API предоставляют программный доступ к функциям таких продуктов, как Gmail, Chat, Calendar, Drive, Docs, Sheets и других, позволяя автоматизировать работу, синхронизировать данные и создавать собственные рабочие процессы.

Обзор потока

ed866ca369a4512f.png

Просмотреть исходный код

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

пакет.json 

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

Включить API календаря

  1. В консоли Google Cloud включите API Google Calendar :

  1. Нажмите Меню ☰ > API и службы > Включенные API и службы , а затем подтвердите, что API Календаря Google есть в списке.

Создать ключ API Google

В консоли Google Cloud выполните следующие действия:

  1. Нажмите Меню ☰ > API и службы > Учетные данные .

  1. Нажмите + Создать учетные данные , а затем выберите Ключ API .
  2. Дождитесь завершения операции.
  3. В диалоговом окне подтверждения найдите текстовое поле Ваш ключ API и нажмите Копировать в буфер обмена .

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/6-custom-tool . Он содержит весь исходный код и ресурсы.
  2. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Замените все содержимое файлов index.js и package.json на содержимое в вашей локальной среде разработки.
  3. Откройте файл env.js и выполните следующие действия.
  4. Добавьте googleApiKey к экспортируемым полям 
export const env = {
 ...
 googleApiKey: 'your-google-api-key',
};
  1. Замените your-google-api-key ключом Google API, скопированным на предыдущем шаге. Его можно получить на странице учётных данных Google Cloud, нажав кнопку «Показать ключ» .

  1. Нажмите «Сохранить и повторно развернуть» .
  2. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

  1. В Календаре Google выполните следующие действия:
  2. В разделе «Другие календари» нажмите + , затем нажмите Создать новый календарь .
  3. Установить имя для My Public Calendar
  4. Нажмите «Создать календарь».
  5. Дождитесь завершения операции.
  6. В разделе «Настройки моих календарей» выберите недавно созданный календарь «Мой публичный календарь».
  7. В разделе Разрешения на доступ к событиям выберите Сделать доступным для публики , а затем нажмите кнопку ОК в диалоговом окне Предупреждение .
  8. В разделе «Разрешения на доступ к событиям» выберите «Просмотреть все сведения о событиях» в раскрывающемся меню рядом с опцией «Сделать доступным для публики».
  9. В разделе «Интеграция календаря» скопируйте значение поля «ID календаря» в буфер обмена.
  10. Чтобы выйти из настроек , нажмите левую стрелку в левом верхнем углу.
  11. Нажмите на календарь, чтобы создать новое событие на завтра, введите Important meeting , выберите «Мой публичный календарь» в раскрывающемся списке, затем нажмите « Сохранить».
  12. В поле для личных сообщений в приложении «Чат» Google Chat введите When is the next meeting? и нажмите enter . Приложение должно запросить уточнение, поскольку неясно, о каком календаре идёт речь.

40383099311b0813.png

  1. В поле для личных сообщений приложения «Чат» в Google Chat вставьте идентификатор календаря, скопированный ранее в буфер обмена, и нажмите enter . Приложение должно ответить подробностями о ранее созданном мероприятии.

4c614c7e444e3b45.png

9. Приложение для потоковой передачи

Это приложение использует модель Gemini для генерации двухминутных историй на основе тем, предложенных пользователями. Поскольку для генерации полных ответов требуется время, приложение обращается к модели в потоковом режиме и использует API Google Chat для отправки контента и статусов в сообщениях по мере продвижения.

Обзор концепций

API Google Чата

API Google Chat позволяет разработчикам программно взаимодействовать с Google Chat, что позволяет им отправлять сообщения, создавать чаты, управлять участниками и многое другое, а также создавать пользовательские интеграции и ботов.

Потоковое вещание

Потоковая передача данных подразумевает получение данных непрерывным потоком, а не ожидание полного ответа. При вызовах моделей ИИ потоковая передача позволяет приложениям отображать частичные результаты пользователям сразу по мере их появления, что повышает воспринимаемую производительность и удобство использования, особенно при длительных задачах генерации. Это особенно актуально для генеративных моделей ИИ, которым может потребоваться значительное время для получения полного результата.

Обзор потока

25f9036eecd9a48b.png

Просмотреть исходный код

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
 }]}};
}

пакет.json 

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

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/7-stream . Он содержит весь исходный код и ресурсы.
  2. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Замените все содержимое файлов index.js и package.json на содержимое в вашей локальной среде разработки.
  3. Нажмите «Сохранить и повторно развернуть» .
  4. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

В поле для прямых сообщений в приложении «Чат» Google Chat введите turtle и нажмите enter . Приложение должно ответить сообщением-подтверждением, историей, отображающей статус выполнения, и сообщением о завершении.

17600cd1490972c7.png

26af4b3d442712a5.png

10. Мультимодальное приложение

Это приложение использует модель редактирования изображений на основе текстовых инструкций пользователей. И пользователи, и приложение добавляют свои изображения в виде вложений к сообщениям Google Chat для обмена. Приложение использует API Google Chat для программной загрузки и выгрузки изображений.

Обзор концепций

Вложение сообщения Google Chat

Вложения к сообщениям Google Chat — это файлы, такие как изображения или видео, которые загружаются в сообщение Google Chat. Этими вложениями можно управлять программно, что позволяет приложениям взаимодействовать с мультимедийными материалами непосредственно в ходе беседы.

Делегирование на уровне домена (DWD)

Делегирование на уровне домена (DWD) позволяет учетной записи службы выдавать себя за пользователей в домене Google Workspace, позволяя приложениям выполнять действия от имени этих пользователей без прямой авторизации. Это полезно для приложений, которым требуется доступ к пользовательским данным или выполнение действий (например, загрузка вложений в Google Chat) в контексте пользователя, даже когда пользователь не присутствует в данный момент, предоставляя учетной записи службы широкий доступ в пределах домена.

Обзор потока

74295b25761f1682.png

Просмотреть исходный код

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

Настройте учетную запись службы и экспортируйте закрытый ключ

  1. Делегируйте учетную запись службы Cloud Run по умолчанию для управления сообщениями Google Chat для пользователей. Следуйте инструкциям на странице https://www.googleapis.com/auth/chat.messages . Чтобы получить идентификатор клиента учетной записи службы Cloud Run по умолчанию, выполните следующие действия:
  2. Нажмите Меню ☰ > IAM и администрирование > Учетные записи служб.

  1. Щелкните учетную запись службы с именем Учетная запись службы вычислений по умолчанию .
  2. Развернуть раздел Расширенные настройки
  3. Скопировать идентификатор клиента в буфер обмена.
  4. Создайте и загрузите новый закрытый ключ для учетной записи службы Cloud Run по умолчанию.
  5. Нажмите Меню ☰ > IAM и администрирование > Учетные записи служб.

  1. Щелкните учетную запись службы с именем Учетная запись службы вычислений по умолчанию .
  2. Выберите вкладку Ключи , нажмите Добавить ключ , затем Создать новый ключ .
  3. Выберите JSON , затем нажмите Создать .
  4. Ваша новая пара открытого и закрытого ключей будет сгенерирована и загружена на ваш компьютер в виде нового файла. Сохраните загруженный JSON-файл и скопируйте его содержимое в буфер обмена. Этот файл — единственная копия данного ключа. Сведения о безопасном хранении ключа см. в разделе Управление ключами учётной записи службы .

Обновление функции Google Cloud Run Node.js

  1. В локальной среде разработки измените текущий каталог на node/chat/gen-ai-apps/8-multimodal . Он содержит весь исходный код и ресурсы.
  2. Перейдите на вкладку «Источник» на странице сведений о службе функции Google Cloud Run.

  1. Нажмите «Изменить источник» .
  2. Нажмите ➕ , введите credentials.json и нажмите ✔️, чтобы создать отсутствующий файл ресурсов.
  3. Вставьте содержимое JSON-файла, загруженного на предыдущем шаге, во вновь созданный файл credentials.json .
  4. Замените все содержимое файла index.js на содержимое в вашей локальной среде разработки.
  5. Откройте файл env.js и задайте для параметра model значение gemini-2.0-flash-preview-image-generation . 
...
model: 'gemini-2.0-flash-preview-image-generation',
...
  1. Нажмите «Сохранить и повторно развернуть» .
  2. Дождитесь успешного завершения развертывания ревизии.

487b64f2d3b1a104.png

Попробуй это

В поле для личных сообщений приложения «Чат» в Google Chat загрузите свой портрет в формате PNG, введите Change the background color to blue и нажмите enter . Приложение должно отправить вам версию изображения на синем фоне и сообщение с подтверждением отправки.

270547e7a83c1841.png

11. Уборка

Удалить проект Google Cloud

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этой лабораторной работе, мы рекомендуем вам удалить проект Google Cloud.

В консоли Google Cloud выполните следующие действия:

  1. Нажмите Меню ☰ > IAM и администрирование > Настройки .

  1. Нажмите «Завершить работу» .
  2. Введите идентификатор проекта.
  3. Нажмите «Все равно выключить» .

407699a4e03afea6.png

12. Поздравления

Поздравляем! Вы создали приложения Google Chat как дополнения к Google Workspace, интегрирующие фундаментальные концепции искусственного интеллекта!

Что дальше?

В этой лабораторной работе мы демонстрируем только минималистичные варианты использования, но есть множество областей расширения, которые вы, возможно, захотите рассмотреть в своих приложениях Google Chat, например следующие:

  • Поддержка других типов медиа, таких как аудио и видео.
  • Интеграция с другими моделями ИИ, включая таможенные, размещенными на специализированных платформах, таких как Vertex AI.
  • Интеграция с агентами, включая таможенных, размещенными на специализированных платформах, таких как Agentspace и Dialogflow CX.
  • Используйте циклы обратной связи и классификации для мониторинга и повышения производительности.
  • Публикуйте на торговой площадке, чтобы расширить возможности команд, организаций или обычных пользователей.

Узнать больше

Разработчикам доступно множество ресурсов, таких как видеоролики на YouTube, сайты с документацией, примеры кода и учебные пособия: