Healthcare AGENTS.md Template for Healthcare Workflow Agents

Overview

The AGENTS.md template for healthcare workflow agents defines the operating context for AI coding agents used in health IT workflows. It governs both single-agent operation and multi-agent orchestration, with explicit handoffs, supervisor behavior, and governance rules to ensure patient safety and regulatory compliance.

When to Use This AGENTS.md Template

• Use when coordinating AI agents for patient triage, data integration from EHR, labs, and imaging, and care coordination.
• When you require tool governance, security, and privacy controls aligned with HIPAA.
• When you need clear handoffs and escalation paths between planner, implementer, researcher, reviewer, tester, and domain specialist.
• When you want a reproducible operating manual that can be shared across teams.
• When you plan to run multi-agent workflows with robust validation and rollback rules.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Healthcare AI operations orchestrator for patient triage and care coordination.

Agent roster and responsibilities:
- Planner: defines tasks, sequencing, and decision boundaries for patient data processing and triage.
- Implementer: executes steps using EHR/Lab/API integrations and writes outputs to sources of truth.
- Reviewer: medically validates outputs and ensures alignment with clinical guidelines.
- Tester: validates correctness against synthetic and de-identified data.
- Researcher: sources updated domain knowledge and verifies new data sources.
- Domain Specialist: provides clinical domain expertise (e.g., cardiology, oncology) for specialized triage rules.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates all agents, enforces the memory model, and maintains the source of truth.
- It triggers handoffs, resolves conflicts, and ensures data lineage.

Handoff rules between agents:
- Planner → Implementer: provide task specification and data schemas.
- Implementer → Reviewer: present results for validation.
- Reviewer → Implementer: request changes if clinical criteria fail.
- Implementer → Researcher/Domain Specialist: for rule updates or new data sources.
- Researcher/Domain Specialist → Planner: propose improvements to workflow logic.

Context, memory, and source-of-truth rules:
- Use a dedicated data store as the source of truth; preserve patient context across steps.
- Avoid PHI leakage in memory; only summarized or de-identified context is stored for training/testing.
- All PHI must be encrypted at rest and in transit; access controlled by role-based policies.

Tool access and permission rules:
- Access EHR_API, LAB_API, NOTIFY_API with scoped permissions; secrets stored securely.
- Read-only memory for historical PHI; write permissions only for approved steps.
- All tool invocations logged with agent, timestamp, and rationale.

Architecture rules:
- Event-driven architecture with microservices for planner, implementer, reviewer, tester, and domain specialist.
- Central orchestrator maintains workflow state and memory.
- Use versioned interfaces for tool calls; backfill and audit logs kept.

File structure rules:
- Organize by agents and workflows; keep clinical data separate from code.
- Do not store raw PHI in code or logs.

Data, API, or integration rules when relevant:
- Use HL7/FHIR for patient data exchanges where possible.
- Validate data formats before processing; reject malformed records.

Validation rules:
- All outputs must pass clinical validation checks and be auditable.
- Every handoff must include a rationale and expected outcome.

Security rules:
- Do not log full PHI; sanitize data in memory; encrypt sensitive data at rest.
- Enforce RBAC and least privilege.

Testing rules:
- Use synthetic and de-identified data for tests; verify end-to-end with CI.
- Include edge-case tests for incomplete records.

Deployment rules:
- Gate changes through a HIPAA-compliant deployment pipeline; require human review for critical clinical logic.
- Rollback plan and incident reporting in case of failures.

Human review and escalation rules:
- Clinician or Domain Specialist must review critical decisions; escalate to on-call healthcare professional as needed.
- Automatic escalation if confidence score falls below threshold for a task.

Failure handling and rollback rules:
- Retry with exponential backoff; if persistent, rollback to last good state and notify stakeholders.

Things Agents must not do:
- Do not modify patient data outside approved workflow steps.
- Do not bypass access controls or exfiltrate PHI.
- Do not perform unsupervised changes in production.

Recommended Agent Operating Model

The agent operating model defines roles, decision boundaries, and escalation paths. The Planner sets constraints and handoff protocols; the Orchestrator enforces governance; clinicians provide guardrails; and the Supervisor ensures auditability and safety. Escalation paths route high-risk decisions to human clinicians, while low-risk steps stay within automated coordination.

Recommended Project Structure

healthcare-workflow/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   └── domain-specialist/
├── workflows/
│   └── patient-triage/
├── config/
├── data/
├── logs/
└── tests/

Core Operating Principles

• Explicit boundaries: each agent has a defined scope and decision limits.
• Single source of truth: all patient context is stored in a central, auditable store.
• Privacy and regulatory compliance: PHI handling follows HIPAA and best practices.
• Deterministic outputs and auditability: every action is traceable with rationale.
• Clear handoffs and escalation: explicit triggers for planner, implementer, reviewer, tester, and clinician handoffs.
• Idempotent and recoverable: operations can be retried without adverse effects.
• Separation of concerns: agents focus on their defined roles with minimal overlap.

Agent Handoff and Collaboration Rules

Handoff rules ensure smooth collaboration among planner, implementer, reviewer, tester, researcher, and domain specialist. Handoffs include data payloads, rationale, expected outcomes, and confidence scores. The orchestrator enforces these transitions and records decisions for traceability.

Tool Governance and Permission Rules

• Command execution must go through defined tool interfaces with scoped permissions.
• File edits require approval gates and versioned commits to configuration stores.
• API calls must be auditable, with rate limits and data minimization.
• Secrets must never be exposed in logs or memory outside secure vaults.
• Production access requires validation, role-based access control, and supervisor sign-off for critical actions.

Code Construction Rules

• Write modular, testable components with clear interfaces for each agent role.
• Use explicit input/output contracts; validate all inputs against schemas.
• Document assumptions and edge cases in the AGENTS.md template block.
• Avoid duplicating logic across agents; share utilities responsibly.

Security and Production Rules

• Encrypt PHI at rest and in transit; apply strict access controls.
• Do not deploy clinical logic without human review for high-risk decisions.
• Maintain an incident response plan with logging and traceability.

Testing Checklist

• Unit tests for each agent function with synthetic data.
• Integration tests covering end-to-end patient triage flows.
• Security tests including data leakage checks and access controls.
• Regression tests for rule changes and new data sources.
• Deployment tests with rollback and alerting simulations.

Common Mistakes to Avoid

• Skipping clinician validation for high-risk decisions.
• Allowing uncontrolled memory growth or PHI leakage in logs.
• Unsafe shortcuts that bypass security or data governance.
• Unbounded handoffs without clear decision criteria.
• Duplicating logic across agents instead of refactoring shared utilities.

FAQ

What is the purpose of this AGENTS.md template for healthcare workflows?

This AGENTS.md template defines a project-level operating manual for coordinating AI coding agents in healthcare tasks, enabling single-agent and multi-agent orchestration with governance.

How should this template be used in a healthcare project?

Copy the AGENTS.md block into your repository, then customize roles, tools, and workflow specifics for your clinical context while following tool governance and security rules.

How is PHI protected in this workflow?

PHI is encrypted at rest and in transit, access is RBAC-controlled, and testing uses de-identified data to prevent exposure.

How are agent handoffs and escalations managed?

Handoff rules specify when to transfer tasks between agents, with an orchestrator enforcing transitions and clinicians escalating when confidence is below a threshold.

What should be validated before deployment?

Data mappings must be correct, outputs clinically validated, access rules enforced, and rollback procedures in place.