Minilição · Português

Como adicionar um chatbot de IA ao seu site

Execute um chatbot privado pronto com um assistente de programação e teste se uma pergunta seguinte usa a conversa e resiste a uma solicitação com falha.

Começar a aula interativaLer as notas da aula

Para quem é esta lição?

Para quem quer adicionar um assistente de conversa a um pequeno site. O projeto é fornecido; você orienta seu comportamento e o testa em vez de escrever código de tratamento de mensagens.

Antes de começar

Você precisa do seu acesso à API do Google AI Studio e do projeto completo separado de funções de servidor. A aula de chaves explica a configuração privada, se necessário. Confira antes modelos disponíveis, limites e cobranças. Use mensagens fictícias e um código mantido pelo responsável; autenticação, limites duráveis e monitoramento de orçamento são necessários antes do uso público.

Tempo estimado: 20–32 min

Estimativas com os arquivos iniciais e as contas e ferramentas necessárias já prontas. Configuração, filas de publicação e esperas de e-mail ou DNS exigem tempo adicional. Solicitações reais usam a cota da conta configurada. Autenticação pública, limites duradouros e revisão de privacidade são trabalhos separados.

O que você vai aprender

  • Obtenha uma primeira resposta real de IA.
  • Verifique uma pergunta seguinte que dependa da mensagem anterior.
  • Mantenha uma mensagem com falha disponível para nova tentativa.

Arquivos da oficina

Etapa 1

Escolha uma conversa curta para testar

A segunda mensagem deve depender da primeira.

Abra o projeto de chatbot pronto com seu assistente. Escolha um tema fictício simples e uma pergunta que se refira à resposta anterior para avaliar se a conversa continua.

Uma boa resposta isolada não comprova uma conversa funcional. Planeje examinar as duas mensagens e a relação entre elas.

Um exemplo concreto

Peça uma explicação curta e depois uma versão mais simples daquela mesma explicação.

Use o projeto de chatbot fornecido e oriente a configuração privada em run-locally.txt. Mantenha credenciais e instruções do modelo no servidor. Ajude-me a fazer uma pergunta inicial, continuar no mesmo tema e testar uma solicitação com falha sem perder a mensagem digitada. Não reconstrua o site nem alegue que a conversa funciona só pela primeira resposta.

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Acrescente um chatbot capaz de continuar uma conversa

Uma integração útil precisa ler a mensagem mais recente do estudante e seu contexto.

Esta lição cria um pequeno tutor web. O visitante pergunta, lê a resposta e faz uma pergunta relacionada. O navegador envia a conversa aceita com cada mensagem; o servidor chama Gemini e retorna uma resposta genuína do modelo.

Um modelo não lembra automaticamente a solicitação HTTP anterior. Mantemos um histórico curto na memória desta aba. Recarregar o limpa e a oficina para após quatro trocas bem-sucedidas para limitar a prática.

Exemplo resolvido

Pergunte “What is DNS?” (o que é DNS?) e depois “Explain that using a street-address example.” (explique usando um endereço de rua). A segunda solicitação precisa da pergunta e resposta anteriores para estabelecer o significado de “isso”.

Extra implementation exercise

Por que uma resposta no segundo turno pode parecer sem relação mesmo quando a API tem sucesso?

Mostrar uma solução comentada

A integração pode ter enviado apenas uma instrução genérica ou omitido o histórico. Examine o array messages de saída e confirme os turnos aceitos anteriores e a nova pergunta em ordem.

  • Verifica se as mensagens anteriores foram incluídas.
  • Verifica se a mensagem mais recente do usuário foi preservada.

Etapa 2

Inicie o chatbot fornecido

Peça ao assistente para cuidar da configuração privada do servidor.

Siga run-locally.txt com o assistente. Confirme conta/modelo e condições, configure os valores privados de server-env.example.txt e abra a URL indicada pelo proxy local. Digite o código separado no formulário, nunca a chave do provedor. Essa preparação é obrigatória; escrever o código do servidor é opcional.

A chave do provedor e as instruções que regem o comportamento ficam no servidor. Se sua conta ou modelo estiver indisponível, relate essa etapa exata em vez de preencher a página com uma resposta falsa.

Um exemplo concreto

Um campo do site não deve permitir ao visitante escolher suas credenciais privadas do provedor.

Gemini: API generateContent · Gemini: chaves de API · Gemini: IDs e capacidades atuais dos modelos · Node.js: estado de suporte das versões

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Conecte o navegador a uma função de servidor limitada

Mantenha credenciais e papel do tutor sob controle do servidor.

Implante as pastas e configure as variáveis de START-HERE.txt. public/app.js envia mensagens user/assistant à função mini-chat. Ela aceita apenas papéis alternados, texto limitado e um histórico pequeno.

O servidor converte assistant para o papel model do Gemini e fornece uma instrução de sistema separada. Quem chama não pode escolher URL do provedor nem substituir a instrução com um papel system do cliente. O código do proprietário restringe o laboratório; não substitui autenticação pública e controles duradouros de gastos.

generate é uma função auxiliar local em netlify/functions/mini-chat.mjs, não outro serviço implantado. Para mudar o tutor, edite o texto passado a generate nesse arquivo de servidor. Uma variável .env frontend não é alternativa: um valor substituído em código de navegador vira público.

Para a sequência local completa, abra run-locally.txt: prepare o ambiente privado da raiz, vincule apenas o projeto de prática e inicie o proxy de funções do Netlify. server-env.example.txt lista nomes de variáveis sem segredos reais. Abrir apenas o HTML não executa o servidor.

