Construa o projeto com o Gemini

O projeto é escrito em Python. O Gemini só consegue rodar o código se o Python estiver instalado. Primeiro confira. Se faltar, instale.

Antes de abrir o terminal: o que é e para que serve

O terminal é uma janela onde se digitam comandos para o computador. Neste projeto ele serve para conferir ferramentas e para deixar os programas ligados. Os programas do projeto só funcionam enquanto o terminal deles estiver aberto.

A) Conferir o que você já tem

Abra o terminal: tecla Windows, digite PowerShell, Enter. Digite os três comandos, um de cada vez:

python --version
pip --version
git --version

Pedido: conferir as ferramentas

Verifique, no meu computador, se o Python e o pip estão instalados e funcionando, e se o Git está instalado. Mostre a versão de cada um.
Se algum faltar, explique em passos curtos, para Windows, como instalar. Peça minha permissão antes de rodar cada comando.

B) Instalar o Python (se faltar)

1. Abra python.org/downloads.
2. Clique no botão amarelo Download Python. O número da versão muda com o tempo (hoje aparece a 3.14). Qualquer versão 3.11 ou mais nova serve: o projeto foi testado na 3.12 e na 3.14. Evite versões anteriores à 3.11, que deixam de receber correções.
3. Abra o arquivo baixado.
4. Marque a caixinha "Add python.exe to PATH" (embaixo, na primeira tela).
5. Clique em Install Now e espere terminar.

winget install Python.Python.3.12

C) Fechar e abrir de novo

Abra um terminal novo e repita python --version.

D) Instalar o Git (se faltar)

O Git guarda as versões da sua pasta e só será usado no final. Você pode instalar agora ou na Etapa 6 do manual.

1. Abra git-scm.com/download/win e baixe o instalador.
2. Abra o arquivo e clique em Next até o fim. As opções padrão servem.
3. Feche e abra o terminal. Confira com git --version.

E) Teste o Python de verdade

Ver a versão não basta. Rode um programinha seu. No PowerShell, digite:

python -c "print('Olá, oficina!')"

Deve aparecer Olá, oficina!. Agora instale uma peça de teste e use:

python -m pip install requests
python -c "import requests; print(requests.__version__)"

Apareceu um número de versão? O pip funciona. Você vai usar isso na API.

F) Os arquivos que você vai ver no projeto

G) Ativar o ambiente virtual

O Gemini vai criar o ambiente virtual no Passo 5. Para ligar o ambiente, o PowerShell usa este comando, dentro da pasta do projeto:

.venv\Scripts\Activate.ps1

Deu certo se o começo da linha do terminal mostrar (.venv). Para desligar, digite deactivate.

H) Se algo der errado

Cola de comandos do dia a dia

Você já fez a Etapa 1 do manual: criou a pasta oficina-digital e abriu no Antigravity. Confira antes de continuar.

1. O Antigravity está aberto com a pasta oficina-digital.
2. O painel do assistente aparece do lado direito do editor.
3. O Gemini respondeu ao seu primeiro olá.

Antes de criar qualquer coisa, peça um plano. Assim você entende o caminho e não se perde.

Pedido do plano

Sou aluno iniciante. Fale em frases curtas e palavras simples.

Vamos criar, nesta pasta, um projeto chamado Oficina Digital: uma oficina de conserto de computadores de mentirinha.
O cliente abre um chamado num site. Uma API em Python guarda o pedido. Uma triagem faz o laudo. O técnico recebe aviso no Telegram. O cliente acompanha o chamado no site.

As partes são: site (HTML, CSS e JavaScript), API (Python com FastAPI e banco SQLite), triagem com grafo de conhecimento, automação em Python, agente CrewAI com Gemini (no Google Colab) e bot do Telegram.

As chaves e senhas ficarão num arquivo .env, que não vai para o GitHub.

NÃO crie nenhum arquivo agora. Mostre só o plano, em passos curtos e na ordem certa, e a estrutura de pastas. Depois pergunte se pode começar.

1. Leia o plano com calma. Se não entender algo, pergunte: "Explique a parte X de novo, mais simples."
2. Quando estiver claro, responda: "Pode começar pelo site."

O site é a vitrine: o cliente preenche o chamado e acompanha o andamento.

Pedido do site

Agora crie só o SITE, numa pasta chamada "site".

