Agent System¶

Overview¶

Curaway's AI agent system is the brain of the platform. It orchestrates multi-step workflows that combine clinical understanding, patient interaction, provider matching, and natural-language explanation. The system is built on three pillars:

• LangGraph -- Orchestration framework for multi-node, stateful AI workflows
• LangChain -- Tool wrappers that give agents access to databases, APIs, and external services
• Langfuse -- Observability platform for tracing, prompt management, and cost tracking

Architecture¶

Single Entry Point¶

All patient interactions flow through one API endpoint:

POST /api/v1/cases/{case_id}/chat

The handler (app/routers/chat.py) does not run a phase state machine. It resolves the conversation architecture for the case and dispatches the turn. Architecture is resolved once per case, at the first turn, and written to case.workflow_state.prompt_arch — flag flips never re-route an in-flight conversation (see sticky dispatch).

Conversation architecture dispatch¶

The chat handler dispatches each turn to one of three architecture generations, selected per case via Flagsmith and made sticky on first resolve:

graph TD
    Entry["POST /chat"] --> Dispatch[Architecture dispatcher]
    Dispatch -->|sticky per-case| Resolve{"workflow_state.prompt_arch"}
    Resolve -->|v6.2-flexible| T62["run_triage_turn_v6_2<br/>(single call + SOPContract)"]
    Resolve -->|v6| C6["compose_v6<br/>(stages + addendums)"]
    Resolve -->|v4 / fallback| V4["phase×layer<br/>(rollback floor)"]
    T62 --> Agents["Specialized agents:<br/>Clinical Context · Match · Explanation"]
    C6 --> Agents
    V4 --> Agents

    style Dispatch fill:#008B8B,color:#fff
    style T62 fill:#FF7F50,color:#fff
    style Agents fill:#FF7F50,color:#fff

Sticky dispatch. resolve_prompt_arch_for_case resolves the architecture once and persists it on the case. A case that starts on v6.1 finishes on v6.1 even if prompt_arch_v6_2_flexible is flipped mid-conversation. A rollout (or rollback) only changes which arch new cases resolve to — it can never yank a patient mid-conversation onto a different engine. This is the property that makes the canary safe.

The Four Agents¶

1. Clinical Context Agent¶

The Clinical Context Agent processes medical documents and extracts structured clinical data. It is the most complex agent, implemented as a 4-node LangGraph workflow.

Purpose: Transform unstructured medical documents into structured FHIR R4 resources.

Model: Claude Sonnet 4.6 (requires high-accuracy clinical reasoning)

graph LR
    A[extract_clinical_entities] --> B[map_to_medical_codes]
    B --> C[generate_fhir_resources]
    C --> D[store_resources]

    style A fill:#008B8B,color:#fff
    style B fill:#008B8B,color:#fff
    style C fill:#008B8B,color:#fff
    style D fill:#008B8B,color:#fff

Node Details:

State Schema:

class ClinicalContextState(TypedDict):
    """State passed between Clinical Context Agent nodes."""
    document_id: str
    tenant_id: str
    patient_id: str
    case_id: str
    raw_text: str
    extracted_entities: dict          # From node 1
    medical_codes: dict               # From node 2
    fhir_resources: list[dict]        # From node 3
    store_confirmation: dict          # From node 4
    errors: list[str]
    fallback_used: bool

2. Intake Agent¶

The Intake Agent conducts conversational intake to gather patient preferences, travel constraints, and treatment requirements.

Purpose: Collect structured preferences through natural conversation.

Model: Claude Haiku 4.5 (conversational, low-cost)

graph LR
    A[classify_message] --> B[collect_preferences]
    B --> C[suggest_options]
    C --> D[update_case]

    style A fill:#008B8B,color:#fff
    style B fill:#008B8B,color:#fff
    style C fill:#008B8B,color:#fff
    style D fill:#008B8B,color:#fff

Node Details:

Collected Preferences:

class PatientPreferences(BaseModel):
    """Preferences collected by the Intake Agent."""
    budget_range_usd: Optional[tuple[int, int]]
    preferred_countries: list[str]           # ISO 3166-1 alpha-3
    excluded_countries: list[str]
    preferred_languages: list[str]
    travel_date_range: Optional[tuple[date, date]]
    companion_count: int = 0
    dietary_restrictions: list[str]
    accessibility_needs: list[str]
    insurance_provider: Optional[str]
    previous_medical_travel: bool = False
    priority: str = "balanced"               # "cost", "quality", "speed", "balanced"

State Schema:

class IntakeState(TypedDict):
    """State passed between Intake Agent nodes."""
    case_id: str
    tenant_id: str
    patient_id: str
    message: str
    intent: str                              # From node 1
    current_preferences: dict                # Existing preferences
    new_preferences: dict                    # From node 2
    suggestions: list[str]                   # From node 3
    update_confirmation: dict                # From node 4
    conversation_history: list[dict]
    missing_fields: list[str]
    errors: list[str]

3. Match Agent¶

The Match Agent orchestrates the provider matching workflow, combining graph traversal, semantic search, and weighted scoring.

Purpose: Find and rank the best providers and doctors for a patient's case.

Model: Claude Haiku 4.5 (orchestration) + deterministic scoring

