agentic-member-assistant

A virtual health assistant with identity-scoped retrieval and tool-first agent reasoning for healthcare payer environments. Every tool call is guarded by member context, policy enforcement, and PHI filtering.

Why This Architecture

Principle	Implementation
Tool-first reasoning	Agent reasons over structured tool calls, not free-text generation
Identity-scoped retrieval	Every data access is scoped to the authenticated member's context
Policy enforcement at every decision	RefusalEngine + ScopeGuard block unauthorized actions before execution
PHI boundary enforcement	PHIFilter redacts protected health information from all agent outputs
Confidence gating	Low-confidence responses are held back rather than hallucinated

Architecture

User Query
    |
    v
[ContentGuard] -- blocks harmful/injection content
    |
    v
[ReasoningEngine] -- intent detection, tool selection, confidence scoring
    |
    v
[ScopeGuard] -- identity-scoped access control (member, dependents, tier)
    |
    v
[RefusalEngine] -- policy enforcement (blocked actions, sensitive data)
    |
    v
[ToolRegistry] -- execute healthcare tools (benefits, claims, providers, formulary)
    |
    v
[PHIFilter] -- redact SSN, DOB, email, phone, MRN from output
    |
    v
[SSEHandler] -- stream response tokens to client

Healthcare Tools

Tool	Description	Scope
lookup_benefits	Deductibles, copays, coverage details	All tiers
check_claim_status	Claim processing status and amounts	All tiers
find_provider	In-network provider search	All tiers
check_formulary	Medication coverage and tier	Standard+
schedule_appointment	Book with in-network provider	Standard+
request_prior_auth	Prior authorization requests	Premium only

Safety Layers

1. ContentGuard — blocks prompt injection, harmful content, and medical diagnosis requests
2. ScopeGuard — enforces member identity isolation, dependent access, tier restrictions
3. RefusalEngine — blocks dangerous actions (account deletion, enrollment changes) and sensitive data in parameters
4. PHIFilter — detects and redacts SSN, DOB, email, phone, MRN patterns from all outputs

Quick Start

npm install
npm run build
npm test

Project Structure

src/
├── agent/
│   ├── orchestrator.ts    # Turn handling, safety pipeline, tool execution
│   ├── reasoning.ts       # Intent detection, tool selection, response synthesis
│   └── state.ts           # Conversation state management
├── identity/
│   ├── memberContext.ts    # Member identity model
│   └── scopeGuard.ts      # Identity-scoped access control
├── tools/
│   ├── registry.ts        # Tool registration and execution
│   └── healthcareTools.ts # Healthcare-specific tool implementations
├── safety/
│   ├── refusalEngine.ts   # Policy enforcement and action blocking
│   ├── phiFilter.ts       # PHI detection and redaction
│   └── contentGuard.ts    # Content safety and injection detection
├── streaming/
│   ├── sseHandler.ts      # SSE connection management and broadcasting
│   └── tokenStream.ts     # Token-level streaming
└── observability/
    ├── logger.ts          # Structured logging with level filtering
    └── tracer.ts          # Distributed tracing with spans

Payer Architecture Alignment

This assistant maps to the Member Apps and AI Orchestration layers of healthcare payer architecture:

Legacy Systems (Facets, QNXT)
  └─→ FHIR Integration Layer
       └─→ Data & Analytics
            └─→ Digital Experience
                 └─→ AI Orchestration ← agentic-member-assistant
                      └─→ Member Apps (web, mobile, IVR)

Related Repositories

• agentic-eval-harness — Scenario-based evaluation
• agentic-streaming-backend — SSE streaming pipeline
• agentic-policy-engine — Policy governance
• fhir-integration-service — FHIR R4 interoperability

License

MIT