Dale a un agente de IA externo dos tareas de contabilidad y mantén cada cambio en el libro mayor bajo tu revisión: importa un CSV bancario con una verificación previa a vista, luego responde una pregunta de saldo desde la salida de consultas e informes.
Instala bea con la guía de inicio rápido de CLI. Los comandos locales de importación, consulta e informes no necesitan una cuenta de Beancount.io. Tu agente de chat solo necesita su propia suscripción o clave de API. Solo el asistente integrado bea ask necesita credenciales alojadas, y estas recetas no lo usan.
¿Eligiendo entre herramientas? Cinco herramientas de contabilidad para agentes de IA compara Beancount.io, hledger, Xero, QuickBooks Online y Puzzle en los mismos criterios de flujo de trabajo de agentes, con fuentes con fecha.
Qué hace el agente y qué hace bea
El agente propone categorías y redacta consultas. Bea valida la estructura del libro mayor y calcula los totales. Tú ejecutas cada comando a continuación tú mismo. El agente nunca escribe directamente en tu libro mayor.
Receta 1: importar un estado de cuenta con categorías propuestas por el agente
Convierte una exportación bancaria en asientos validados. El agente sugiere las reglas de categorización. La vista previa y la revisión de duplicados deciden qué se escribe.
Requisitos previos
Necesitas bea y un directorio demo nuevo. Sin cuenta y sin importador de Python.
Preparar las entradas
Crea el directorio y el libro mayor. Los objetivos explícitos --file mantienen cada comando apuntado a los libros 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 USDGuarda esta muestra 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.99Guarda estas reglas de categorización como rules.toml:
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"Copiar el prompt de tarea
Pega este prompt a tu agente externo junto con el contenido 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.Ejecutar los equivalentes de CLI
Vista previa primero, luego aplica los asientos revisados y verifica el 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"Verificar la salida esperada
La vista previa informa 3 listos, 0 duplicados exactos, 0 posibles duplicados y sale con código 0. No escribe nada. La ejecución de aplicar informa Se escribieron 3 asientos. La verificación no informa errores. La cola ! lista la única fila no coincidente de Unknown Shop a -9.99 USD. La consulta de saldo informa 930.01 USD en cuenta corriente. Repetir la aplicación informa 0 listos, 3 duplicados exactos y escribe 0 asientos.
Revisar y corregir
Recategoriza deliberadamente la fila ! en tu libro mayor después de leerla. Una verificación que pasa solo prueba que el libro mayor cuadra. No dice nada sobre si Expenses:Uncategorized es la cuenta correcta. Para la política de duplicados, el manejo de conflictos y la ruta avanzada de Python, sigue el tutorial de CSV bancario.
Receta 2: responder una pregunta de saldo sin escrituras
Responde una pregunta de los libros demo: cuánto se gastó en comida y combustible en agosto de 2026. El agente redacta la consulta. Los comandos de solo lectura producen la respuesta.
Requisitos previos
Necesitas el libro mayor demo de la receta 1 o tus propios libros. Cada comando a continuación es de solo lectura.
Copiar el prompt de tarea
Pega este prompt a tu 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.Ejecutar los equivalentes de CLI
Ejecuta la consulta redactada contra un objetivo de libro mayor explícito, luego verifica cruzadamente con un informe:
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-08Los consumidores máquina añaden la bandera global --json antes del subcomando:
bea --file books/main.bean --json query "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"Los sobres JSON, los códigos de salida y la colocación de banderas globales siguen la referencia de CLI. La guía del lenguaje de consultas documenta la superficie completa de BQL.
Verificar la salida esperada
La consulta informa 20.00 USD para Expenses:Groceries, 40.00 USD para Expenses:Transport:Fuel, y 9.99 USD para Expenses:Uncategorized. Comida más combustible es 60.00 USD. El estado de resultados está de acuerdo: 69.99 USD de gastos de agosto con una ganancia neta de -69.99 USD. La variante JSON devuelve las mismas filas dentro de data.rows con metadatos de columnas en data.columns.
Revisar y corregir
Una consulta contra un nombre de cuenta incorrecto imprime (sin filas) en stderr y aún así sale con código 0. Compara el nombre con la salida de bea list open y ejecuta la consulta nuevamente. Nunca corrijas un total sorprendente editando el libro mayor para que coincida con la respuesta. Corrige la consulta o corrige los libros, luego vuelve a ejecutar bea check.
Primer desafío: cuadrar tres filas sintéticas
Un primer desafío portátil con entradas explícitas y una respuesta derivada independientemente. Descarga los tres archivos a continuación, ejecuta la importación y verifica los dos totales. Sin cuenta y sin pasar por caja.
Libros abiertos el 2026-09-01 en USD con 1000 USD en cuenta corriente. Registra tres filas de septiembre: un pago de cliente de 2000.00 USD, una factura de hosting de 29.00 USD y una visita a un café de 12.50 USD. La cuenta corriente termina en 2958.50 USD, de 1000 + 2000 - 29 - 12.50. La ganancia de septiembre es 1958.50 USD, de 2000 - 29 - 12.50. Ambas expectativas provienen de esa aritmética, no de la salida de informes.
Preparar las entradas
Crea el directorio y abre las dos cuentas que la plantilla no incluye. Expenses:Dining ya viene de la plantilla 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 USDEsos tres comandos producen el libro mayor a continuación. Descárgalo como main.bean en lugar de escribirlo.
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 USDGuarda este estado de cuenta como statement.csv, o descárgalo como statement.csv:
Date,Payee,Amount
2026-09-02,Client,2000.00
2026-09-03,Hosting,-29.00
2026-09-04,Cafe,-12.50Guarda estas reglas como rules.toml, o descárgalas como rules.toml. Cada regla nombra una cuenta que el libro mayor inicial abre.
[[rule]]
match = "client"
account = "Income:Consulting"
[[rule]]
match = "hosting"
account = "Expenses:Software"
[[rule]]
match = "cafe"
account = "Expenses:Dining"Ejecutar el desafío
Vista previa primero, luego aplica y verifica. Los montos, fechas, nombres de campos y nombres de cuentas son idénticos en cada idioma. Solo la prosa que los rodea está traducida.
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-09Verificar la salida esperada
La vista previa informa 3 listos, 0 duplicados exactos, 0 posibles duplicados y sale con código 0. La ejecución de aplicar informa Se escribieron 3 asientos. La verificación no informa errores. La consulta de saldo tiene 2958.50 USD en cuenta corriente. El estado de resultados muestra 2000.00 USD de ingresos de Consultoría contra 41.50 USD de gastos, para una ganancia neta de 1958.50 USD. Repetir la aplicación informa 0 listos, 3 duplicados exactos y escribe 0 asientos.
Cuando una receta se convierte en un trabajo repetido
Los prompts anteriores son aptos para tareas puntuales impulsadas a mano. Los trabajos que repites semanalmente son aptos para las habilidades con versiones en el repositorio del producto. Cada enlace a continuación abre el código fuente actual de la habilidad, que incluye sus propias instrucciones de configuración y activación. Este CMS no guarda copias de estos archivos.
- Comienza un libro mayor nuevo desde un directorio vacío con beancount-init. Crea el archivo del libro mayor, un ejecutor de Fava y un proyecto de Python.
- Convierte una exportación bancaria en asientos categorizados con beancount-import. Organiza cada fila, sugiere categorías desde el historial del libro mayor, omite filas ya importadas y escribe solo después de la confirmación. La receta 1 anterior es la forma manual de este trabajo.
- Prueba que una cuenta coincide con su estado de cuenta con beancount-reconcile. Compara el libro mayor contra el estado de cuenta y registra una afirmación de saldo de fin de período después de la confirmación.
- Responde una pregunta de los libros con beancount-ask. Ejecuta consultas de solo lectura y muestra cada consulta junto a su cifra. La receta 2 anterior es la forma manual de este trabajo.
- Cierra un mes con beancount-close. Concilia cada cuenta activa, verifica asientos recurrentes y banderas de revisión, y registra el cierre como un commit.
La colección completa vive en el árbol canónico de habilidades.
Dale bea a un agente con capacidad de shell, o carga una habilidad en un cliente
Estos son dos pasos separados. Instalar bea nunca instala ni configura habilidades.
Un agente con capacidad de shell necesita el comando en su ruta. Instálalo con la guía de inicio rápido de CLI, luego el agente ejecuta los mismos comandos bea que muestran las recetas. El agente propone, tú revisas y bea valida.
Una habilidad se carga en el propio cliente del agente, mediante el mecanismo de habilidades de ese cliente. El repositorio del producto expone un árbol canónico a ambos clientes compatibles: Claude Code lo lee bajo .claude/skills y Codex bajo .agents/skills, como directorios enlazados a la misma fuente. Apunta la ubicación de habilidades del cliente a la carpeta de habilidades que necesites y sigue leyendo su fuente actual para frases de activación y actualizaciones.
bea ask carga sus propias habilidades por separado, desde un SKILL.md junto a tu libro mayor — consulta Extender bea ask con habilidades.
Preguntas tipo ask sin bea ask
La receta 2 responde preguntas del libro mayor con un agente externo más los comandos de solo lectura bea query y bea report. Esa ruta es local. No necesita cuenta ni instalación adicional.
bea ask es un asistente integrado separado. No es ni la receta anterior ni la habilidad beancount-ask. Enruta la pregunta a través del servicio de IA alojado, por lo que necesita el extra ask y credenciales alojadas, como se documenta en la referencia de CLI. Instala la CLI base primero, luego añade el extra solo cuando quieras respuestas alojadas.
Salidas citadas y verificación de CLI
Cada comando anterior se ejecutó contra el paquete publicado bea 0.1.0 en un directorio nuevo. Los conteos, saldos y mensajes citados son verificación de CLI.
Un cliente ha completado el primer desafío en una copia nueva de las descargas sin reglas proporcionadas de antemano. Muse Code 1.1.1 (modelo muse-spark-1.3-contributor) derivó su propia categorización, previsualizó 3 listos sin escribir nada, aplicó 3 asientos e informó 2958.50 USD en cuenta corriente con 1958.50 USD de ganancia de septiembre — coincidiendo con las expectativas anteriores. Su única aplicación fallida (un bloqueo de caché en sandbox, recuperado mediante XDG_CACHE_HOME) se mantiene en el registro. Lee el prompt completo, la secuencia de herramientas y la verificación en la transcripción de ejecución, o reproduce la ruta de trabajo con el script de demostración y su salida capturada.
Esa ejecución es verificación de salida de CLI de una sola ejecución, no un punto de referencia de modelos. No afirma nada sobre otros clientes, precisión contable en general ni uso de producción sin supervisión.
La historia completa de la prueba — entradas, metodología, resultados observados, fallos, limitaciones y descargas — está publicada como ¿Puede tu agente cuadrar estos libros?.
Explora la investigación más amplia detrás de estos flujos de trabajo en Bean Labs, el centro de investigación de automatización contable de Beancount.io.