convez.ai
MCP ServerFinanceiroAvançado
Miny-Labs

Manthan - Investigador Autônomo de Disputas de Faturamento B2B

Miny-Labs/manthan

Multi-agente para resolver disputes de faturamento B2B em minutos, não horas

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema multi-agente autônomo construído com Google ADK e Gemini para investigar e resolver disputas de faturamento B2B em ~3 minutos. Coordena cinco especialistas em paralelo que leem dados de nove sistemas de negócio, aplica políticas documentadas e propõe decisões (fight, refund, accept ou escalate) com rastreamento completo das fontes. LLM nunca acessa credenciais de escrita — um mecanismo de políticas roteia para aprovação humana e um executor determinístico executa as ações.

Instalação

$npx convez-ai Miny-Labs/manthan

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
37%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Investigação automatizada de chargebacks e reclamações de faturamento
  • Coordenação de análise cross-sistema (Stripe, CRM, suporte, observabilidade, políticas)
  • Geração de briefings de decisão com rastreamento de fontes para aprovação humana
  • Escalas de conformidade e governance em disputas financeiras

Veredito

Solução empresarial sólida para automação de processos de disputas de faturamento, com arquitetura de multi-agentes bem pensada e governança by design. Ideal para merchants em escala que precisam de velocidade sem abrir mão do controle humano sobre decisões financeiras.

README

A tradução para o português deste README ainda está na fila.

https://github.com/user-attachments/assets/afa2105c-3cc1-40e2-a799-6fcd2ee2f3f8

What this is

Billing disputes come in many shapes — a chargeback, a refund demand, a failed payment, an early fraud warning, a contested invoice — and in every one of them the truth is scattered: the charge lives in Stripe, the account in the CRM, the complaint in the support desk, the outage that triggered it in observability, the refund formula in the policy docs. Someone has to read all of it, apply the documented policy, compute what's actually owed, and respond before the clock runs out. A senior analyst spends ~5 hours per dispute doing exactly that — or the merchant eats the loss.

Manthan is that analyst, rebuilt as a team of agents that finishes in ~3 minutes:

  • The triage agent receives the Stripe dispute (or an investigate_dispute call from another agent), frames the case, and dispatches the investigator over A2A.
  • The investigator agent — a coordinator commanding five specialists in parallel — reads across nine business systems via Coral SQL and writes a decision brief: fight, refund, accept, or escalate, with the math shown and every claim cited to the source record it came from.
  • The agent only ever proposes. A policy engine routes each decision to its human approval tier, and a deterministic actor executes the approved actions — refund, dispute response, customer email — with idempotency keys. The LLM never holds write credentials.
  • The advisor agent answers questions about any case — for operators, and for other agents over A2A.

Track 3 compliance map

MandateImplementationWhere
B2B focusBilling-dispute resolution for B2B SaaS merchants — chargebacks, refund demands, failed payments, fraud warningsBusiness case
Cloud-native runtimeSix Cloud Run services + Cloud SQL + Secret Manager; Agent Engine documented for the investigatordeploy/gcp/
Gemini-powered intelligenceAll reasoning on Gemini: 3.1-pro (coordinator) · 3.5-flash (specialists, advisor) · 3.1-flash-lite (triage, prettifier)agent/.../config.py
A2A interoperabilityThree Agent Cards, JSON-RPC /a2a, triage→investigator over A2A, 12 skills for external agentsagent/.../a2a/
Multi-agent ADK orchestrationCoordinator + five parallel specialists (shared Evidence set); triage / investigator / advisor as identified macro agentsagent/.../team.py
Grounding + RAGPrivate data via Coral SQL · RAG over merchant policy docs · google_search for card-network rulesGrounding & RAG
Agent IdentityOne service account per agent; identity block on every Agent Card; rendered in the Agent Rosterdeploy/gcp/deploy.sh
Collaboration > single agentScoped parallel specialists; failures degrade, never abort; external agents join cases over A2AMulti-agent

Coral — the retrieval layer

Dispute facts live in nine systems of record: the charge in Stripe, the account in the CRM, the complaint in support, the outage in observability, the refund formula in the policy docs. Coral (Apache-2.0, Rust) exposes them as Postgres-compatible SQL schemas behind one MCP server — retrieval becomes a query plan instead of per-vendor tool calls stitched together in the model's context:

