Создайте агента поддержки клиентов на основе искусственного интеллекта с помощью Firebase AI Logic.

1. Введение

В этом практическом занятии вы добавите интеллектуальный виджет чата поддержки клиентов в интернет-магазин товаров для активного отдыха под названием Rugged Terrain Guide . Вы будете использовать Firebase AI Logic для создания этого агента и узнаете, как настроить шаблон запроса на стороне сервера ( product-agent ), который обрабатывает профиль ИИ, строгие правила ограничения бюджета и динамически использует каталог товаров в качестве контекста.

Что вы будете делать:

  • Получите стартовый код для веб-приложения этого семинара.
  • Создайте проект Firebase.
  • Настройте и инициализируйте сервисы Firebase (например, Firebase AI Logic) в веб-приложении.
  • Настройте шаблон запроса на стороне сервера в консоли Firebase.
  • Доступ к шаблону осуществляется путем вызова сервиса генеративного ИИ из интерфейса на TypeScript, подобного React.

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

  • Веб-браузер, например Chrome .
  • Базовые знания TypeScript и Node.js.
  • Среда разработки или текстовый редактор на ваш выбор. Antigravity — хороший выбор.

2. Получите стартовый код

  1. В терминале клонируйте стартовый репозиторий: 
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Перейдите в каталог с кодом и установите зависимости: 
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Создайте проект Firebase.

Создайте проект Firebase.

  1. Войдите в консоль Firebase, используя свою учетную запись Google.
  2. Нажмите кнопку, чтобы создать новый проект, а затем введите название проекта (например, rugged-terrain-ai ).
  3. Нажмите «Продолжить» .
  4. Если появится запрос, ознакомьтесь с условиями использования Firebase и примите их, после чего нажмите «Продолжить» .
  5. (Необязательно) Включите помощь ИИ в консоли Firebase (в Firebase она называется "Gemini").
  6. Для этого практического занятия вам не понадобится Google Analytics, поэтому отключите эту опцию.
  7. Нажмите «Создать проект» , дождитесь завершения подготовки проекта, а затем нажмите «Продолжить» .

Обновите свой тарифный план Firebase.

Для использования сервисов Firebase в этом практическом задании ваш проект Firebase должен быть подключен к тарифному плану с оплатой по мере использования (Blaze) , то есть он должен быть связан с учетной записью Cloud Billing .

Чтобы перейти на тарифный план Blaze для вашего проекта, выполните следующие шаги:

  1. В консоли Firebase выберите вариант обновления вашего тарифного плана .
  2. Выберите тарифный план Blaze. Следуйте инструкциям на экране, чтобы связать учетную запись Cloud Billing с вашим проектом.
    • Если вы используете кредиты Google Cloud для выполнения этого практического задания, то учетная запись для выставления счетов, скорее всего, называется Google Cloud Platform Trial Billing Account или My Billing Account .
    • Если в рамках этого обновления вам потребовалось создать учетную запись Cloud Billing, возможно, вам нужно будет вернуться к процессу обновления в консоли Firebase, чтобы завершить обновление.

4. Настройте службы Firebase и подключите ваше приложение.

Для выполнения этого практического задания вам необходимо настроить Cloud Storage for Firebase и Firebase AI Logic в вашем проекте Firebase. Вам также необходимо связать исходный код вашего приложения с вашим проектом Firebase.

Настройка облачного хранилища для Firebase

В этом практическом занятии для хранения описаний товаров используется Cloud Storage for Firebase.

  1. В консоли Firebase перейдите в раздел «Базы данных и хранилище» > «Хранилище» .
  2. Нажмите « Начать» .
  3. Выберите местоположение для вашего хранилища по умолчанию.
    Для регионов US-WEST1 , US-CENTRAL1 и US-EAST1 доступен тариф "Всегда бесплатно" от Google Cloud Storage. Для регионов во всех остальных регионах действуют тарифные планы и правила использования Google Cloud Storage .
  4. Нажмите «Производственный режим» . В следующих шагах вы обновите эти правила безопасности, чтобы они соответствовали условиям данной практической работы.
  5. Нажмите «Создать» .
  6. Обновите правила безопасности:
    1. После создания хранилища перейдите на вкладку «Правила» .
    2. Скопируйте и вставьте следующие правила: 
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Нажмите «Опубликовать» .
  7. Загрузите описания товаров из стартового кода:
    1. Для выбора хранилища перейдите на вкладку «Файлы» .
    2. Нажмите «Загрузить файл» , а затем загрузите файл products.txt из стартового кода. Этот файл находится по адресу: src/data/products.txt .

