Confiez deux tâches de tenue de livres à un agent IA externe tout en gardant chaque modification du grand livre sous votre contrôle : importez un CSV bancaire avec une vérification préalable via aperçu, puis répondez à une question de solde à partir de la sortie de requête et de rapport.
Installez bea avec le démarrage rapide CLI. Les commandes locales d'importation, de requête et de rapport ne nécessitent pas de compte Beancount.io. Votre agent de discussion n'a besoin que de son propre abonnement ou de sa propre clé API. Seul l'assistant intégré bea ask nécessite des identifiants hébergés, et ces recettes ne l'utilisent pas.
Vous hésitez entre les outils ? Cinq outils comptables pour agents IA compare Beancount.io, hledger, Xero, QuickBooks Online et Puzzle selon les mêmes critères de flux de travail pour agents, avec des sources datées.
Ce que fait l'agent et ce que fait bea
L'agent propose des catégories et rédige des requêtes. Bea valide la structure du grand livre et calcule les totaux. Vous exécutez vous-même chaque commande ci-dessous. L'agent n'écrit jamais directement dans votre grand livre.
Recette 1 : importer un relevé avec des catégories proposées par l'agent
Transformez un export bancaire en écritures validées. L'agent suggère les règles de catégorisation. L'aperçu et l'examen des doublons décident de ce qui est écrit.
Prérequis
Vous avez besoin de bea et d'un nouveau répertoire de démonstration. Pas de compte et pas d'importateur Python.
Préparer les entrées
Créez le répertoire et le grand livre. Des cibles --file explicites maintiennent chaque commande pointée vers les livres de démonstration.
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 USDEnregistrez cet exemple sous 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.99Enregistrez ces règles de catégorisation sous rules.toml :
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"Copier l'invite de tâche
Collez cette invite à votre agent externe avec le contenu du 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.Exécuter les équivalents CLI
Aperçu d'abord, puis appliquez les écritures examinées et vérifiez le résultat :
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"Vérifier la sortie attendue
L'aperçu signale 3 prêtes, 0 doublons exacts, 0 doublons possibles et se termine avec le code 0. Il n'écrit rien. L'exécution d'application signale 3 écritures écrites. La vérification ne signale aucune erreur. La file ! répertorie la seule ligne non appariée de Unknown Shop à -9.99 USD. La requête de solde signale 930.01 USD en compte courant. Répéter l'application signale 0 prêtes, 3 doublons exacts et écrit 0 écriture.
Examiner et corriger
Recatégorisez délibérément la ligne ! dans votre grand livre après l'avoir lue. Une vérification réussie prouve seulement que le grand livre est équilibré. Elle ne dit rien sur le fait que Expenses:Uncategorized soit le bon compte. Pour la politique de doublons, la gestion des conflits et le parcours Python avancé, suivez l'atelier d'importation de CSV bancaire.
Recette 2 : répondre à une question de solde sans écriture
Répondez à une question à partir des livres de démonstration : combien est allé à l'épicerie et au carburant en août 2026. L'agent rédige la requête. Les commandes en lecture seule produisent la réponse.
Prérequis
Vous avez besoin du grand livre de démonstration de la recette 1 ou de vos propres livres. Chaque commande ci-dessous est en lecture seule.
Copier l'invite de tâche
Collez cette invite à votre agent externe :
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.Exécuter les équivalents CLI
Exécutez la requête rédigée sur une cible de grand livre explicite, puis recoupez avec un rapport :
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-08Les consommateurs machine ajoutent l'indicateur global --json avant la sous-command :
bea --file books/main.bean --json query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"Les enveloppes JSON, les codes de sortie et le placement des indicateurs globaux suivent la référence CLI. Le guide du langage de requête documente toute la surface BQL.
Vérifier la sortie attendue
La requête signale 20.00 USD pour Expenses:Groceries, 40.00 USD pour Expenses:Transport:Fuel et 9.99 USD pour Expenses:Uncategorized. L'épicerie plus le carburant font 60.00 USD. Le compte de résultat confirme : 69.99 USD de dépenses d'août avec un bénéfice net de -69.99 USD. La variante JSON renvoie les mêmes lignes dans data.rows avec les métadonnées de colonnes dans data.columns.
Examiner et corriger
Une requête sur un nom de compte incorrect affiche (aucune ligne) sur stderr et se termine quand même avec le code 0. Comparez le nom avec la sortie de bea list open et relancez la requête. Ne corrigez jamais un total surprenant en modifiant le grand livre pour correspondre à la réponse. Corrigez la requête ou corrigez les livres, puis relancez bea check.
Premier défi : équilibrer trois lignes synthétiques
Un premier défi portable avec des entrées explicites et une réponse dérivée indépendamment. Téléchargez les trois fichiers ci-dessous, exécutez l'importation et vérifiez les deux totaux. Pas de compte et pas de paiement à la caisse.
Ouvrez les livres au 2026-09-01 en USD avec 1000 USD en compte courant. Saisissez trois lignes de septembre : un paiement client de 2000.00 USD, une facture d'hébergement de 29.00 USD et une visite de café de 12.50 USD. Le compte courant se termine à 2958.50 USD, à partir de 1000 + 2000 - 29 - 12.50. Le bénéfice de septembre est de 1958.50 USD, à partir de 2000 - 29 - 12.50. Les deux attentes proviennent de cette arithmétique, pas de la sortie du rapport.
Préparer les entrées
Créez le répertoire et ouvrez les deux comptes que le modèle ne contient pas. Expenses:Dining vient déjà du modèle 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 USDCes trois commandes produisent le grand livre ci-dessous. Téléchargez-le en tant que main.bean au lieu de le saisir.
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 USDEnregistrez ce relevé sous statement.csv, ou téléchargez-le en tant que statement.csv :
Date,Payee,Amount
2026-09-02,Client,2000.00
2026-09-03,Hosting,-29.00
2026-09-04,Cafe,-12.50Enregistrez ces règles sous rules.toml, ou téléchargez-les en tant que rules.toml. Chaque règle nomme un compte que le grand livre de démarrage ouvre.
[[rule]]
match = "client"
account = "Income:Consulting"
[[rule]]
match = "hosting"
account = "Expenses:Software"
[[rule]]
match = "cafe"
account = "Expenses:Dining"Exécuter le défi
Aperçu d'abord, puis appliquez et vérifiez. Les montants, les dates, les noms de champs et les noms de comptes sont identiques dans toutes les langues. Seule la prose qui les entoure est traduite.
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-09Vérifier la sortie attendue
L'aperçu signale 3 prêtes, 0 doublons exacts, 0 doublons possibles et se termine avec le code 0. L'exécution d'application signale 3 écritures écrites. La vérification ne signale aucune erreur. La requête de solde contient 2958.50 USD en compte courant. Le compte de résultat montre 2000.00 USD de revenus de conseil contre 41.50 USD de dépenses, pour un bénéfice net de 1958.50 USD. Répéter l'application signale 0 prêtes, 3 doublons exacts et écrit 0 écriture.
Quand une recette devient une tâche récurrente
Les invites ci-dessus conviennent aux tâches ponctuelles pilotées à la main. Les tâches que vous répétez chaque semaine conviennent aux compétences versionnées du référentiel produit. Chaque lien ci-dessous ouvre le code source actuel de la compétence, qui comporte ses propres instructions de configuration et de déclenchement. Ce CMS ne conserve aucune copie de ces fichiers.
- Commencez un nouveau grand livre dans un répertoire vide avec beancount-init. Il crée le fichier du grand livre, un exécuteur Fava et un projet Python.
- Transformez un export bancaire en écritures catégorisées avec beancount-import. Il prépare chaque ligne, suggère des catégories à partir de l'historique du grand livre, ignore les lignes déjà importées et n'écrit qu'après confirmation. La recette 1 ci-dessus est la forme manuelle de cette tâche.
- Prouvez qu'un compte correspond à son relevé avec beancount-reconcile. Il compare le grand livre au relevé et pose une assertion de solde de fin de période après confirmation.
- Répondez à une question à partir des livres avec beancount-ask. Il exécute des requêtes en lecture seule et affiche chaque requête à côté de son chiffre. La recette 2 ci-dessus est la forme manuelle de cette tâche.
- Clôturez un mois avec beancount-close. Il rapproche chaque compte actif, vérifie les écritures récurrentes et les indicateurs de revue, et enregistre la clôture comme un commit.
La collection complète se trouve dans l'arborescence canonique des compétences.
Donner bea à un agent capable d'utiliser un shell, ou charger une compétence dans un client
Ce sont deux étapes distinctes. Installer bea n'installe ni ne configure jamais de compétences.
Un agent capable d'utiliser un shell a besoin de la commande dans son chemin d'accès. Installez-la avec le démarrage rapide CLI, puis l'agent exécute les mêmes commandes bea que celles montrées dans les recettes. L'agent propose, vous examinez et bea valide.
Une compétence se charge dans le client de l'agent lui-même, via le mécanisme de compétences propre au client. Le référentiel produit expose une arborescence canonique aux deux clients pris en charge : Claude Code la lit sous .claude/skills et Codex sous .agents/skills, comme des répertoires liés vers la même source. Pointez l'emplacement des compétences du client vers le dossier de compétences dont vous avez besoin et continuez à lire sa source actuelle pour les phrases de déclenchement et les mises à jour.
bea ask charge ses propres compétences séparément, à partir d'un SKILL.md à côté de votre grand livre — voir Étendre bea ask avec des compétences.
Questions de type « ask » sans bea ask
La recette 2 répond aux questions sur le grand livre avec un agent externe plus les commandes en lecture seule bea query et bea report. Ce parcours est local. Il ne nécessite ni compte ni installation supplémentaire.
bea ask est un assistant intégré distinct. Ce n'est ni la recette ci-dessus ni la compétence beancount-ask. Il achemine la question via le service IA hébergé, donc il nécessite l'option supplémentaire ask et des identifiants hébergés, comme documenté dans la référence CLI. Installez d'abord la CLI de base, puis ajoutez l'option supplémentaire uniquement lorsque vous souhaitez des réponses hébergées.
Sorties citées et vérification CLI
Chaque commande ci-dessus a été exécutée avec le paquet publié bea 0.1.0 dans un répertoire vierge. Les comptes, soldes et messages cités sont une vérification CLI.
Un client a complété le premier défi sur une copie vierge des téléchargements sans règles fournies à l'avance. Muse Code 1.1.1 (modèle muse-spark-1.3-contributor) a dérivé sa propre catégorisation, prévisualisé 3 prêtes sans rien écrire, appliqué 3 écritures et rapporté 2958.50 USD en compte courant avec 1958.50 USD de bénéfice de septembre — correspondant aux attentes ci-dessus. Son unique application échouée (un verrou de cache sandboxé, récupéré via XDG_CACHE_HOME) est conservée dans le dossier. Lisez l'invite complète, la séquence d'outils et la vérification dans la transcription d'exécution, ou rejouez le parcours fonctionnel avec le script de démonstration et sa sortie capturée.
Cette exécution est une vérification de sortie CLI d'une seule exécution, pas un banc d'essai de modèle. Elle ne prétend rien sur d'autres clients, sur l'exactitude comptable en général, ni sur une utilisation en production sans surveillance.
L'histoire complète de la preuve — entrées, méthodologie, résultats observés, échecs, limites et téléchargements — est publiée dans Votre agent peut-il équilibrer ces livres ?.
Explorez la recherche plus large derrière ces flux de travail dans Bean Labs, le hub de recherche sur l'automatisation comptable de Beancount.io.