Criar um agente de suporte ao cliente com tecnologia de IA usando o Firebase AI Logic

1. Introdução

Neste codelab, você vai adicionar um widget de chat de suporte ao cliente inteligente a uma loja de e-commerce de equipamentos para atividades ao ar livre chamada Rugged Terrain Guide. Você vai usar o Firebase AI Logic para criar esse agente e aprender a configurar um modelo de comando do lado do servidor (product-agent) que processa a persona da IA, regras de orçamento de compensação estritas e usa dinamicamente o catálogo de produtos como contexto.

Atividades deste laboratório:

  • Acessar o código inicial do app da Web deste codelab.
  • Configurar um projeto do Firebase.
  • Configurar e inicializar serviços do Firebase (como o Firebase AI Logic) em um app da Web.
  • Configurar um modelo de comando do lado do servidor no console do Firebase.
  • Acessar o modelo de uma chamada para o serviço de IA generativa de um front-end do TypeScript semelhante ao React.

Você vai precisar do seguinte:

  • Um navegador da Web, como o Chrome.
  • Familiaridade básica com TypeScript e Node.js.
  • Um ambiente de desenvolvimento integrado ou editor de texto de sua escolha. O Antigravity é uma boa opção.

2. Acessar o código inicial

  1. No terminal, clone o repositório inicial:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Navegue até o diretório de código e instale as dependências:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Configurar um projeto do Firebase

Criar um projeto do Firebase

  1. Faça login no console do Firebase usando sua Conta do Google.
  2. Clique no botão para criar um novo projeto e insira um nome (por exemplo, rugged-terrain-ai).
  3. Clique em Continuar.
  4. Se solicitado, leia e aceite os Termos do Firebase e clique em Continuar.
  5. (Opcional) Ative a assistência de IA no console do Firebase (chamada de "Gemini no Firebase").
  6. Neste codelab, você não precisa do Google Analytics. Portanto, desative a opção do Google Analytics.
  7. Clique em Criar projeto, aguarde o provisionamento do projeto e clique em Continuar.

Fazer upgrade do plano de preços do Firebase

Para usar os serviços do Firebase neste codelab, seu projeto do Firebase precisa estar no plano de preços de pagamento por uso (Blaze), o que significa que ele está vinculado a uma conta do Cloud Billing.

  • Uma conta do Cloud Billing exige uma forma de pagamento, como cartão de crédito.
  • Se você ainda não conhece o Firebase e o Google Cloud, confira se tem qualificação para receber um crédito de US$300 e uma conta do Cloud Billing de teste sem custo financeiro.
  • Se você estiver fazendo este codelab como parte de um evento, pergunte ao organizador se há créditos do Cloud disponíveis.

Para fazer upgrade do seu projeto para o plano Blaze, siga estas etapas:

  1. No console do Firebase, selecione Fazer upgrade do seu plano.
  2. Selecione o plano Blaze. Siga as instruções na tela para vincular uma conta do Cloud Billing ao seu projeto.
    Se você precisou criar uma conta do Cloud Billing como parte desse upgrade, talvez seja necessário voltar para o fluxo de upgrade no console do Firebase para concluir o upgrade.

4. Configurar os serviços do Firebase e conectar seu app

Para este codelab, é necessário configurar o Cloud Storage para Firebase e o Firebase AI Logic no seu projeto do Firebase. Você também precisa conectar o código-fonte do app ao seu projeto do Firebase.

Configurar o Cloud Storage para Firebase

Este codelab usa o Cloud Storage para Firebase para armazenar descrições de produtos.

  1. No console do Firebase, acesse Bancos de dados e armazenamento > Armazenamento.
  2. Clique em Começar.
  3. Selecione um local para o bucket de armazenamento padrão.
    Os buckets em US-WEST1, US-CENTRAL1 e US-EAST1 podem aproveitar o nível "Sempre sem custo financeiro" do Google Cloud Storage. Os buckets em todos os outros locais seguem os preços e usos do Google Cloud Storage.
  4. Clique em Modo de produção. Nas etapas abaixo, você vai atualizar essas regras de segurança para serem específicas deste codelab.
  5. Clique em Criar.
  6. Atualize as regras de segurança:
    1. Depois que o bucket for provisionado, acesse a guia Regras.
    2. Copie e cole as seguintes regras:
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Clique em Publicar.
  7. Faça upload das descrições dos produtos do código inicial:
    1. Clique na guia Arquivos do bucket de armazenamento.
    2. Clique em Fazer upload do arquivo e faça upload do arquivo products.txt do código inicial. Esse arquivo pode ser encontrado em: src/data/products.txt.

Configurar o Firebase AI Logic

O Firebase AI Logic é o principal serviço do Firebase que você vai usar neste codelab.

  1. No console do Firebase, acesse Serviços de IA > Lógica de IA.
  2. Clique em Começar.
  3. No card API Vertex AI Gemini, clique em Começar a usar essa API e siga as instruções na tela. Esse fluxo vai ativar as APIs necessárias para você usar o Firebase AI Logic com a API Vertex AI Gemini.
  4. (Opcional) Selecione Ativar o monitoramento de IA para observar várias métricas e usos no nível do app para ter uma visibilidade abrangente das suas solicitações pelo Firebase AI Logic.

