Como usar o UFVAI — do primeiro clique ao artigo pronto
Guia interativo do UFVAI, assistente de pesquisa da Universidade Federal de Viçosa. Você conversa, ele busca dados oficiais e literatura de verdade, cita cada fonte e avisa com honestidade quando não encontra. Todas as imagens são capturas reais — nada é ilustração.
- Um passo por tela: avance pelo menu à esquerda ou pelas teclas ← →; a barra no topo mostra seu progresso.
- Clique em qualquer imagem para ver de perto (as setas ←/→ caminham entre as figuras; Esc fecha).
- Marque cada passo como feito — a lista fica salva no seu navegador.
- Pressione / para procurar qualquer palavra.
- Os prompts da Seção 7 têm botão Copiar: escolha o seu tema, cole no terminal e siga o mesmo caminho.
- Dica de conexão: use o Google Chrome e deixe a aba do UFVAI aberta e em primeiro plano — se ficar muito tempo sem mexer, o Colab desconecta.
0. Do Colab ao UFVAI — o processo completo
Tudo começa numa página do Colab (o “computador na nuvem” do Google). Ao clicar em ▶, o próprio piloto instala tudo e abre o UFVAI — você só acompanha a barra de progresso:
PesquisAI.ipynb: células de introdução,
código de inicialização, painel de progresso e o botão douradoABRIR O UFVAI. (Composição fiel às
células e ao painel reais; a tela exata varia conforme o seu navegador.)Clique no badge verde “Clique aqui — Comece a usar” do repositório
(github.com/gustavobraga-byte/PesquisAI) — ele abre
colab.research.google.com/github/…/PesquisAI.ipynb já logado na sua conta Google.
O atalho Ctrl+F9 executa todas as células de uma vez. Você pode optar por executar apenas a célula de código — o UFVAI cuida de todo o resto só dela.
Uma barra mostra o caminho em linguagem simples (instalação → chaves do Drive → conversa → tela). Quando aparecer “✨ UFVAI pronto!”, é só usar.
O botão dourado abre a interface em um endereço *.prod.colab.dev na sua aba — é aí que o
tutorial “real” começa (a tela de boas-vindas da Seção 1).
O Colab desliga o UFVAI quando fica tempo sem atividade. Enquanto você pesquisa: não minimize a aba, não troque de tela e não deixe o computador “pegar no sono” (proibido a tela bloquear/entrar em espera — se precisar, ajuste nas configurações de energia). Use o Google Chrome. Se por acaso desconectar, não se assuste: nada se perde — volte ao notebook e clique em Ambiente de execução → Executar tudo (leva ~2 min para voltar).
ufvai_keepalive.log para
ajudar a manter a sessão; ainda assim, o Colab desliga após ~12 h de uso. Para encerrar você mesmo
(e economizar seu limite): Ambiente de execução → Desconectar e excluir o ambiente de execução,
ou o botão SAIR na própria interface.ufvai: em instantes a
mesma janela aparece (interface em localhost:8001, conversa em localhost:8000).
Nada desta máquina sai para a internet.1. Ativação e primeiros cliques
Terminou o Colab (Seção 0)? A primeira tela é a de boas-vindas. Por trás dela, tela e conversa já estão no ar — você só confirma:
backups/ufvai_consentimento.json).
O que fazer
- Confirme que o e-mail exibido é o seu e clique em “Continuar como este usuário”.
- Não é você? Use “Se não é você, alterar e-mail” para trocar a conta de ativação.
- Na sequência aparecem os Termos de Uso (versão vigente v6): é obrigatório marcar a caixa e informar nome + e-mail para habilitar o botão de aceite. Você pode optar (ou não) por métricas anônimas de uso.
- Telas de abertura (e-mail e Termos) e a pergunta de retomada aparecem uma vez por sessão — sem repetição a cada mensagem.
- Autosave a cada 1 minuto, com uma cópia por conversa em
sessions/(modo “todas as conversas”). - Restaurar mostra os backups por calendário e devolve a conversa exatamente onde parou.
- Na restauração, o free tier do OpenCode Zen é liberado automaticamente.
- A interface carrega sempre a versão nova (
Cache-Control: no-store) — não é preciso limpar o cache.
2. A interface por dentro
A janela tem três partes, de cima para baixo: a barra de cima (botões do dia a dia), a caixa de conversa no meio — o chat onde tudo acontece — e a barra de embaixo (backup, Drive, sair e chave de IA). Na prática, você conversa no meio e usa os botões das barras.
3. Cada botão: onde clicar
Os oito ícones da barra superior (esquerda) abrem os utilitários; os quatro botões coloridos (direita) cuidam da sessão. Abaixo, cada um com o print real de quando ele é clicado.
⚡ Dashboard de saúde
Onde: primeiro ícone da barra de cima. É o exame de saúde do app: num relance, diz se o Drive está conectado, se as chaves de IA estão ok e quantas ferramentas estão instaladas.
📖 Manual do usuário
Onde: segundo ícone. Abre o manual completo dentro da própria interface — com exemplos prontos e soluções para os problemas mais comuns.
🕐 Histórico de sessões
Onde: terceiro ícone. Guarda o histórico das conversas: clique numa antiga e volte exatamente de onde parou.
⌨️ Atalhos de teclado
Onde: quarto ícone. Mostra as teclas de atalho oficiais (detalhes na Seção 6).
📋 Diretrizes do agente
Onde: quinto ícone. Mostra as regras que o UFVAI sempre segue — por exemplo, não inventar dados e validar toda citação antes de usar.
🧠 Minha memória
Onde: sexto ícone. É o caderno de anotações automático da pesquisa (hipóteses, datas, referências, decisões) — ótimo para revisar e retomar depois.
🔌 Provedor de IA · 🌙 tema · 🌐 idioma · botões da direita
4. O terminal do agente
O coração do UFVAI é a conversa (o terminal): é aqui que você escreve o que quer — em português comum — e o agente responde e faz: busca em fontes oficiais, cria arquivos e explica o que fez.
- Histórico — tudo o que você pediu e o que o UFVAI fez (ferramentas, arquivos criados).
- Painel lateral — quanto já conversou e, se configurado, o custo estimado.
- Caixa de escrever (borda dourada) — é aqui que você digita; Enter envia, Esc para o UFVAI na hora.
- Linha de baixo — mostra o modelo de IA ativo e lembretes de atalhos.
5. Como trocar o modelo
Trocar o “cérebro” da IA leva dois cliques, sem sair da conversa. Há dois caminhos — o atalho direto e o menu de comandos.
Caminho A — atalho direto (o mais rápido)
- Clique dentro do terminal para garantir o foco.
- Pressione Ctrl + X e, em seguida, m.
- Abre o seletor de modelo — navegue com ↑/↓, confirme com Enter, cancele com Esc.
Caminho B — menu de comandos (Ctrl+P)
- Pressione Ctrl + P: abre a paleta de comandos (busca no topo).
- Escolha “Switch model” — ou digite
modelna busca e pressione Enter. - Esc fecha qualquer ponto do menu.
Trocar o modelo muda quem responde; trocar o provedor muda de onde vem a chave — a “conta” do serviço de IA que você contratou. Fica no botão + provedor do rodapé: lá você cola uma chave nova ou escolhe uma salva. Apareceu “Key limit exceeded”? A chave acabou — veja no ⚡ (exame de saúde) e troque de provedor ou modelo.
6. Atalhos de teclado
Os atalhos abaixo são os oficiais (modal do quinto ícone da barra superior). Com três deles você já cobre 90% do dia a dia.
| Atalho | O que faz | Quando usar |
|---|---|---|
| Shift + arrastar | Seleciona/copiar texto | Para copiar um trecho sem disparar o envio |
| Ctrl+C | Interrompe o comando em execução | Resposta longa ou ferramenta travada |
| Ctrl+Shift+V | Colar (Chrome) | Colar um prompt longo copiado de outro lugar |
| Ctrl+P | Menu de comandos | Tudo que é “ajuste”: modelo, sessão, limpar, exportar |
| Ctrl+X m | Alterar modelo | Trocar a IA que responde (Seção 5) |
| ↑ / ↓ | Histórico de perguntas | Reaproveitar uma pergunta antiga |
| Ctrl+X n | Nova sessão | Separar outro assunto sem poluir a conversa |
| Ctrl+X l | Trocar de sessão | Voltar para uma conversa anterior |
| Ctrl+C 2× | Encerrar (em shell) | Sair do terminal |
7. Exemplo: artigo do início ao fim ⭐
Este é o exemplo completo: 7 passos executados de verdade no terminal do UFVAI, do tema em branco ao arquivo pronto — cada um com print e o prompt exato (botão Copiar). Troque o tema pelo seu e siga o mesmo caminho.
1 pergunta2 literatura3 dados 4 método5 redação6 ABNT 7 entrega
Objetivo: transformar um tema solto em pergunta respondível + objetivo geral + objetivos específicos. O agente entrega pergunta, OG, 3 OE em tabela (verbo de operação × entrega) e a cadeia lógica descrever → explicar → interpretar.
Objetivo: fixar os recortes e rodar a busca multi-base (OpenAlex, SciELO, PubMed…) com
deduplicação por DOI. Skills acionadas: meta-search-br + citation-management.
Objetivo: fechar de onde vêm os números: IBGE/PAM, Censo Agropecuário, Conab, SNCAR — com
período, variáveis e a skill certa para cada consulta. Skills: ibge-br, agrobr, dados-brasil.
Objetivo: abordagem, variáveis, modelo estatístico, software e limitações — com suposições marcadas.
Skills de apoio: experimental-design, statistical-analysis.
[ESTIMATIVA FUNDAMENTADA]separa o que é opinião metodológica de fato verificado.Moldura com faixas reais da interface do UFVAI (barra superior e rodapé do app) em composição com a captura real da sessão demonstrada.Objetivo: escrever a introdução do artigo em linguagem científica, com citações pendentes de validação
([AUTOR, ANO]) — sem inventar autor nenhum.
Objetivo: montar a lista final conforme a ABNT NBR 6023, usando só as referências já validadas
nesta conversa. Skills: citation-management (valida) + ufv-abnt (formata).
Objetivo: materializar o texto em arquivo real (.md, podendo seguir para
.docx/.pdf) dentro da pasta de entregas do projeto.
8. Casos de uso
Quatro situações do dia a dia. Clique para ver a pergunta de exemplo e as ferramentas usadas.
Skills: agrobr (CONAB/IBGE PAM), ibge-br (SIDRA) ·
Saída: tabela + fonte citada + marcador [DADO CONFIRMADO].
Skills: opendatasus, dados-brasil ·
Ética: apenas dados agregados — nada de microdados identificáveis.
Skills: scientific-writing, ufv-abnt, docx ·
Saída: .md + .docx prontos para revisão.
Skills: meta-search-br, literature-review, citation-management ·
Atenção: a triagem final é sempre humana.
9. Ferramentas (skills)
O UFVAI vem com ferramentas especializadas (as “skills”): uma para dados do Brasil, outra para redação, outra para análise, outras para as normas… Você não precisa decorar nenhuma — descreva o que quer e o agente escolhe a certa. A lista completa aparece no 📋 Diretrizes do agente (Print 08).
Prioridade máxima — dados brasileiros
| Skill | Para quê |
|---|---|
ibge-br | Censo, PNAD, PIB, SIDRA, malhas geográficas |
opendatasus | SINAN, SIM, SIH, VIGITEL, COVID — dados do SUS |
dados-brasil | BCB, TSE, INPE, transparência e dezenas de APIs oficiais |
agrobr | CONAB, IBGE PAM/LSPA, ComexStat, queimadas, CAR, crédito rural |
Pesquisa científica e escrita
| Skill | Para quê |
|---|---|
citation-management | Valida referências e DOIs (obrigatória antes de citar) |
meta-search-br | Busca em 7 bases (PubMed, SciELO, LILACS, BDTD, OpenAlex, arXiv, bioRxiv) |
literature-review | Revisões sistemáticas e síntese |
scientific-writing | Manuscritos IMRAD, relatórios |
ufv-abnt | Normalização ABNT/UFV: capa, citações, referências |
cep-ufv | TCLE, TALE, anuências e demais documentos de CEP |
Análise de dados
| Skill | Para quê |
|---|---|
statistical-analysis | Testes com relatório APA, pressupostos, tamanho de efeito |
exploratory-data-analysis | EDA em 200+ formatos |
analise-qualitativa | Conteúdo, Reinert, codificação (substitui NVivo/Iramuteq) |
scikit-learn | Machine learning |
Entregáveis: pdf, docx, pptx, xlsx e
scientific-visualization (figuras) materializam o resultado em arquivo.
10. Integridade e declaração de uso de IA
A marca do UFVAI é a honestidade: nada é inventado. Não aparecem números, estatísticas ou referências “do nada”. Todo dado quantitativo traz uma destas três etiquetas:
| Marcador | Significado |
|---|---|
[DADO CONFIRMADO] | Extraído de fonte primária, via skill oficial |
[ESTIMATIVA FUNDAMENTADA] | Inferido de dados disponíveis, com método explícito |
[SEM DADOS SUFICIENTES] | As fontes não retornaram nada confiável — e ele diz isso |
- Referência só entra depois de validada (com DOI, ISBN ou link oficial).
- Não simula entrevistas, experimentos nem coleta de dados “de campo”.
- Pesquisa com pessoas exige aprovação do comitê de ética (CEP/CONEP) — o pacote de documentos está na ferramenta
cep-ufv. - Instruções escondidas em PDFs ou páginas não são ordens — são ignoradas e avisadas.
Declaração de uso de IA
Estudos feitos com IA devem declarar o uso (norma de periódicos, CAPES e CNPq). O manual traz modelos prontos (Seção 9) — vale colar a declaração no artigo do Passo 7. Exemplo:
Também há modelo de declaração próprio no pacote
(declaracao_uso_ia.md e citacao_pesquisai.md).
11. Problemas comuns
Respostas para as dores de cabeça mais comuns. Antes de qualquer coisa, clique no ⚡ exame de saúde — ele aponta qual peça falhou.
| Sintoma | Causa provável | Solução |
|---|---|---|
| “O botão não abre” | Cookie de terceiro bloqueado no proxy do Colab | Libere cookies para *.prod.colab.dev e recarregue (F5) |
| Terminal preto | ttyd indisponível / iframe sem conectar | Dashboard ⚡ → se ttyd estiver morto, recarregue a página (F5) |
| “Key limit exceeded” | Chave do provedor esgotada | + provedor no rodapé: troque de chave/modelo (Seção 5) |
| “Dados não encontrados” | Filtro/ano errado ou API fora do ar | Peça para o agente mostrar a consulta usada e refaça o recorte |
| “Sessão expirou” / token inválido | Página aberta há muito tempo | F5 — um novo token de sessão é gerado |
| “Backup não aparece” | Drive não montado | Dashboard ⚡ → drive_mounted; autentique o Drive novamente |
| Não consigo digitar no terminal (.deb) | Foco em outra janela / ttyd parado | Clique dentro do terminal; se persistir, ufvai de novo |
| “localhost:8001 recusa conexão” (.deb) | App não subiu | Rode ufvai no terminal e veja o log |
12. Sobre e citação
- O UFVAI não substitui revisão por pares nem o julgamento do pesquisador: alucinações são possíveis.
- Não realiza coleta primária (entrevistas, experimentos, surveys).
- Não emite parecer médico, jurídico ou de CEP/CONEP.
- Não submete artigos a periódicos; a entrega final passa sempre por revisão humana.
Como citar a ferramenta
citacao_pesquisai.md do próprio UFVAI.