Skip to main content

Medical HIPAA-Aware Extension

A canonical AAEP extension that adapts the protocol for healthcare contexts where Protected Health Information (PHI) is involved. Adds HIPAA-aware redaction rules, audit-friendly event structures, BAA-compatible capability negotiation, and medical-domain risk classification.

This is the second canonical extension after Multilingual African Languages, and the first to demonstrate AAEP's "profile" extension pattern — one that adds privacy and security constraints rather than translating content.

Referenced from Specification Chapter 7 §7.7.2 and the FAQ.


Why this extension exists

Healthcare is one of the largest accessibility-relevant domains: clinicians who are blind, low-vision, deaf, or have motor impairments need access to the same agent-driven tools as their colleagues. But healthcare has stricter privacy requirements than most domains. A naive AAEP integration in a clinical setting would leak PHI through:

  • summary_normal strings containing patient names or conditions
  • args_summary exposing medication doses or diagnoses
  • request_text echoing the clinician's spoken query verbatim
  • output.streaming chunks streaming PHI-laden agent responses
  • OTEL bridge spans accidentally indexing PHI in observability backends

This extension addresses each leak point with explicit redaction rules, audit log formats that match HIPAA's "minimum necessary" standard, and a Business Associate Agreement (BAA) capability flag for negotiating PHI-cleared sessions.

The extension does NOT make AAEP HIPAA-compliant by itself. HIPAA compliance is a property of the entire system (producer, subscriber, network, storage, business processes). This extension provides the protocol-layer building blocks; the operator still owns compliance.


What the extension provides

1. PHI redaction in event fields

Event field Default behavior in PHI mode
summary_normal Replace patient names/identifiers with [PATIENT]; replace specific dosages with [DOSE]
args_summary Use placeholders for any field containing PHI
request_text Hash-only, do NOT echo verbatim
output.streaming chunks Subscribers MUST NOT log chunks; MAY display ephemerally
tool names Tool names themselves are not PHI; pass through
error_message Strip identifiers but preserve technical detail

A producer_phi_redaction capability field signals the producer's commitment:

"capabilities": {
  "ext_medical_hipaa.producer_phi_redaction": "strict"
}

2. BAA capability negotiation

A Business Associate Agreement (BAA) is a legal document required when one party (e.g., a software vendor) handles PHI on behalf of a covered entity (e.g., a hospital). AAEP can't make this contract for you, but it can mark sessions where both parties have one in force:

"capabilities": {
  "ext_medical_hipaa.baa_in_force": true,
  "ext_medical_hipaa.baa_party": "MyAgentVendor, Inc.",
  "ext_medical_hipaa.baa_document_id": "BAA-2026-001"
}

Subscribers in BAA-cleared sessions MAY relax redaction; subscribers in non-BAA sessions MUST apply strict redaction or refuse to operate. The default is strict redaction.

3. Medical-domain risk classification

The extension recommends additional high-risk irreversible categorizations specific to healthcare:

Tool category Default classification
Prescribe medication high-risk, irreversible
Order test high-risk (cost/wait implications), reversible
Send referral high-risk, reversible-with-effort
Update medical record high-risk, reversible-with-audit
Order imaging high-risk (radiation exposure), reversible-with-effort
Read patient chart medium-risk, reversible (audit logged)
Search drug database low-risk, reversible

Each gets an awaiting.confirmation by default to satisfy the spec's safety-by-default principle for irreversible high-risk actions.

4. Audit log integration

HIPAA requires audit logging of PHI access. The extension defines an audit_metadata envelope field that subscribers and OTEL bridges can forward to compliance systems:

{
  "type": "aaep:agent.tool.invoked",
  "ext_medical_hipaa.audit_metadata": {
    "minimum_necessary": true,
    "purpose_of_use": "treatment",
    "user_role": "physician",
    "patient_identifier_hash": "sha256:abc...",
    "session_correlation_id": "session-2026-001"
  }
}

The minimum_necessary flag declares the producer's assertion that this access is the minimum PHI required for the task. purpose_of_use uses HL7-defined values (treatment, payment, operations, etc.).

5. Critical event escalation for medical alerts

The extension adds two new critical event subtypes:

  • aaep:agent.medical.alert — for clinical-significance alerts (drug interaction warning, abnormal lab value, allergy alert)
  • aaep:agent.medical.override_required — for situations where the agent recommends an action but requires a credentialed user's override

These extend the core awaiting.confirmation model with medical-specific metadata.


What this extension does NOT do

To be unambiguous about scope:

  • Does NOT make a system HIPAA-compliant. HIPAA compliance requires policies, training, business processes, and infrastructure security beyond the scope of any single protocol.
  • Does NOT replace a BAA. The baa_in_force capability is an assertion; the actual legal agreement must exist independently.
  • Does NOT define clinical decision support semantics. AAEP carries the alerts; the medical correctness of those alerts is the agent's responsibility.
  • Does NOT cover non-US regulations (GDPR healthcare-specific provisions, UK Caldicott Principles, etc.) — separate extensions could address these.

