Pesquisa é um Processo Iterativo

Pesquisa é uma investigação sistemática para descrever, explicar, prever e controlar o fenômeno observado. (Babbie 2015)

• Um projeto de pesquisa envolve milhares de pequenas decisões: código, dados, escrita, referências bibliográficas.
• A maior parte do tempo não é gasta pensando, mas sim em trabalho mecânico:
  • limpeza de dados, depuração de scripts, formatação de tabelas, resolução de erros.
• A IA Agêntica atua exatamente nessa camada mecânica, permitindo que você dedique mais tempo à reflexão e à análise crítica.

Por Que IA “Agêntica”?

O Que É um Grande Modelo de Linguagem (LLM)?

Um LLM é um motor de raciocínio e linguagem — não uma base de dados e muito menos uma fonte absoluta da verdade.

• Uma rede neural treinada para prever o próximo token a partir de volumes massivos de texto. (Vaswani et al. 2017)
• Seu conhecimento fica congelado na data de corte do treinamento.
• Por si só, não possui acesso aos seus arquivos locais, aos seus dados ou à internet em tempo real.
• É extremamente competente com linguagem e padrões, e muito convincente ao soar confiante mesmo quando está errado. (Bender et al. 2021)

Chatbot vs. Agente

Chatbot vs. Agente: O Fluxo

O Ciclo do Agente, Visualizado

Níveis de Autonomia

Comece no nível que você consegue supervisionar. A autonomia deve ser conquistada com base na confiabilidade.

• Sugestão (Suggestion) — sugestões no estilo autocompletar.
• Chat — respostas conversacionais às suas perguntas.
• Uso de ferramentas (Tool use) — o modelo invoca ferramentas (arquivos, código, buscas). (Schick et al. 2023)
• Autonomia supervisionada — tarefas em múltiplas etapas com sua aprovação a cada passo.
• Autonomia total — execução de ponta a ponta. Poderosa, mas arriscada: use em ambiente isolado (sandbox). (Lu et al. 2024)

O Que Agentes Realmente Podem Fazer com comprovada eficácia

Sistemas Multiagente (a fronteira)

• Múltiplos agentes especializados colaboram entre si: um planejador, um programador, um revisor. (Wu et al. 2024)
• Úteis para tarefas complexas, mas mais difíceis de supervisionar e reproduzir.
• Para pesquisa científica, um único agente bem instruído costuma ser o melhor ponto de partida.
• A pesquisa sobre descoberta científica autônoma avança rápido — e levanta questões profundas sobre responsabilidade. (Lu et al. 2024)

A Caixa de Ferramentas de Pesquisa

Git — A Espinha Dorsal da Pesquisa Reprodutível

Se não está sob controle de versão, nunca aconteceu.

• Controle de versão para código, texto e pequenos conjuntos de dados.
• Registra quem alterou o quê, quando e por quê.
• Permite desfazer praticamente qualquer alteração e criar ramos (branches) para testar ideias arriscadas.
• Viabiliza a colaboração sem precisar enviar por e-mail analise_final_v3_REAL.zip.
• Hospedagem remota (GitHub/GitLab) oferece backup, visibilidade e portfólio acadêmico.

Git — Comandos Essenciais

# Iniciar um repositório
git init
git add .
git commit -m "Estrutura inicial do projeto"

# Inspecionar
git status
git log --oneline --graph
git diff                 # o que mudou desde o último commit

# Testar um experimento com segurança
git branch experimento-01
git checkout experimento-01
# ... trabalhar, depois mesclar (merge) ou descartar ...

# Fazer backup e colaborar
git remote add origin <url-do-repositorio>
git push -u origin main
git pull

Git — Ramificação = Experimentos Seguros

Ramificação no Git, Visualizada

Git — Proteja Seus Segredos e Dados

# .gitignore  -> arquivos que o Git NUNCA deve rastrear
.env
*_token.json
credentials/
data/raw/          # dados brutos volumosos ou confidenciais
_cache/
*.html             # saídas geradas automaticamente

• Nunca comite chaves de API, senhas ou dados pessoais/confidenciais.
• Se um segredo for enviado ao repositório remoto, considere-o comprometido: revogue e troque-o imediatamente.
• Mantenha os dados brutos imutáveis e fora do versionamento se forem volumosos ou sensíveis.

opencode — Seu Agente Dentro do Projeto

• Um agente de código aberto (open-source) que roda no terminal (TUI) e no desktop.
• Agnóstico quanto ao modelo: conecta-se a OpenAI, Anthropic, Google ou modelos locais (ex.: Ollama).
• Opera direto no repositório: lê código, edita arquivos, executa comandos.
• Mantém sessões que podem ser retomadas, com permissões explícitas para você aprovar ou rejeitar cada ação.
• Configurável via opencode.json, AGENTS.md, comandos personalizados, skills e plugins.

Em vez de copiar respostas de uma janela de chat, você colabora diretamente sobre os arquivos reais.

opencode — Principais Capacidades

Por Que o Agente Deve Ficar no Repositório?

