How msft-innovation-hub-india/bfsi-multi-agent-health-insurance works
1. Repository shape
- This is a two-part system: a Python backend that performs AI-assisted claim fraud analysis, and a React/TypeScript frontend that visualizes claims, evidence, and agent workflow.
- The backend also includes batch/demo entrypoints and a FastAPI API layer, so it supports both command-line execution and interactive app usage.
2. Primary backend orchestration path
- The main execution flow starts in run_fraud_detection.py or main.py, then moves into orchestrator.py / workflow_manager.py.
- These modules coordinate the end-to-end claim pipeline: collect evidence, run multi-agent analysis, extract a final decision, and generate a report.
3. Core domain and shared logic
- core/ is the shared business-logic boundary.
- core/models.py defines the domain objects such as claim data and fraud decision outputs.
- core/prompts.py, core/instructions.py, and core/queries.py hold the LLM/agent prompt templates and retrieval queries, while core/config.py and root config.py centralize runtime settings.
4. Service layer responsibilities
- services/ contains reusable orchestration helpers rather than agent logic itself.
- agent_factory.py builds the AutoGen agents, evidence_collector.py gathers source material from Azure systems, decision_extractor.py parses the final outcome from agent conversations, and report_generator.py formats the result for output.
5. Specialized agent boundary
- agents/ contains focused analysis modules for specific claim dimensions.
- The README describes the collaborating roles: fraud detection, medical validation, billing validation, policy balance validation, exclusions validation, and final coordination.
- The code files show additional specialization for X-ray analysis, billing, claim processing, and patient summary generation.
6. Multi-agent decision flow
- The key architectural pattern is an AutoGen GroupChat-style collaboration.
- Evidence is fed into multiple agents, each agent produces a perspective, and a final coordinator synthesizes them into one of the system outcomes: approved, rejected, or pending.
- This makes the analysis pipeline conversational and modular rather than a single monolithic model call.
7. External data and AI services
- The backend integrates with Azure AI Search for document retrieval, Azure Blob Storage for stored claim/X-ray assets, Azure OpenAI for reasoning, and Azure Custom Vision for X-ray classification.
- Deployment notes also show Azure Cosmos DB used for claim/state persistence in the hosted API setup.
- Managed identity is the main runtime auth model in Azure deployment, reducing secret handling in production.
8. Document indexing subsystem
- Index-Creation/ and index-creation-portal/ define the ingestion/search preparation side of the system.
- Three search indexes are expected: one for bills, one for claims/exclusions/inclusions, and one for diagnostic data.
- This is a distinct pre-processing boundary: documents are indexed first, then queried during claim analysis.
9. Backend API layer
- api/ contains the FastAPI-facing runtime pieces: main.py, Cosmos integration, and a real-time processor.
- This layer likely exposes endpoints for triggering claim processing, polling results, and updating persisted claim state.
- It acts as the bridge between the frontend and the AI/workflow subsystems.
10. Frontend architecture
- health-insurance-frontend/ is a standalone Vite React app written in TypeScript.
- Its components are organized around the insurer workflow: dashboard stats, claim analysis, evidence analysis, patient summary, system status, and workflow visualization.
- The frontend is presentation-first; it consumes APIs and local demo data rather than implementing analysis logic.
11. Frontend data and utility boundaries
- src/api/ contains client-side API adapters, including claim APIs and realtime hooks.
- src/utils/ provides loaders and transformers for claim data, logs, markdown simplification, and Azure storage helpers.
- src/types/ defines the frontend contract for claims, dashboard data, and underwriting-related shapes.
12. Sample data and operational demo assets
- The Data/ directory contains example PDFs for bills, discharge summaries, medical records, exclusions, and X-rays.
- These assets support local testing, document viewer demos, and end-to-end workflow validation without needing a live claims feed.
13. Deployment and runtime packaging
- Dockerfile.backend and Dockerfile.frontend package the two runtimes separately.
- The frontend is served through Nginx in a multi-stage build, while the backend runs as Python/FastAPI with Uvicorn.
- The repo is clearly designed for Azure Container Apps deployment with external ingress and managed identity.
14. Architecture summary for a diagram
- A good diagram should show: documents and X-rays entering Azure storage/search, backend orchestration pulling evidence and invoking multiple AI agents, decision/report generation, and frontend visualization of the workflow and results.
- The important boundaries are: ingestion/indexing, analysis orchestration, API/persistence, and UI presentation.
Main entry points: main.py API main · App.tsx React app · agent_factory.py Agent factory · workflow_manager.py Workflow manager
Components 29
Backend AI system
Python orchestration, agents, API, and shared domain logic for claim fraud analysis.
- Run fraud · Batch/demo entrypoint for starting fraud analysis from the command line.
run_fraud_detection.py - Main app · Top-level Python launcher for the backend runtime.
main.py - Orchestrator · Coordinates the end-to-end claim analysis pipeline.
orchestrator.py - Workflow manager · Manages multi-step claim processing and agent handoffs.
workflow_manager.py - Domain models · Claim and fraud-decision objects shared across backend layers.
core/models.py - Prompts · Prompt templates used to steer agent reasoning.
core/prompts.py - Instructions · System instructions and behavioral guidance for the agents.
core/instructions.py - Queries · Search and retrieval queries used during evidence gathering.
core/queries.py - Core config · Shared configuration for the backend analysis runtime.
core/config.py - Agent factory · Constructs the AutoGen agents used in the collaborative workflow.
services/agent_factory.py - Evidence collector · Gathers claim evidence from Azure-backed sources and search.
services/evidence_collector.py - Decision extractor · Extracts the final fraud outcome from agent conversation output.
services/decision_extractor.py - Report generator · Formats the analysis result into a report for users or downstream systems.
services/report_generator.py - Claim agent · Primary claim reasoning and fraud assessment specialist.
agents/claim.py - Bill agent · Billing-focused validation and line-item scrutiny specialist.
agents/bill.py - X-ray agent · X-ray classification and image-based claim evidence specialist.
agents/xrayanalysis.py - Patient summary · Generates a concise patient-centric summary for the workflow.
agents/patientsummary.py - API main · FastAPI runtime layer that exposes backend processing endpoints.
api/main.py - Cosmos service · Persistence integration for claim and workflow state in Cosmos DB.
api/cosmos_service.py - Realtime processor · Handles incremental processing and live updates for claim runs.
api/realtime_processor.py
Indexing pipeline
Document preparation and search index creation used before claim analysis.
- Index creation · Builds the search indexes used to prepare documents for retrieval.
Index-Creation/create_index.py - Index config · Defines document index configuration and field layout.
Index-Creation/doc_index_config.py - Sample docs · Representative claim, medical, and billing PDFs used for indexing and demo runs.
Data/Discharge-Summary.pdf
Frontend app
React/TypeScript UI for claim review, workflow visualization, and demo data.
- React app · Frontend shell for the insurer workflow visualization and demos.
health-insurance-frontend/src/App.tsx - Dashboard · High-level claim status, stats, and summary presentation.
health-insurance-frontend/src/InsurerDashboard.tsx - Claim analysis · Claim review and evidence analysis screens.
health-insurance-frontend/src/components/ClaimAnalysis.tsx - Workflow view · Agent workflow, conversation, and pipeline visualization.
health-insurance-frontend/src/components/MultiAgentWorkflowPipeline.tsx - API client · Client-side adapters for claims APIs and realtime hooks.
health-insurance-frontend/src/api/claimsApi.ts - UI utils · Loaders and transformers for claims, logs, markdown, and Azure storage.
health-insurance-frontend/src/utils/claimDataLoader.ts
Connections 32
- Run fraud → Orchestrator: starts · CLI execution enters the main workflow coordinator.
- Main app → API main: runs · Primary backend startup can enter the FastAPI layer.
- Orchestrator → Workflow manager: delegates · Orchestrator hands step control to the workflow manager.
- Workflow manager → Evidence collector: collects · Workflow begins by gathering claim evidence.
- Workflow manager → Agent factory: builds agents · Workflow creates the collaborating analysis agents.
- Agent factory → Claim agent: instantiates · Factory assembles the primary claim analysis agent.
- Agent factory → Bill agent: instantiates · Factory assembles the billing validation agent.
- Agent factory → X-ray agent: instantiates · Factory assembles the X-ray analysis agent.
- Agent factory → Patient summary: instantiates · Factory assembles the patient summary agent.
- Claim agent → Prompts: uses · Agent reasoning is guided by shared prompt templates.
- Bill agent → Instructions: follows · Agent behavior follows shared instructions.
- X-ray agent → Domain models: exchanges · Agent consumes and emits shared claim decision objects.
- Patient summary → Domain models: exchanges · Agent consumes and emits shared claim decision objects.
- Evidence collector → Queries: queries · Retrieval is driven by shared search/query definitions.
- Evidence collector → Sample docs: reads · Evidence is sourced from indexed claim documents and assets.
- Evidence collector → Index creation: depends on · Collected evidence assumes the search indexes exist.
- Index creation → Index config: configured by · Index creation uses the index schema definition.
- Index creation → Sample docs: indexes · Source PDFs and assets are ingested into search indexes.
- Workflow manager → Decision extractor: extracts decision · Conversation output is parsed into a final outcome.
- Decision extractor → Report generator: feeds · Parsed decision is formatted into a report.
- API main → Cosmos service: persists · API layer stores and retrieves claim state.
- API main → Realtime processor: streams · API layer supports live claim processing updates.
- API main → Workflow manager: triggers · API requests can start backend workflow runs.
- React app → Dashboard: renders · App composes the dashboard and main workflow screens.
- React app → Claim analysis: renders · App hosts the claim analysis and evidence review screens.
- React app → Workflow view: renders · App hosts the agent workflow and conversation visualizations.
- React app → API client: calls · UI uses API adapters to reach backend endpoints.
- React app → UI utils: loads · UI uses helper utilities for demo data and transformations.
- API client → API main: consumes · Client adapters communicate with the backend API.
- UI utils → Sample docs: demo data · UI loaders can work with local sample documents and logs.
- Core config → API main: configures · Runtime settings are shared with the API deployment.
- Core config → Orchestrator: configures · Workflow execution uses shared backend settings.