A credential-free, production-oriented reference implementation for bounded agentic banking support. The flagship workflow handles an unauthorized card transaction by retrieving trusted context, proposing a typed multi-step plan, collecting customer and admin approval for the exact side effects, and safely executing card block, dispute creation, and replacement-card request.
This repository is a reference platform, not a production banking system. Banking APIs, authentication, authorization, customer data, and side effects are simulated.
- Explicit LangGraph planner-executor loop with intent analysis, authentication gate, risk classification, schema-validated planning, policy checks, scoped HITL approval, execution, observation, verification, bounded replanning, escalation, and termination.
- Pydantic contracts for plans, steps, approvals, budgets, tool metadata, and results.
- Five registered tools with input/output schemas, version, permissions, risk, approval, timeout/retry, idempotency, and audit requirements.
- Durable SQLite operation ledger that prevents duplicate side effects and recovers when an external action succeeds but the response is lost.
- Separate thread checkpoint persistence through LangGraph and side-effect recovery through the operation ledger.
- Customer and admin approval views that disclose the goal, plan revision, risk, permissions, exact arguments, expected results, expiry, and reviewer scope.
- Structured audit and observability events with node, planner/model, and tool latency; token and cost budgets; optional LangSmith tracing.
- Provider-neutral OIDC verification and an authenticated BFF that binds subject, tenant, role, time-bounded step-up assurance, session, customer mapping, and reviewer identity before forwarding a signed delegated context to a default-deny private LangGraph API.
- A versioned 100-scenario evaluation dataset, executable quality gates, deterministic demo, unit and integration tests, dependency/secret scanning, Docker validation, and CI.
The committed evaluation report measures the deterministic planner and fake banking provider:
| Metric | Result |
|---|---|
| Scenarios | 100 |
| Intent routing / plan correctness / tool precision | 100% / 100% / 100% |
| Supported-task completion | 100% |
| Approval-policy compliance | 100% |
| Unauthorized tool calls / duplicate side effects | 0 / 0 |
| Loop termination | 100% |
| Tool-call success rate | 92.31% |
| p50 / p95 workflow latency | 3.19 ms / 38.17 ms |
These are repeatable local simulation results, not live-model or production-service benchmarks.
The operations view exposes the complete plan revision, permissions, expected outcomes, and exact side effects before a decision:
The decision controls remain attached to the reviewed scope, and the same contract renders as a single-column mobile review:
| Decision scope | Mobile |
|---|---|
 |
 |
Requires Python 3.12+.
cd backend
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
cd ..
make demoThe script pauses for a customer decision and an admin decision, injects one deterministic timeout,
replans, completes all five steps, performs each of the three simulated side effects exactly once,
and writes backend/artifacts/flagship-audit-report.json.
Run the evidence suite:
make test
make eval
docker compose config --quiet
docker compose build langgraph-apiAfter selecting an IdP and hosted topology, make acceptance-hosted runs the non-mutating OIDC,
authorization, and private-ingress checks documented in
hosted identity and network acceptance.
No API key is required for tests, evaluation, or the demo. An OpenAI planner can be selected explicitly in code and is constructed lazily; deterministic policy remains outside the model.
cp .env.example .env
make start| Service | Local URL |
|---|---|
| Customer chat | http://localhost:3000 |
| Admin dashboard | http://localhost:5173/approvals |
| FastAPI support API | http://localhost:8000 |
LangGraph is intentionally reachable only on the Compose network through the authenticated BFF. The Docker stack requires generated database and pgAdmin credentials, binds optional host ports to loopback, and keeps the checkpoint database private; it still uses mock banking data. Configure a real OIDC issuer and three independent security secrets, and do not expose it to the internet without completing the production-readiness checklist.
- System architecture and execution sequence
- Baseline gap matrix
- Tool governance and failure policies
- Memory and retention design
- Evaluation methodology
- Reliability SLOs and measurement contract
- Workflow-degradation runbook
- Disaster-recovery design
- Incident tabletop facilitator package
- Security hardening option portfolio
- Threat model
- Approval operations
- Model advisory boundary
- Production-readiness checklist
- Demo script and reviewer walkthrough
- Implementation report, resume bullets, and interview walkthrough
- Architecture decision records
- Release notes
- Graphify code graph and report
The refreshed code graph contains 1,723 nodes and 2,609 edges. Its benchmark estimates roughly 20.2× fewer tokens per representative repository query than reading the 86,150-word corpus.
| Classification | Current evidence |
|---|---|
| Implemented and locally tested | Bounded graph, schemas, governance, scoped approvals, approval queue ownership/maker-checker rules, idempotency/recovery, OIDC/BFF identity boundary, restricted-data rejection/redaction, tenant/role/time-bounded step-up enforcement, signed private-graph context, hosted acceptance runner, audit artifact, 100-scenario evaluation, 200-run reliability experiment, planner release/fallback controls, desktop/mobile automated WCAG browser checks, digest-pinned non-root containers, and local supply-chain gates |
| Implemented but not externally validated | OIDC provider adapters, LangGraph custom-auth hosting, optional OpenAI planner, LangSmith export, Postgres-backed Agent Server runtime |
| Simulated | IdP tokens/test keys, banking core, card block, dispute, replacement, customer records |
| Planned / required before production | Managed operation ledger (the reference SQLite ledger is production-disabled), workforce/customer IdP selection and acceptance, revocation/session policy, secrets manager, provider contracts, field/backup encryption and KMS, rate limits/WAF, privacy/legal workflows, SLOs/on-call, image signing, hosted load/penetration testing, and manual screen-reader/device acceptance |
backend/src/graphs/flagship_graph.py bounded state machine
backend/src/services/planner.py deterministic and optional model planners
backend/src/tools/governed_registry.py capability registry and policy enforcement
backend/src/services/operation_ledger.py durable idempotency and recovery
backend/src/evaluation/ executable metrics and gates
backend/src/reliability/ concurrent load and recovery gates
backend/evaluations/ versioned dataset and reports
frontend/customer-chat/ customer approval experience
frontend/admin-dashboard/ operations approval experience
docs/ architecture, policy, decisions, readiness
The legacy supervisor/domain-agent graph remains available as banking_support; the reference
workflow is registered as flagship_support. The UI still inherits upstream Agent Chat UI bundle
size and lint warnings. Full-stack browser validation uses local simulated state, not a real identity
provider or banking sandbox. See the readiness checklist for the complete boundary.