Uma página (index.html) com letra grande e fácil de ler.
- Formulário "Abrir chamado" com quatro campos: nome, contato (e-mail ou telefone), equipamento e relato do problema. Botão "Enviar chamado". Ao enviar, mostre o número do chamado.
- Área "Acompanhar": a pessoa digita o número e vê o status, a prioridade e o laudo.
- O site conversa com a API em http://localhost:8000. Use EXATAMENTE estes nomes de campo no JSON:
  - POST /chamados: envia {"nome", "contato", "equipamento", "relato"} e recebe {"numero", "status"}.
  - GET /chamados/{numero}: recebe {"numero", "equipamento", "status", "prioridade", "laudo", "data"}. Se "laudo" vier vazio, o laudo ainda está sendo feito: mostre "A triagem ainda está trabalhando".
- Se a API estiver desligada, mostre um aviso claro.

Explique cada arquivo em palavras simples. Ainda não crie a API.

1. Cole o pedido no painel do assistente e aperte Enter.
2. Leia o que ele vai criar. Aceite se entender.
3. Na pasta site, dê dois cliques em index.html para ver no navegador.

A API é o programa que recebe os chamados e guarda no banco de dados. Ela precisa ficar ligada para o site funcionar.

Pedido da API

Agora crie só a API, numa pasta chamada "api", com Python e FastAPI.
- Banco de dados SQLite, num arquivo.
- POST /chamados: recebe nome (mínimo 2 letras), contato (mínimo 5), equipamento (mínimo 2) e relato (mínimo 10, máximo 1000). Responde com {"numero": N, "status": "aberto"}.
- GET /chamados/{numero}: devolve {"numero", "equipamento", "status", "prioridade", "laudo", "data"}. NÃO devolva nome nem contato. Enquanto o laudo não estiver pronto, "laudo" vem vazio (null). Se o número não existir, responda 404.
- Use EXATAMENTE esses nomes de campo: o site do projeto depende deles.
- Status possíveis: aberto, em_andamento, concluido.
- Libere CORS para uso local.

Crie o arquivo requirements.txt. Depois me diga, passo a passo, como criar o ambiente virtual, instalar as peças e ligar a API, e o que devo ver no terminal. Peça minha permissão antes de rodar qualquer comando.

1. Cole o pedido. O assistente cria a pasta api e os arquivos.
2. Ele vai pedir permissão para rodar comandos (criar o ambiente, instalar as peças, ligar a API). Leia cada um e aceite se entender.
3. A API fica rodando no terminal. Não feche esse terminal. Para parar: Ctrl + C.

A triagem faz o laudo. Ela usa o grafo: a memória da oficina, que liga aparelho → sintoma → causa → peça.

Pedido da triagem com o grafo

Agora crie a triagem com um grafo de conhecimento, em Python simples, que funcione SEM internet e SEM chave.

O grafo liga aparelho, sintoma, causa e peça. Use exatamente estes sete casos:
1. Dell G15 | desliga sozinho | pasta térmica de fábrica ressecada e aletas obstruídas | Pasta Térmica Alta Condutividade, Thermal Pads
2. Dell G15 | não liga | curto no circuito de carga (MOSFET de entrada) | MOSFET Canal N 30V, Carregador 130W
3. Acer Nitro 5 | tela azul | oxidação nos contatos da memória RAM | Limpa Contato Isopropílico, Memória DDR4
4. Acer Nitro 5 | tela preta | cabo flat da tela rompido ou solto na dobradiça | Cabo Flat EDP Nitro 5
5. MacBook Air | bateria não carrega | ciclos da bateria esgotados ou conector oxidado | Bateria Original A1466
6. Desktop | reinicia em jogos | fonte genérica sem potência suficiente | Fonte ATX 600W 80 Plus
7. Notebook | lentidão extrema | HD mecânico antigo com setores ruins | SSD NVMe 500GB ou SATA

Depois que um chamado é criado, faça o laudo em segundo plano: procure o aparelho e as palavras do relato no grafo.
- Se achar um caso: prioridade "alta" quando o relato tiver "não liga" ou "desliga", senão "media". Use a causa e as peças do caso.
- Se não achar: prioridade "media" e causa "necessário teste detalhado na bancada".
Guarde a prioridade e o laudo no chamado.

Crie também testes automáticos com pytest e me diga como rodar.

Teste no site

1. Com a API ligada, abra o index.html do site.
2. Preencha um chamado: equipamento Dell G15, relato "Esquenta muito e desliga sozinho quando eu jogo".
3. Clique em Enviar chamado e anote o número.
4. Em Acompanhar, digite o número e consulte.