Installation

cd examples/extensions/medical-hipaa
pip install -e .

Requires Python 3.10 or newer.


Usage

Producer side

from aaep_minimal_producer.emitter import AAEPEmitter
from aaep_ext_medical_hipaa import (
    classify_medical_risk,
    redact_phi,
    audit_metadata_for,
)

emitter = AAEPEmitter(
    send_event=my_transport,
    agent_id="clinical-agent",
)

# Begin a session with BAA capability
session_id = emitter.start_session(
    summary_normal="Reviewing patient chart.",  # No PHI in summary
    capabilities={
        "ext_medical_hipaa.producer_phi_redaction": "strict",
        "ext_medical_hipaa.baa_in_force": True,
        "ext_medical_hipaa.baa_party": "MyAgentVendor, Inc.",
    },
    extension_data={
        "ext_medical_hipaa.audit_metadata": audit_metadata_for(
            purpose_of_use="treatment",
            user_role="physician",
            patient_identifier="MRN12345678",  # gets hashed
        ),
    },
)

# Risk-classify a medical tool
risk = classify_medical_risk("prescribe_medication")
# RiskAssessment(risk_level="high", irreversible=True, requires_confirmation=True)

emitter.tool_invoked(
    session_id=session_id,
    tool="prescribe_medication",
    args_summary=redact_phi(
        "patient=MRN12345678 medication=amoxicillin dose=500mg",
    ),
    risk_level=risk.risk_level,
    irreversible=risk.irreversible,
)

Subscriber side

Subscribers integrating this extension SHOULD:

  1. Refuse to operate without a BAA-cleared session OR strict redaction
  2. Treat medical.alert and medical.override_required events as critical
  3. Forward audit metadata to compliance systems (not just speak it to the user)
  4. Avoid logging PHI to any persistent store the user hasn't explicitly authorized

Risk classification reference

The shipped classifier includes 14 default tool categorizations. The full table is in aaep_ext_medical_hipaa/risk_table.json and editable per-deployment.


Project layout

medical-hipaa/
├── README.md
├── extension.json              # Extension manifest
├── pyproject.toml
├── aaep_ext_medical_hipaa/
│   ├── __init__.py
│   ├── redaction.py            # PHI pattern detection and replacement
│   ├── risk_classification.py  # Medical-domain risk classifier
│   └── audit.py                # audit_metadata_for() helper
├── risk_table.json             # Default tool→risk mappings
└── tests/
    └── test_redaction.py

Conformance

This extension is non-normative (per AAEP Chapter 7 §7.3). It defines optional capabilities, optional events, and recommended practices. Producers and subscribers MAY adopt it; the spec does not require it for AAEP conformance.

Conformance to the extension is signaled via:

{
  "supported_extensions": ["aaep-ext-medical-hipaa-1.0"]
}

A producer signaling this extension MUST follow its redaction rules in PHI-context sessions. A subscriber signaling this extension MUST handle the additional event types and audit metadata fields appropriately.


Compliance disclaimer

This extension is informational and does not constitute legal or compliance advice. Healthcare operators MUST consult their HIPAA Privacy and Security Officers, qualified counsel, and applicable regulations before deploying AAEP-based agents in clinical settings. Anthropic, the AAEP project, and the author of this extension do not assume responsibility for compliance failures in any deployment.


See also

Metadata

Release files for aaep-ext-medical-hipaa 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aaep-ext-medical-hipaa 1.0.0
File Size Uploaded Provenance Actions
aaep_ext_medical_hipaa-1.0.0.tar.gz 17.5 kB Without provenance Details for aaep_ext_medical_hipaa-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aaep-ext-medical-hipaa 1.0.0
File Interpreter ABI Platform Actions
aaep_ext_medical_hipaa-1.0.0-py3-none-any.whl Python 3 none any Details for aaep_ext_medical_hipaa-1.0.0-py3-none-any.whl

Total release size: 33.2 kB

Release files / aaep_ext_medical_hipaa-1.0.0.tar.gz

Download URL aaep_ext_medical_hipaa-1.0.0.tar.gz
Size 17.5 kB
Tags Source
SHA-256 checksum
How to use checksums
6f2769a90ed3257db073c0393294e19e474848ae78642e25568000db29d11907
BLAKE2b-256 checksum
How to use checksums
c6bea59226f708e7353408a48cd1e1b6234eaef6812159c00334ef7404531926
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / aaep_ext_medical_hipaa-1.0.0-py3-none-any.whl

Download URL aaep_ext_medical_hipaa-1.0.0-py3-none-any.whl
Size 15.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bc171220e59233e5f79af546233ca2b641841865d75c4a43e3cf8e6a3e027493
BLAKE2b-256 checksum
How to use checksums
7874987515e4652f5b5fd11de1222b3daaf3f9f0085e73998daebbafd8ee0114
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for aaep-ext-medical-hipaa 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page