Building HIPAA-Ready AI Agents: A Compliance Engineer's Checklist

Taking an AI agent into a HIPAA-covered environment is not impossible. It is exacting. The OCR (Office for Civil Rights) doesn’t read your code; they read your audit trail, your access controls, and your incident logs. The job of the engineering team is to produce those artifacts by construction, not by retrofit.

This is a practical checklist. We’ll go through what an AI agent in a HIPAA environment has to do, with examples from ONTO where they apply.

1. Decide where PHI lives

PHI lives in three places in an agent system:

• The prompt. Patient name, condition, history in the model’s input.
• The memory. Anything the agent retains across sessions.
• The logs. Inputs, outputs, intermediate tool calls.

For each, you need a story. Not a story like “we encrypt at rest” (that’s the table stakes); a story like “this specific data type has this specific retention, lives in this specific store, accessible only to these specific scopes.”

In ONTO, the primitive for this is regulation tags. Every Assertion carries tags ([phi], [pii], [mnpi], custom). Tags drive routing, retention, decay, and which consent scopes can read or write. A typical PHI memory write looks like:

onto.memory.add_assertion(
    subject="patient_a912",
    predicate="reported_symptom",
    object="chest_pain",
    tags=["phi"],
    consent_scopes=["patient:intake"],
    provenance=Source(message_id="m_42", session_id="s_2026_04_28"),
)

The [phi] tag triggers your retention policy. The consent scope governs who can read it later.

2. Sign a BAA with every vendor in the data path

If a hosted service sees PHI, you need a Business Associate Agreement with the vendor. The path of PHI is:

• The LLM provider (Claude / GPT) — needs a BAA, only available on enterprise tiers.
• The vector store (if PHI is embedded) — needs a BAA.
• The logging / observability service — needs a BAA.
• The hosting platform — needs a BAA.

This is the lift that pushes many health systems to on-prem. With ONTO’s default deployment (local Ollama + Postgres in your VPC), there are no external vendors in the PHI path. The BAA list shortens to “internal.”

3. Role-based access at the call site

HIPAA distinguishes between users with different access levels — an intake nurse, a treating clinician, a billing analyst. A single agent serving all three needs to behave differently for each.

The pattern is per-call consent scopes:

# Intake nurse: can write patient data.
onto.run_sync(
    intake_message,
    user_id="patient_a912",
    consent_scopes=["memory:write", "patient:intake"],
)

# Clinician: can read patient data and place orders.
onto.run_sync(
    "Summarize the case and propose orders.",
    user_id="patient_a912",
    consent_scopes=["memory:read", "patient:order", "audit:write"],
    mode="plan_only",
)

The Policy Guard refuses any tool whose required_consent isn’t covered. If the clinician tries to call remember() (which requires memory:write), the runtime refuses. The audit log records the refusal — which is itself evidence that the access control is working.

4. Plan Mode before any irreversible clinical action

Some agent outputs are reversible (a draft note). Some are not (a placed order, a scheduled procedure, a shared record). For the irreversible ones, an autonomous loop is unsafe — by the time the human reviews, the action has already happened.

Plan Mode separates proposal from execution. The agent proposes orders in mode="plan_only". The clinician reviews the typed Task list. They approve task by task. A second run, with execute scopes, actually places the orders.

plan = onto.run_sync(
    "Propose next steps for patient_a912.",
    user_id="patient_a912",
    mode="plan_only",
    consent_scopes=["memory:read", "tasks:write"],
)
# clinician_ui.show(plan.tasks)
# clinician approves...
for task in approved_tasks:
    onto.execute_task(task, consent_scopes=["patient:order", "audit:write"])

The audit log distinguishes Plan rows from Execute rows by plan_id. The clinician’s approval is recorded.

5. Append-only audit log at the database layer

The HIPAA Security Rule requires recording specific events: access attempts, modifications, and access by user. The right place to enforce append-only is the database, not the application.

CREATE OR REPLACE FUNCTION reject_audit_mutation()
RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
  RAISE EXCEPTION 'audit_log is append-only';
END;
$$;

