Agent Patterns

The following patterns have proven themselves in practice when agents work with the general ledger via MCP. They build on a single core principle: read first, then propose, then get confirmation, then write. This minimizes incorrect postings and keeps every step traceable.

Proven patterns

Pattern 1 Read → Propose → Confirm → Write

The standard flow for any posting agent. Before anything is written to the ledger, the agent loads real data (accounts, periods, documents), forms a proposal, and obtains an explicit approval. Only then does it write. This pattern makes decisions transparent and prevents the agent from "guessing in the dark".

1 Load context: chart of accounts, open periods, and existing postings where relevant (read tools)
2 Form a posting proposal — with real account numbers and periods from the tenant, not from the model's training
3 Show the proposal to the user and obtain explicit approval
4 Only write after confirmation (post_booking or post_booking_with_document)

Pattern 2 Bank reconciliation in two stages

Bank transactions should never be reconciled fully automatically and opaquely. The pattern splits the process into two phases: first load suggestions and show them to the user, then reconcile selectively. This keeps a human in the decision loop and keeps the reconciliation status traceable at all times.

1 Load open transactions: get_unreconciled_transactions + get_reconciliation_suggestions
2 Show suggestions with confidence scores to the user — what matches confidently, what needs review?
3 After approval, reconcile selectively: reconcile_bank_transaction per approved match

Pattern 3 Posting with document in a single step

When the document and posting data come from the same pipeline — for example an outgoing invoice that comes straight out of a document workflow — both can be combined in a single tool call. This avoids a separate upload phase and keeps the document and posting linked from the start.

1 Prepare the document (PDF, image) and posting data together
2 MCP: post_booking_with_document — document and posting are stored atomically
3 Alternatively via REST: POST /v1/bookings/with-document — identical behavior

Pattern 4 Skill-driven workflow

For recurring high-level tasks (process an invoice, reconcile a bank statement, close a month), the MCP server ships ready-made playbooks as prompts. Instead of the agent reinventing the workflow, it loads the matching skill and follows its steps. Skills compose the patterns above — they codify the same read-propose-confirm-write discipline with task-specific tool sequences and tax/scope gates.

1 prompts/list — discover the skills available for the caller's scopes (scope-gated)
2 prompts/get <skill_name> — fetch the playbook. Server auto-selects EN or DE by tenant locale; override via args.locale
3 Execute the workflow from the playbook's step list, respecting its confirmation gates and escape hatches
4 Fall back to Pattern 1 when no skill matches the task — or read the skill markdown as a resource (ledgerlou://skills/<slug>) on clients without prompt support

Anti-patterns (avoid)

These patterns lead to incorrect postings or compliance issues

Posting directly without an upfront check — always load the chart of accounts and periods first. Accounts the model knows from training may not exist in the tenant or may be locked.
Write keys for analysis agents — an agent that only reads gets only read scopes. Broad write rights for read-only agents are a security risk with no benefit.
Running sensitive tools automatically without confirmation — tools such as post_booking or reconcile_bank_transaction should always require an explicit user approval before they are executed.
General-ledger postings relying on model training — always load SKR account numbers, periods, and tenant data live from the general ledger, never from the model's context window. Training data can be outdated or incomplete.

Core principle

Each of these patterns follows the same core: the agent first loads facts from the real ledger, then proposes something, and only writes after explicit confirmation. That way the behavior stays deterministic, auditable, and GoBD-compliant — regardless of which model or which AI app is used.