Agent on FHIR: How to Build FHIR AI Agents That Read, Reason, and Write Clinical Data

Part of our complete guide to AI agents transforming care delivery.

FHIR AI agents connect to clinical data through an EHR's FHIR REST API, using a SMART on FHIR token that limits what they can see and change. The model never calls the API itself: it asks a tool layer, which checks the request, makes the FHIR call, logs it, and writes anything clinical back as a draft for a clinician to sign.

Updated October 2026. Specifications were checked on 30 October 2026.

This guide is for teams building agents on FHIR data: which resources to read and write, how scopes and tool calling work, where MCP fits, and how to mark AI output. If you need a team to build the connection, see our FHIR integration services. For the wider question of connecting an agent to an EHR by any route, including HL7 v2 feeds and work without an API, read how AI agents integrate with EHR systems.

How do healthcare AI agents connect to FHIR data?

Healthcare AI agents connect in five steps, and only the tool layer ever touches the FHIR server. Each step has a different owner, which is what makes healthcare agent data integration reviewable by a security team.

This design also lets an agent integrate with existing systems without disrupting operations, because a read-only agent changes nothing in the EHR and a draft waits in a clinician's normal review step. Start read-only, then add one write at a time.

What FHIR gives an AI agent, and what it leaves out

FHIR gives an agent a common data model, a search API and a shared authorization pattern, so the same Observation search can work across vendors. It does not give you write access: the ONC certification criterion for standardized APIs, 170.315(g)(10), covers read services and specifically excludes write.

That split shapes every plan for FHIR and AI. Reads are the dependable part of a FHIR API for AI, while writes vary by vendor, resource and customer. Profiles differ too, so test against each real target and read its capability statement at GET /metadata. Oracle Health documents this check for its Millennium APIs, and Epic publishes per-resource API pages at fhir.epic.com.

Generative AI in FHIR healthcare work mostly takes three forms: summarizing a chart from FHIR data, drafting a note or task from it, and answering questions about it. A related use, turning old HL7 v2 messages into FHIR, belongs to the integration layer and needs the same testing. For retrieval over larger records, see our guide to a FHIR-native RAG pipeline, which covers how to prepare FHIR data for AI search.

What should a FHIR AI agent read?

A FHIR AI agent should read only the resources its task needs. That keeps the prompt small and supports HIPAA's minimum necessary principle. A medication reconciliation agent needs medications and allergies, and it has no use for every old note.

Search support differs by server, so confirm each parameter in the capability statement. Sorting with _sort is one to check before you rely on it. Rate limits differ too. We could not find one published figure that holds across EHRs, so read the limit in your target's documentation, cache what rarely changes, and back off on a 429 response.

What can an AI agent safely write through FHIR?

An agent can safely write proposals that a person reviews: a preliminary note, a draft order or a task. Nothing should become active until a clinician approves it, and your target EHR must accept that write in the first place.

Here is an illustrative note write. The AIAST tag comes from the HL7 guide covered below.

POST /DocumentReference
{
  "resourceType": "DocumentReference",
  "meta": {
    "security": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
      "code": "AIAST",
      "display": "Artificial Intelligence asserted"
    }]
  },
  "status": "current",
  "docStatus": "preliminary",
  "type": {"coding": [{"system": "http://loinc.org", "code": "11506-3", "display": "Progress note"}]},
  "subject": {"reference": "Patient/{patient_id}"},
  "content": [{"attachment": {"contentType": "text/plain", "data": "{base64_encoded_note}"}}]
}

Which EHRs accept this varies, so check before you design around it. Our guide to clinical notes with FHIR DocumentReference compares EHRs on this write.

Keep these rules outside the model, in code it cannot change:

• Give each tool one FHIR operation and its narrowest scope, for example patient/Task.c.
• Take the patient ID from the launch context. Never accept it from the model.
• Validate each resource before you send it. FHIR defines a $validate operation for this, if the server supports it.
• Treat note text and retrieved documents as untrusted input. Nothing in them can widen what a tool may do, which is your main prompt-injection boundary.
• Log the user, patient, scope, tool and result of every call.

Our guide to HIPAA compliant AI agent architecture covers BAAs, PHI flows and security review.

Which SMART on FHIR scopes and flow does an agent need?

Use SMART App Launch when a clinician is present, and SMART Backend Services when the agent runs with no user. App launch keeps the agent inside that user's and patient's context, while backend services give it its own identity, so its pre-approved scope list needs extra care.

SMART v2 scopes use the letters c, r, u, d and s for create, read, update, delete and search, so patient/Observation.rs means read and search. The older .read maps to .rs, and .write to .cud. Some servers still expect the older form, so check what yours supports.

Backend Services uses the client_credentials grant with a one-time signed JWT. The spec requires the iss, sub, aud, exp and jti claims, sets exp no more than five minutes ahead, and says clients should sign with RS384 or ES384. It also says expires_in should not exceed 300 seconds, so plan on signing often.

How do healthcare AI agents handle tool calling?

Healthcare AI agents handle tool calling in a loop: the model asks for a tool, your code checks the request and calls FHIR, and the trimmed result goes back until the model can finish. The model chooses what to ask for, and your code decides whether that happens.

Keep the tool parameters small. A well-formed tool has no patient_id parameter, because the tool layer already knows the patient. This illustrative definition shows the shape:

{
  "name": "get_active_medications",
  "description": "Return the current patient's active medications with RxNorm codes when present",
  "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
}

