AI medical assistant
The components of an AI medical assistant — LLM, medical context, patient data, consent, FHIR, safety and audit — a request step by step, and the warnings to build in.
An AI medical assistant is an application in which a language model answers health questions using a specific person's medical data — "how has my blood pressure changed since I started amlodipine?", "what should I bring to my cardiology visit?". Building one takes more than a model: it needs the patient's data in a usable form, consent to use it, a way to keep facts apart from generated text, safety rules and an audit. Anpheros provides the data side of that: the patient's HL7 FHIR R4 record, consent, the context API and the access log.
In this architecture Anpheros is the medical data layer — the managed FHIR R4 store of the patient's record and the API around it. The assistant, its prompts and the model are yours.
Anpheros Daily, the Anpheros patient app, includes such an assistant for its users. This page describes the components for building your own.
The components
┌─────────────────────────────────────────────────────────────────────┐
│ Assistant UI chat, voice, suggested questions, sources │
├─────────────────────────────────────────────────────────────────────┤
│ Your backend identity, safety rules, prompt, model calls │
│ ├─ Consent ───────► OAuth grant from the patient (Anpheros) │
│ ├─ Context ───────► POST /v1/context (Anpheros) │
│ ├─ LLM ───────► the model you choose (hosted or local) │
│ └─ Write-back ─────► optional notes with author_type "ai" (Anpheros)│
├─────────────────────────────────────────────────────────────────────┤
│ Patient data FHIR R4 record, provenance, access log │
└─────────────────────────────────────────────────────────────────────┘
| Component | Role | Provided by |
|---|---|---|
| LLM | understands the question and writes the answer | you choose: a hosted provider or a local model |
| Medical context | the relevant part of the record, within a budget, labelled by source | Anpheros context API |
| Patient data | coded observations, conditions, medications, allergies, documents | Anpheros FHIR R4 record |
| Consent | the patient's permission for the assistant to read their record | Anpheros OAuth grants (or your project's own patients) |
| FHIR | a standard model the context is built from | Anpheros |
| Safety layer | what the assistant must not do, and when to hand over to a person | your backend and prompts |
| Audit | who read what, when | Anpheros access log, manifest_id per context |
A request, step by step
- The user asks a question in your app.
- Your backend checks who the user is and which Anpheros record they may use (their own, or a dependent's they hold).
- It requests a context:
POST /v1/contextwith the question, a task description and a budget. - It builds the prompt: your system instructions, the context text with its source labels, and the question.
- It calls the model and receives an answer.
- It checks the answer against its safety rules and shows it with the sources used.
- It stores the
manifest_idwith the conversation, so the answer can later be traced to the data it was based on.
import { Anpheros, apiKey } from '@anpheros/sdk';
const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });
const ctx = await anpheros.context.build({
patient: patientId, task: 'answer a patient question', question, budget_tokens: 2000, format: 'text',
});
const answer = await callYourModel({ system: SAFETY_AND_PROVENANCE_RULES, context: ctx.text, question });
await saveConversationTurn({ question, answer, manifestId: ctx.manifest_id, omitted: ctx.omitted });
callYourModel is your own code for the provider or local runtime you use.
Warnings to build in
- It is not a clinician. The assistant should explain and summarise the person's data, not diagnose or change treatment. Anything that looks like an urgent symptom should lead to a clear instruction to contact a doctor or emergency services.
- Regulation. Depending on its claims, an assistant can fall under medical-device rules. Anpheros does not claim medical-device certification or any regulatory approval; that assessment belongs to the product.
- Hallucinations. Show the sources the answer relies on, tell the model to say when the context is partial (
omitted), and keep AI-generated notes apart from facts (ai_notes). - Data leaving your infrastructure. With a hosted model the context is sent to that provider; consent, privacy notice and agreements must cover it. A local model keeps the prompt in your infrastructure.
- Access scope. Request only the scopes the assistant needs; a context requires read access to observations, conditions, medications and allergies.
- Transparency. The patient sees every context request in the access log of your application. Say in your product that the assistant reads their record.