LangGraph · FastAPI · MCP

AI Multi-Agent
Workflow Engine

You type a business request in plain English. A router figures out what kind of job it is, sends it to the right specialist agent, and that agent does the work using a shared set of tools. If the job involves money, everything stops and waits for a human before anything is paid. That is the whole idea.

85.0% autonomous resolution*
100% routing accuracy*
20 golden-set eval cases
0 payments without approval

* Measured by python -m app.eval on this repo's 20-case golden set. See results.

What this is

No jargon needed. Here is the idea in three sentences.

🏢

The problem

Business teams get the same requests all day: “Is this invoice real?”, “What do we owe this vendor?”, “What is the leave policy?” Answering them by hand is slow, and letting an AI pay invoices on its own is dangerous.

🤖

The idea

Split the work between specialists. One agent only handles invoices, one only writes reports, one only looks up data, one only answers policy questions. A router sends each request to the right specialist, and every specialist uses the same toolbox.

🛡️

The safety net

Reading is free, paying is not. Anything that moves money pauses for a human — the system literally cannot pay without an approval. And if a multi-step job fails halfway, it undoes the steps it already did, so nothing is left half-finished.

How it works, step by step

The animation starts when you scroll here. Click any step to highlight it in the diagram.

How a request flows through the engine One request in. One verified result out. A human steps in only when money is involved. Request a business question Router classifies intent Domain Agents Invoice · Report Lookup · Policy MCP Tools lookup · validate search · draft HITL Gate human approves money moves Result citations + trace 👤 Human approves / rejects ✓ Every tool call goes through the MCP server — agents never touch data directly. ✓ If a step fails mid-way, the saga reverses the steps already done. Nothing is left half-applied.
1 · Request — You type a request in plain English — for example, “Approve payment for invoice INV-1003” or “What is the expense reimbursement limit?”. No forms, no special syntax. The request is just a sentence, and the engine treats it as a job to be done.

Watch a workflow run

Pick a request, press Play, and watch it move. The dot is the request. A station lights up only while it is working. When money is involved, the flow stops at the human gate and waits for you.

Press Play the run to send the request through the engine.

Input

Request

“Validate invoice INV-1001”

LangGraph

Router

Reads the request and picks an intent.

LangGraph nodes

Domain agents

One specialist takes the job. The others stay dark.

InvoiceAgent ReportAgent DataLookupAgent PolicyAgent
FastMCP · /mcp

MCP tools

Agents never touch data. Every call goes through this toolbox.

LangGraph interrupt()

Human gate

Money moves stop here. Nothing is paid without a human.

Compensating saga

Payment steps

Three steps, each with its own undo. A failure runs the undos in reverse.

1 · Reserve funds 2 · Post ledger entry 3 · Notify vendor
Result

Result

Answer, citations, trace, cost.

Trace · Langfuse

  1. No run yet. Press Play the run.

Architecture, layer by layer

Five layers. Each one does one job, and each one can be swapped without touching the others. Hover a layer for why it is there.

1 · Requests in

FastAPI

HTTP API and the dashboard. A request arrives as JSON, the answer leaves as JSON with citations and a trace.

Why: one front door. The engine behind it can change without changing the API.

2 · Route and run

LangGraph

The router classifies the request, the graph runs the agents as nodes, and state is checkpointed after every step.

Why: the workflow is a graph, so its state is visible, pausable and resumable.

3 · Specialists

Domain agents

InvoiceAgent, ReportAgent, DataLookupAgent, PolicyAgent. Each owns one kind of work and calls tools through MCP.

Why: one job per agent makes each one easy to test, easy to trust and easy to replace.

4 · Tools and memory

FastMCP · PostgreSQL · SQLite · Qdrant

Every data access flows through the MCP tool server. Checkpoints live in Postgres, or SQLite when no database is set.

Why: agents never touch data directly, so every access is logged in one place, and a killed run resumes exactly once.

5 · Proof

OpenTelemetry · Langfuse · Eval harness

Every run leaves a trace with latency, tokens and cost. The eval harness scores a 20-case golden set and reports the measured rate.

Why: the numbers on this page come from the repo's own eval run.

The four agents

Each agent owns one kind of work, and each one only calls tools through MCP.

🧾 InvoiceAgent

Invoice intake and validation. Checks the purchase order, flags duplicates, spots overdue invoices, and proposes payments — never executes them.

validate_invoice · lookup_invoice

📊 ReportAgent

Report generation from real figures: totals, pending counts, overdue amounts, per-vendor breakdowns — drafted from the ledger.

draft_report · get_ledger

🔎 DataLookupAgent

