Read-only vs write-back AI agents on FHIR: what changes when an agent writes?
An agent that only reads FHIR data can be wrong without changing the record. An agent that writes back becomes a participant: its output lands in the chart, the worklist or the claim. That move changes the scopes you request, the resources you can touch, the status each write carries and how retries behave.
What changes when a healthcare AI agent writes FHIR data instead of reading it?
Quick answer
Read-only vs write-back AI agents differ in what can go wrong. A read-only agent risks a bad suggestion; a write-back agent risks a bad record. Writing needs create or update scopes, resources the EHR accepts, draft statuses with sign-off, Provenance and duplicate-safe retries. Agnotic Technologies builds agents that climb this ladder one rung at a time.
| Criterion | Read-only agent | Write-back agent |
|---|---|---|
| SMART scopes | Read and search only, such as patient/Observation.rs | Adds create or update, such as patient/Observation.cu, or system scopes for backend services |
| What the EHR must support | Read and search on each resource used | Create or update on each resource, declared in the server's CapabilityStatement, checked per site |
| Status of the output | Shown to the user; nothing stored in the record | Stored as draft or preliminary until a clinician signs, such as a MedicationRequest in draft status |
| Attribution | Access logged by the EHR | A Provenance resource naming the agent, the approving user and the source data for each write |
| Retries | Safe to repeat | Must be duplicate-safe: conditional create with If-None-Exist and a business identifier |
| Stale data | A stale read gives a stale suggestion | A stale read before a write can overwrite a newer change; use version-aware updates |
| Human review | Optional, at the point of reading | Required before anything clinical becomes final |
What they are
What is Read-only agent
A read-only agent queries FHIR resources, reasons over them and shows the result to a person: a summary, a suggested code or a CDS card. It holds read and search scopes only, and nothing it produces enters the record unless a person enters it.
What is Write-back agent
A write-back agent creates or updates FHIR resources: a draft order, a preliminary note, a task, a questionnaire response or an administrative field. Its writes become part of the record, so each one needs a status, an author trail and a review step that fit its risk.
Key differences
Which SMART scopes does a write-back agent need?
SMART App Launch v2 builds scopes from the letters c, r, u, d and s: create, read, update, delete and search. The specification's own examples are patient/Observation.cu to create and update observations and patient/Observation.rs to read and search them. Request the narrowest set per resource, and expect sites to grant less than you ask for.
How do you know which writes an EHR accepts?
Read the server's CapabilityStatement, which documents the interactions it supports for each resource, then confirm in each site's sandbox. Support differs by vendor, version and site configuration, so keep a per-site matrix and let the agent fall back to a suggestion where a write is not supported. Our Epic FHIR capabilities page covers Epic specifics.
Why should every agent write carry Provenance?
The FHIR Provenance resource records the activity that created, revised or signed a version of a resource and the agents involved. For an AI write, name the agent and model version as one agent, the approving user as another, and the resources it read as entities. That lets a reviewer answer who or what wrote this line, and from which data.
How do you stop duplicate writes on retry?
Use conditional create. With an If-None-Exist header carrying a business identifier, the server creates the resource only if no match exists, returns 200 OK if one does, and returns 412 Precondition Failed if several match. For updates, send If-Match with the version you read, so a change made since your read is not overwritten. FHIR R4 marks conditional interactions as trial use, so test them on each server.
What goes wrong when agents write?
Four failures recur. Duplicate writes when a timeout triggers a retry. Wrong-patient writes when the launch context changes mid-task and the agent keeps the old patient. Stale reads, where the chart changed between the read and the write. And an unsupported resource at one site that fails quietly while the agent reports success. Each needs a test case before go-live.
Does writing back change the FDA picture?
The FD&C Act excludes some clinical decision support software from the device definition when, among other criteria, it lets the professional independently review the basis for its recommendations (21 U.S.C. 360j(o)(1)(E)). A draft that a clinician signs without seeing its sources weakens that review. Show the source data with every draft the agent writes.
When to use each
When to use Read-only agent
- Chart summaries and pre-visit briefs.
- Coding or documentation suggestions that a person accepts in the EHR's own screen.
- Early pilots, while you measure accuracy against real charts.
- Sites whose EHR does not accept writes for the resource you need.
When to use Write-back agent
- Draft notes and orders that a clinician signs inside the EHR.
- Tasks and worklist items created from inbox or referral triage.
- Low-risk administrative data, such as a confirmed contact preference.
- Workflows where retyping a suggestion would add errors of its own.
How does an agent move up the permission ladder?
1. Read only. The agent reads Patient, Condition, Observation and notes with rs scopes and shows a summary. Review: the user reads it.
2. Suggest. The agent returns a CDS card or in-app suggestion, the user accepts it in the EHR's own screen, and the EHR writes the record. Review: at the moment of acceptance.
3. Draft for sign-off. The agent creates a MedicationRequest in draft status or a DocumentReference with a preliminary docStatus, using c scopes. Review: a clinician signs, and only then is it final.
4. Write with per-action approval. The agent creates a Task or updates an Appointment after a person approves that specific action. Review: one approval per write, recorded in Provenance.
5. Autonomous write for low-risk administrative data. The agent updates fields such as a contact preference without per-action approval. Review: a sampled audit of writes and a switch that turns writing off.
Move up one rung only when the clinical owner accepts the error rate measured on the rung below, on real charts.
Which sources does this comparison rely on?
- HL7 SMART App Launch 2.2.0: scopes and launch context (hl7.org)
- HL7 FHIR R4 RESTful API: conditional create and version-aware updates (hl7.org)
- HL7 FHIR R4 Provenance resource (hl7.org)
- HL7 FHIR R4 CapabilityStatement resource (hl7.org)
- 21 U.S.C. 360j(o): software functions excluded from the device definition (govinfo)