SELECT
  d.id AS dispute_id, d.amount, d.reason, d.evidence_due_by,
  c.email AS customer_email,
  (SELECT COUNT(*) FROM stripe.disputes
     WHERE customer = d.customer AND id <> d.id)            AS prior_disputes,
  (SELECT COUNT(*) FROM intercom.conversations
     WHERE source_author_email = c.email)                   AS support_threads,
  (SELECT COUNT(*) FROM datadog.incidents
     WHERE service = 'custom-reports-svc'
       AND window @> tstzrange(ch.created, ch.created + interval '7 days'))
                                                            AS incidents_in_window,
  (SELECT body FROM notion.pages
     WHERE title ILIKE '%pro-rata credit%' AND active)      AS policy_body
FROM stripe.disputes d
JOIN stripe.charges   ch ON ch.id = d.charge_id
JOIN stripe.customers c  ON c.id  = d.customer
WHERE d.id = 'dp_aperture_345478';

One query, one round-trip, one rowset. Why it's the right grounding layer:

  • Live system-of-record data — queried at decision time, not embeddings of a stale copy. No ETL, no index drift.
  • Structural provenance — every row carries source/table/record id; row-level citations are free and clickable.
  • Joins beat tool-call chains — cross-system correlation happens in the query engine, not in the context window.
  • The provider is a slot — 170+ adapters upstream, nine connected here. HubSpot or Salesforce, Intercom or Zendesk, Notion or Confluence: same SQL surface, discovered from the catalog at run time.
  • Read-only by design — the retrieval plane cannot write; actions go through the actor after approval.
  • Credentials stay with Coral — per-tenant secrets, used at query time. The model sees rows, never keys.

The token bill is an architecture decision

  • Per-vendor MCP chains re-read the whole context every turn → quadratic cost (~43× a single-call estimate by step ten), plus per-vendor tool catalogs re-bought every turn and a 10–20% malformed-call retry tax.
  • Coral's discipline: one query language · discover-then-query (catalog walked at case start, no schema dump in the prompt) · typed rows · constrained call generation (malformed calls can't be produced).
  • Coral's published 82-task benchmark vs direct vendor MCPs: 31% more accurate · 64% fewer tokens · 70% cheaper · 55% faster. Worked example: 29 tool calls / 134 s via vendor MCPs → 1 query, 6 calls / 21 s via Coral.

Same data, same model — the architecture decides the bill. The coordinator and the four data specialists share one Coral MCP session (coral_sql, coral_list_catalog, coral_describe_table); every query is recorded as an event and visible as raw SQL in the Workspace's Coral mode.

The business case

Disputes arrive with deadlines, evidence requirements vary by network and reason code, and the facts span payments, CRM, support, observability, and policy docs. Teams either eat the loss or burn analyst hours reconstructing what happened.

Manthan returns one of four decisions — fight (network-compliant evidence) · refund (correctly-computed amount, including partial pro-rata credits) · accept · escalate (tradeoff named) — gated by policy (auto < $50 · one-click $50–500 · two-person $500+), with a full audit trail.

As buyers become agents (AP2), disputes become agent-to-agent conversations — Manthan's A2A surface is the merchant's side of that conversation.

A multi-agent system, not a chatbot

  • Scoped specialists, run in parallel — payments thinks in stripe.* joins, reliability correlates incidents with the disputed window, policy retrieves the authoritative SOP. Wall-clock ≈ the slowest specialist, not the sum.
  • One shared Evidence set — specialists write into it; the coordinator's citations stay globally indexed.
  • An honest boundary — ADK's built-in google_search can't mix with function tools, so the network-rules analyst is necessarily its own agent.
  • Failures degrade, never abort — ResilientAgentTool caps each specialist at 180 s; a 503-storm or hung connection becomes an error result the coordinator routes around.
  • Governed reasoning — the pacer (pure rules as ADK before_model / before_tool callbacks) nudges drift and refuses to finalize a refund whose math no finding shows. It rejected the first conclude() in the validation run.
   │ Stripe webhooks (5 event types)          │ A2A (external agents)
   │ dispute · fraud-warning · payment        │ message/send · tasks/get
   ▼                                          ▼
┌────────────────┐  A2A investigate_dispute ┌─────────────────────────────────┐
│  triage agent  │ ───────────────────────▶ │  investigator agent             │
│ flash-lite ·   │  (in-process fallback    │  gemini-3.1-pro-preview         │
│ per-org slug   │   in local dev)          │  coordinator + 5 parallel       │
└────────────────┘                          │  specialists, one Evidence set: │
                                            │   · payments_analyst            │
