# Bkper Agent

Bkper Agent turns documents and short descriptions into draft transactions inside Bkper. Use it to reduce data entry while keeping each result as a draft until you post it.

This page is a usage guide. The canonical app overview and current configuration reference live at [Bkper Agent](https://bkper.com/apps/bookbot.md).

> **Note: Source of truth**
> AI extraction creates drafts, not final records. In Bkper, drafts do not affect balances. Posted transactions move resources from one Account to another and update the Book.
## When it runs

Bkper Agent is installed automatically on every Book. You do not start a session or connect a separate assistant. It runs from Book events such as:

- **file uploaded** — extracts transactions from receipts, invoices, bills, statements, and CSVs;
- **transaction created** — updates transactions from attached files and uses descriptions to suggest dates, amounts, Accounts, hashtags, and properties;
- **transaction posted or updated** — learns from corrected drafts and improves future extraction patterns.

This is different from [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md), which is an interactive terminal assistant you start yourself for local files, scripts, tests, and Bkper CLI commands. It is also different from [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md), which connects conversational assistants to Bkper through MCP tool calls.

For calculations, reports, reconciliations, or tax worksheets, use deterministic tools and reviewable scripts instead. See [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md).

## How documents become drafts

| Input                                    | What Bkper Agent does                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| Receipt, invoice, or bill                | One transaction with extracted date, amount, description, and properties |
| Bank or credit card statement            | One transaction per recognized statement row                             |
| CSV statement                            | Multiple transactions from rows                                          |
| File attached to an existing transaction | The existing transaction is updated and keeps the file                   |
| Email forwarded to a Book                | Attachments are parsed and kept with the resulting drafts                |

## Guide the Agent

Good results come from clear context and consistent corrections.

1. **Start from the right Account.** The Agent uses the selected context and historical transactions to infer the missing side of the movement.
2. **Use consistent descriptions and hashtags.** Reusing tags such as `#rent`, `#software`, or `#client_acme` gives the Agent stronger signals for future account matching.
3. **Correct drafts before posting.** Fix the date, amount, Accounts, description, hashtags, and properties. Posted corrections help the Agent improve future extraction.
4. **Prefer repeated corrections over one-off prompts.** If a vendor, bank, or statement format repeats, your corrected posted transactions become useful training examples.
5. **Add explicit instructions only for stable patterns.** If the same document type is repeatedly parsed wrong, add Account or Group instructions such as which column to use, which total to extract, or which property name to fill. Keep instructions factual and narrow.

For hashtag hygiene and account-matching signals, see [Hashtags](https://bkper.com/docs/guides/using-bkper/hashtags.md). For advanced prompt and parser properties, use the [Bkper Agent app reference](https://bkper.com/apps/bookbot.md#configuration).

## Before posting

Before posting an AI-created draft, check:

- **Date** — matches the transaction, purchase, service, posting, or payment date you intend to record.
- **Amount** — matches the source document or statement row.
- **From and To Accounts** — represent the actual resource movement in Bkper's from-to model.
- **Description and hashtags** — are searchable and consistent with your Book.
- **Properties** — include useful metadata, but not noisy values you do not report on.
- **Attachment** — belongs to the transaction and remains available as evidence.
- **Duplicates** — especially after importing statements or forwarding the same document twice.

If the draft is incomplete, keep it as a draft until the missing Account, date, amount, or evidence is resolved.

## Related guides

- [Bkper Agent app reference](https://bkper.com/apps/bookbot.md) — current capabilities, configuration properties, and supported file types.
- [Record Transactions by Email](https://bkper.com/docs/guides/using-bkper/record-by-email.md) — forward invoices, receipts, and statements to a Book.
- [Attachments](https://bkper.com/docs/guides/using-bkper/attachments.md) — keep documents with the transactions they support.
- [Hashtags](https://bkper.com/docs/guides/using-bkper/hashtags.md) — use tags consistently so the Agent can match patterns.
- [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md) — keep AI-assisted financial work reviewable and deterministic.