Настройка логики Firebase AI

Firebase AI Logic — это основной сервис Firebase, который вы будете использовать в этом практическом занятии.

  1. В консоли Firebase перейдите в раздел AI Services > AI Logic .
  2. Нажмите « Начать» .
  3. На карточке API Agent Platform Gemini нажмите « Начать работу с этим API» и следуйте инструкциям на экране. Этот процесс активирует необходимые API для использования Firebase AI Logic с API Agent Platform Gemini.
  4. (Необязательно) Включите мониторинг с помощью ИИ , чтобы отслеживать различные метрики и использование на уровне приложения и получать полную картину ваших запросов с помощью Firebase AI Logic.

Подключите свой код к проекту Firebase.

В процессе настройки Firebase AI Logic вам будет предложено создать веб-приложение Firebase и добавить конфигурацию в исходный код.

  1. В процессе настройки Firebase AI Logic при появлении соответствующего запроса нажмите « Веб» ( Значок для регистрации нового веб-приложения.
  2. Назовите приложение (например, Rugged Web ).
  3. Скопируйте объект firebaseConfig из инструкций по настройке.

Далее обновите стартовый код:

  1. В редакторе кода откройте src/firebase.ts .
  2. Замените существующий firebaseConfig на тот, который вы скопировали из консоли Firebase.

Ваш файл должен выглядеть примерно так:

import { getAI, getTemplateGenerativeModel, AgentPlatformBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// Initialize Firebase
export const app = initializeApp(firebaseConfig);

const ai = getAI(app, { backend: new AgentPlatformBackend() });

5. Создайте шаблон запроса на стороне сервера.

Вместо того чтобы жестко прописывать сложные подсказки ИИ в клиентском приложении, вы будете использовать синтаксис Dotprompt для безопасного управления инструкциями на сервере.

Это предотвращает ознакомление конечных пользователей с секретными правилами «бюджета умиротворения».

  1. В консоли Firebase перейдите в раздел AI Services > AI Logic > вкладка Prompt templates .
  2. Нажмите «Создать шаблон» и выберите «Пустой шаблон» .
  3. Задайте имя шаблона как Product Agent , а идентификатор — как product-agent .
  4. Установите модель на gemini-3.1-flash-lite (или последнюю доступную версию).
  5. Скопируйте содержимое файла product-agent.prompt (найдите этот файл в корневом каталоге) из предоставленного для этого практического задания стартового кода. Затем вставьте это содержимое в поле «Подсказка и (необязательно) системные инструкции» шаблона подсказки сервера в консоли Firebase. Это содержимое безопасно указывает модели, как вести себя в качестве «надежного оператора» и ссылаться на каталог продукции.
  6. В поле ввода «Тест» укажите схему ввода точно следующим образом: 
    {
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "the customers ask of the robot"
    },
    "productId": {
      "type": "string",
      "description": "the product the customer is looking at right now"
    },
    "history": {
      "type": "array",
      "description": "list of previous history between the user and system",
      "items": {
        "type": "object",
        "required": [
          "role",
          "contents"
        ],
        "properties": {
          "role": {
            "type": "string"
          },
          "contents": {
            "type": "string"
          }
        }
      }
    }
  }
}
  7. Нажмите «Сохранить шаблон» , чтобы сохранить и опубликовать шаблон product-agent .

6. Вызовите модель ИИ.

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

  1. В редакторе кода вернитесь к src/firebase.ts .
  2. Ниже, после инициализации, используйте getTemplateGenerativeModel для подключения к шаблону: 
    const model = getTemplateGenerativeModel(ai);

