Putting AI agents on FHIR data

Four ways to connect an agent

The choice here determines what every later control can do. Policy you cannot enforce at the connection point has to be enforced in a prompt, and a prompt is a request rather than a constraint.

Grant read and search, not everything

SMART App Launch 2.0 replaced the coarse .read and .write with five letters — create, read, update, delete, search — which must appear in that order. The distinction matters for agents specifically: reading a known resource and searching across a type are different capabilities, and an agent exploring a record does far more of the second.

Write scopes are a different decision

Read access to the wrong resource is a privacy incident. Write access to the wrong resource changes a clinical record. Grant c, u and d in a separate token from the read path, so that widening the agent's reading never silently widens what it can change.

Minimum necessary, applied to a context window

HIPAA's minimum necessary standard predates the idea that a request would be assembled by a statistical model, but it maps onto it cleanly: the agent should receive the least data that lets it do the job. The practical difficulty is that FHIR resources carry identity in more places than people expect.

The narrative block is the one people miss

Nearly every resource may carry a text.div — an XHTML restatement of its contents for human display. Strip Patient.name and leave the narrative untouched and you have redacted nothing; the name is still there, in markup, one field over.

{
  "resourceType": "Patient",
  "id": "example",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">
              Jane Q. Doe, MRN 44xxxx19, born 1974-03-02
            </div>"
  },
  "name": [ { "_family": { "extension": [ /* redacted */ ] } } ],
  "identifier": [ /* redacted */ ]
}

The other reliable carriers are Patient.telecom, Patient.address and every free-text note on a clinical resource. Dates of service are quasi-identifiers too: a handful of them plus a postcode re-identifies a person more often than teams assume.

Record what a model did, not just what a client did

A conventional access log answers “which client read this record.” For an agent that is not enough to answer the question you will actually be asked, which is why it read the record and who was accountable for the result.

FHIR gives you two resources for this and they do different jobs. AuditEvent records that an access happened. Provenance records where a piece of data came from, which is what you need when an agent contributes to the record rather than only reading it.

Capture the model as a first-class actor

At minimum, an agent action should be reconstructable from the audit trail alone: which model and version, which system prompt revision, which tool was called with which parameters, which human approved it if a human did, and which patient compartment it ran in. If you cannot answer those from storage six months later, you do not have an audit trail — you have logs.

Writes go to a queue, not to the server

The safest agent write path does not write. It proposes: the agent produces a candidate resource, the broker holds it, and a human approves or rejects it before anything reaches the FHIR server. The approval is itself recorded, so the clinical record carries a human's accountability rather than a model's.

This is unglamorous and it is the control that survives contact with a compliance review. It also degrades well: when the model is wrong, the failure is a rejected proposal rather than a corrected chart.

What actually goes wrong

Ordered roughly by how often they appear in real implementations rather than by severity.

Reference implementation

HealthClaw is the broker pattern described above, built in the open. Redaction, audit and human sign-off are enforced server-side rather than requested in a prompt, which is the whole argument of this page reduced to running code.