Guia

Usar com IA

Se você usa um assistente de IA para analisar dados, dê a ele esta documentação em vez de deixá-lo adivinhar: as 54 coleções campo a campo, a sintaxe das consultas e — o que mais importa — as regras de modelagem que fazem a diferença entre um número certo e um número plausível.

Há dois caminhos, e eles não competem:

Caminho	Quando usar
Colar o endereço	Qualquer ferramenta que abra links. Nada para instalar, e sempre na versão de hoje
Instalar a skill	Assistentes que suportam skills. Entra sozinha no assunto e traz um cliente de linha de comando junto

Por que não colar a documentação no chat

Os dois formatos são gerados do mesmo contrato que gera este site, então não inventam campo e não envelhecem junto com uma página que alguém copiou mês passado. E carregam as armadilhas de dupla contagem, que são justamente o que um assistente sem contexto erra com confiança.

Colar o endereço

Peça ao assistente para ler /llms.txt — o índice, com uma linha sobre cada coleção e o link de cada guia. Ele busca só o que a sua pergunta pede.

text

Leia https://docs.agrosti.com.br/llms.txt e depois
me ajude a montar um relatório de custo por talhão da safra 2025.

Se a ferramenta não seguir links, use /llms-full.txt: é tudo num arquivo só — os guias e as 54 coleções campo a campo. É grande de propósito; em ferramenta com limite de contexto apertado, prefira o índice.

Instalar a skill

A skill é a mesma documentação empacotada para o assistente carregar sozinho quando o assunto for AGROs — sem você precisar lembrar de colar nada. Traz junto um cliente de linha de comando que já resolve paginação e limite de requisições.

bash

# Claude Code: descompacte na pasta de skills do projeto
unzip openagros.skill -d .claude/skills/

# para valer em todos os projetos
unzip openagros.skill -d ~/.claude/skills/

O pacote também está aqui: openagros.skill — um zip com a pasta da skill dentro. Em outros clientes, procure onde eles leem skills e descompacte lá; o formato é o padrão, uma pasta com SKILL.md na raiz.

Dar o token

Nem a skill nem os arquivos de texto trazem credencial nenhuma. Exporte o seu token em OPENAGROS_TOKEN antes de abrir o assistente — assim ele nunca precisa que você cole o token numa conversa. Se ainda não tem um, veja Autenticação.

Usar

A partir daí é conversa normal:

text

Puxe do AGROs a colheita da safra 2025 por fazenda
e me diga a produtividade em kg/ha de cada uma.

E o cliente de linha de comando que vem na skill funciona sozinho, sem assistente nenhum:

bash

export OPENAGROS_TOKEN=oag_...
python .claude/skills/openagros/scripts/consultar.py Harvest \
  --filter "season eq '2025'" \
  --select id,date,farm,grossWeightKg \
  --csv colheita.csv

O que eles sabem

As 54 coleções, campo a campo: tipo, o que aceita filtro, o que aceita ordenação e o que cada campo significa.
Oito receitas de ponta a ponta — produtividade, custo por talhão, colheita por unidade, produção por pessoa, contas a pagar, carga incremental — com a consulta pronta e a armadilha de cada uma, conferidas contra uma base real.
As regras de modelagem de Como modelar sem errar — custo que se repete por talhão, colheita contada duas vezes, unidades que não somam entre si, área que só vem da dimensão.
Power BI: o conector certo, a autenticação que funciona, os relacionamentos e o que não pode ser somado.
Os erros da API e o que fazer com cada um.

Eles leem, não escrevem

A API é somente leitura, e o que você instala aqui também: consulta os seus dados e monta relatórios. Nada do que o assistente fizer altera qualquer coisa no AGROs.