Use o guia atual abaixo ou execute list-text-models.mjs na raiz privada da oficina com seu ambiente. Ele lista candidatos generateContent visíveis à conta sem imprimir a chave. Escolha um modelo de texto com suporte, confira termos e cota e copie seu ID exato para GEMINI_MODEL no servidor.

Exemplo resolvido

O validador rejeita uma mensagem system injetada antes de chamar o provedor. Não torna a resposta infalível, mas mantém o formato e a configuração privilegiada sob seu controle.

Gemini: API generateContent · Gemini: chaves de API · Gemini: IDs e capacidades atuais dos modelos · Node.js: estado de suporte das versões

Extra implementation exercise

O navegador deve escolher GEMINI_API_KEY ou enviar uma mensagem system para substituir o tutor?

Mostrar uma solução comentada

Nenhum dos dois. Configure chave e papel no servidor. Valide papéis e tamanhos; as respostas ainda precisam ser avaliadas quanto à correção.

  • Mantém segredos do provedor no servidor.
  • Trata mensagens do cliente como entrada de conversa não confiável.

Etapa 3

Continue a conversa e experimente uma falha

Proteja a mensagem digitada quando a solicitação falhar.

Envie a pergunta dependente e compare sua resposta com a troca anterior. Peça ao assistente para ajudar a simular ou reproduzir uma solicitação com falha no projeto descartável.

A continuação deve permanecer sobre sua conversa e um envio com falha deve preservar o rascunho e as mensagens anteriores para tentar novamente.

Um exemplo concreto

Uma falha na segunda interação não deve apagar a pergunta que você acabou de digitar.

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Teste a continuação e a falha

Inclua o segundo turno no teste de conclusão.

Faça a pergunta sobre DNS do exemplo e depois uma pergunta de acompanhamento que se refira a ela. Examine o corpo da solicitação nas ferramentas do navegador e compare a resposta com a última pergunta real. Uma resposta longa e fluente não comprova relevância.

Tente um código errado no envio seguinte. O rascunho permanece em textarea e nenhuma troca que falhou é acrescentada ao histórico aceito. Corrija e tente de novo. Enter envia; Shift+Enter cria uma linha. O botão fica desativado durante a espera.

Exemplo resolvido

Tempo esgotado ou resposta incompleta do provedor produz falha visível. O navegador não acrescenta uma mensagem assistant vazia fingindo que a conversa continuou.

Extra implementation exercise

A primeira resposta é boa, mas a segunda solicitação falha. O que deve acontecer com o texto digitado e o histórico?

Mostrar uma solução comentada

Mantenha o rascunho e os turnos aceitos. Mostre a falha com honestidade, restabeleça os controles e acrescente o novo par apenas depois de uma resposta válida.

  • Preserva o rascunho para tentar novamente.
  • Não registra uma resposta inventada do assistente.

Etapa 4

Entregue o comportamento da conversa

Use várias trocas em vez de uma única resposta atraente.

Conclua um teste de três trocas com seu tema fictício e guarde uma transcrição com dados sensíveis ocultados. Repita a recuperação de envio com falha após qualquer correção.

Verifique se repetir não perde o rascunho nem duplica uma troca bem-sucedida. Marque testes indisponíveis como não realizados. Este exemplo não busca notas confiáveis do site nem garante respostas factuais; a próxima aula, content-chatbot, adiciona uma tarefa com fontes fornecidas e verificação.

Um exemplo concreto

Suas provas devem mostrar o que o visitante perguntou, o que voltou e como uma solicitação com falha foi recuperada.

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Sua tarefa: criar um tutor com quem vale continuar

Avalie relevância em vez de contar apenas solicitações bem-sucedidas.

Mude a instrução do servidor para um tutor conciso de HTML/CSS. Faça três trocas: pergunte sobre uma âncora quebrada, proponha um par href/id incorreto e pergunte por que falha. Use código sintético, não fontes privadas.

Guarde uma transcrição sem dados sensíveis e anote se cada resposta aborda a última mensagem. Repita um envio com falha e demonstre que a nova tentativa mantém a coerência. Antes do acesso público, planeje autenticação real, cotas persistentes por usuário e explicação do destino das mensagens.

Exemplo resolvido

Um tutor útil identifica os href/id que não correspondem. Conselhos genéricos sobre nomes de variáveis não atenderiam à resposta específica do estudante, mesmo sendo tecnicamente verdadeiros.

O roteiro completo de referência está em reference/assignment-walkthrough.txt. Compare as etapas com seu resultado; preencha o registro de teste com observações do seu próprio projeto.

Extra implementation exercise

Produza uma transcrição de três trocas e uma observação de falha e nova tentativa.

Mostrar uma solução comentada

Edite a instrução da função de servidor para um tutor HTML/CSS conciso. Não mude uma variável frontend nem mova generate para public. A função de referência mostra a versão completa alterada.

Avaliação de exemplo: o usuário pergunta por que <a href='#work'> não chega a <section id='projects'>. Uma resposta relevante aponta essa incompatibilidade. Depois propõe href='#projects'; uma continuação relevante verifica essa correção específica. Conselhos genéricos sobre variáveis falhariam mesmo com HTTP 200.

Envie com código errado em um turno posterior. A conversa aceita deve permanecer intacta e textarea deve manter o rascunho não enviado. Corrija e tente novamente; acrescente um par user/assistant só depois de resposta válida. Esta transcrição é um guia de avaliação, não uma afirmação de resultado gerado ao vivo.

  • As continuações respondem às mensagens reais anteriores.
  • A falha preserva rascunho e histórico e a chave continua privada.

Esta lição foi útil?

Deixe uma curtida ou compartilhe com alguém que possa aproveitar.

Continue aprendendo

Explore as outras lições