01
Identity
Do the records refer to the same patient, member and provider? Compare identifiers and record uncertainty before trusting a join across systems.
Free architecture whitepaper + Java reference code
Context engineering for healthcare AI agents
The Agent Context Layer
Before an agent drafts a request or proposes an action, decide which patient it concerns, which facts it can use, which rule applies and who may approve the next step. This whitepaper proposes an integration-first context layer and includes a small, runnable Java reference build using fictional data.
- 33-page PDF
- 7 context questions
- Java 17+ reference
Start before the agent acts
What is healthcare AI context engineering?
Context engineering for healthcare AI agents is the work of selecting, preparing and maintaining the information available for a particular task. The Agent Context Layer applies that idea to healthcare integrations: facts arrive with sources, rules have versions, conflicts remain visible, gaps are explicit and the requested action has a permission decision. The paper proposes a shared layer between agents and the systems they use.
In a prior-authorization workflow, a useful answer needs more than a matching paragraph. The team needs to know whether the EHR and payer records refer to the same person, which rule applies to the service, which evidence is admissible and which step requires a reviewer. The paper uses that workflow to make the architecture concrete.
If you are scoping the engineering, explore AI agents for healthcare and healthcare interoperability services. A context layer depends on the underlying access and integration work; the whitepaper does not make those connections available by itself.
Healthcare agentsEligibility, prior authorization, denials and other bounded tasks
Agent Context LayerTask-specific facts, source evidence, rules, authority and case state
Integration Control PlanePermitted connections and execution paths to EHRs, payers and clearinghouses
This diagram describes the proposed architecture. The emailed reference exercises local context-assembly logic only.
Make each input reviewable
Seven questions a healthcare agent’s context should answer
02
Facts and sources
Where did this value come from, when was it obtained and why was it selected? Preserve competing evidence when sources disagree.
03
Rules and versions
Which payer policy or operating procedure applies to the task? Record its version and the date or service context it covers.
04
Authority
Which data may this task receive, and which actions are permitted, require approval or remain prohibited? An available tool is not itself permission.
05
Case memory
What has already been submitted, received or reviewed? Keep case history and follow-up state distinct from a conversational summary.
06
Document trust
Which inputs are evidence to inspect rather than instructions to follow? The proposed design treats retrieved documents and tool content as untrusted data.
07
Gaps
What is missing, conflicting or outside the evidence rules? Give the reviewer a specific question instead of asking a model to invent an answer.
A reading path through the whitepaper
Five parts, then a build plan and technical reference
Start with the problem and pattern, compare approaches, then inspect what the reference actually demonstrates. The final pages separate the proposed production packet from the small code example.
- 01
Pages 4–7
Why context and control matter
Examine wrong-entity joins, stale policies, unauthorized actions, untrusted input and context leakage. The paper separates published research, vendor claims and architectural judgment.
- 02
Pages 8–11
Define the context layer
Locate the proposed layer above healthcare connections and below agents. Review its two jobs: assemble task-specific context and record the evidence behind a run.
- 03
Pages 12–16
Compare the available approaches
Compare retrieval, graphs, semantic definitions, matching, memory, live tools and fine-tuning. Consider how MCP and existing healthcare standards fit into the design.
- 04
Pages 17–21
Design the architecture and workflow
Review six design principles, a ten-component proposed architecture, a worked prior-authorization flow and twelve engineering challenges to resolve.
- 05
Pages 22–25
Inspect the reference build and its limits
Follow a dependency-free Java example through identity comparison, field selection, conflicting sources, evidence criteria, authority decisions and a local case ledger.
- 06
Pages 26–33
Plan the first slice and implementation
Use the suggested build order, decision owners, code instructions, proposed packet shape and source list to prepare a scoped technical discussion.
Compose the tools around the task
Context layer, RAG, memory or live tool calls?
These approaches solve different parts of the information problem. The comparison below describes their roles in the paper’s proposed design. It does not rank products or predict an accuracy gain.
| Approach | Useful role | Boundary to review |
|---|---|---|
| Document retrieval | Find policy text, operating procedures and supporting documents. | A retrieved passage still needs authority, version, date and trust checks. |
| Knowledge graph | Represent links among patients, coverage, providers, orders and encounters. | A plausible relationship is not a confirmed identity match; freshness and permissions remain separate concerns. |
| Semantic definitions | Give terms such as active coverage and authorization required a shared meaning. | Definitions need an owner and a version; the layer must still select the applicable source evidence. |
| Patient and member matching | Compare identities before joining EHR and payer records. | A production matcher needs measured thresholds and review. The reference uses fixed comparisons, not a scored matching service. |
| Case memory | Retain submissions, reference numbers, responses and follow-up state. | The demo appends a local ledger line. It does not implement a durable, multi-tenant case-management system. |
| Live tools and APIs | Obtain current data through a permitted system connection. | Access, retries, data minimization, cross-source reconciliation and a verified result still need design. |
| Fine-tuning | Adapt response style or output format where appropriate. | Changing model weights does not provide field-level sources or keep a payer rule current. Check content rights for any training or retrieval use. |
Design principles and implementation boundaries
Sources, freshness, conflicts, gaps and authority
Attach provenance to facts
Keep the source, relevant dates and selection reason with the value. A source label supports review; it does not establish that the underlying value is correct.
Make freshness a decision
Define the age and effective-date requirements for each task. Production stale-data stops are proposed work, not demonstrated by the current reference.
Keep conflicts visible
Use an explicit precedence rule and retain the competing value and reason. The demo’s fictional portal preference is specific to its fixture.
Represent missing evidence
Return a gap the reviewer can act on. The reference marks an unsigned treatment plan as a gap without making a medical-necessity decision.
Carry field-level restrictions
The proposed packet includes sensitivity, consent and licensing labels. Those labels and their enforcement are not implemented in the reference build.
Define action authority outside the model
The reference returns alone, needs approval or never from a local policy. Production execution needs an enforced gate and a recorded approval, not just a returned label.
Field selection demonstrates one narrow policy behavior. It does not establish HIPAA compliance, valid consent or permission to use licensed content.
Inspect the supplied working code
A synthetic prior-authorization context demo
The reference reads a fictional EHR bundle, eligibility response, payer rule and authority policy from local files. Its 17 self-checks passed when run with OpenJDK 17 on October 30, 2026. These checks cover the fixture behaviors, rather than a clinical or production outcome.
Verification note on the supplied PDF
Page 24 describes an identity mismatch as stopping the case. In the supplied code, it adds a warning flag and still returns the packet. The website describes that narrower behavior; the PDF and code are preserved as supplied.
Recorded synthetic output · no live connections
Choose an action to inspect its saved Java reference output. This viewer makes no model, EHR or payer call and accepts no patient data.
Clinician approval required by the demo policy
Returned decision: needs approval from clinician. No action was executed.
- Identity comparison
- matched in the fictional fixture
- Fields withheld
- patient.phone, patient.address
- Open evidence gap
- Unsigned treatment plan remains a GAP
Permission and readiness are separate: the drafting decision remains “alone” while an evidence gap is still present. The reference returns flags and decisions; it does not enforce a production action gate.
Inspect the allowlisted output
{
"action": "submit_request",
"authority": {
"requested": "submit_request",
"decision": "needs approval from clinician"
},
"identity": {
"matched_on": [
"name",
"date of birth",
"member id"
],
"status": "matched"
},
"withheld": [
"patient.phone",
"patient.address"
],
"criteria": [
{
"criterion": "diagnosis",
"status": "met",
"source": "FHIR Condition/cond-1",
"excluded": []
},
{
"criterion": "symptom_severity",
"status": "met",
"source": "FHIR Observation/obs-v12",
"excluded": [
"obs-pcp: author outside treating practice",
"obs-intake: 119 days old, window is 30"
]
},
{
"criterion": "functional_impairment",
"status": "met",
"source": "FHIR Observation/obs-impair",
"excluded": [
"obs-impair-old: 45 days old, window is 30"
]
},
{
"criterion": "treatment_plan",
"status": "GAP",
"source": "FHIR CarePlan/cp-1",
"excluded": []
},
{
"criterion": "response_to_treatment",
"status": "met",
"source": "FHIR Observation/obs-intake, /obs-v12",
"excluded": []
}
],
"flags": [
"GAP: treatment_plan to the clinician"
],
"deadline": {
"value": "2026-11-10",
"source": "NSH-BH-OP-7",
"as_of": null,
"why": "5 business days before the visit"
},
"conflict": {
"value": 40,
"source": "payer portal",
"as_of": "2026-11-04",
"why": "portal wins for behavioral health benefits; 271 said 35"
}
}Run the Java reference locally
Extract the ZIP, put Java 17 or newer on your PATH and open the demo directory. The run script compiles the source, runs its self-checks, then writes a packet and ledger under out/.
./run.sh
./run.sh edit_chartKeep the evidence boundary visible
What the reference demonstrates
Identity comparison
Compares name, date of birth and member ID across the synthetic EHR and eligibility inputs. A mismatch produces a status and warning flag.
Purpose-based field selection
Omits the configured phone and address fields from the returned facts and lists them as withheld. This is a narrow fixture demonstration, not a compliance assessment.
Source conflict explanation
Chooses the fictional portal copay under a written fixture rule and records the differing eligibility value in the reason.
Evidence selection and gaps
Uses the treating-practice and age conditions in the example; records exclusions and marks the unsigned plan as a gap.
Authority decision
Returns the configured action decision. Submitting requires clinician approval, chart editing returns never, and an unlisted action defaults to never.
Local record
Writes a context packet and appends a ledger entry. It does not send a payer request, write a chart, or create a standards-conformant audit service.
What remains outside this reference
- No live EHR, clearinghouse, payer API, model call or MCP server is connected.
- Identity mismatch raises a flag; the assembler still returns a packet. It is not an enforced disclosure or execution stop.
- Action authority is a returned decision. No real action is executed, approved or prevented by an execution gateway.
- No production authentication, tenant isolation, consent evaluation, terminology service or licensing enforcement is implemented.
- The deadline helper skips weekends. It does not use payer-specific holiday calendars.
- The local ledger is not tamper-evident, and the demonstration does not establish clinical accuracy, ROI or deployment readiness.
Choose one slice you can measure
Move from a reference packet to an implementation plan
The paper recommends starting with a read-only task on connections the customer can already use. Agree the needed inputs, source ownership, expected output and review process. Save representative packets and disagreements so later changes can be evaluated against the same cases.
Before allowing a write or submission, implement and test the actual gate: the requested action, the identity and authority of its approver, the exact record being changed, the execution receipt and the recovery path. Returning a permission label in a context packet is only one input to that process.
Production scope also needs decisions about tenant isolation, data retention, audit integrity, freshness rules, source changes and the customer’s contracts. The whitepaper proposes a build order and a packet shape; it does not provide a fixed delivery schedule or a preconfigured product.
Read the actual pages
Preview the context questions, architecture and reference evidence
Seven context questions for each task
The proposed reference architecture
Inputs and outputs of the Java reference
What the reference does and does not show
Questions before you request it
Healthcare context engineering: common questions
What is context engineering for healthcare AI agents?
It means preparing the information an agent receives for a specific healthcare task, including identity, source evidence, applicable rules, permissions and missing information. The whitepaper proposes an Agent Context Layer to assemble this information above the integration layer and keep a record of the decisions.
How is a context layer different from RAG?
Retrieval-augmented generation finds supporting material. The proposed layer also addresses identity, source precedence, rule versions, task permissions, case state and gaps. Retrieval can be one component; finding a relevant document does not establish that its rule applies to the case.
How does this relate to MCP and FHIR?
The paper discusses MCP as an interface for tools and context, and FHIR and other healthcare interfaces as sources and exchange mechanisms. The proposed architecture still needs permission, trust and action checks around them. The supplied Java demo reads local synthetic fixtures; it is not a FHIR server or MCP implementation.
What comes in the email?
The complete 33-page PDF and a ZIP of the runnable Java reference code. The code includes fictional input data, a run script and 17 self-checks. The four page previews come from the same PDF.
Can I run the Java reference code locally?
Yes. Extract the ZIP, make Java 17 or newer available on your PATH, open the demo directory and run ./run.sh. Run ./run.sh edit_chart to inspect the forbidden-action decision. The script compiles the source, runs the self-checks and writes a context packet and local ledger under out/.
Is the example using real patient or payer data?
No. The patient, practice, payer, policy and dates are fictional. The browser viewer shows an allowlisted summary of recorded reference runs and accepts no patient data. It does not call a model, EHR, payer or clearinghouse.
Does an identity mismatch stop the demo?
The PDF describes a stopping boundary. The supplied reference reports MISMATCH and adds a warning flag, then still assembles and returns the packet. A production implementation must explicitly enforce any required stop before disclosure or action; the warning flag alone does not do that.
Does needs approval mean an approval workflow exists?
No. It is a decision returned from the local policy. The reference does not collect an approval, verify an approver or submit a request afterward. Those are separate implementation steps for a real execution gateway.
Do the 17 passing checks establish production readiness?
No. They check the narrow reference behaviors against its synthetic fixtures. They do not prove real-system connectivity, scored patient matching, security controls, clinical accuracy, standards conformance or improved business outcomes.
How do I get the PDF and the code?
Enter your work email in the form on this page and we send both files to your inbox. It does not subscribe you to marketing emails.
Connect the architecture to the work
Related healthcare engineering guides and services
A concrete starting point
Bring one agent task and its source systems
Discuss the context packet, integration access, source conflicts and approval boundary your team needs. Bring sanitized workflow details and the decision you want to test.
Discuss your context layer ↗Scope, access requirements, evidence and ownership need agreement before implementation. No patient data is needed for an initial discussion.