export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => {
    // Generate content using the published 'product-agent' template
    const result = await model.generateContent('product-agent', {
        query,
        productId,
        history,
    });
    return result.response.text();
}

7. Защитите агента с помощью Firebase App Check.

Модели искусственного интеллекта мощны, но ими также можно злоупотреблять, если общедоступные конечные точки остаются незащищенными. Всегда используйте Firebase App Check, чтобы убедиться, что только ваше веб-приложение может успешно отправлять запросы к API Gemini, блокируя ботов и неавторизованных клиентов.

  1. В консоли Google Cloud перейдите в раздел Безопасность > Защита от мошенничества.
  2. Нажмите «Создать ключ» и заполните поля:
    • Отображаемое имя : Codelab Key
    • Тип приложения : Веб
    • Список доменов : добавьте localhost и 127.0.0.1 , чтобы вашему локальному серверу Vite было разрешено отправлять запросы.
  3. Нажмите «Создать ключ» , чтобы зарегистрировать ключ.
  4. Скопируйте идентификатор ключа сайта в буфер обмена в верхней части страницы «Информация о ключе защиты от мошенничества».
  5. В консоли Firebase перейдите в раздел Безопасность > Проверка приложений .
  6. Перейдите на вкладку «Приложения» , разверните ваше веб-приложение ( Rugged Web ) и выберите поставщика reCAPTCHA Enterprise .
  7. В поле «Ключ сайта reCAPTCHA Enterprise» вставьте идентификатор ключа сайта со страницы «Подробные сведения о ключе защиты от мошенничества» и нажмите «Сохранить» .
  8. В редакторе кода снова откройте src/firebase.ts .
  9. В самом начале добавьте следующие импорты: 
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  10. Добавьте инициализацию App Check сразу после вызова initializeApp(firebaseConfig) и вставьте скопированный идентификатор ключа сайта: 
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  isTokenAutoRefreshEnabled: true
});
  11. Обновите вызов функции getAI() , чтобы использовать эти токены. Внесите следующее изменение:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    Установив значение параметра useLimitedUseAppCheckTokens равным true, вы гарантируете применение кратковременных токенов, что поможет ограничить злоупотребления в вашей серверной части.

8. Запустите приложение

После настройки Firebase и подключения виджета чата поддержки, можно запускать приложение.

  1. В терминале запустите сервер разработки Vite: 
    npm run dev
  2. Откройте указанный локальный URL (обычно http://localhost:5173/ ).
  3. Нажмите плавающую кнопку тактической поддержки (FAB) в правом нижнем углу.
  4. Попробуйте задать вопросы о товарах, например:
    • "Мне нужна непромокаемая куртка".
    • «Моя шапка для минусовых температур бракованная, что мне делать?»
    • Продолжайте оказывать сопротивление, чтобы запустить логику «бюджета умиротворения» ИИ!

9. (Необязательно) Очистка ресурсов из Codelab.

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

  1. В консоли Firebase перейдите во вкладку «Настройки» > «Общие».
  2. Убедитесь, что вы просматриваете именно тот проект, который использовали для этой практической работы. Если это не ваш проект, вы можете воспользоваться выпадающим списком выбора проектов в верхнем левом углу, чтобы сменить проект.
  3. Прокрутите страницу вниз и нажмите «Удалить проект» .
  4. Следуйте инструкциям на экране, чтобы подтвердить удаление.

10. Поздравляем!

🎊 Миссия выполнена! Вы успешно интегрировали мощный, основанный на шаблонах, агент поддержки клиентов на основе искусственного интеллекта.

Чего вы достигли:

  • Инициализировали Firebase и бэкэнд Agent Platform в клиентском приложении.
  • Настроен защищенный шаблон запроса на стороне сервера с использованием Handlebars и строгих схем ввода для определения сложного поведения агента.
  • Динамически вызываемый LLM обеспечивает безопасную передачу истории чата и контекстных идентификаторов продуктов без раскрытия внутренней логики запросов клиенту.

Что дальше?

  • Firebase App Check : Защитите свои конечные точки ИИ от злоупотреблений.