Core Concepts

Registered Agent

A clinical agent must be registered before it can create Runtime Sessions or submit Agent Runs. Registration answers: which agent is connecting, what clinical tasks is it allowed to perform, and is it currently trusted to run?

• Lifecycle: draft → active → suspended/deprecated. Only active agents may run (a draft agent may opt in for testing via allow_draft_agent when creating a session — never for external Agent Run submissions).
• deprecated is terminal — register a new agent_id (new version) instead of reactivating.
• agent_id is unique within a tenant, not globally — see Security for what tenant scoping does and doesn't mean today.

See Agent Registry for the full API.

Runtime Session

One controlled clinical workflow. Long-lived — it's the object you poll and act on while work is happening (pause, resume, cancel, approve, reject, retry). A session owns one or more Agent Runs over its lifetime.

See Runtime Sessions.

Agent Run

One execution of an agent within a session. The first attempt is Agent Run #1; a retry creates a new Agent Run, never mutating the previous one. A run's execution_origin is internal (the engine's own reference adapter) or external (a third-party agent submitted via POST /runtime/agent-runs).

See External Agent Runs.

Decision Context Record

The immutable audit record produced by exactly one Agent Run: input hash, retrieved sources, agent output, evidence results, policy results, risk score, and the human review outcome if any. A retried run creates a brand-new record — the previous one is never edited.

See Decision Records.

Decision Controller

The component that turns evidence + policy + risk results into one control action: allow, pause, require_human_review, block, retry, or finalize. It is entirely deterministic — the same inputs always produce the same decision.

Policy Evaluation

Configurable, data-defined rules evaluated against every agent output. Each policy has a condition_type (e.g. "medication recommendation present", "diagnosis claim unsupported"), an action (allow, flag, pause, require_human_review, block), and a severity. Policies can be listed, enabled, and disabled at runtime — no redeploy required. See GET /runtime/policies.

Evidence Evaluation

A deterministic, set-membership check: a claim is "supported" only if every source id it cites resolves to a real retrieved source for that case. This is not NLP-based fact verification — agents must emit structured claims with explicit source citations; there is no claim-extraction step inside the engine.

Runtime Risk

A computed score (0–100, mapped to low/medium/high) derived deterministically from evidence and policy results — never a black-box model score.

Human Review

When the Decision Controller selects require_human_review (or an output is blocked pending review), the session enters waiting_for_human_review. A reviewer then approves, rejects, or triggers a retry via the session action endpoints. See the Human review flow integration pattern.

Decision Replay

Reconstructs the full chronological sequence of a decision (or an entire multi-run session) from its recorded events and Decision Context Record(s) — what happened, in what order, and what the system knew at each step. See Decision Replay.