Commission reconciliation: repair what can be repaired, hand off the rest

Scenario

A typical scenario: in commission reconciliation the hard part is the evidence. The ledger says the commission was settled at 5%, the agent agreement summary says 7%, and the summary carries neither an effective start and end date nor the version number of the rate table in force on the transaction date. Without those two, any rate is a guess.

The example's rule: insufficient evidence is a typed terminal state, and the system stops there and hands off to a person. It first states exactly what is missing, then looks for it specifically, and if it cannot be found, hands the whole evidence package to a person.

How it works

The models in the table are the example repository's defaults; the actual choice is made per scenario at the design stage.

All four agents are bound to a deterministic adapter that computes its return value from the prompt content. Only the model call is replaced: scheduling, dependency injection, failure detection and plan repair all run through OMA's real code paths. Every task sets maxRetries: 0, memoryScope: 'dependencies' and dependencyPayload: 'structured', and the team sets sharedMemory: false, so a downstream task only receives the Zod-validated structured results of its direct predecessors.

The arbiter has an afterRun hook: when the output is valid JSON but its content is an "insufficient evidence" diagnosis, the hook marks the run as failed and returns normally, leaving the diagnosis and usage for the replanner to read. The replanner reacts only to this one typed failure: it adds four tasks in one revision and cancels the old output task that has not run yet. The repair budget is fixed at maxPlanRevisions: 1 / maxAddedTasks: 4 (framework defaults 3 / 20).

Result

Runnable artifacts and how to verify them:

Runs with no API key. The source header states "No API key, network request, or Bash is required", and the official README lists it under "No API key needed". Two commands: npx tsx packages/core/examples/cookbook/commission-reconciliation-recovery.ts --case recovered, and the same with --case unresolved at the end.

--case recovered goes through the repair path. Local run (2026-09-06): the initial reconciliation fails and the old output task is cancelled; one plan revision adds 4 tasks, retrieves the agreement's effective period and the rate-table version, and reconciles again, outputting status: "RECONCILED", selectedRule: "AGENT_AGREEMENT", disposition: "UNDERPAID" and 5 source IDs, exit code 0. All amounts come from synthetic records inlined in the script.

--case unresolved goes to a person, as designed. Local run (2026-09-06): the archive has no agreement record, and the replacement reconciliation still lacks the agreement's effective period. The replanner proposes a fifth task, the framework's real revision limit rejects it, and the task graph stops growing; outside the orchestration the result is mapped to MANUAL_REVIEW_REQUIRED, with the missing items, source IDs and next action attached, exit code 1.

The schema keeps amount fields out of the failure state. Zod strict mode blocks rate and amount fields in the insufficient-evidence output shape, and the repository's tests assert this field by field; the source header states "No payment is adjusted", and the result JSON on the recovered path carries a note saying the same.

Sources

How this relates to YuanASI

The material on this page is a cookbook example in the official open-multi-agent repository, maintained by YuanASI; all records, rules and amounts are synthetic.

If you run a reconciliation or claims-verification process that gathers evidence across several systems, and you need the rule "say plainly when evidence is missing, fill the gap where possible, and hand off to a person with the evidence package when not", with every repair step auditable, the matching YuanASI service is Multi-Agent System Integration →