graph LR
    A[analyze_requirements] --> B[gather_requirements]
    B --> C[execute_scoring]
    C --> D[rerank_and_explain]

    style A fill:#FF7F50,color:#fff
    style B fill:#FF7F50,color:#fff
    style C fill:#FF7F50,color:#fff
    style D fill:#FF7F50,color:#fff

Node Details:

State Schema:

class MatchState(TypedDict):
    """State passed between Match Agent nodes."""
    case_id: str
    tenant_id: str
    patient_id: str
    clinical_data: dict                      # FHIR resources
    patient_preferences: dict
    matching_criteria: dict                  # From node 1
    candidates: list[dict]                   # From node 2
    scored_results: list[dict]               # From node 3
    final_results: list[dict]                # From node 4
    strategy_used: str
    errors: list[str]
    fallback_used: bool

4. Explanation Agent¶

The Explanation Agent generates natural-language explanations of matching results, tailored to the patient's locale and language.

Purpose: Make AI matching decisions transparent and understandable.

Model: Claude Haiku 4.5 (natural language generation)

Capabilities:

• Generates per-provider explanations (why this provider was recommended)
• Generates per-dimension explanations (why the clinical score is X)
• Adapts language to patient's preferred_language
• Adapts complexity to patient's indicated health literacy level
• Highlights strengths and potential concerns for each match

class ExplanationOutput(BaseModel):
    """Output from the Explanation Agent."""
    provider_id: str
    summary: str                             # 2-3 sentence overview
    strengths: list[str]                     # Top 3 strengths
    considerations: list[str]                # Things to be aware of
    dimension_explanations: dict[str, str]   # Per-scoring-dimension
    confidence_note: Optional[str]           # If data completeness is low
    locale: str                              # Language code used

Pre-Operative Risk Assessor (Rule-Based)¶

At the end of every EHR rebuild, ehr_builder_agent runs app/services/risk_assessor.py — a pure-function, rule-based pre-operative risk classifier (no LLM). It mirrors the lab_analyzer pattern: deterministic, auditable, healthcare-safe.

The assessor inspects four buckets and writes the result to ehr_snapshot.risk_factors:

Each risk record carries source provenance (which document / observation / med record it came from) and an is_blocking flag. Blocking risks halt forwarding until resolved; the frontend EHR drawer surfaces a "BLOCKING" badge when any risk is blocking. Covered by 26 unit tests in tests/test_risk_assessor.py.

Deterministic Fallbacks¶

Every agent node has a fallback implementation that runs without LLM calls:

async def extract_clinical_entities(state: ClinicalContextState) -> ClinicalContextState:
    """Extract clinical entities from document text."""
    try:
        # Primary: LLM-based extraction
        result = await llm_extract(state["raw_text"])
        state["extracted_entities"] = result
    except (LLMError, TimeoutError, ValidationError) as e:
        # Fallback: Regex + lookup table extraction
        logger.warning(f"LLM extraction failed, using fallback: {e}")
        result = regex_extract(state["raw_text"])
        state["extracted_entities"] = result
        state["fallback_used"] = True
        state["errors"].append(f"Fallback used for extraction: {str(e)}")
    return state

MCP Server¶

Curaway exposes an MCP (Model Context Protocol) server with 6 tools for external AI assistants to interact with the platform:

# MCP tool registration
@mcp_server.tool("search_providers")
async def search_providers(criteria: ProviderSearchCriteria, tenant_id: str):
    """Search for healthcare providers matching the given criteria."""
    results = await provider_service.search(
        tenant_id=tenant_id,
        specialty=criteria.specialty,
        country=criteria.country,
        accreditation=criteria.accreditation,
        max_results=criteria.max_results or 10,
    )
    return [provider.to_mcp_response() for provider in results]

Feature Flags¶

Agent behavior is controlled by Flagsmith feature flags:

Observability¶

Events Table¶

Every agent action is logged to the events table:

await log_event(
    tenant_id=tenant_id,
    event_type="agent.clinical_context.extraction_complete",
    case_id=case_id,
    payload={
        "document_id": doc_id,
        "entities_found": len(entities),
        "fallback_used": False,
        "duration_ms": elapsed,
    }
)

Langfuse Traces¶

Each agent invocation creates a Langfuse trace with:

• Trace: Full agent execution (e.g., clinical_context_agent)
• Spans: Individual node executions (e.g., extract_clinical_entities)
• Generations: LLM calls with input/output tokens and cost
• Scores: Quality metrics (extraction accuracy, explanation helpfulness)

graph TD
    T[Trace: clinical_context_agent] --> S1[Span: extract_clinical_entities]
    T --> S2[Span: map_to_medical_codes]
    T --> S3[Span: generate_fhir_resources]
    T --> S4[Span: store_resources]
    S1 --> G1[Generation: claude-sonnet-4.6]
    S2 --> G2[Generation: claude-haiku-4.5]
    S3 --> G3[Generation: claude-haiku-4.5]

    style T fill:#008B8B,color:#fff
    style S1 fill:#4A90D9,color:#fff
    style S2 fill:#4A90D9,color:#fff
    style S3 fill:#4A90D9,color:#fff
    style S4 fill:#4A90D9,color:#fff
    style G1 fill:#FF7F50,color:#fff
    style G2 fill:#FF7F50,color:#fff
    style G3 fill:#FF7F50,color:#fff

Model Selection¶