┌────────────────┐                          │   · customer_context            │
│ advisor agent  │                          │   · reliability_analyst         │
│ gemini-3.5-    │                          │   · policy_analyst (SOP RAG)    │
│ flash · ask /  │                          │   · network_rules_analyst       │
│ precheck_refund│                          │     (google_search grounding)   │
│ / history /    │                          │  pacer rules as ADK callbacks   │
│ exposure /     │                          └──────────┬──────────────────────┘
│ contribute +   │                                     │ Coral SQL over MCP
│ 6 reads        │                          ┌──────────▼──────────┐
└──────┬─────────┘                          │  Coral (mcp-stdio)  │
       │ per-case operator chat             │  9 SaaS schemas as  │
       │ lands as agent_reply               │  pg-SQL (read-only) │
       │                                    └─────────────────────┘
       │        both write through services/case_store.py
       ▼                                               ▼
┌────────────────────────────────────────────────────────────────┐
│   manthan-api · FastAPI + asyncpg · PostgreSQL                 │
│   • cases / events / findings / actions  (per-org PG schema)   │
│   • per-Clerk-user workspace isolation                         │
│   • SSE streams: /api/inbox/stream, /api/cases/:id/stream      │
│   • A2A: /.well-known/agent-card.json + JSON-RPC /a2a          │
└──────────────────────────┬─────────────────────────────────────┘
                           │ approved actions
                           │ (policy gates: auto <$50 ·
                           │  one-click $50-500 · two-person $500+)
                           ▼
              ┌──────────────────────┐      ┌──────────────────────┐
              │  workers/main.py     │ ───▶ │  Action adapters     │
              │  actor + prettifier  │      │  • Stripe · refunds  │
              │  (deterministic -    │      │  • Stripe · disputes │
              │   the only workers)  │      │  • Resend · emails   │
              └──────────────────────┘      │  • HubSpot · notes   │
                                            │  • Slack  · posts    │
                                            │  • Notion · blocks   │
                                            └──────────────────────┘

Grounding & RAG

SurfaceWhatHow
Private data — CoralNine systems of record as one SQL surface (above)Every query → Evidence row with provenance; findings cite Evidence indices; chips deep-link to the record
RAG — merchant policyThe policy analyst retrieves the merchant's own SOPs — Notion, Confluence, or Google Docs, discovered from the catalogSearch → page → formula; "two degraded days in a thirty-day cycle" is quoted from the merchant's policy page, not model priors
Google Search — network rulesCard-network evidence requirements (e.g. Visa CE 3.0 per reason code) via ADK's built-in google_searchRules change too often to hardcode; retrieved fresh when a fight brief needs them

A2A interoperability

Three Agent Cards (/.well-known/agent-card.json per service), JSON-RPC at /a2a, API-key security scheme. A2A is also the internal communication layer (triage → investigator). 12 skills:

SkillWhat another agent can do
Actinvestigate_disputeOpen a full investigation
contribute_evidencePush evidence into an open case, provenance tagged with the contributor's identity
AdviseaskGrounded, citation-bearing Q&A over a case or the portfolio
precheck_refundHistory + risk + approval gate before granting a refund
get_customer_historyPrior disputes and outcomes by customer
dispute_exposureOpen-exposure aggregates for finance agents
Readget_case · list_cases · get_brief · get_findings · get_actions · get_audit_trailEvery case artifact — state is never locked in the UI
curl -s https://<advisor-url>/.well-known/agent-card.json
curl -s -X POST https://<advisor-url>/a2a -H 'content-type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "message/send",
  "params": {"skill": "precheck_refund",
             "args": {"customer_ref": "billing@aperture-analytics.co", "amount_minor": 84000}}}'

Governed by design

  • Agent Identity — one service account per agent; agent id, SA, model, and signing fingerprint on every card; rendered in the Agent Roster (/app/agents).
  • HITL policy gates — auto / one-click / two-person by amount and account. The agent proposes, humans approve, the deterministic actor executes with idempotency keys. The LLM never holds write credentials.
  • Honest failure — upstream rejections are recorded as failed with the verbatim error; no synthesized success refs.
  • Observability — OpenTelemetry end to end; Cloud Trace exporter; live span-tree per case (/app/traces); trace ids on every event.
  • Audit — append-only event log per case, exposed over A2A (get_audit_trail) and in the UI.

Quick start

Prerequisites

  • Node 20+ · pnpm or npm
  • Python 3.12+ · uv
  • Docker (for the local Postgres)
  • The Coral binary on your PATH (or set CORAL_BINARY)

Setup

git clone https://github.com/Miny-Labs/manthan
cd manthan

