Доручіть зовнішньому AI-агенту два завдання з бухгалтерії та тримайте кожну зміну в бухгалтерській книзі під вашим контролем: імпортуйте банківський CSV із перевіркою через попередній перегляд, а потім дайте відповідь на питання про залишок на основі запиту та виводу звіту.
Встановіть bea за допомогою швидкого старту CLI. Локальні команди імпорту, запитів та звітів не потребують облікового запису Beancount.io. Вашому чат-агенту потрібна лише власна підписка або API-ключ. Лише вбудований помічник bea ask потребує хостингових облікових даних, і ці рецепти його не використовують.
Обираєте між інструментами? П'ять бухгалтерських інструментів для AI-агентів порівнює Beancount.io, hledger, Xero, QuickBooks Online та Puzzle за тими самими критеріями робочих процесів для агентів, із датованими джерелами.
Що робить агент і що робить bea
Агент пропонує категорії та складає чернетки запитів. Bea перевіряє структуру бухгалтерської книги та обчислює підсумки. Ви самі запускаєте кожну команду нижче. Агент ніколи не пише безпосередньо у вашу бухгалтерську книгу.
Рецепт 1: імпорт виписки з категоріями, запропонованими агентом
Перетворіть банківський експорт на перевірені записи. Агент пропонує правила категоризації. Попередній перегляд і перевірка дублікатів вирішують, що буде записано.
Передумови
Вам потрібні bea та свіжа демонстраційна директорія. Жодного облікового запису та Python-імпортера не потрібно.
Підготовка вхідних даних
Створіть директорію та бухгалтерську книгу. Явні цілі --file тримають кожну команду спрямованою на демонстраційні книги.
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 USDЗбережіть цей зразок як 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.99Збережіть ці правила категоризації як rules.toml:
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"Скопіюйте текст завдання
Вставте цей запит вашому зовнішньому агенту разом із вмістом 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.Запустіть еквіваленти CLI
Спочатку попередній перегляд, потім застосуйте переглянуті записи та перевірте результат:
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"Перевірте очікуваний результат
Попередній перегляд повідомляє 3 ready, 0 exact duplicates, 0 possible duplicates і завершується з кодом 0. Він нічого не записує. Запуск застосування повідомляє Wrote 3 entries. Перевірка не повідомляє про помилки. Черга ! містить один неспівставлений рядок від Unknown Shop на -9.99 USD. Запит про залишок повідомляє 930.01 USD на чековому рахунку. Повторне застосування повідомляє 0 ready, 3 exact duplicates і записує 0 записів.
Перегляд і виправлення
Свідомо перекатегоризуйте рядок ! у вашій бухгалтерській книзі після його прочитання. Успішна перевірка лише доводить, що книга збалансована. Вона нічого не говорить про те, чи є Expenses:Uncategorized правильним рахунком. Щодо політики дублікатів, обробки конфліктів і розширеного шляху Python дотримуйтеся покрокового посібника з банківського CSV.
Рецепт 2: відповідь на питання про залишок без записів
Дайте відповідь на одне питання з демонстраційних книг: скільки пішло на продукти та пальне у серпні 2026 року. Агент складає чернетку запиту. Лише команди для читання дають відповідь.
Передумови
Вам потрібна демонстраційна бухгалтерська книга з рецепта 1 або ваші власні книги. Кожна команда нижче є лише для читання.
Скопіюйте текст завдання
Вставте цей запит вашому зовнішньому агенту:
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.Запустіть еквіваленти CLI
Виконайте складений запит із явною цільовою бухгалтерською книгою, а потім перехресно перевірте за допомогою звіту:
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-08Машинні споживачі додають глобальний прапорець --json перед підкомандою:
bea --file books/main.bean --json query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"JSON-обгортки, коди виходу та розміщення глобальних прапорців описані в довіднику CLI. Посібник із мови запитів документує повну поверхню BQL.
Перевірте очікуваний результат
Запит повідомляє 20.00 USD для Expenses:Groceries, 40.00 USD для Expenses:Transport:Fuel і 9.99 USD для Expenses:Uncategorized. Продукти плюс пальне становлять 60.00 USD. Звіт про прибутки та збитки погоджується: 69.99 USD серпневих витрат із чистим прибутком -69.99 USD. Варіант JSON повертає ті самі рядки всередині data.rows із метаданими колонок у data.columns.
Перегляд і виправлення
Запит проти неправильної назви рахунку виводить (no rows) у stderr і все одно завершується з кодом 0. Порівняйте назву з виводом bea list open і запустіть запит знову. Ніколи не виправляйте дивовижний підсумок, редагуючи книгу, щоб вона відповідала відповіді. Виправте запит або виправте книги, а потім повторно запустіть bea check.
Перше завдання: балансування трьох синтетичних рядків
Портативне перше завдання з явними вхідними даними та незалежно виведеною відповіддю. Завантажте три файли нижче, запустіть імпорт і перевірте два підсумки. Жодного облікового запису та оформлення замовлення не потрібно.
Відкрийте книги на 2026-09-01 у доларах США з 1000 USD на чековому рахунку. Проведіть три вересневі рядки: платіж клієнта на 2000.00 USD, рахунок за хостинг на 29.00 USD і візит до кав'ярні на 12.50 USD. Чековий рахунок закінчується на 2958.50 USD, з 1000 + 2000 - 29 - 12.50. Вересневий прибуток становить 1958.50 USD, з 2000 - 29 - 12.50. Обидва очікування походять із цієї арифметики, а не з виводу звіту.
Підготовка вхідних даних
Створіть директорію та відкрийте два рахунки, яких немає в шаблоні. Expenses:Dining уже надходить із шаблону 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 USDЦі три команди створюють книгу нижче. Завантажте її як main.bean замість того, щоб друкувати її.
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 USDЗбережіть цю виписку як statement.csv або завантажте її як statement.csv:
Date,Payee,Amount
2026-09-02,Client,2000.00
2026-09-03,Hosting,-29.00
2026-09-04,Cafe,-12.50Збережіть ці правила як rules.toml або завантажте їх як rules.toml. Кожне правило називає рахунок, який відкриває стартова книга.
[[rule]]
match = "client"
account = "Income:Consulting"
[[rule]]
match = "hosting"
account = "Expenses:Software"
[[rule]]
match = "cafe"
account = "Expenses:Dining"Запустіть завдання
Спочатку попередній перегляд, потім застосуйте та перевірте. Суми, дати, назви полів та назви рахунків ідентичні в кожній локалі. Лише проза навколо них перекладена.
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-09Перевірте очікуваний результат
Попередній перегляд повідомляє 3 ready, 0 exact duplicates, 0 possible duplicates і завершується з кодом 0. Запуск застосування повідомляє Wrote 3 entries. Перевірка не повідомляє про помилки. Запит про залишок містить 2958.50 USD на чековому рахунку. Звіт про прибутки та збитки показує 2000.00 USD доходу від консалтингу проти 41.50 USD витрат, що дає чистий прибуток 1958.50 USD. Повторне застосування повідомляє 0 ready, 3 exact duplicates і записує 0 записів.
Коли рецепт стає повторюваною роботою
Наведені вище запити підходять для одноразових завдань, які виконуються вручну. Роботи, які ви повторюєте щотижня, підходять для версіонованих навичок у репозиторії продукту. Кожне посилання нижче відкриває поточний вихідний код навички, який містить власні інструкції з налаштування та запуску. Ця CMS не зберігає копій цих файлів.
- Почніть свіжу бухгалтерську книгу з порожньої директорії за допомогою beancount-init. Він створює файл книги, запускач Fava та Python-проєкт.
- Перетворіть банківський експорт на категоризовані записи за допомогою beancount-import. Він розміщує кожен рядок на етапі, пропонує категорії на основі історії книги, пропускає вже імпортовані рядки та записує лише після підтвердження. Рецепт 1 вище є ручною формою цієї роботи.
- Доведіть, що один рахунок відповідає його виписці, за допомогою beancount-reconcile. Він порівнює книгу з випискою та після підтвердження додає перевірку залишку на кінець періоду.
- Дайте відповідь на питання з книг за допомогою beancount-ask. Він виконує запити лише для читання та показує кожен запит поруч із його цифрою. Рецепт 2 вище є ручною формою цієї роботи.
- Закрийте місяць за допомогою beancount-close. Він звіряє кожен активний рахунок, перевіряє періодичні записи та прапорці перегляду та фіксує закриття як комміт.
Повна колекція знаходиться в канонічному дереві навичок.
Дайте агенту з підтримкою оболонки bea або завантажте навичку в клієнта
Це два окремі кроки. Встановлення bea ніколи не встановлює та не налаштовує навички.
Агенту з підтримкою оболонки потрібна команда в його PATH. Встановіть її за допомогою швидкого старту CLI, і тоді агент виконує ті самі команди bea, які показують рецепти. Агент пропонує, ви переглядаєте, а bea перевіряє.
Навичка завантажується в самого клієнта агента через власний механізм навичок цього клієнта. Репозиторій продукту надає одне канонічне дерево обом підтримуваним клієнтам: Claude Code читає його в .claude/skills, а Codex у .agents/skills, як пов'язані директорії до того самого джерела. Вкажіть розташування навичок клієнта на потрібну папку навичок і продовжуйте читати її поточний вихідний код для фраз запуску та оновлень.
bea ask завантажує власні навички окремо, з SKILL.md поруч із вашою книгою — див. Розширення bea ask навичками.
Питання в стилі ask без bea ask
Рецепт 2 відповідає на питання про книгу за допомогою зовнішнього агента плюс команд bea query та bea report лише для читання. Цей шлях є локальним. Він не потребує облікового запису та додаткових встановлень.
bea ask — це окремий вбудований помічник. Він не є ні рецептом вище, ні навичкою beancount-ask. Він маршрутизує питання через хостинговий AI-сервіс, тому потребує додатка ask і хостингових облікових даних, як задокументовано в довіднику CLI. Спочатку встановіть базовий CLI, а потім додайте додаток лише тоді, коли ви хочете отримувати відповіді від хостингового сервісу.
Процитовані виводи та перевірка CLI
Кожна команда вище була виконана проти опублікованого пакета bea 0.1.0 у свіжій директорії. Процитовані кількості, залишки та повідомлення є перевіркою CLI.
Один клієнт завершив перше завдання на свіжій копії завантажень без попередньо наданих правил. Muse Code 1.1.1 (модель muse-spark-1.3-contributor) вивів власну категоризацію, попередньо переглянув 3 готових без запису, застосував 3 записи та повідомив 2958.50 USD на чековому рахунку з 1958.50 USD вересневого прибутку — що збігається з очікуваннями вище. Його одна невдала спроба застосування (заблоковане кеш-блокування пісочниці, відновлене через XDG_CACHE_HOME) збережена в записі. Прочитайте повний запит, послідовність інструментів і перевірку в транскрипті запуску або відтворіть робочий шлях за допомогою демонстраційного скрипта та його зафіксованого виводу.
Цей запуск є перевіркою виводу CLI одного виконання, а не бенчмарком моделі. Він нічого не стверджує про інших клієнтів, точність бухгалтерії загалом або неконтрольоване виробниче використання.
Повна історія доказів — вхідні дані, методологія, спостережувані результати, невдачі, обмеження та завантаження — опублікована як Чи може ваш агент збалансувати ці книги?.
Досліджуйте ширші дослідження за цими робочими процесами на Bean Labs, дослідницькому хабі автоматизації бухгалтерії Beancount.io.