Skip to content

Steer-03: Intake Agent v2 — Records-First with EHR Awareness

Read first: specs/sdd-mvp/04-agent-pipeline.md, specs/sdd-mvp/05-ehr-builder.md, specs/sdd-mvp/08-conversation-design.md

Context & Goal

Upgrade the Intake Agent to be EHR-aware and records-first. Instead of asking questions blindly, it checks what data already exists in the EHR (from documents, prior chat turns, Clinical Context Agent output) and only asks for gaps. Integrates with EHR Builder and event system from steer-01 and steer-02.

Backend (curaway-ai/curaway-backend)

Step 1: Update Intake Agent State Schema

Update app/agents/intake/state.py: - Add ehr_summary: EHRSummary to agent state — loaded from EHR Builder before each turn - Add procedure_requirements: list[Requirement] — loaded from Neo4j for the identified procedure - Add missing_fields: list[str] — computed from EHR summary vs procedure requirements - Add intake_progress: float — from EHR Builder calculation

Step 2: Update classify_intent Node

The intent classifier should now handle: - intake_update — patient providing new clinical info in conversation - document_upload — patient mentioning or attaching a document - question — patient asking about process, requirements, timeline - preference_update — changing preferences (budget, language, dietary) - procedure_clarification — patient clarifying what procedure they need

Step 3: Update collect_information Node

Before extracting from chat message: 1. Load current EHR summary via ehr_builder_service.get_ehr_summary() 2. Compare against procedure requirements 3. Extract structured data from message (conditions, medications, allergies, demographics) 4. Call ehr_builder_service.update_from_chat() with extracted data 5. Emit clinical_entities_extracted event if clinical data found

Step 4: Update suggest_actions Node

Generate context-aware suggestions: - If missing required documents → suggest upload with specific document names - If missing lab values conditional on comorbidities → explain why needed - If enough data for matching → suggest "Ready to find providers" - Suggestions rendered as suggested_actions in response (chips in frontend)

Step 5: Update System Prompt

Update Langfuse prompt for Intake Agent: - Add records-first instruction: "Before asking any question, check if the information already exists in the patient's EHR summary provided in context." - Add DO/DON'T/REDIRECT guardrails (from guardrails.yaml) - Include procedure-specific context: "The patient needs {procedure_name}. Required information: {missing_fields}" - Curaway brand tone: professional, warm, concise, never medical advice

Step 6: Tests

  • Test records-first: give agent an EHR with conditions already populated, verify it doesn't re-ask
  • Test missing field detection: incomplete EHR → agent asks for specific gaps
  • Test entity extraction from chat: "I take metformin" → medication extracted, EHR updated
  • Test suggest_actions: missing X-ray → suggests upload
  • Test guardrails: medical advice request → redirect response

Backend Verification

python -m pytest tests/test_intake_agent.py -v
# Manual test via chat endpoint (uses a clean per-persona account —
# demo-patient-aisha-001 is quarantined, see
# docs/runbook/test-data-hygiene.md):
curl -X POST http://localhost:8000/api/v1/patients/demo-patient-maria-001/chat \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-ID: tenant-curaway-patients" \
  -H "Content-Type: application/json" \
  -d '{"message": "I have diabetes and take metformin daily"}'

Frontend (curaway-ai/curaway-frontend)

Step 1: Suggested Action Chips

Create src/components/chat/ActionChips.tsx: - Renders suggested_actions from agent response as tappable pills - Types: upload (opens file dialog), info (sends predefined message), action (triggers API call) - Styled with Teal/Coral brand colors - Disappear after tapped (one-shot)

Step 2: Inline EHR Extraction Indicator

When agent extracts clinical data from chat, show subtle inline confirmation: - Small teal badge below agent message: "✓ Noted: Type 2 diabetes (E11)" - Animated appearance (fade in) - Links to EHR summary in left panel

Step 3: Progress Strip Integration

Update progress strip to show: - Intake phase with completion percentage - List of missing items (from missing_fields in agent metadata) - "Ready to match" indicator when progress >= threshold

Frontend Verification

npm run build
npx tsc --noEmit
# Manual: send chat message, verify action chips render and EHR indicator appears

Checklist

  • [ ] No new migrations expected
  • [ ] Seed data: ensure TKR procedure requirements are in Neo4j
  • [ ] Error codes: INTAKE_EXTRACTION_001, INTAKE_PROGRESS_001
  • [ ] Feature flag: records_first_intake (Flagsmith)
  • [ ] Langfuse: updated Intake Agent prompt version
  • [ ] Unit tests: records-first logic, extraction, guardrails
  • [ ] PostHog: action_chip_tapped, ehr_indicator_shown
  • [ ] Loading states: typing indicator during agent processing
  • [ ] Mobile: action chips wrap properly on small screens
  • [ ] CLAUDE.md: update Intake Agent description in both repos
  • [ ] Rollback: disable records_first_intake flag → old intake behavior