# 1 · Environment - fill in GOOGLE_API_KEY (aistudio.google.com/apikey),
#                   CORAL_BINARY, STRIPE_API_KEY, HUBSPOT_ACCESS_TOKEN,
#                   SLACK_TOKEN, NOTION_API_KEY, CLERK_*
cp .env.example .env
cp manthan-api/.env.example manthan-api/.env
cp agent/.env.example agent/.env

# 2 · Database
docker compose -f manthan-api/docker-compose.yml up -d postgres

# 3 · Backend - API gateway (runs investigations in-process in local dev)
#     + deterministic workers (actor + prettifier)
cd manthan-api && uv sync
uv run uvicorn manthan_api.main:app --reload --port 8000 &
uv run python -m manthan_api.workers.main &

#     Optional - the three A2A agent services as separate processes
#     (full cloud parity; each serves its own agent card):
# uv run uvicorn manthan_api.agents.triage:app --port 8001 &
# uv run uvicorn manthan_api.agents.investigator:app --port 8002 &
# uv run uvicorn manthan_api.agents.advisor:app --port 8003 &

# 4 · Frontend
cd ../manthan-ui && npm install && npm run dev

Visit http://localhost:5173, sign in via Clerk. Fire a case with stripe trigger charge.dispute.created (webhook: /webhooks/stripe/{org}) or over A2A with the investigate_dispute skill. The canonical seeded case — $8,400 dispute → $560 pro-rata credit — is du_1Tch1O… in the test-mode Stripe account.

Tests (pure-logic, no LLM spend): cd agent && uv run pytest (79) · cd manthan-api && uv run pytest (71).

Deploy on Google Cloud

Runbook, Dockerfiles, and scripts in deploy/gcp/:

  • Cloud Run — six services from two images: API gateway, manthan-triage, manthan-investigator, manthan-advisor (each under its own service account), worker, UI.
  • Cloud SQL Postgres — five migrations via sql-migrate.sh.
  • Secret Manager — per-tenant coral-{tenant}-{credential} secrets, per-secret IAM, via secrets-bootstrap.sh.
  • Cloud Trace — OTel spans for every model call, tool call, and specialist.
  • Vertex AI Agent Engine — documented alternative host for the investigator (same ADK code, Vertex backend flag).
  • Coral sidecar — Coral 0.4.2 over streamable-HTTP MCP in the cloud; local dev spawns coral mcp-stdio per investigation.

How a case runs

StageWhat happens
1 · TriggerStripe webhook (charge.dispute.created · funds_withdrawn · closed · radar.early_fraud_warning.created · invoice.payment_failed) hits triage — or an external agent calls investigate_dispute
2 · InvestigateTriage dispatches the investigator over A2A; coordinator fans out five specialists in parallel; pacer governs every round
3 · BriefExecutive memo, math shown, every number cited — written straight to Postgres by the investigator
4 · DecideRefund / fight / accept / escalate + the drafted action set, gated by policy tier
5 · Approve & actOne click; the actor fires actions with idempotency keys; the advisor answers follow-ups

Tech stack

RoleModel
Investigator coordinatorgemini-3.1-pro-preview
Specialists + advisorgemini-3.5-flash
Triage + prettifiergemini-3.1-flash-lite
Action execution (actor)deterministic — no model

All Gemini via AI Studio (GOOGLE_API_KEY).

  • Agent — Google ADK 2.x: coordinator + five specialists as AgentTools over one Evidence set; coral tools (read) + record_finding / ask_human / conclude (coordinator-only); pacer as callbacks; OpenTelemetry throughout. Details: agent/README.md.
  • Backend — FastAPI + asyncpg + PostgreSQL; three A2A agent services + two deterministic workers (FOR UPDATE SKIP LOCKED).
  • Frontend — React 19 + Vite + TypeScript, Tailwind v4, Clerk auth; observability pages: Roster (/app/agents), Traces (/app/traces), Controls (/app/controls).
  • Data plane — Coral: Rust binary, 9 SaaS schemas as Postgres SQL over MCP.
  • Write adapters (actor-only, post-approval) — Stripe refunds + dispute evidence, Resend emails, HubSpot notes, Slack posts, Notion blocks.

Repo map

PathContents
agent/ADK multi-agent brain + A2A protocol layer (cards, dispatch, client, store)
manthan-api/API gateway, three agent services, case store, policy engine, actor
manthan-ui/Merchant product + agent observability surfaces
deploy/gcp/Cloud Run / Cloud SQL / Secret Manager runbook + scripts

License

Apache 2.0 — see LICENSE. A hosted version runs at manthan.quest, maintained in a separate production repository.


Built by miny-labs for the Google for Startups AI Agents Challenge · Made with 🪸 Coral

Ver o original no GitHub

Bom para

Relacionados