Skip to content

Governed agents

OpenMed provides local contracts for permissioned agent workflows: bounded authority, minimum data, human review, evidence and recovery. The application composes these contracts around its own dispatch boundary. Installing OpenMed, validating a schema or recording a digest does not install that boundary or authorize a tool call.

OpenMed makes no autonomous clinical decisions. These contracts do not authorize diagnosis, treatment, prescribing, enrollment, outreach or clinical orders. A human-review packet requests review; it cannot supply approval. Production effects require the application's policy, valid authority, required human approval and a bounded executor. Synthetic examples demonstrate contract behavior, not clinical validation or permission to act on real records.

Lifecycle

Stage Application responsibility before advancing
Authority Verify signed capability constraints, audience, expiry and any delegation ancestry for the exact tool, resource, action and policy
Minimum data Verify the run- and purpose-bound access ticket; plan the permitted fields before materializing records or tool arguments
Preview Validate the action graph, tool catalog, argument policy, target capabilities and staged changes; retain a value-free preview of the proposed effect
Approval Obtain review through the trusted reviewer boundary; verify the approval against the exact action or preview digest, reviewer role and exclusive expiry
Execution Recheck the approved context at dispatch; keep credentials and clinical values in trusted local code and delegate only the bounded approved effect
Evidence Record controlled outcomes, opaque correlations, counts, offsets and digests; preserve the distinction between success, abstention, review, denial and failure
Recovery Reconcile durable commit evidence before a retry; repeat only a proven-absent effect under still-valid approval, and send ambiguity to human review
Evaluation Bind the evaluated submission and evidence, apply every release gate and disclose limitations before deployment review

These stages explain composition; they are not an automatic end-to-end orchestrator. Individual helpers validate only their documented boundary. Capability lifetime checks do not verify a signature, a cached FHIR capability check does not validate a clinical resource on a server, and a batch's approval binding does not independently authenticate its reviewer. The deployment must supply each missing integration before dispatch.

For a synthetic example, suppose a run has permission to read declared evidence and proposes an OMOP update. The read grant cannot authorize that update, so dispatch stops before a clinical write. A separately authorized write still requires minimum-data planning, a reviewed preview, matching approval and a trusted committer. Copying the preview digest into a receipt is not review.

Authority and minimum data

Choose exact scopes before loading data. Tool schemas and catalogs describe the reviewed surface; they do not grant authority by themselves.

Approvals and previews

Keep reviewer handoffs separate from approval. A changed action, expired approval or consumed nonce cannot silently acquire permission for another dispatch.

Write-back and execution

Preflight and staging precede write dispatch. Check cached FHIR capabilities before obtaining write credentials or materializing a resource. Local FHIR capability metadata establishes declared interaction support; SMART scope comparison is an offline audit. Neither performs OAuth, obtains credentials or sends a resource. Legacy direct FHIR/OpenMRS writers remain outside the complete governed lifecycle. Applications must compose the reviewed authority and approval boundary around any production writer.

Evidence

Evidence records what was checked or observed. Structural completeness is not proof of clinical truth, a digest is not anonymity, and an outcome report cannot authorize a subsequent action. Apply access controls and retention limits to opaque references, offsets and digests as well as to protected source artifacts.

Recovery

Reconcile each effect using the same durable idempotency key. A committed effect must not be repeated; ambiguous, missing, conflicting or changed evidence needs review. Rollback manifests describe structural coverage and protected artifact bindings. They neither establish semantic reversibility nor execute a rollback. Compensating clinical writes remain proposals requiring separate review.

Evaluation

Keep fixtures synthetic and evaluated surfaces reproducible. Passing synthetic checks is regression evidence, not clinical validation. A failed required gate cannot be offset by another score or turned into permission to deploy or write.

Assurance

The deployment owner verifies that the composed boundary actually guards every effect. Conformance tests and assurance packs provide technical evidence; they do not provide certification or autonomous clinical authority.

Migration

  • Migrate from 3.0 to 3.1: map legacy callers to explicit governed adapters, retained compatibility and human-review boundaries.

Maintaining this section

Add a new governance guide to its relevant navigation subsection when the guide lands, link it once from this overview and update the publication classification. Keep its existing file path when regrouping pages so public URLs remain stable. Describe the helper's actual boundary and required application integration; do not present a schema, projection, preview or evidence artifact as an executor.