A automação é um segundo robô, de reserva. Ele procura chamados que ficaram sem laudo e completa.

Para que serve

Imagine um funcionário que, de tempos em tempos, olha a fila e pergunta: "tem chamado sem laudo?". Se tiver, faz o laudo. Se não tiver, avisa que está tudo em dia. É um programa que repete uma verificação, sem ninguém mandar. Esse tipo de programa se chama laço (loop).

Pedido da automação

Crie a automação em Python, um programa separado, de reserva.
A cada 5 segundos ela procura chamados SEM laudo e preenche o laudo usando a mesma triagem com grafo. Se não houver nenhum, escreve "Nenhum chamado pendente no momento". Deve parar com Ctrl + C.
Explique como ligar, em um terminal separado.

1. Cole o pedido e aceite o que fizer sentido.
2. Ligue a automação num segundo terminal, como o assistente explicar. Deixe a API ligada no primeiro.

Veja a automação trabalhando

1. Deixe a automação ligada.
2. No site, abra um chamado novo.
3. Olhe o terminal da automação. Se a API já fez o laudo, ela continua dizendo que não há pendentes. É o esperado.

O CrewAI junta dois agentes de IA: um atendente e um técnico. Este passo é opcional. Ele roda no Google Colab, um caderno de código na nuvem do Google. Você não instala nada no seu computador.

Entenda a ideia antes de começar

Pense numa oficina de verdade. O cliente chega e conta o problema. O atendente ouve e decide a urgência. Depois o técnico pega essa informação e diz o que fazer. O CrewAI faz o mesmo com duas IAs.

A ordem aqui é em sequência (sequential): primeiro o atendente, depois o técnico, que recebe o resultado do atendente.

A) Abrir o Colab

1. Abra colab.research.google.com e entre com a sua conta Google.
2. Crie um novo notebook e dê o nome agente-crewai.

B) Pegar a chave do Gemini

A chave do Gemini é uma senha que deixa o seu programa usar o Gemini. Ela se chama chave de API.

Onde encontrar:

1. Abra aistudio.google.com com a mesma conta Google.
2. No menu da esquerda, procure Chaves de API (API keys). Se não achar, procure um botão Get API key.
3. Clique em Criar chave de API (Create API key). Se pedir um projeto, escolha o que aparecer.
4. A chave é um texto longo. Copie e guarde num papel. Não cole no chat do assistente.

Pedido: onde acho a chave do Gemini

Preciso de uma chave de API do Gemini para usar no Google Colab. Explique, em passos curtos, onde eu encontro essa chave no Google AI Studio e como guardar nos Segredos do Colab. NÃO peça que eu cole a chave aqui no chat.

C) Guardar a chave nos Segredos do Colab

1. Na barra da esquerda do Colab, clique no ícone de chave (Secrets, ou Segredos).
2. Clique em Adicionar novo segredo.
3. No nome, escreva GEMINI_API_KEY. No valor, cole a chave.
4. Ative a opção de acesso do notebook a esse segredo.

D) Pedir o código ao Gemini

Pedido do agente CrewAI (para o Colab)

Crie o agente CrewAI para rodar no GOOGLE COLAB, e não no meu computador.

Dois agentes que trabalham em sequência (Process.sequential):
1) "Atendente de triagem de uma oficina de informática". Objetivo: entender o relato do cliente e dizer a urgência (alta, média ou baixa). Dê a ele uma backstory curta: atende há anos, fala simples e não inventa nada.
2) "Técnico de bancada". Objetivo: sugerir a causa provável e 3 próximos passos. Ele recebe o resultado do atendente.

Duas tarefas, uma para cada agente, cada uma com description e expected_output claros:
- Tarefa do atendente: saída em 2 linhas, "Urgência: ..." e "Motivo: ...".
- Tarefa do técnico: saída "Causa provável: ..." e uma lista de 3 passos curtos.
O relato entra como variável {relato} no kickoff(inputs=...).

Use o Gemini como modelo, com a classe LLM do CrewAI. Confirme qual é o nome de modelo Gemini válido hoje e me diga qual escolheu. Instale com !pip install "crewai[google-genai]".
A chave vem dos Segredos do Colab:
from google.colab import userdata
userdata.get("GEMINI_API_KEY")
NUNCA escreva a chave no código nem a mostre na saída.