CREATE TRIGGER audit_no_update
  BEFORE UPDATE OR DELETE ON audit_log
  FOR EACH ROW EXECUTE FUNCTION reject_audit_mutation();

If the application has a bug that tries to UPDATE the audit log, the database refuses. Compliance properties shouldn’t depend on the application being correct.

6. Encrypt at rest, encrypt in transit, rotate keys

Standard but easy to forget:

• TLS for all in-network traffic, including between ONTO and Postgres.
• Postgres pgcrypto for column-level encryption of PHI-tagged columns, or full-disk encryption on the volume.
• KMS-managed keys with rotation. Don’t roll your own.
• Audit log columns that contain PHI excerpts: encrypted.

ONTO’s storage layer accepts encrypted columns; configure your Postgres deployment accordingly.

7. Retention and disposal policies

HIPAA requires retention of certain records for specific durations and disposal of PHI when the retention period ends. The agent’s memory layer needs:

• Per-tag retention policy ([phi] data retained N years from last access).
• Automated purge or anonymization at expiry.
• A documented disposal procedure.

ONTO’s decay curves attach to assertions. A nightly job purges expired [phi] rows; the audit log records the purges.

8. Anonymize for evals and training

Your eval set may need to look like real PHI for the model to behave realistically. It must not actually be PHI. Three options, increasing in rigor:

• Synthetic data: generate plausible cases that aren’t real patients. Hardest to get right; safest.
• De-identification: strip the 18 HIPAA identifiers from real cases. Still PHI-derived; lower risk.
• k-anonymization: ensure no record is identifiable to fewer than k patients. Stronger but more complex.

ONTO’s eval harness reads test cases from a separate directory you can keep on a non-PHI store. Don’t run your evals against your production memory.

9. Incident response

Every covered entity has an incident response plan. Your AI agent’s piece:

• Detect. OpenTelemetry traces with PHI-tagged tool calls. Alerts when consent scope mismatches spike (indicates someone is probing).
• Contain. Disable specific consent scopes globally; pause the agent. Have a kill switch.
• Investigate. Audit log query by user_id, session_id, and tool. Plan / Execute rows linked by plan_id. The whole story is reconstructible.
• Notify. OCR has timelines. Don’t wait until you find the entire scope; report on the OCR-required schedule.

10. Documentation, documentation, documentation

The OCR auditor reads your policies before they look at your code. Have:

• A data flow diagram showing every place PHI lives.
• A consent scope matrix (which role gets which scopes).
• A retention policy per tag.
• An incident response runbook.
• A list of every system in the PHI path with the BAA on file.

This is paperwork that engineers don’t love, and it’s the difference between a green audit and a yellow one.

What ONTO gives you for free

To be concrete, here’s what the ONTO primitives map to on the HIPAA checklist:

• Regulation tags on memory → §164.308(a)(1) risk management and §164.312(b) audit controls
• Consent scopes → §164.308(a)(4) access management
• Plan Mode → §164.310(a) physical safeguards (analogue: gating high-impact actions)
• Append-only audit log → §164.312(b)
• On-prem deployment story → minimizes the BAA list

It does not give you compliance. Compliance is your policies, your training, your physical safeguards, your incident response. It gives you the technical primitives that produce the evidence those policies require.

---

See the healthcare industry page for the runnable triage example, or the features page for the consent scope details.

Frequently asked questions

Does running an AI agent automatically make my system HIPAA-covered?

No. HIPAA applies when you handle PHI. If your agent processes PHI on behalf of a covered entity or business associate, the agent system is covered. The checklist below assumes that's the case.

Can I use a hosted model like Claude or GPT under HIPAA?

Only if the vendor signs a BAA (Business Associate Agreement) and you configure their service in HIPAA-eligible mode. Anthropic and OpenAI both offer this on enterprise tiers. For many smaller health systems the cleaner path is on-prem with an open-weight model.

Is ONTO HIPAA-compliant?

ONTO is software, not a service. It provides the primitives needed to build HIPAA-aligned systems (audit trail, regulation tags, on-prem deployment, consent scopes). HIPAA compliance is a property of your overall deployment, not of any single library.