Structured data lookup. Finds invoices, vendors and balances, and answers with citations so you can check every fact it states.

lookup_invoice · list_vendors

📖 PolicyAgent

Policy and handbook Q&A with retrieval over seeded documents (expense, leave, procurement, travel). Returns the matching section.

search_policy

Why it's safe to let it run

Three mechanisms do the heavy lifting. They are enforced in code.

✋

Human-in-the-loop, by construction

A financial action cannot execute without approval is True. The graph pauses at an interrupt(); the only way forward is a human decision in the review queue. Tests prove a payment never runs without approval, and a rejection leaves no side effects.

↩️

Sagas that undo themselves

A payment is three steps: reserve funds, post the ledger entry, notify the vendor. If step three fails, the saga runs compensations in reverse — reverses the ledger entry, releases the reservation. Nothing is left half-applied, and every step is idempotent, so resuming never double-pays.

💾

Checkpoints: save points for workflows

Like a save point in a video game. State is checkpointed after every step (Postgres when DATABASE_URL is set, SQLite otherwise). Kill the process mid-payment and restart it — the run resumes from the checkpoint and the payment is applied exactly once.

Money waits for a human.

A payment cannot move until someone clicks Approve. That rule sits in the code.

Measured results — not marketing numbers

An eval harness runs a 20-case golden set of labelled workflows through the live graph and scores it. These are the numbers from the run on 8 Nov 2026, mock provider. Re-run any time with python -m app.eval.

MetricValue
Golden cases20
Routing accuracy100.0%
Agent accuracy100.0%
Outcome accuracy100.0%
Autonomous resolution rate85.0% (17/20)
Cases needing human approval3
Avg latency per case24.5 ms
Total tokens (mock provider)7,035

The 3 cases that need approval are the 3 payment/credit requests in the golden set — by design, those can never resolve autonomously. Per-case detail: data/eval_results.json.

A note on the 88%. In production at BDO India, the same architecture resolved 88% of 100+ workflows autonomously. That is a production result from a different system and dataset. This repo's own measured number is 85.0% on its 20-case golden set. They are not the same number, and this page does not mix them up.

Run the engine

One command. No keys needed — the mock LLM provider is the default, so everything runs offline and deterministically.

# 1. Set up
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Run
uvicorn app.main:app --port 8000

# 3. Open http://127.0.0.1:8000 and try:
#    "Validate invoice INV-1001"
#    "Approve payment for invoice INV-1003"  (pauses for approval)
#    "What is the expense reimbursement limit?"

With Docker (api + Postgres): docker compose up --build

Run the tests and the eval:

pytest -q
python -m app.eval

API: POST /api/runs · GET /api/approvals · POST /api/approvals/{id}/approve · GET /api/metrics · GET /api/eval · MCP server at /mcp. Full list in the README.

Screenshots

Real screenshots of the running dashboard — not mockups.

Dashboard overview with metrics cards and run form
Run timeline with a run detail showing steps and trace
Human review queue with a payment awaiting approval
A payment run paused at the human gate, showing the financial action and trace
Eval panel showing measured results

FAQ

What is an “agent” here?

A specialist worker that does one kind of job. The InvoiceAgent only handles invoices; the PolicyAgent only answers policy questions. Splitting the work makes each one easier to test, easier to trust, and easier to replace.

What is MCP?

The Model Context Protocol — a standard way for an AI system to call tools. Here it is a FastMCP server that exposes named tools (lookup, validate, search, draft). Agents call the tools; they never touch the data directly, so every data access is logged in one place.

What is a saga?

A multi-step job where every step knows how to undo itself. If step three fails, steps two and one are undone in reverse order. Think of it as a checklist that erases itself cleanly when something goes wrong.

Can it pay an invoice by itself?

No — and that is the point. A payment pauses at the human-in-the-loop gate and waits in the review queue. The graph cannot proceed without a human clicking Approve. The tests prove it: a payment without approval never executes, and a rejection leaves zero side effects.

Does it need an OpenAI key?

No. The mock provider is the default: deterministic, offline, and what the tests and eval use. Set AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY and AZURE_OPENAI_DEPLOYMENT to switch to a real Azure OpenAI model — and re-run the eval before quoting any accuracy number with it.

Is the data real?

No. Vendors, invoices and policies are realistic but invented seed data, for demo and evaluation. The golden set uses dates relative to today so it never goes stale.

What is untested?

The Docker path and the Postgres checkpointer were not run end to end on the build machine (no Docker or Postgres there), and the Qdrant backend needs a live Qdrant server to verify. The default JSON + SQLite path is fully tested — 34 tests, all passing. The README lists every limitation honestly.