Drug interaction checks need a named source. Older agent examples called the NLM RxNorm interaction API, but NLM announced its discontinuation for about January 2024. Pick a maintained source your clinical team accepts, and let the model report what that source returned instead of judging interactions itself. That same rule covers trusted medication information in general.

What triggers a FHIR AI agent?

A FHIR AI agent is usually triggered in one of three ways: a CDS Hooks call during a clinical action, a clinician opening a SMART app, or a background event. The trigger decides how long the agent has and how it authenticates.

For HL7 FHIR AI integration, a v2 feed and a FHIR API often work together: the feed says something happened, and the agent reads the detail through FHIR. AI note-taking systems integrate with FHIR, SMART on FHIR and EMR APIs in a similar way, with a SMART launch for patient context and a DocumentReference write for the draft note. Voice agents that integrate with Epic, athenahealth or other major EHRs follow the same pattern where those systems allow it.

Where does MCP fit with FHIR?

MCP is one way to expose FHIR tools to a model, and it sits above FHIR without replacing any part of it. It is an open protocol separate from HL7, so it has no bearing on FHIR conformance.

An MCP server can publish tools such as get_active_medications, translate them into FHIR calls, and return structured results. That lets several models share one tool set, and it can connect AI agents with trusted medication information through the same interface.

Three points from the 28 July 2026 specification matter in healthcare:

• Authorization is optional in MCP, so a health data server has to turn it on and test it.
• MCP servers must not accept or pass along tokens issued for other services. Keep the SMART token inside the server, separate from the token the MCP client presents.
• The spec says MCP cannot enforce its consent principles at protocol level, and that tool descriptions from untrusted servers should be treated as untrusted. Approval and audit remain your code's job.

Research is early. An open-source MCP-FHIR framework from 2025 was evaluated on synthetic SMART sandbox data and its abstract reports no quantitative results, so treat it as a design example.

How do you test a FHIR AI agent?

Test retrieval and reasoning separately, on synthetic or de-identified records, before any real patient data is involved. FHIR-AgentBench, a public benchmark of 2,931 real-world clinical questions, found that retrieving data from complex FHIR resources and reasoning over it both substantially affect performance.

Your own test set should cover the wrong patient, an empty search, paged results, an expired token, a denied scope, a rejected write, a duplicate write after a retry, and a note containing instructions aimed at the model. Score whether each answer cites the right resources as well as whether it reads well.

How do you mark AI output in FHIR?

Mark AI output with the AIAST security label in meta.security, and add a Provenance record when readers need the detail. Both come from HL7's AI Transparency on FHIR guide, which you can pilot but which has not reached a final release.

As of 30 October 2026, the published edition is the 1.0.0 STU1 ballot, trial use, and it states that no official version has been published. NIST says organizations may pilot it and expects further revisions. The guide records how AI was involved. As NIST puts it, the guide does not evaluate AI systems, judge the data, or detect undisclosed AI use.

Check that your EHR keeps these labels and accepts Provenance. If it does not, hold the same record in your own audit store and link it to the resource ID. AIAST alone does not say whether a clinician reviewed the output, so record the review separately.

What is the best agent-ready integration for HL7 FHIR in healthcare?

No product is the best agent-ready integration for every buyer, because the right one depends on which EHRs you must reach and which writes they accept. Judge any vendor, AI CDS platform or tool by what it can show on your own target systems.

This matters for procurement because AI CDS that supports FHIR-based data exchange can move with you across EHRs, while a custom feed often has to be rebuilt. Interoperability with major EHR ecosystems still has to be evaluated system by system.

Two common requests need plain answers. A voice agent cannot be guaranteed to behave deterministically, because the model output can vary. What you can control is the structured FHIR output, by validating it against a schema and a profile before anything is saved. For building a production-ready agent that can query EHR and claims data, expect separate sources, since claims may arrive as CARIN Blue Button ExplanationOfBenefit resources or X12 files, and the same patient may be modeled differently in each. Reconcile patient identity before the agent sees either set. If your FHIR data sits in Medplum or another FHIR server, the same governance and audit trail questions apply, and a development partner should be able to answer them on that server.

How do you build your first agent on FHIR?

Build one read-only workflow first, on synthetic data, and add a single draft write only after it passes tests. This order works with any healthcare AI agent framework, since the safety rules live in your tool layer.

1. Pick one workflow with a named clinical owner.
2. Stand up a test FHIR R4 server, such as HAPI FHIR, or use your EHR's sandbox. Load Synthea synthetic patients.
3. Choose the trigger and request the smallest scopes.
4. Write one tool per FHIR operation, and use MCP if several models or clients will share them.
5. Run the test set above, then show the results to the clinical owner.
6. Add one draft write with an approval step, an AIAST label and Provenance.
7. Check every assumption in the customer's own environment, since scopes and profiles there can differ from the sandbox.

What we can show you

We are ISO 27001:2022 certified and we sign BAAs. Public work you can inspect includes a SMART on FHIR app run against Epic and Oracle Health developer sandboxes and an open-source headless EHR that passed 47 of 47 ONC (g)(10) SMART App Launch Standalone Patient App tests on 27 October 2026. That result covers the SMART group only, and it is not full (g)(10) certification. We have also built more than 350 Mirth Connect interfaces, which helps when an agent needs HL7 v2 events.

Planning an agent that reads or writes FHIR data? We can review your scopes, approval flow and write paths before you build. See AI agent development for healthcare or talk to our team.