Escreva o código em células curtas e numeradas:
1) instalar
2) ler a chave dos Segredos e criar o modelo
3) criar os dois agentes
4) criar as duas tarefas e a equipe
5) rodar com o relato "Dell G15 esquenta muito e desliga sozinho quando eu jogo" e mostrar o laudo com print(resultado.raw)

Explique cada célula em uma frase. Diga quanto tempo a instalação pode levar e o que fazer se o Colab pedir para reiniciar a sessão.

1. Cole o pedido no painel do assistente do Antigravity. Se o Colab mostrar o ícone do Gemini no rodapé do notebook, você também pode pedir lá.
2. Copie uma célula de cada vez para o Colab (botão + Código).

E) Rodar no Colab

1. Clique no botão de play de cada célula, na ordem.
2. A instalação pode levar alguns minutos. Espere terminar.
3. Se o Colab pedir para reiniciar a sessão, aceite e rode de novo a partir da célula 2.

O laudo aparece na saída da última célula. Deve ter as linhas Urgência e Motivo, e depois Causa provável e os 3 passos. O texto muda um pouco a cada vez: a IA não responde sempre igual.

Entenda o código que o Gemini escreveu

Abaixo está um modelo para você comparar com o seu. O seu pode ter nomes diferentes e estar certo. Confira se as mesmas peças aparecem.

#  Célula 1: instalar (leva alguns minutos)
!pip install -q "crewai[google-genai]"

#  Célula 2: ler a chave dos Segredos e criar o modelo
from google.colab import userdata
from crewai import Agent, Task, Crew, Process, LLM
llm = LLM(model="gemini/gemini-3.6-flash",
          api_key=userdata.get("GEMINI_API_KEY"))

#  Célula 3: os dois agentes
atendente = Agent(
    role="Atendente de triagem de uma oficina de informática",
    goal="Entender o relato do cliente e dizer a urgência: alta, média ou baixa",
    backstory="Você atende clientes há anos, fala simples e não inventa informação.",
    llm=llm)
tecnico = Agent(
    role="Técnico de bancada",
    goal="Sugerir a causa provável e os próximos passos",
    backstory="Você conserta notebooks há 10 anos e explica de forma direta.",
    llm=llm)

#  Célula 4: as duas tarefas e a equipe
t1 = Task(
    description="Leia o relato: {relato}. Diga a urgência e explique em uma frase.",
    expected_output="Duas linhas: 'Urgência: ...' e 'Motivo: ...'",
    agent=atendente)
t2 = Task(
    description="Com a urgência já definida, sugira a causa provável e 3 passos para: {relato}",
    expected_output="'Causa provável: ...' e uma lista de 3 passos curtos.",
    agent=tecnico, context=[t1])
equipe = Crew(agents=[atendente, tecnico], tasks=[t1, t2],
              process=Process.sequential)

#  Célula 5: rodar
resultado = equipe.kickoff(inputs={"relato":
    "Dell G15 esquenta muito e desliga sozinho quando eu jogo"})
print(resultado.raw)

Experimente mudar

Mudar uma coisa e ver o resultado é o melhor jeito de aprender. Faça uma de cada vez e rode de novo as células 4 e 5.

1. Troque o relato. Por exemplo: "Acer Nitro 5 com tela azul". O laudo muda?
2. Mude a backstory do técnico. Escreva "Você é muito caprichoso e sempre avisa o preço do conserto". O texto mudou?
3. Mude a saída esperada. Peça "uma lista de 5 passos". A resposta obedeceu?
4. Peça ao Gemini: "Por que o técnico respondeu isso? Explique em palavras simples."

Pergunta para o seu áudio de comprovante: o que mudou quando eu mudei a backstory?

Se algo der errado no Colab

O que o CrewAI faz além disso

O CrewAI é muito maior que este exercício. Você não precisa usar estas partes agora. Só saiba que existem:

Quer saber mais? A documentação oficial está em docs.crewai.com. É em inglês. Peça ao Gemini para explicar em português simples.

F) Guardar o notebook na sua pasta

No Colab: Arquivo → Fazer download → .ipynb. Coloque o arquivo na pasta oficina-digital. Assim ele vai junto para o GitHub no final.

O bot manda os chamados para o seu celular e aceita comandos. Esta parte também é opcional. Aqui você usa duas informações secretas: o token do bot e o seu Id.

Entenda como funciona

O Telegram é um aplicativo de mensagens. Um bot é uma conta controlada por programa, não por pessoa. O seu programa em Python conversa com o bot, e o bot conversa com o seu celular.

