Entregue a um agente de IA externo duas tarefas de escrituração e mantenha cada alteração no livro-razão sob sua revisão: importe um CSV bancário com uma verificação prévia, e depois responda a uma pergunta de saldo a partir de saída de consulta e relatório.
Instale o 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 da própria assinatura ou chave de API. Apenas o auxiliar integrado bea ask precisa de credenciais hospedadas, e estas receitas não o utilizam.
Escolhendo entre ferramentas? Cinco ferramentas de contabilidade para agentes de IA compara Beancount.io, hledger, Xero, QuickBooks Online e Puzzle nos mesmos critérios de fluxo de trabalho para agentes, com fontes datadas.
O que o agente faz e o que o bea faz
O agente propõe categorias e elabora 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 no 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 revisão prévia e de duplicatas decide o que é gravado.
Pré-requisitos
Você precisa do bea e de um diretório demo novo. Nenhuma conta e nenhum importador Python.
Prepare as entradas
Crie o diretório e o livro-razão. Alvos explícitos --file mantêm cada comando apontado para os livros demo.
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,groceries,-20.00
2026-08-03,Shell,gas,-40.00
2026-08-04,Unknown Shop,mystery,-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"Copie o prompt da tarefa
Cole este prompt no seu agente externo junto com o conteúdo do CSV:
Propose Beancount categorization rules for my bank CSV rows.
Suggest one TOML rule per merchant with a match pattern and a
destination expense account. Never change dates, payees, or amounts.
Leave rows you cannot categorize confidently unmatched: they post to
Expenses:Uncategorized with flag ! for my review. I run bea import
preview and apply locally. You do not write my ledger.Execute os equivalentes na 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"Verifique a saída esperada
A pré-visualização relata 3 prontos, 0 duplicatas exatas, 0 duplicatas possíveis e sai com código 0. Ela não grava nada. A execução de aplicação relata 3 lançamentos gravados. A verificação não relata erros. A fila ! lista a única linha não correspondida de Unknown Shop em -9.99 USD. A consulta de saldo relata 930.01 USD em conta corrente. Repetir a aplicação relata 0 prontos, 3 duplicatas exatas e grava 0 lançamentos.
Revise e corrija
Recategorize deliberadamente a linha ! no seu livro-razão após lê-la. Uma verificação aprovada apenas prova que o livro-razão está equilibrado. Ela não diz nada sobre se Expenses:Uncategorized é a conta certa. 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 demo: quanto foi gasto em supermercado e combustível em agosto de 2026. O agente elabora a consulta. Comandos somente leitura produzem a resposta.
Pré-requisitos
Você precisa do livro-razão demo da receita 1 ou dos seus próprios livros. Cada comando abaixo é somente leitura.
Copie o prompt da tarefa
Cole este prompt no seu agente externo:
Draft a Beancount query (BQL) that answers: how much did I spend on
groceries and fuel in August 2026. Use my account names exactly as
listed by bea list open. Propose read-only commands only: bea query
or bea report with an explicit --file target. Do not propose ledger
edits to fix a surprising total. A surprising total means the query
or the books need review, not a compensating entry.Execute os equivalentes na CLI
Execute a consulta elaborada contra um alvo de livro-razão explícito e 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 flag global seguem a referência da CLI. O guia de linguagem de consulta documenta toda a superfície BQL.
Verifique 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. Supermercado mais combustível é 60.00 USD. A demonstração de resultados concorda: 69.99 USD de despesas de agosto com lucro líquido de -69.99 USD. A variante JSON retorna as mesmas linhas dentro de data.rows com metadados de coluna em data.columns.
Revise e corrija
Uma consulta contra um nome de conta errado imprime (sem linhas) 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 execute bea check novamente.
Primeiro desafio: equilibrar três linhas sintéticas
Um primeiro desafio portátil com entradas explícitas e uma resposta derivada de forma independente. Baixe os três arquivos abaixo, execute a importação e verifique os dois totais. Nenhuma conta e nenhum checkout de produto.
Abra livros em 2026-09-01 em USD com 1000 USD em conta corrente. Registre três linhas de setembro: um pagamento de cliente de 2000.00 USD, uma conta de hospedagem de 29.00 USD e uma visita a cafeteria de 12.50 USD. A conta corrente termina em 2958.50 USD, de 1000 + 2000 - 29 - 12.50. O lucro de setembro é 1958.50 USD, de 2000 - 29 - 12.50. Ambas as expectativas vêm dessa aritmética, não da saída de relatórios.
Prepare as entradas
Crie o diretório e abra as duas contas que o modelo não carrega. Expenses:Dining já vem do modelo da CLI.
mkdir agent-challenge && cd agent-challenge
bea --no-input init books --currency USD --date 2026-09-01 --opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-09-01 --account Income:Consulting -c USD
bea --file books/main.bean add open --date 2026-09-01 --account Expenses:Software -c USDEsses três comandos produzem o livro-razão abaixo. Baixe-o como main.bean em vez de digitá-lo.
option "title" "Personal ledger"
option "operating_currency" "USD"
; Add more accounts with bea add open. Amounts on credit accounts are negative.
; bea import books rows it cannot categorize to Expenses:Uncategorized with flag '!'.
2026-09-01 open Assets:Checking USD
2026-09-01 open Assets:Savings USD
2026-09-01 open Assets:Cash USD
2026-09-01 open Liabilities:CreditCard USD
2026-09-01 open Income:Salary USD
2026-09-01 open Income:Interest USD
2026-09-01 open Expenses:Groceries USD
2026-09-01 open Expenses:Dining USD
2026-09-01 open Expenses:Rent USD
2026-09-01 open Expenses:Transport USD
2026-09-01 open Expenses:Utilities USD
2026-09-01 open Expenses:Fees USD
2026-09-01 open Expenses:Uncategorized USD
2026-09-01 open Equity:OpeningBalances USD
2026-09-01 * "Opening balances"
Assets:Checking 1000 USD
Equity:OpeningBalances -1000 USD
2026-09-01 open Income:Consulting USD
2026-09-01 open Expenses:Software USDSalve este extrato como statement.csv, ou baixe-o como statement.csv:
Date,Payee,Amount
2026-09-02,Client,2000.00
2026-09-03,Hosting,-29.00
2026-09-04,Cafe,-12.50Salve estas regras como rules.toml, ou baixe-as como rules.toml. Cada regra nomeia uma conta que o livro-razão inicial abre.
[[rule]]
match = "client"
account = "Income:Consulting"
[[rule]]
match = "hosting"
account = "Expenses:Software"
[[rule]]
match = "cafe"
account = "Expenses:Dining"Execute o desafio
Pré-visualize primeiro, depois aplique e verifique. Valores, datas, nomes de campos e nomes de contas são idênticos em todos os idiomas. Apenas o texto ao redor é traduzido.
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee --account Assets:Checking --rules rules.toml
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee --account Assets:Checking --rules rules.toml --apply
bea --file books/main.bean check
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"
bea --file books/main.bean report income-statement --time 2026-09Verifique a saída esperada
A pré-visualização relata 3 prontos, 0 duplicatas exatas, 0 duplicatas possíveis e sai com código 0. A execução de aplicação relata 3 lançamentos gravados. A verificação não relata erros. A consulta de saldo mantém 2958.50 USD em conta corrente. A demonstração de resultados mostra 2000.00 USD de renda de Consultoria contra 41.50 USD de despesas, para um lucro líquido de 1958.50 USD. Repetir a aplicação relata 0 prontos, 3 duplicatas exatas e grava 0 lançamentos.
Quando uma receita vira um trabalho repetido
Os prompts acima servem para tarefas pontuais conduzidas manualmente. Trabalhos que você repete semanalmente servem para as 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 acionamento. Este CMS não mantém cópias desses arquivos.
- Comece um livro-razão novo 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 coloca cada linha em espera, 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 desse trabalho.
- Prove que uma conta corresponde ao seu extrato com beancount-reconcile. Ele compara o livro-razão com o extrato e registra uma asserçã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 número. A receita 2 acima é a forma manual desse trabalho.
- Encerre um mês com beancount-close. Ele reconcilia cada conta ativa, verifica lançamentos recorrentes e sinalizadores de revisão, e registra o fechamento 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 o 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, e o agente executará os mesmos comandos bea que as receitas mostram. O agente propõe, você revisa, e o bea valida.
Uma habilidade carrega no próprio cliente do agente, através do mecanismo de habilidades 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 o local de habilidades do cliente para a pasta de habilidade que você precisa e continue lendo sua fonte atual para frases de acionamento e atualizações.
bea ask carrega suas próprias habilidades separadamente, de um SKILL.md ao lado do seu livro-razão — veja Estenda o bea ask com habilidades.
Perguntas semelhantes a ask sem o bea ask
A receita 2 responde perguntas do 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 e nenhuma instalação extra.
bea ask é um auxiliar integrado separado. Ele não é a receita acima nem a habilidade beancount-ask. Ele roteia a pergunta pelo serviço de IA hospedado, então precisa do extra ask e de credenciais hospedadas, como documentado na referência da CLI. Instale a CLI base primeiro e 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.
Um cliente completou o primeiro desafio em uma cópia nova dos downloads sem regras fornecidas antecipadamente. Muse Code 1.1.1 (modelo muse-spark-1.3-contributor) derivou sua própria categorização, pré-visualizou 3 prontos sem gravar nada, aplicou 3 lançamentos e relatou 2958.50 USD em conta corrente com 1958.50 USD de lucro de setembro — correspondendo às expectativas acima. Sua única aplicação falha (um bloqueio de cache em sandbox, recuperado via XDG_CACHE_HOME) é mantida no registro. Leia o prompt completo, a sequência de ferramentas e a verificação na transcrição de execução, ou reproduza o caminho funcional com o script de demonstração e sua saída capturada.
Essa execução é verificação de saída da CLI de uma única execução, não um benchmark de modelo. Ela não alega nada sobre outros clientes, precisão contábil em geral ou uso de produção não supervisionado.
A história completa de prova — entradas, metodologia, resultados observados, falhas, limitações e downloads — é publicada como Seu agente consegue equilibrar estes livros?.
Explore a pesquisa mais ampla por trás desses fluxos de trabalho no Bean Labs, o hub de pesquisa em automação contábil do Beancount.io.