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
- No terminal, clone o repositório inicial:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git - 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
- Faça login no console do Firebase com sua Conta do Google.
- Clique no botão para criar um projeto e insira um nome (por exemplo,
rugged-terrain-ai).
- Clique em Continuar.
- Se solicitado, leia e aceite os Termos do Firebase e clique em Continuar.
- (Opcional) Ative a assistência de IA no console do Firebase (chamada de "Gemini no Firebase").
- Neste codelab, você não precisa do Google Analytics. Portanto, desative a opção do Google Analytics.
- 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.
- Uma conta do Cloud Billing exige uma forma de pagamento, como cartão de crédito.
- Durante promoções especiais ou se você estiver fazendo este codelab como parte de um evento, talvez haja créditos do Google Cloud disponíveis.
- 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 de avaliação sem custos financeiros do Cloud Billing.
Para fazer upgrade do seu projeto para o plano Blaze, siga estas etapas:
- No console do Firebase, selecione Fazer upgrade do seu plano.
- 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 AccountouMy 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.
- Se você estiver usando créditos do Google Cloud para este codelab, a conta de faturamento provavelmente será chamada de
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.
- No console do Firebase, acesse Bancos de dados e armazenamento > Storage.
- Clique em Começar.
- Selecione um local para seu bucket de armazenamento padrão.
Os buckets emUS-WEST1,US-CENTRAL1eUS-EAST1podem 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. - Clique em Modo de produção. Nas etapas abaixo, você vai atualizar essas regras de segurança para que sejam específicas deste codelab.
- Clique em Criar.
- Atualize suas regras de segurança:
- Depois que o bucket for provisionado, acesse a guia Regras.
- Copie e cole as seguintes regras:
rules_version = '2'; service firebase.storage { match /b/{bucket}/o { match /products.txt { allow read; } } } - Clique em Publicar.
- Faça upload das descrições de produtos do código inicial:
- Clique na guia Arquivos do bucket de armazenamento.
- Clique em Fazer upload do arquivo e faça upload do arquivo
products.txtdo 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.
- No console do Firebase, acesse Serviços de IA > Lógica de IA.
- Clique em Começar.
- 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.
- (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.
- Quando solicitado no fluxo de configuração do Firebase AI Logic, clique no ícone Web (
) para registrar um novo app da Web. - Dê um nome ao app (por exemplo,
Rugged Web). - Copie o objeto
firebaseConfigdas instruções de configuração.
Em seguida, atualize o código inicial:
- No editor de código, abra
src/firebase.ts. - Substitua o
firebaseConfigatual 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".
- No console do Firebase, acesse a guia Serviços de IA > Lógica de IA > Modelos de comandos.
- Clique em Criar modelo e escolha Modelo em branco.
- Defina o nome do modelo como
Product Agente o ID comoproduct-agent. - Defina o modelo como
gemini-3.1-flash-lite(ou a versão mais recente disponível). - 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. - 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" } } } } } } - 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.
- No editor de código, volte para
src/firebase.ts. - Abaixo da inicialização, use
getTemplateGenerativeModelpara 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.
- No console do Google Cloud, acesse Segurança > Fraud Defense.
- Clique em Criar chave e preencha os campos:
- Nome de exibição:
Codelab Key - Tipo de aplicativo: Web
- Lista de domínios: adicione
localhoste127.0.0.1para que o servidor Vite local possa fazer solicitações.
- Nome de exibição:
- Clique em Criar chave para registrar a chave.
- 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.
- No console do Firebase, acesse Segurança > App Check.
- Clique na guia Apps, expanda seu app da Web (
Rugged Web) e clique no provedor reCAPTCHA Enterprise. - 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.
- No editor de código, abra
src/firebase.tsde novo. - Adicione as seguintes importações na parte de cima:
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check"; - 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 }); - Atualize a chamada de função
getAI()para usar esses tokens. Faça a seguinte mudança: Ao definir o valor deconst ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });useLimitedUseAppCheckTokenscomo "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.
- No terminal, execute o servidor de desenvolvimento do Vite:
npm run dev - Abra o URL local fornecido (geralmente
http://localhost:5173/). - Clique no botão de ação flutuante (FAB) Suporte tático no canto inferior direito.
- 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.
- No console do Firebase, acesse a guia Configurações > Geral.
- 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.
- Role até a parte de baixo da página e clique em Excluir projeto.
- 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
- Firebase App Check: proteja seus endpoints de IA contra abusos.