Entregue a um agente de IA externo duas tarefas contábeis e mantenha cada alteração no livro-razão sob sua revisão: importe um CSV bancário com uma verificação prévia, depois responda a uma pergunta de saldo a partir de consulta e saída de relatório.
Instale bea com o início rápido da CLI. Comandos locais de importação, consulta e relatório não precisam de conta Beancount.io. Seu agente de chat precisa apenas de sua própria assinatura ou chave de API. Somente o auxiliar integrado bea ask precisa de credenciais hospedadas, e estas receitas não o utilizam.
O que o agente faz e o que o bea faz
O agente propõe categorias e redige consultas. O Bea valida a estrutura do livro-razão e calcula os totais. Você executa cada comando abaixo você mesmo. O agente nunca escreve diretamente em seu livro-razão.
Receita 1: importar um extrato com categorias propostas pelo agente
Transforme uma exportação bancária em lançamentos validados. O agente sugere as regras de categorização. A pré-visualização e a revisão de duplicatas decidem o que é gravado.
Pré-requisitos
Você precisa de bea e de um diretório de demonstração novo. Sem conta e sem importador Python.
Preparar as entradas
Crie o diretório e o livro-razão. Alvos explícitos com --file mantêm cada comando apontado para os livros de demonstração.
mkdir ai-agent-demo && cd ai-agent-demo
bea --no-input init books --currency USD --date 2026-08-01 --opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USDSalve esta amostra como statement.csv:
Date,Payee,Narration,Amount
2026-08-02,Whole Foods,compras de supermercado,-20.00
2026-08-03,Shell,combustível,-40.00
2026-08-04,Unknown Shop,desconhecido,-9.99Salve estas regras de categorização como rules.toml:
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"Copiar o prompt da tarefa
Cole este prompt ao seu agente externo junto com o conteúdo do CSV:
Proponha regras de categorização Beancount para minhas linhas de CSV bancário.
Sugira uma regra TOML por comerciante com um padrão de correspondência e uma
conta de despesa de destino. Nunca altere datas, beneficiários ou valores.
Deixe linhas que você não conseguir categorizar com confiança sem correspondência:
elas vão para Expenses:Uncategorized com a flag ! para minha revisão. Eu executo
bea import preview e apply localmente. Você não escreve meu livro-razão.Executar os equivalentes da CLI
Pré-visualize primeiro, depois aplique os lançamentos revisados e verifique o resultado:
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee,narration=Narration --account Assets:Checking --rules rules.toml
bea --file books/main.bean import statement.csv --apply
bea --file books/main.bean check
bea --file books/main.bean list transaction --flag '!'
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"Verificar a saída esperada
A pré-visualização relata 3 ready, 0 exact duplicates, 0 possible duplicates e sai com código 0. Ela não grava nada. A execução de apply relata Wrote 3 entries. A verificação não relata erros. A fila ! lista a única linha sem correspondência de Unknown Shop em -9.99 USD. A consulta de saldo relata 930.01 USD em checking. Repetir o apply relata 0 ready, 3 exact duplicates e grava 0 lançamentos.
Revisar e corrigir
Recategorize deliberadamente a linha ! em seu livro-razão após lê-la. Uma verificação aprovada apenas prova que o livro-razão equilibra. Ela não diz nada sobre se Expenses:Uncategorized é a conta correta. Para política de duplicatas, tratamento de conflitos e o caminho avançado em Python, siga o passo a passo de CSV bancário.
Receita 2: responder a uma pergunta de saldo sem gravações
Responda a uma pergunta a partir dos livros de demonstração: quanto foi gasto em compras de supermercado e combustível em agosto de 2026. O agente redige a consulta. Comandos somente leitura produzem a resposta.
Pré-requisitos
Você precisa do livro-razão de demonstração da receita 1 ou de seus próprios livros. Cada comando abaixo é somente leitura.
Copiar o prompt da tarefa
Cole este prompt ao seu agente externo:
Redija uma consulta Beancount (BQL) que responda: quanto gastei em
compras de supermercado e combustível em agosto de 2026. Use meus nomes
de conta exatamente como listados por bea list open. Proponha apenas
comandos somente leitura: bea query ou bea report com um alvo --file
explícito. Não proponha edições no livro-razão para corrigir um total
surpreendente. Um total surpreendente significa que a consulta ou os
livros precisam de revisão, não de um lançamento compensatório.Executar os equivalentes da CLI
Execute a consulta redigida contra um alvo de livro-razão explícito, depois faça a verificação cruzada com um relatório:
bea --file books/main.bean query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"
bea --file books/main.bean report income-statement --time 2026-08Consumidores de máquina adicionam a flag global --json antes do subcomando:
bea --file books/main.bean --json query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"Envelopes JSON, códigos de saída e posicionamento de flags globais seguem a referência da CLI. O guia da linguagem de consulta documenta toda a superfície BQL.
Verificar a saída esperada
A consulta relata 20.00 USD para Expenses:Groceries, 40.00 USD para Expenses:Transport:Fuel e 9.99 USD para Expenses:Uncategorized. Compras de supermercado mais combustível é 60.00 USD. A demonstração de resultados concorda: 69.99 USD de despesas de agosto com um lucro líquido de -69.99 USD. A variante JSON retorna as mesmas linhas dentro de data.rows com metadados de colunas em data.columns.
Revisar e corrigir
Uma consulta contra um nome de conta errado imprime (no rows) no stderr e ainda sai com código 0. Compare o nome com a saída de bea list open e execute a consulta novamente. Nunca corrija um total surpreendente editando o livro-razão para corresponder à resposta. Corrija a consulta ou corrija os livros e depois reexecute bea check.
Quando uma receita se torna um trabalho recorrente
Os prompts acima servem para tarefas pontuais dirigidas manualmente. Trabalhos que você repete semanalmente servem às habilidades versionadas no repositório do produto. Cada link abaixo abre o código-fonte atual da habilidade, que carrega suas próprias instruções de configuração e gatilho. Este CMS não mantém cópias desses arquivos.
- Inicie um novo livro-razão a partir de um diretório vazio com beancount-init. Ele cria o arquivo do livro-razão, um executor Fava e um projeto Python.
- Transforme uma exportação bancária em lançamentos categorizados com beancount-import. Ele prepara cada linha, sugere categorias a partir do histórico do livro-razão, pula linhas já importadas e grava apenas após confirmação. A receita 1 acima é a forma manual deste trabalho.
- Prove que uma conta corresponde ao seu extrato com beancount-reconcile. Ele compara o livro-razão com o extrato e estabelece uma afirmação de saldo de fim de período após confirmação.
- Responda a uma pergunta a partir dos livros com beancount-ask. Ele executa consultas somente leitura e mostra cada consulta ao lado de seu valor. A receita 2 acima é a forma manual deste trabalho.
- Encerre um mês com beancount-close. Ele reconcilia cada conta ativa, verifica lançamentos recorrentes e flags de revisão e registra o encerramento como um commit.
A coleção completa vive na árvore canônica de habilidades.
Dê bea a um agente com capacidade de shell ou carregue uma habilidade em um cliente
Estes são dois passos separados. Instalar bea nunca instala ou configura habilidades.
Um agente com capacidade de shell precisa do comando em seu caminho. Instale-o com o início rápido da CLI, depois o agente executa os mesmos comandos bea que as receitas mostram. O agente propõe, você revisa e bea valida.
Uma habilidade carrega no próprio cliente do agente, através do mecanismo de habilidade desse cliente. O repositório do produto expõe uma árvore canônica para ambos os clientes suportados: Claude Code a lê em .claude/skills e Codex em .agents/skills, como diretórios vinculados à mesma fonte. Aponte a localização de habilidades do cliente para a pasta de habilidade que você precisa e continue lendo seu código-fonte atual para frases de gatilho e atualizações.
Perguntas estilo ask sem bea ask
A receita 2 responde perguntas sobre o livro-razão com um agente externo mais comandos somente leitura bea query e bea report. Esse caminho é local. Ele não precisa de conta nem de instalação extra.
bea ask é um auxiliar integrado separado. Ele não é a receita acima nem a habilidade beancount-ask. Ele roteia a pergunta através do serviço de IA hospedado, então precisa do extra ask e de credenciais hospedadas, conforme documentado na referência da CLI. Instale a CLI base primeiro, depois adicione o extra apenas quando quiser respostas hospedadas.
Saídas citadas e verificação da CLI
Cada comando acima foi executado contra o pacote publicado bea 0.1.0 em um diretório novo. Contagens, saldos e mensagens citados são verificação da CLI. Os prompts das tarefas não foram executados contra nenhum modelo. O comportamento do modelo é avaliado separadamente.
