Affida a un agente AI esterno due attività di contabilità e mantieni ogni modifica al registro sotto la tua revisione: importa un CSV bancario con un controllo di anteprima, poi rispondi a una domanda sul saldo tramite query e report di output.
Installa bea con la guida rapida CLI. I comandi locali di importazione, query e report non richiedono un account Beancount.io. Il tuo agente di chat necessita solo della propria sottoscrizione o chiave API. Solo l'helper integrato bea ask richiede credenziali ospitate, e queste ricette non lo utilizzano.
Stai scegliendo tra strumenti? Cinque strumenti di contabilità per agenti AI confronta Beancount.io, hledger, Xero, QuickBooks Online e Puzzle sugli stessi criteri di flusso di lavoro per agenti, con fonti datate.
Cosa fa l'agente e cosa fa bea
L'agente propone categorie e abbozza query. Bea valida la struttura del registro e calcola i totali. Esegui tu stesso ogni comando qui sotto. L'agente non scrive mai direttamente nel tuo registro.
Ricetta 1: importa un estratto conto con categorie proposte dall'agente
Trasforma un export bancario in voci validate. L'agente suggerisce le regole di categorizzazione. L'anteprima e la revisione dei duplicati decidono cosa viene scritto.
Prerequisiti
Ti servono bea e una nuova directory demo. Nessun account e nessun importatore Python.
Prepara gli input
Crea la directory e il registro. I target espliciti con --file mantengono ogni comando puntato sui libri 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 USDSalva questo campione come 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.99Salva queste regole di categorizzazione come rules.toml:
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"Copia il prompt dell'attività
Incolla questo prompt al tuo agente esterno insieme al contenuto del 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.Esegui gli equivalenti CLI
Anteprima prima, poi applica le voci revisionate e verifica il risultato:
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"Controlla l'output atteso
L'anteprima riporta 3 pronte, 0 duplicati esatti, 0 possibili duplicati ed esce con codice 0. Non scrive nulla. L'esecuzione di applicazione riporta Scritte 3 voci. Il controllo non riporta errori. La coda ! elenca la riga non corrispondente da Unknown Shop a -9.99 USD. La query sul saldo riporta 930.01 USD nel conto corrente. Ripetendo l'applicazione si riporta 0 pronte, 3 duplicati esatti e si scrivono 0 voci.
Revisiona e correggi
Ricategorizza deliberatamente la riga ! nel tuo registro dopo averla letta. Un controllo superato dimostra solo che il registro quadra. Non dice nulla sul fatto che Expenses:Uncategorized sia il conto giusto. Per la politica sui duplicati, la gestione dei conflitti e il percorso avanzato in Python, segui la procedura dettagliata per CSV bancari.
Ricetta 2: rispondi a una domanda sul saldo senza scritture
Rispondi a una domanda dai libri demo: quanto è stato speso in generi alimentari e carburante ad agosto 2026. L'agente abbozza la query. I comandi di sola lettura producono la risposta.
Prerequisiti
Ti serve il registro demo della ricetta 1 o i tuoi libri. Ogni comando qui sotto è di sola lettura.
Copia il prompt dell'attività
Incolla questo prompt al tuo agente esterno:
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.Esegui gli equivalenti CLI
Esegui la query abbozzata su un target di registro esplicito, poi verifica incrociata con un report:
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-08I consumatori automatici aggiungono il flag globale --json prima del sottocomando:
bea --file books/main.bean --json query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"I contenitori JSON, i codici di uscita e il posizionamento dei flag globali seguono il riferimento CLI. La guida al linguaggio di query documenta l'intera superficie BQL.
Controlla l'output atteso
La query riporta 20.00 USD per Expenses:Groceries, 40.00 USD per Expenses:Transport:Fuel e 9.99 USD per Expenses:Uncategorized. Generi alimentari più carburante fanno 60.00 USD. Il conto economico concorda: 69.99 USD di spese di agosto con un utile netto di -69.99 USD. La variante JSON restituisce le stesse righe dentro data.rows con i metadati delle colonne in data.columns.
Revisiona e correggi
Una query su un nome di conto errato stampa (nessuna riga) su stderr ed esce comunque con codice 0. Confronta il nome con l'output di bea list open e riesegui la query. Non correggere mai un totale sorprendente modificando il registro per far corrispondere la risposta. Correggi la query o correggi i libri, poi riesegui bea check.
Prima sfida: bilancia tre righe sintetiche
Una prima sfida portatile con input espliciti e una risposta derivata in modo indipendente. Scarica i tre file qui sotto, esegui l'importazione e controlla i due totali. Nessun account e nessun checkout di prodotto.
Apri i libri il 2026-09-01 in USD con 1000 USD nel conto corrente. Registra tre righe di settembre: un pagamento cliente di 2000.00 USD, una fattura di hosting di 29.00 USD e un caffè di 12.50 USD. Il conto corrente termina a 2958.50 USD, da 1000 + 2000 - 29 - 12.50. L'utile di settembre è 1958.50 USD, da 2000 - 29 - 12.50. Entrambe le aspettative derivano da quell'aritmetica, non dall'output del report.
Prepara gli input
Crea la directory e apri i due conti che il modello non porta. Expenses:Dining arriva già dal modello 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 USDQuei tre comandi producono il registro qui sotto. Scaricalo come main.bean invece di digitarlo.
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 USDSalva questo estratto conto come statement.csv, o scaricalo come statement.csv:
Date,Payee,Amount
2026-09-02,Client,2000.00
2026-09-03,Hosting,-29.00
2026-09-04,Cafe,-12.50Salva queste regole come rules.toml, o scaricale come rules.toml. Ogni regola nomina un conto che il registro iniziale apre.
[[rule]]
match = "client"
account = "Income:Consulting"
[[rule]]
match = "hosting"
account = "Expenses:Software"
[[rule]]
match = "cafe"
account = "Expenses:Dining"Esegui la sfida
Anteprima prima, poi applica e verifica. Importi, date, nomi dei campi e nomi dei conti sono identici in ogni locale. Solo la prosa attorno a essi è tradotta.
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-09Controlla l'output atteso
L'anteprima riporta 3 pronte, 0 duplicati esatti, 0 possibili duplicati ed esce con codice 0. L'esecuzione di applicazione riporta Scritte 3 voci. Il controllo non riporta errori. La query sul saldo tiene 2958.50 USD nel conto corrente. Il conto economico mostra 2000.00 USD di reddito da Consulenza contro 41.50 USD di spese, per un utile netto di 1958.50 USD. Ripetendo l'applicazione si riporta 0 pronte, 3 duplicati esatti e si scrivono 0 voci.
Quando una ricetta diventa un lavoro ripetitivo
I prompt sopra si adattano ad attività una tantum guidate a mano. I lavori che ripeti settimanalmente si adattano alle competenze versionate nel repository del prodotto. Ogni link qui sotto apre il sorgente attuale della competenza, che porta le proprie istruzioni di configurazione e attivazione. Questo CMS non conserva copie di questi file.
- Inizia un nuovo registro da una directory vuota con beancount-init. Crea il file del registro, un esecutore Fava e un progetto Python.
- Trasforma un export bancario in voci categorizzate con beancount-import. Prepara ogni riga, suggerisce categorie dalla cronologia del registro, salta le righe già importate e scrive solo dopo conferma. La ricetta 1 sopra è la forma manuale di questo lavoro.
- Prova che un conto corrisponda al suo estratto conto con beancount-reconcile. Confronta il registro con l'estratto conto e inserisce un'asserzione di saldo di fine periodo dopo conferma.
- Rispondi a una domanda dai libri con beancount-ask. Esegue query di sola lettura e mostra ogni query accanto alla sua cifra. La ricetta 2 sopra è la forma manuale di questo lavoro.
- Chiudi un mese con beancount-close. Riconcilia ogni conto attivo, controlla le voci ricorrenti e i flag di revisione e registra la chiusura come un commit.
La collezione completa vive nell'albero delle competenze canonico.
Dai bea a un agente con shell, o carica una competenza in un client
Questi sono due passaggi separati. Installare bea non installa né configura mai competenze.
Un agente con shell ha bisogno del comando nel suo percorso. Installalo con la guida rapida CLI, poi l'agente esegue gli stessi comandi bea mostrati nelle ricette. L'agente propone, tu revisioni e bea valida.
Una competenza si carica nel client dell'agente stesso, tramite il meccanismo di competenze del client. Il repository del prodotto espone un unico albero canonico a entrambi i client supportati: Claude Code lo legge sotto .claude/skills e Codex sotto .agents/skills, come directory collegate allo stesso sorgente. Punta la posizione delle competenze del client alla cartella di competenze di cui hai bisogno e continua a leggere il suo sorgente attuale per frasi di attivazione e aggiornamenti.
bea ask carica le proprie competenze separatamente, da un SKILL.md accanto al tuo registro — vedi Estendi bea ask con competenze.
Domande simili ad ask senza bea ask
La ricetta 2 risponde a domande sul registro con un agente esterno più i comandi di sola lettura bea query e bea report. Quel percorso è locale. Non serve account né installazioni extra.
bea ask è un helper integrato separato. Non è né la ricetta sopra né la competenza beancount-ask. Instrada la domanda attraverso il servizio AI ospitato, quindi ha bisogno dell'extra ask e delle credenziali ospitate, come documentato nel riferimento CLI. Installa prima la CLI di base, poi aggiungi l'extra solo quando vuoi risposte ospitate.
Output citati e verifica CLI
Ogni comando sopra è stato eseguito contro il pacchetto bea 0.1.0 pubblicato in una nuova directory. Conteggi, saldi e messaggi citati sono verifica CLI.
Un client ha completato la prima sfida su una copia nuova dei download senza regole fornite in anticipo. Muse Code 1.1.1 (modello muse-spark-1.3-contributor) ha derivato la propria categorizzazione, ha visualizzato in anteprima 3 pronte senza scrivere nulla, ha applicato 3 voci e ha riportato 2958.50 USD nel conto corrente con 1958.50 USD di utile di settembre — corrispondenti alle aspettative sopra. Il suo unico tentativo di applicazione fallito (un blocco cache sandbox, recuperato tramite XDG_CACHE_HOME) è conservato nel registro. Leggi il prompt completo, la sequenza di strumenti e la verifica nella trascrizione dell'esecuzione, o riproduci il percorso funzionante con lo script demo e il suo output catturato.
Quella esecuzione è verifica dell'output CLI di una singola esecuzione, non un benchmark di modelli. Non afferma nulla su altri client, sull'accuratezza contabile in generale o sull'uso in produzione senza supervisione.
L'intera storia della prova — input, metodologia, risultati osservati, fallimenti, limitazioni e download — è pubblicata come Il tuo agente può bilanciare questi libri?.
Esplora la ricerca più ampia dietro questi flussi di lavoro su Bean Labs, l'hub di ricerca sull'automazione contabile di Beancount.io.