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 inteligente de suporte ao cliente 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 lida com a persona da IA, regras rígidas de orçamento de compensação e usa dinamicamente o catálogo de produtos como contexto.

Atividades deste laboratório:

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

Você vai precisar do seguinte:

  • Um navegador da Web, como o Chrome.
  • Conhecimento básico de TypeScript e Node.js.
  • Um ambiente de desenvolvimento integrado ou editor de texto de sua escolha. 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 com sua Conta do Google.
  2. Clique no botão para criar um 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 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 Blaze (pagamento por uso), o que significa que ele está vinculado a uma conta do Cloud Billing.

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ê estiver usando créditos do Google Cloud para este codelab, a conta de faturamento provavelmente será chamada de Google Cloud Platform Trial Billing Account ou My Billing Account.
    • 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 processo.

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

Para este codelab, você precisa configurar o Cloud Storage para Firebase e o Firebase AI Logic no seu projeto do Firebase. Também é necessário conectar o código-fonte do app ao 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 > Storage.
  2. Clique em Começar.
  3. Selecione um local para seu 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 que sejam específicas deste codelab.
  5. Clique em Criar.
  6. Atualize suas 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 de 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. O 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 Gemini da Agent Platform, clique em Começar a usar esta 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 Gemini da Agent Platform.
  4. (Opcional) Selecione Ativar o monitoramento de IA para observar várias métricas e o uso no nível do app e 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 precisar 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. Dê um nome ao 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, 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. Criar o modelo de comando do lado do servidor

Em vez de fixar no código comandos complexos de IA 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 compensação".

  1. No console do Firebase, acesse a guia Serviços de IA > Lógica de IA > Modelos de comandos.
  2. Clique em Criar modelo e escolha Modelo em branco.
  3. Defina o nome do modelo como Product Agent e o ID como product-agent.
  4. Defina o modelo como gemini-3.1-flash-lite (ou a versão mais recente disponível).
  5. No código inicial fornecido para este codelab, copie o conteúdo de product-agent.prompt (encontre esse arquivo no diretório raiz). Em seguida, cole esse conteúdo no campo Comando e instruções do sistema (opcional) do modelo de comando do servidor no console do Firebase. Esse conteúdo instrui o modelo de forma segura sobre como se comportar como "Rugged Operator" e fazer referência ao catálogo de produtos.
  6. No campo Entrada de teste, defina o esquema de entrada exatamente da seguinte maneira:
    {
      "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. Clique em Salvar modelo para salvar e publicar 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, volte para 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 indevidamente se os endpoints públicos ficarem desprotegidos. Use sempre o Firebase App Check para garantir que apenas seu web app real possa fazer solicitações bem-sucedidas à API Gemini, bloqueando bots e clientes não autorizados.

  1. No console do Google Cloud, acesse Segurança > Fraud Defense.
  2. Clique em Criar chave e preencha os campos:
    • Nome de exibição: Codelab Key
    • Tipo de aplicativo: Web
    • Lista de domínios: adicione localhost e 127.0.0.1 para que o servidor Vite local possa fazer solicitações.
  3. Clique em Criar chave para registrar a chave.
  4. Na parte de cima da página de detalhes do Fraud Defense, copie o ID da chave do site para a área de transferência.
  5. No console do Firebase, acesse Segurança > App Check.
  6. Clique na guia Apps, expanda seu app da Web (Rugged Web) e clique no provedor reCAPTCHA Enterprise.
  7. No campo Chave de site do reCAPTCHA Enterprise, cole o ID da chave de site da página de detalhes do Fraud Defense e clique em Salvar.
  8. No editor de código, abra src/firebase.ts de novo.
  9. Adicione as seguintes importações na parte de cima:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
    
  10. Adicione a inicialização do App Check logo após a chamada initializeApp(firebaseConfig) e cole o ID da chave do site que você copiou:
    // Initialize App Check
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
      isTokenAutoRefreshEnabled: true
    });
    
  11. Atualize a chamada de função getAI() para usar esses tokens. Faça a seguinte mudança:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    
    Ao definir o valor de useLimitedUseAppCheckTokens como "true", você garante que tokens de curta duração sejam aplicados para ajudar a limitar o abuso que seu back-end pode receber.

8. Executar o app

Com a configuração do Firebase no lugar e o widget de chat de suporte conectado, é 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) Suporte tático no canto inferior direito.
  4. Faça perguntas sobre os produtos, por exemplo:
    • Estou procurando um casaco resistente a intempéries
    • "Meu gorro para temperaturas abaixo de zero está com defeito. O que posso fazer?"
    • Continue insistindo para acionar a lógica de "Orçamento de apaziguamento" da IA.

9. (Opcional) Limpar os recursos do codelab

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

  1. No console do Firebase, acesse a guia Configurações > Geral.
  2. Verifique se o projeto que você está visualizando é o mesmo usado neste codelab. Se não for o projeto do seu codelab, use o menu suspenso do seletor de projetos no canto superior esquerdo para mudar de projeto.
  3. Role até a parte de baixo da página e clique em Excluir projeto.
  4. 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 baseado em modelos.

O que você conquistou:

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

A seguir