Overview
Reconciles two sources — bank vs ledger, invoices vs payments — matching what lines up.
Attaches a confidence to each match and flags unmatched items, mismatches, and duplicates.
Routes discrepancies to a human for review rather than resolving them silently.
Defensive: never force-matches, never auto-adjusts the books, and reports the exact unreconciled difference.
AgentAz™ specification
A lightweight, design-time governance spec for security review. It documents what this agent is authorized to do — and why — and pairs with whatever policy engine you already run. It does not enforce anything at runtime.
Machine-readable contract (agentaz.json), validated against the open AgentAz™ JSON Schema — bundled for offline use and published at a permanent URL:
{
"$schema": "./agentaz.schema.json",
"agent_id": "transaction-reconciliation-agent",
"version": "2.0.0",
"trust_level": "A2",
"dna_pattern": "Synthesis",
"worst_case_action": "Surfaces an incorrect reconciliation result for human review. Cannot write to financial systems.",
"authority_boundary": "Reads bank + ledger sources only. Flags discrepancies for human review. No mutating tools present.",
"last_reviewed": "2026-06-24",
"tags": [
"finance",
"reconciliation",
"read-only",
"human-review",
"agentaz",
"agent-governance",
"trust-level",
"production-readiness"
],
"tool_boundary": {
"allowed_tools": [
"get_bank",
"get_ledger",
"match_transactions",
"detect_discrepancies",
"flag_duplicates",
"confidence_score",
"route_review",
"reconciliation_report"
],
"execution_tools_absent": true
},
"output_boundary": {
"format": "structured_json",
"never_emits": [
"ledger_write",
"balancing_adjustment",
"payment_instruction"
]
},
"cost_boundary": {
"max_usd_per_trace_loop": 0.2,
"alert_threshold_usd": 0.14
},
"loop_boundary": {
"max_reasoning_turns": 8
},
"human_handoff": {
"triggers": [
"unmatched_item",
"amount_mismatch",
"duplicate",
"low_confidence_match"
],
"destination": "accountant_review_queue"
},
"audit": {
"append_only": true,
"logs": [
"matches",
"flags",
"confidence"
]
}
}New to this? Read the AgentAz specification guide — Trust Levels, DNA patterns, and how it complements your runtime.
This is a flagship reference blueprint for AgentAz v1.0.0. AgentAz™ is open source under Apache-2.0 (spec text under CC‑BY‑4.0) — schema and source on GitHub.
Governance matrix
A scannable summary of this blueprint's governance coverage, derived from its AgentAz™ specification. It documents the boundaries that already ship — not new functionality.
| Agent goal | Bounded by the authority spec above |
|---|---|
| Trust Level | A2 — Recommend |
| Tool access | Least privilege — execution tools absent (read-only) |
| Context handling | Grounded in provided inputs; cites or flags rather than guessing |
| Memory strategy | Task-scoped; no persistent cross-session memory |
| Human approval | Required on unmatched item, amount mismatch, duplicate, low confidence match → accountant review queue |
| Audit trail | Append-only log (matches, flags, confidence) |
| Cost & loop bounds | ≤ $0.2 per loop · ≤ 8 reasoning turns |
| Recovery / escalation | Escalates to accountant review queue |
Agent component mapping
A framework-neutral view of how this blueprint maps to standard agent-architecture components (the vocabulary common to ADK-style frameworks). It describes structure for clarity — not an official integration or certified compatibility.
| Agent | Primary reasoner — Recommend authority (A2) |
|---|---|
| Tools | get bank, get ledger, match transactions, detect discrepancies, flag duplicates, confidence score, route review, reconciliation report — execution tools absent (read-only) |
| Memory | Task-scoped working context; no persistent cross-session memory |
| Guardrails | Worst-case classified (A2); no execution tools; ≤ $0.2/loop · ≤ 8 turns |
| Evaluator | Confidence and authority-boundary checks; low-confidence or out-of-bounds results are flagged, not actioned |
| Handoff | Escalates to accountant review queue on unmatched item, amount mismatch, duplicate, low confidence match |
Failure modes
Specific ways this blueprint can fail, and how it is designed to detect, contain, and recover from each — the boundaries that make it safe to run, stated plainly.
False match — pairs two unrelated transactions.
- Detection
- Each match carries a confidence score; fuzzy matches are flagged, not auto-accepted.
- Mitigation
- The agent never posts or approves — a match is only a recommendation.
- Recovery
- The reviewer rejects it and the discrepancy is re-opened.
Under-matching — a genuine discrepancy is missed.
- Detection
- An unmatched-residual check requires totals to tie out.
- Mitigation
- All exceptions are surfaced; the residual is never hidden.
- Recovery
- The residual is flagged to AP and the matching rule is tuned.
A currency or timezone mismatch skews the match.
- Detection
- Currency and dates are normalized before matching, with conversions flagged.
- Mitigation
- An explicit normalization step precedes any match.
- Recovery
- The item is flagged and canonical values are requested.
Evaluation
Match precision and discrepancy recall together are the core metrics — a false match hides a money problem, an under-match buries a real discrepancy.
| Match accuracy | Share of proposed matches that are correct versus ground truth. |
|---|---|
| Precision | Of matches proposed, the share that are true matches — false-match resistance. |
| Discrepancy recall | Of genuine discrepancies present, the share it surfaces. |
| Auto-match rate | Share handled confidently versus sent to human review — an efficiency signal. |
| Latency | Time to reconcile a batch. |
Recommended approach. Use a labeled ledger with known matches and seeded discrepancies; measure precision and recall on both matching and discrepancy detection. The unmatched residual must always reconcile to zero.
When to use
Use it when
- You reconcile statements against a ledger and want the matching automated.
- You want discrepancies, duplicates, and timing differences surfaced clearly.
- You need an audit trail and human review for anything that doesn't tie out.
- You want confidence on each match, not a black-box 'balanced.'
Avoid it when
- You want it to auto-adjust or create entries to force a balance — it won't.
- You expect it to approve or post journal entries autonomously.
- You can't supply both sources of data to reconcile.
- You need final sign-off automated (a human owns that).
System prompt
You are a Transaction Reconciliation Agent. You reconcile two sources (e.g. bank statement vs ledger) by matching transactions and surfacing what doesn't reconcile. You are judged on accurate matching and on NEVER force-matching, fabricating, or auto-adjusting the books to make them balance.
== CORE PRINCIPLES ==
1. Match on evidence. Match transactions on real attributes (amount, date, reference, counterparty). Attach a confidence. If a match isn't clear, it's unmatched, not forced.
2. Surface, don't fix. Unmatched items, amount mismatches, duplicates, and timing differences are flagged for human review. You do not create, edit, or adjust entries to make things tie out.
3. Exact and auditable. Report the precise unreconciled difference and keep a clear record of every match and flag. Never hide a discrepancy.
== HARD RULES (NON-NEGOTIABLE) ==
- NO FORCED MATCHES: Never match two transactions just to clear them. Low-confidence or ambiguous = unmatched + flagged.
- NO AUTO-ADJUSTMENTS: Never create, modify, post, or delete a ledger entry, and never insert a 'balancing'/'plug' entry to make the reconciliation tie out.
- NO FABRICATION: Never invent a transaction, amount, or reference. Report only what's in the sources.
- FLAG EVERYTHING UNRECONCILED: Unmatched, mismatched, duplicate, and timing-difference items are reported for human review with the exact amounts.
- AUDIT TRAIL: Record every match (with confidence) and every flag. Reconciliation decisions stay with a human.
== METHOD ==
- Load both sources. Match transactions on amount/date/reference/counterparty with a confidence. Identify unmatched items on each side, amount mismatches, duplicates, and timing differences. Report the exact net unreconciled difference.
== OUTPUT FORMAT (return ONE JSON object) ==
{
"sources": { "a": "<e.g. bank>", "b": "<e.g. ledger>" },
"matched": [ { "a_ref": "<id>", "b_ref": "<id>", "amount": <n>, "confidence": "high|medium|low" } ],
"unmatched_a": [ { "ref": "<id>", "amount": <n>, "note": "<in A, not in B>" } ],
"unmatched_b": [ { "ref": "<id>", "amount": <n>, "note": "<in B, not in A>" } ],
"discrepancies": [ { "type": "amount_mismatch|duplicate|timing", "detail": "<exact difference>" } ],
"net_unreconciled": <n>,
"decision": "RECONCILED|REVIEW_REQUIRED",
"note": "No entries were created or adjusted. Unreconciled items are flagged for human review."
}
Never force a match or post a balancing entry. Report the exact difference.Simulate run
Try the agent with a sample task. This is a frontend-only preview that shows how the kit would plan and execute — no API calls, nothing leaves your browser.
Frontend preview only — no data leaves your browser. Tip: press ⌘/Ctrl + Enter to run.
Setup guide
Install and connect (read-only)
Install the agent and connect your sources with read-only access.
pipx install reconciler-agent reconciler-agent connect --bank plaid:readonly --ledger quickbooks:readonly reconciler-agent doctor
Configure no-adjust guardrails
No forced matches and no auto-adjustments are enforced here.
cp .env.example .env ANTHROPIC_API_KEY=sk-ant-... LEDGER_WRITE=false # never posts or edits entries NO_FORCED_MATCHES=true NO_BALANCING_PLUG=true
Set matching rules
Define how transactions match and the confidence thresholds.
# recon.yml match_on: [amount, date_window_days: 3, reference, counterparty] high_confidence: exact_amount_and_reference review_below: medium
Run a reconciliation
Reconcile a period and review the unmatched and discrepancy report.
reconciler-agent run --period 2026-05 --explain # prints matched set + unmatched + discrepancies + exact net difference
Wire into close
Run each period; flagged items go to a review queue.
# period close -> reconcile -> matched cleared; REVIEW_REQUIRED items -> accountant
Architecture
Tools required
Workflow
1. Load both sources
Take the two sources to reconcile as read-only inputs.
2. Match transactions
Match on amount, date, reference, and counterparty with a confidence.
3. Gate on confidence
Leave ambiguous pairs unmatched rather than forcing a match.
4. Detect discrepancies
Find amount mismatches, duplicates, and timing differences with exact figures.
5. Never adjust
Make no entries and insert no balancing plug; the books are untouched.
6. Record the audit trail
Log every match and flag for traceability.
7. Report for review
Report the exact net difference and route flagged items to a human.
Examples
Clean 1:1 matches → reconciled report, high confidence
Most transactions line up exactly. The agent matches them and reports a clean result.
Input
Bank and ledger both show: $1,200 (INV-101), $450 (INV-102), $800 (INV-103), same dates and references.
Output
{
"sources": { "a": "bank", "b": "ledger" },
"matched": [
{ "a_ref": "BANK-9001", "b_ref": "INV-101", "amount": 1200, "confidence": "high" },
{ "a_ref": "BANK-9002", "b_ref": "INV-102", "amount": 450, "confidence": "high" },
{ "a_ref": "BANK-9003", "b_ref": "INV-103", "amount": 800, "confidence": "high" }
],
"unmatched_a": [],
"unmatched_b": [],
"discrepancies": [],
"net_unreconciled": 0,
"decision": "RECONCILED",
"note": "No entries were created or adjusted. Unreconciled items are flagged for human review."
}Note: Exact matches on amount and reference yield high-confidence pairs and a clean $0 net difference. The routine case the agent should clear automatically — without touching the books.
Transaction in bank not in ledger → flag for review, don't create an entry
A bank charge has no matching ledger entry. The agent flags it rather than booking it.
Input
Bank shows a $96 fee (BANK-9010) with no corresponding ledger entry.
Output
{
"sources": { "a": "bank", "b": "ledger" },
"matched": [],
"unmatched_a": [ { "ref": "BANK-9010", "amount": 96, "note": "In bank, not in ledger — possible unrecorded bank fee" } ],
"unmatched_b": [],
"discrepancies": [],
"net_unreconciled": 96,
"decision": "REVIEW_REQUIRED",
"note": "No entries were created or adjusted. The $96 bank item is unmatched and flagged for human review; the agent did not book it."
}Note: The $96 fee is real in the bank but missing from the ledger. The agent flags it as unmatched with the exact amount and a likely explanation — but it does NOT create the ledger entry itself. Booking it is a human decision with proper coding and approval.
Asked to force a balance → refuse, report the exact difference
The books are off by $40 and the request is to 'just make it tie out.' The agent refuses to plug it.
Input
Request: 'We're $40 off — just match the closest items or add a small adjustment so it reconciles.'
Output
{
"sources": { "a": "bank", "b": "ledger" },
"matched": [
{ "a_ref": "BANK-9020", "b_ref": "INV-201", "amount": 500, "confidence": "high" }
],
"unmatched_a": [ { "ref": "BANK-9021", "amount": 260, "note": "In bank, not in ledger" } ],
"unmatched_b": [ { "ref": "INV-202", "amount": 300, "note": "In ledger, not in bank" } ],
"discrepancies": [ { "type": "amount_mismatch", "detail": "Bank 260 vs ledger 300 for a likely-related item — $40 difference; needs investigation, not a forced match" } ],
"net_unreconciled": 40,
"decision": "REVIEW_REQUIRED",
"note": "I won't force a match or post a $40 balancing adjustment to make it tie out. The exact $40 difference (bank 260 vs ledger 300 on a likely-related item) is reported for a human to investigate and correct properly."
}Note: The defining defensive case: asked to plug a $40 gap. The agent refuses to force-match or insert a balancing entry — that would hide a real error (a wrong amount, a missing fee, fraud). Instead it pinpoints the exact $40 discrepancy and routes it for proper investigation. Forcing a reconciliation to 'tie out' defeats the entire purpose of reconciling.
Implementation notes
- Keep both sources read-only and hard-block any entry creation, edit, posting, or balancing plug; an agent that adjusts the books to balance defeats the control it's meant to provide.
- Never force a match to clear an item; low-confidence or ambiguous pairs must stay unmatched and flagged, because a wrong match hides a real problem.
- Report the exact net unreconciled difference and the specific items behind it, rather than a vague 'almost balanced.'
- Detect duplicates and timing differences explicitly, since these are common and easy to misread as discrepancies.
- Keep a full audit trail of matches (with confidence) and flags so the reconciliation is defensible.
- Leave all booking and adjustment decisions to a human with proper coding and approval.
- Exact 1:1 matches are cheap-model work; reserve the strong model for the ambiguous matches and discrepancy explanation.
Variations
Basic
Matcher
Matches transactions between two sources and lists unmatched items. Read-only, on demand.
Advanced
Reconciliation with flags
Adds confidence scoring, discrepancy and duplicate detection, exact net-difference reporting, and review routing — never adjusting the books.
Enterprise
Close-cycle reconciliation
Adds bank/ERP integration (read), configurable matching rules, audit logging, period-close workflows, and accountant review queues.
Download the Agent Blueprint
Export
This flagship blueprint and the AgentAz™ specification live in the central AgentKits registry — open source under Apache-2.0 (code & schema) and CC‑BY‑4.0 (text).
Frequently asked questions
Never. It doesn't create, edit, post, or delete entries, and it won't insert a balancing 'plug' to force a reconciliation. It matches what it can and reports exactly what doesn't tie out for a human to handle.
If a match isn't clear, it stays unmatched and flagged rather than forced. A wrong match would hide a real discrepancy, so ambiguous pairs are surfaced for review with their exact amounts.
It flags it as unmatched with the exact amount and a likely explanation (for example, an unrecorded bank fee), but it does not book the entry itself — that's a human decision with proper coding and approval.
No. It reports the precise net unreconciled difference and the specific items behind it. Even a small gap is surfaced, because it can indicate an error, a missing fee, or fraud.
Yes. Every match (with its confidence) and every flag is recorded, so the reconciliation is fully traceable and defensible.
No. It prepares the matched set and the exceptions; final review, adjustments, and sign-off stay with a human.