Playbook: Build a Reconciliation Agent Across Two Systems
Your finance team reconciles data between two systems that do not talk to each other. Maybe it is your billing system and your payment processor. Maybe it is your ERP and your bank. Maybe it is your CRM and your invoicing tool. Every month, someone exports data from both, pastes it into a spreadsheet, and hunts for mismatches. It takes hours, it is error-prone, and when it finds a problem, the problem is already a month old. This playbook walks you through building an agent that reconciles the data automatically and a sandcastle app that tracks discrepancies and their resolution.
What you will build
By the end of this playbook, you will have:
- Custom tools that pull data from both systems
- A reconciliation agent that runs weekly, compares records across systems, and identifies mismatches
- A sandcastle app where the finance team reviews discrepancies, tracks resolution, and sees trends
- Persistent state that maintains a full history of every discrepancy found, when it was found, and how it was resolved
- Slack alerts for new discrepancies so the team does not have to check the app proactively
This playbook uses a billing system and payment processor as the example, but the pattern works for any two systems that should agree: ERP and bank statements, CRM and invoicing, inventory and shipping, HR system and payroll.
What you need before you start
- An Assist workspace with an MCP server set up. If you have not created one yet, follow Creating an MCP server.
- Your AI client connected to the MCP server. See Connect your client.
- Access credentials for both systems' APIs.
- An understanding of what a "match" means for your data. For billing and payments, this is usually: invoice number, amount, and date. For other systems, define which fields should agree and what tolerance is acceptable (for example, amounts within $0.01, dates within 1 business day).
Step 1: Define the reconciliation rules
Start by telling the AI what you are reconciling:
"I want to build a reconciliation system between our billing platform (https://billing.internal.company.com/api) and our payment processor (https://api.payments-provider.com). Here's what should match:
- Every invoice in billing should have a corresponding payment in the processor
- Every payment in the processor should have a corresponding invoice in billing
- For matched records, the amounts should be within $0.01 of each other
- For matched records, the payment date should be within 2 business days of the invoice date
- Invoice number in billing maps to reference_id in the payment processor
Common discrepancies we find manually:
- Payments with no matching invoice (customer paid but we did not bill)
- Invoices with no matching payment (we billed but payment was not received or was not recorded)
- Amount mismatches (partial payments, double charges, currency rounding)
- Duplicate payments for the same invoice"
The AI will help you refine the matching logic. Let it ask questions about edge cases: How do refunds appear? Are there recurring invoices with the same number? Do you reconcile by invoice or by line item?
Step 2: Build the data extraction tools
Build tools that pull data from each system in a consistent format:
"Create a tool called 'get_billing_invoices' that takes a date range (start_date, end_date) and returns all invoices from our billing platform with: invoice_number, customer_name, amount, currency, invoice_date, status (paid/unpaid/partial/void), and payment_reference if available."
"Create a tool called 'get_processor_payments' that takes a date range and returns all payments from our payment processor with: transaction_id, reference_id (this maps to invoice_number), amount, currency, payment_date, status (completed/pending/failed/refunded), and payer_name."
Test both tools with the same date range and manually verify a few records match what you see in each system:
"Pull all invoices from March 2026 from the billing system."
"Pull all payments from March 2026 from the payment processor."
"Show me invoice INV-2026-0342 from billing and find its matching payment in the processor results."
Step 3: Build the reconciliation engine
Now build the tool that does the actual comparison:
"Create a tool called 'reconcile_period' that takes a date range and does the following:
- Pull all invoices from billing for that period
- Pull all payments from the processor for that period
- Match records by invoice_number = reference_id
- Classify each record into one of these categories:
- matched: Invoice and payment found, amounts match within $0.01, dates within 2 business days
- amount_mismatch: Invoice and payment found, but amounts differ by more than $0.01
- date_mismatch: Invoice and payment found, amounts match, but dates differ by more than 2 business days
- missing_payment: Invoice exists in billing but no matching payment in processor
- missing_invoice: Payment exists in processor but no matching invoice in billing
- duplicate_payment: Multiple payments in processor match the same invoice
- Return a summary with counts for each category and the full list of discrepancies with details from both systems"
Test it on a recent month:
"Reconcile March 2026. How many discrepancies did you find?"
Review the results. Check a few discrepancies manually to verify the tool is classifying them correctly. Adjust the matching rules if needed:
"Our billing system sometimes prefixes invoice numbers with 'INV-' but the payment processor stores them without the prefix. Update the matching logic to strip 'INV-' when comparing."
"Refunds appear as negative amounts in the processor. They should match to credit memos in billing which have negative amounts too. Make sure the reconciliation handles negatives correctly."
Step 4: Build the reconciliation agent
Turn the reconciliation into a scheduled agent:
"Create a subagent that runs every Monday at 6:00 AM. It should:
- Reconcile the previous 7 days
- Also re-check any unresolved discrepancies from prior weeks (pull these from persistent state)
- Compare this week's results to last week's:
- New discrepancies: found this week for the first time
- Resolved discrepancies: were flagged last week but now match (payment came through, invoice was corrected, etc.)
- Ongoing discrepancies: still unresolved from prior weeks
- Store all results in persistent state with: discrepancy_id, type, invoice_number, billing_amount, processor_amount, difference, first_found_date, status (new/ongoing/resolved), resolution_notes
- Post a summary to #finance-ops in Slack:
- 'Weekly reconciliation: X new discrepancies, Y resolved, Z ongoing'
- List new discrepancies with details
- List ongoing discrepancies older than 2 weeks (these need attention)
- Total unreconciled amount"
The agent uses persistent state to track discrepancies across runs. This is what makes it more than a script -- it knows what it found last week and can tell you what changed. A discrepancy that auto-resolves (the payment came through late) gets marked as resolved without anyone doing anything. A discrepancy that persists for three weeks gets escalated in the Slack summary.
Step 5: Build the reconciliation dashboard app
The Slack summary gives the team a weekly pulse. The sandcastle app gives them a place to investigate and resolve discrepancies.
"Build me a sandcastle app for financial reconciliation. It should have these views:
Summary dashboard: Show the results of the latest reconciliation run. Display counts by discrepancy type in a bar chart. Show total unreconciled amount prominently. Show a trend line of discrepancies per week over the last 12 weeks.
Discrepancy list: A filterable table of all discrepancies. Columns: discrepancy_id, type, invoice_number, customer, billing_amount, processor_amount, difference, first_found_date, age (days), status, assigned_to. Filters for type, status, age range, and amount range.
Discrepancy detail: Click a row to see full details from both systems side by side. Show the invoice record from billing on the left, the payment record from the processor on the right, with mismatched fields highlighted. Below, show an action section where someone can:
- Assign the discrepancy to a team member
- Add notes about what they found
- Mark it as resolved with a resolution type (payment received, invoice corrected, write-off approved, duplicate voided, other)
- Escalate it to a manager
Resolution history: A log of all resolved discrepancies with resolution type, who resolved it, when, and notes. This serves as the audit trail.
Aging report: Discrepancies grouped by age bracket (0-7 days, 7-14 days, 14-30 days, 30+ days) with total amounts. Items over 30 days should be visually flagged."
Iterate on the app:
"Add a 'bulk action' feature to the discrepancy list. Let users select multiple discrepancies and assign them all to one person or mark them all as a specific resolution type."
"On the summary dashboard, add a section showing resolution rate: what percentage of discrepancies get resolved within 7 days, 14 days, 30 days. Show this as a trend over the last quarter."
"Add a 'customer view' that groups discrepancies by customer name. This helps identify customers with systematic billing issues."
Step 6: Add escalation logic to the agent
Teach the agent to flag high-priority issues:
"Update the reconciliation agent to escalate these scenarios:
- Any single discrepancy over $10,000
- Any customer with more than 5 unresolved discrepancies
- Any discrepancy older than 30 days that has not been assigned
- Total unreconciled amount exceeding $50,000
For escalations, post a separate message to #finance-leadership with the specific items and why they were escalated."
"Also update the agent to detect patterns: if the same type of discrepancy (for example, amount_mismatch) increases by more than 50% week over week, flag it as a systemic issue that might indicate a configuration problem rather than individual errors."
Step 7: Add ad-hoc reconciliation from your AI client
The scheduled agent covers weekly checks, but sometimes the team needs to investigate immediately. Because the tools are on the MCP server, anyone with access can run a reconciliation from their AI client:
"Reconcile the last 3 days. Did any large payments come through that do not match an invoice?"
"Show me all unresolved discrepancies for Acme Corp."
"What's the total unreconciled amount for Q1 2026?"
The AI uses the same tools the agent uses. The results are consistent whether you check from the app, from Slack, or from a conversation.
Step 8: Extend over time
As the team uses the system, add capabilities:
"Create a tool that pulls bank statement data from our bank's API. Add a third reconciliation layer: billing, payment processor, and bank statement. This catches cases where the processor shows a payment but the bank does not."
"Add a month-end close view to the app that shows: total invoiced, total collected, total unreconciled, and a sign-off button where the finance manager confirms the month is closed. Store the sign-off in collections as an audit record."
"Create a tool that generates a reconciliation report PDF for external auditors. It should include the summary, all discrepancies, resolutions, and the sign-off."
"Add a tool that checks for duplicate invoices within billing: same customer, same amount, within 7 days. These often indicate a billing system error rather than a payment issue."
What you built
You now have an automated reconciliation system:
- Tools that pull data from both systems and compare them against your matching rules
- A reconciliation agent that runs weekly, tracks discrepancies over time, and alerts the team to new issues
- A dashboard app where the finance team investigates discrepancies, assigns work, tracks resolution, and maintains an audit trail
- Persistent state that gives the system memory: it knows when a discrepancy was first found, how long it has been open, and how it was resolved
- Escalation logic that surfaces high-priority issues and detects systemic problems
The monthly spreadsheet exercise is now a weekly automated check. Discrepancies are found in days instead of weeks. The audit trail is automatic. When the person who usually does the reconciliation is out, the agent still runs and the team still has full visibility.