• O contexto é o próprio projeto, e não um histórico solto de chat.
• Cada modificação fica visível no diff do Git, podendo ser revisada ou revertida.
• As diretrizes residem em um arquivo versionado, e não guardadas na sua memória.
• O fluxo de trabalho se torna reprodutível e auditável — pilar indispensável para a ciência.
• Mesmo repositório + mesmas instruções ⇒ comportamento da IA muito mais consistente.

Outras Ferramentas Relevantes

AGENTS.md — O README para Agentes

AGENTS.md é um arquivo Markdown simples e aberto que explica ao agente de código como o seu projeto funciona e como ele deve se comportar.

• Fica na raiz do repositório (assim como o README.md).
• É lido automaticamente pelo opencode e pela maioria das ferramentas modernas de agentes.
• Atua como um contrato entre você e o agente. agents.md
• Pense nele como o manual de integração para um novo colaborador — com a diferença de que esse colaborador é uma IA.

Por Que o AGENTS.md É Importante

Um bom AGENTS.md é a forma mais barata e eficaz de aumentar drasticamente a confiabilidade do agente.

• Contexto persistente: você não precisa reexplicar o projeto a cada nova sessão.
• Consistência: o agente segue as mesmas diretrizes em todas as execuções.
• Limites de segurança (guardrails): você define o que nunca deve ser alterado ou executado.
• Reprodutibilidade: as instruções da IA passam a fazer parte da rastreabilidade da pesquisa.
• Menos alucinações: o agente executa os comandos reais do projeto, em vez de inventá-los.
• Ativo para a equipe: documenta a dinâmica do projeto também para colaboradores humanos.

O Que Incluir no AGENTS.md

Exemplo de AGENTS.md (Projeto de Pesquisa)

# AGENTS.md

## Projeto
Estudo empírico sobre X. Dados brutos em `data/raw` (somente leitura),
código em `R/`, resultados em `output/`.

## Comandos
- Restaurar ambiente: `Rscript -e 'renv::restore()'`
- Rodar análise completa: `Rscript R/01_run_all.R`
- Gerar o relatório:   `quarto render report.qmd`

## Convenções
- Linguagem: R (tidyverse). Indentação de 2 espaços, nomes em snake_case.
- Nunca modificar arquivos em `data/raw/`.
- Todas as figuras devem ser salvas em `output/figs/`.
- Todo script deve rodar de ponta a ponta sem etapas manuais.

## Regras
- NÃO comite segredos (`.env`, `*_token.json`).
- NÃO invente dados, resultados ou citações bibliográficas.
- Peça autorização antes de excluir qualquer arquivo.
- Após qualquer alteração, execute `Rscript R/01_run_all.R` e relate eventuais erros.

O Fluxo de Trabalho de Ponta a Ponta

Exemplos de Tarefas para o Agente

• “Resuma este repositório: objetivo principal, pontos de entrada e como executá-lo.”
• “Refatore este script longo em funções modulares e adicione testes.”
• “Escreva um relatório em Quarto reproduzindo a Tabela 2 a partir de data/processed/panel.parquet.”
• “Explique este erro e proponha uma correção — não altere nenhum arquivo por enquanto.”
• “Converta estes 200 PDFs extraídos via web scraping em um dataframe estruturado.”
• “Elabore um rascunho de revisão bibliográfica com base nestes 30 PDFs e gere uma matriz de citações.”

Engenharia de Prompts para Pesquisa

• Forneça ao agente papel, contexto, objetivo, restrições, formato esperado e exemplos.
• Peça um plano antes de agir; avalie a estratégia antes de autorizar alterações nos arquivos.
• Disponibilize o esquema dos dados (schema) e uma amostra pequena, e não um arquivo bruto de 2 GB.
• Defina explicitamente idioma, estilo de escrita e formato de citação.
• Avance em pequenas etapas incrementais e valide cada uma delas.
• Peça ao agente que indique os arquivos e números de linha em que baseou suas respostas.

Padrões de Prompts (Prompt Patterns)

O Problema das Alucinações

Confie, mas verifique — e verifique novamente.

• LLMs inventam citações, DOIs, números de páginas — e, em alguns casos, até bases de dados.
• Uma resposta fluida, convincente e bem formulada não constitui evidência científica.
• Nunca cite uma referência bibliográfica que você não tenha aberto e lido.
• Verifique cada citação (DOI, Crossref, Google Scholar, o PDF de fato).
• Faça a checagem cruzada de cada valor numérico contra o código que o gerou.

Autoria, Declaração e Aspectos Legais

Armadilhas Comuns

• Aceitar código que você não executou nem leu criticamente.
• Permitir que o agente altere dados brutos ou exponha chaves e senhas.
• Citar referências inventadas (alucinações).
• Prompts vagos gerando saídas igualmente vagas e pouco úteis.
• Trabalhar sem controle de versão — perdendo a capacidade de reverter erros.
• Dependência excessiva e desqualificação técnica: você ainda precisa dominar os fundamentos.
• Inserir volumes massivos de contexto e dispersar o foco do agente.