Conectar seu código ao projeto do Firebase

Como parte da configuração do Firebase AI Logic, você vai receber uma solicitação para criar um app da Web do Firebase e adicionar sua configuração ao código-fonte.

  1. Quando solicitado no fluxo de configuração do Firebase AI Logic, clique no ícone Web () para registrar um novo app da Web.
  2. Nomeie o app (por exemplo, Rugged Web).
  3. Copie o objeto firebaseConfig das instruções de configuração.

Em seguida, atualize o código inicial:

  1. No editor de código, abra src/firebase.ts.
  2. Substitua o firebaseConfig atual pelo que você copiou do console do Firebase.

Seu arquivo deve ser semelhante a este:

import { getAI, getTemplateGenerativeModel, VertexAIBackend } 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 VertexAIBackend() });

5. Criar o modelo de comando do lado do servidor

Em vez de codificar comandos de IA complexos no app cliente, você vai usar a sintaxe Dotprompt para gerenciar instruções com segurança no servidor.

Isso impede que os usuários finais vejam as regras secretas de "orçamento de apaziguamento".

  1. No console do Firebase, navegue até a seção Vertex AI ou Gerenciamento de comandos.
  2. Crie um novo modelo de comando e nomeie-o como product-agent.
  3. Defina o modelo como gemini-2.5-flash.
  4. Defina o esquema de entrada exatamente da seguinte maneira:
    input:
  schema:
    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
  5. Copie o conteúdo de agent-product.prompt do diretório raiz para o campo Comando e instruções opcionais do sistema. Isso instrui o modelo com segurança sobre como se comportar como "Operador robusto" e injetar o catálogo de produtos.
  6. No console do Firebase, salve e publique o modelo product-agent.

6. Chamar o modelo de IA

Agora que o modelo está definido com segurança no servidor, basta chamá-lo no front-end do app.

  1. No editor de código, retorne a src/firebase.ts.
  2. Abaixo da inicialização, use getTemplateGenerativeModel para se conectar ao modelo:
    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. Proteger o agente com o Firebase App Check

Os modelos de IA são poderosos, mas também podem ser usados de forma abusiva se os endpoints públicos forem deixados desprotegidos. Você sempre deve usar o Firebase App Check para garantir que apenas seu app da Web real possa chamar o modelo generativo da Vertex AI, bloqueando bots e clientes não autorizados.

  1. No console do Firebase, navegue até Build > App Check.
  2. Clique na guia Apps , expanda o app da Web (Rugged Web) e clique no provedor reCAPTCHA Enterprise.
  3. Selecione Criar nova chave reCAPTCHA Enterprise e preencha o comando:
    • Nome: Codelab Key
    • Domínios: adicione localhost e 127.0.0.1 para que o servidor Vite local possa fazer solicitações.
  4. Clique em Salvar para registrar o app.
  5. Depois de registrado, o console do Firebase vai mostrar sua chave do site. Copie essa string.
  6. No editor de código, abra src/firebase.ts novamente.
  7. Adicione as seguintes importações na parte de cima:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. Adicione a inicialização do App Check logo após a chamada initializeApp(firebaseConfig) e cole a chave do site que você copiou:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. Atualize a chamada de função getAI() para usar esses tokens. Faça esta mudança:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    Ao definir o valor de useLimitedUseAppCheckTokens como verdadeiro, você garante que tokens de curta duração sejam aplicados para ajudar a limitar o uso indevido que seu back-end pode receber.

8. Executar o app

Com a configuração do Firebase e o widget de chat de suporte conectados, é hora de executar o app.

  1. No terminal, execute o servidor de desenvolvimento do Vite:
    npm run dev
  2. Abra o URL local fornecido (geralmente http://localhost:5173/).
  3. Clique no botão de ação flutuante (FAB, na sigla em inglês) Suporte tático no canto inferior direito.
  4. Tente fazer perguntas sobre os produtos, por exemplo:
    • Estou procurando uma capa resistente a intempéries
    • "Meu gorro de temperatura abaixo de zero está com defeito. O que posso fazer?"
    • Continue pressionando para acionar a lógica de "orçamento de apaziguamento" da IA.

9. (Opcional) Limpar recursos do codelab

Para evitar possíveis cobranças na sua conta do Cloud Billing, exclua os recursos criados durante este codelab.

  1. Acesse o Console do Firebase.
  2. Selecione o projeto rugged-terrain-ai.
  3. Acesse Configurações do projeto (o ícone de engrenagem).
  4. Role até a parte de baixo e clique em Excluir projeto.
  5. Siga as instruções na tela para confirmar a exclusão.

10. Parabéns!

🎊 Missão concluída! Você integrou um agente de suporte ao cliente de IA robusto e orientado por modelos.

O que você realizou:

  • Inicializou o Firebase e o back-end da Vertex AI em um app cliente.
  • Configurou um modelo de comando seguro do lado do servidor usando Handlebars e esquemas de entrada estritos para definir o comportamento complexo do agente.
  • Chamou dinamicamente um LLM transmitindo com segurança o histórico do chat e os IDs de produtos contextuais sem expor a lógica de comando interna ao cliente.

A seguir