How approval-gated writes let an AI agent write to the chart

An AI agent working over clinical data has two kinds of operations: reads and writes. Reads are a privacy question: any chart context the agent pulls goes to your model provider, under your API key, with no approval step. Writes are a different kind of risk: they touch the system of record.

When the agent writes, it is making a claim that becomes part of the clinical record. A model might misread a lab value or confabulate a detail that sounds right but is wrong. If those writes saved silently, they would become chart facts that influence later decisions.

The approval gate interrupts that flow. It stops unilateral writes. But it is not magic: it is a boundary, and boundaries only work if someone stands there and pays attention.

Last EHR uses the Vercel AI SDK's needsApproval flag on its write tools. This is the actual tool definition, abridged from lib/ai/tools.ts:

record_observation: tool({
  inputSchema: z.object({
    patientId: z.string(),
    label: z.string(),   // e.g. "Systolic blood pressure"
    value: z.number(),
    unit: z.string(),    // e.g. "mmHg"
  }),
  needsApproval: true,   // the SDK pauses here
  execute: async ({ patientId, label, value, unit }) => {
    // Runs ONLY after the user clicks Approve.
    return medplum.createResource({
      resourceType: "Observation",
      status: "final",
      code: { text: label },
      subject: { reference: `Patient/${patientId}` },
      valueQuantity: { value, unit },
    });
  },
}),

1. Agent proposes: the agent calls add_note or record_observation with the data filled in.
2. SDK intercepts: because needsApproval is set, execute does not run. Nothing hits the backend.
3. UI renders the card: you see exactly what is proposed: the note text, or the label, value, and unit.
4. Approve: execute runs and the resource is created on the backend.
5. Cancel: the proposal disappears. Nothing is saved.

The proposal itself is not persisted. It lives in the chat session until you decide.

Last EHR makes two kinds of writes, both standard FHIR resources.

Notes (Communication). A note becomes a FHIR Communication with status completed, a subject pointing at the Patient, the note text as payload, and a sent timestamp. The approval card shows the full text, word for word.

Observations (Observation). A vital or lab value becomes a FHIR Observation with a label, a numeric value, and a UCUM-style unit in valueQuantity, plus status final and an effectiveDateTime. The card shows the label, value, and unit.

The exact resource shapes are in the open source, so what gets written is inspectable down to the field. On the public demo, writes are additionally tagged with your session so you only see the seed data plus your own edits; on a self-hosted instance, your Medplum AccessPolicy is the only boundary that matters.

The UI layer (the approval card). The SDK holds the write until you click Approve. This is a user-experience boundary, not a security boundary: it is where a human reads and decides.

The backend layer (AccessPolicy). When the write executes, it runs as the signed-in user, scoped by your Medplum AccessPolicy. If your policy forbids creating Observations, the backend rejects the request no matter what happened in the UI. The agent cannot see what you cannot see and cannot write what your policy forbids.

The two layers are independent. The UI gate stops thoughtless writes; the backend gate enforces permissions even if the UI is bypassed. Neither is a guarantee, but together they raise the bar.

Approval fatigue. If you always click Approve, the card becomes a ritual, not a review. Two decades of alert-fatigue research in clinical software says this is the default failure mode. The UI cannot fix that; only reading the proposals can.

Hallucinated content. The agent can propose a note containing a detail nobody said. The card gives you the chance to catch it; it does not catch it for you.

Ungated reads. Anything the agent reads from the chart goes to your model provider as context before any write is proposed. The gate controls writes; reads are governed by your provider choice and agreements, not by approval.

When the agent reads the chart, it pulls FHIR resources from your Medplum backend and includes them in the prompt to your model provider, under your API key. Last EHR keeps no database of its own: no cache of chart data, no copy of the record. Data flows through your browser session, your Medplum backend, and your model provider; on the hosted demo it also passes through the app's server routes on Vercel.

Handling real PHI would require BAAs with both your model provider and your FHIR backend; consumer API keys do not qualify. The demo runs on synthetic data only. The design intent is that the layer holds nothing: you bring the backend, the model key, and the responsibility.

The approval gate is a starting point, not a solved problem. Open questions worth debating:

• Approval modes. Should low-risk writes ever batch, or skip the card? Today every write is gated, every time. Safe, but it may not scale past a few writes per session.
• Editability. Should you be able to edit a proposed note before approving? Today proposals are atomic: approve as-is or cancel.
• Audit. The backend versions and logs the write itself, but a canceled proposal leaves no trace. Should "user saw this and rejected it" be recorded?
• Scope. Notes and observations are deliberately low-risk write types. Conditions, medications, and orders would each raise the stakes and demand more than a single confirm click.

If you have opinions on any of these, the GitHub repo is open.