Affida a un agente AI esterno due attività contabili mantenendo ogni modifica al registro sotto la tua revisione: importa un CSV bancario con un controllo prima dell'anteprima, poi rispondi a una domanda sul saldo tramite l'output di query e report.
Installa bea con la guida rapida CLI. L'importazione, la query e i comandi di report locali non richiedono un account Beancount.io. Al tuo agente di chat serve solo la propria sottoscrizione o chiave API. Solo l'helper integrato bea ask richiede credenziali ospitate, e queste ricette non lo utilizzano.
Cosa fa l'agente e cosa fa bea
L'agente propone categorie e redige query. Bea valida la struttura del registro e calcola i totali. Esegui tu stesso ogni comando qui sotto. L'agente non scrive mai direttamente il 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
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 --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 esempio 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:
Proponi regole di categorizzazione Beancount per le righe del mio CSV bancario.
Suggerisci una regola TOML per ogni commerciante con un pattern di corrispondenza e un
conto spese di destinazione. Non modificare mai date, beneficiari o importi.
Lascia senza corrispondenza le righe che non puoi categorizzare con sicurezza: vanno a
Expenses:Uncategorized con flag ! per la mia revisione. Eseguo bea import
anteprima e applico localmente. Tu non scrivi il mio registro.Esegui gli equivalenti CLI
Prima l'anteprima, 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 ready, 0 exact duplicates, 0 possible duplicates ed esce con 0. Non scrive nulla. L'esecuzione di apply riporta Wrote 3 entries. Il check non riporta errori. La coda ! elenca l'unica riga senza corrispondenza da Unknown Shop a -9.99 USD. La query sul saldo riporta 930.01 USD sul conto corrente. Ripetendo l'apply si riporta 0 ready, 3 exact duplicates e si scrivono 0 voci.
Revisiona e correggi
Ricategorizza deliberatamente la riga ! nel tuo registro dopo averla letta. Un check 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 sui libri demo: quanto è andato a generi alimentari e carburante ad agosto 2026. L'agente redige la query. I comandi di sola lettura producono la risposta.
Prerequisiti
Servono 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:
Redigi una query Beancount (BQL) che risponda: quanto ho speso in
generi alimentari e carburante ad agosto 2026. Usa i nomi dei miei conti
esattamente come elencati da bea list open. Proponi solo comandi di sola lettura: bea query
o bea report con un target --file esplicito. Non proporre modifiche al registro
per correggere un totale sorprendente. Un totale sorprendente significa che la query
o i libri richiedono una revisione, non una voce compensativa.Esegui gli equivalenti CLI
Esegui la query redatta 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 machine 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"Le buste 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 metadati delle colonne in data.columns.
Revisiona e correggi
Una query su un nome di conto errato stampa (no rows) su stderr ed esce comunque con 0. Confronta il nome con l'output di bea list open ed esegui di nuovo la query. Non correggere mai un totale sorprendente modificando il registro per far combaciare la risposta. Correggi la query o correggi i libri, poi esegui di nuovo bea check.
Prima sfida: bilancia tre righe sintetiche
Una prima sfida portabile 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 sul conto corrente. Registra tre righe di settembre: un pagamento cliente di 2000.00 USD, una bolletta di hosting di 29.00 USD e una visita al bar 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 include. Expenses:Dining viene 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
Prima l'anteprima, poi applica e verifica. Importi, date, nomi dei campi e nomi dei conti sono identici in ogni locale. Solo la prosa attorno è 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 ready, 0 exact duplicates, 0 possible duplicates ed esce con 0. L'esecuzione di apply riporta Wrote 3 entries. Il check non riporta errori. La query sul saldo tiene 2958.50 USD sul 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'apply si riporta 0 ready, 3 exact duplicates e si scrivono 0 voci.
Quando una ricetta diventa un lavoro ripetitivo
I prompt qui sopra si adattano a attività una tantum guidate a mano. I lavori che ripeti settimanalmente si adattano alle skill versionate nel repository del prodotto. Ogni link qui sotto apre il codice sorgente corrente della skill, che porta le proprie istruzioni di configurazione e attivazione. Questo CMS non conserva copie di questi file.
- Avvia 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. Mette in scena 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.
- Dimostra che un conto corrisponde al suo estratto conto con beancount-reconcile. Confronta il registro con l'estratto conto e registra un'asserzione di saldo a 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. Concilia ogni conto attivo, controlla le voci ricorrenti e i flag di revisione e registra la chiusura come commit.
L'intera collezione vive nell'albero delle skill canonico.
Dai bea a un agente con shell, o carica una skill in un client
Questi sono due passaggi separati. Installare bea non installa né configura mai le skill.
Un agente con capacità di shell ha bisogno del comando nel suo PATH. 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 skill si carica nel client dell'agente stesso, tramite il meccanismo di skill 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 alla stessa sorgente. Punta la posizione delle skill del client alla cartella della skill che ti serve e continua a leggere la sua sorgente corrente per frasi di attivazione e aggiornamenti.
Domande simili a bea ask senza bea ask
La ricetta 2 risponde alle domande sul registro con un agente esterno più i comandi di sola lettura bea query e bea report. Quel percorso è locale. Non richiede account né installazioni extra.
bea ask è un helper integrato separato. Non è né la ricetta sopra né la skill beancount-ask. Instrada la domanda attraverso il servizio AI ospitato, quindi richiede l'extra ask e 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 directory nuova. 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 pronti senza scrivere nulla, ha applicato 3 voci e ha riportato 2958.50 USD sul conto corrente con 1958.50 USD di utile di settembre — corrispondenti alle aspettative sopra. Il suo unico apply fallito (un blocco della cache sandbox, recuperato tramite XDG_CACHE_HOME) è conservato nel record. Leggi il prompt completo, la sequenza degli strumenti e la verifica nel trascrizione dell'esecuzione, oppure riproduci il percorso funzionante con lo script demo e il suo output catturato.
Quell'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 di produzione non presidiato.
L'intera storia della prova — input, metodologia, risultati osservati, fallimenti, limitazioni e download — è pubblicata come Il tuo agente può bilanciare questi libri?.