A) Criar o bot e achar o token

1. No Telegram, procure @BotFather (com selo azul de verificado). Envie /start.
2. Envie /newbot.
3. Digite o nome da oficina. Depois um usuário que termine em bot.
4. No fim, o BotFather manda uma mensagem com o token: um texto longo com números, dois pontos e letras. Esse é o token.
5. Abra a conversa com o seu bot e envie /start.

B) Achar o seu Id

O Id é um número que identifica a sua conversa. O bot só obedece a quem tem esse número.

1. No Telegram, procure @userinfobot e envie /start.
2. Ele responde com o seu Id (só números). Anote.

Pedido: mostrar o meu Id

Crie um programa pequeno em Python que mostra, na tela, o número do chat de quem mandar uma mensagem ao meu bot do Telegram. Leia o token do arquivo .env e NUNCA o escreva no código. Explique como rodar.

C) Pedir o código ao Gemini

Pedido do Telegram

Crie o aviso e os comandos do Telegram, sem biblioteca extra (use a API oficial por HTTP).
Quando chegar um chamado, avise o técnico com o laudo.
Aceite só comandos do chat do técnico: /abertos (lista a fila), /ver N (mostra o laudo), /andamento N e /concluir N.

O token do bot e o número do chat devem vir de um arquivo .env (use python-dotenv), NUNCA escritos no código.
Crie também um arquivo .env.example com os NOMES das variáveis e sem valores, e coloque .env no .gitignore.
No fim, me diga os nomes das variáveis que você escolheu e em qual pasta o arquivo .env deve ficar.
Se as variáveis faltarem, só escreva o aviso na tela e continue funcionando.
Explique como testar no meu computador, sem endereço público (buscando as mensagens do bot).

D) Guardar o token e o Id no arquivo .env

As informações secretas ficam num arquivo chamado .env, na pasta indicada pelo assistente. Você mesmo escreve os valores, no editor do Antigravity. Nunca no chat.

1. Na pasta do Antigravity, abra o arquivo .env.example que o assistente criou. Ele mostra os nomes, sem valores.
2. Crie um arquivo novo chamado .env na mesma pasta (se não souber, peça: "Crie um arquivo .env vazio na pasta certa").
3. Escreva uma linha para cada nome, com o valor logo depois do sinal de igual, sem espaços e sem aspas. Exemplo com valores falsos:

   TELEGRAM_TOKEN=123456789:valor-do-seu-token
   TELEGRAM_CHAT_ID=123456789

   Copiar exemplo
4. Troque os valores falsos pelos seus. Salve com Ctrl + S.
5. Abra o arquivo .gitignore e confira que existe uma linha escrita .env. Assim o arquivo não vai para o GitHub.

Veja mais no Guia das chaves.

Como o programa recebe as mensagens

O pedido manda "buscar as mensagens do bot". Isso quer dizer que o seu programa pergunta ao Telegram, de tempos em tempos, se chegou algo novo (getUpdates). Assim você não precisa de endereço público na internet. Só funciona enquanto o programa estiver ligado no seu computador.

E) Testar no celular

Ordem sugerida: ligue a API e o programa do Telegram, abra um chamado no site e veja o aviso chegar no celular. Depois teste cada comando.

Hora do teste de ponta a ponta. Confira cada item:

1. A API está ligada (terminal mostra Uvicorn running).
2. No site, você abre um chamado e recebe o número.
3. O laudo aparece em Acompanhar, com prioridade e causa.
4. Os testes passam (peça ao assistente: "Rode os testes e me diga o resultado.").
5. Se fez o Telegram: o aviso chega no celular e os comandos funcionam.

Teste de ponta a ponta, na ordem

1. Ligue a API (terminal 1).
2. Abra o site: dois cliques em index.html.
3. Preencha um chamado com o relato "Dell G15 desliga sozinho quando jogo".
4. Anote o número. Em Acompanhar, digite o número e veja o laudo.
5. Prioridade alta e causa pasta térmica? A triagem funcionou.
6. Teste um relato que o grafo não conhece. O laudo deve dizer "necessário teste detalhado na bancada".
7. Desligue a API e envie de novo. O site deve mostrar o aviso de API desligada.
8. Se fez o Telegram, o aviso deve chegar no celular.

Antes de levar ao GitHub

• Nenhum arquivo tem chave ou token escrito.
• O arquivo .gitignore tem as linhas .env e .venv.
• O notebook do Colab não mostra a chave na saída das células.