Agent Registry

Every agent that runs through the engine must first be registered. The registry governs whether an agent may run; it says nothing about how it runs (that's your model, your infrastructure).

Lifecycle

draft ──activate──> active ──suspend──> suspended ──activate──> active
  │                    │                                          │
  └──────deprecate─────┴──────────────────deprecate────────────────┘
                                     │
                                     ▼
                               deprecated (terminal)

• New agents register as draft by default.
• Only active agents may create Runtime Sessions or submit external Agent Runs (a draft agent may opt into session creation via allow_draft_agent — testing only, never for external submissions).
• deprecated is terminal — register a new agent_id (a new version) rather than trying to reactivate.

Risk tiers

low | medium | high | critical — a platform-assigned classification for the agent itself, distinct from the per-decision runtime risk score computed at evaluation time.

Fields

Field	Required	Notes
agent_id	yes	Unique within the resolved tenant.
name, owner, version	yes
clinical_domain	yes	Free text (e.g. radiology, inpatient_discharge).
allowed_tasks	yes	Which TaskTypes this agent may perform.
capabilities	yes	Free-text capability tags.
model_provider, model_version	yes
risk_tier	yes	See above.
status	no	Defaults to draft.
adapter_id	no	Deprecated, display-only as of Initiative 3. Kept for backward compatibility only — ManagedExecutionResolver never reads it.
provider_connection_id	no	Deprecated. Never stored on the agent record — see execution_profile_id below.
execution_profile_id	no	Execution Profile for managed execution — the canonical execution contract (model, adapter, provider connection, inference parameters). Not validated for existence at registration time; enforced only when managed execution is attempted. A caller still submitting the old adapter_id+provider_connection_id shape gets one auto-created and activated — see Execution Profiles' backward compatibility section.
metadata	no	Free-form object.

API

POST   /runtime/agents
GET    /runtime/agents
GET    /runtime/agents/{id}
PATCH  /runtime/agents/{id}
POST   /runtime/agents/{id}/activate
POST   /runtime/agents/{id}/suspend
POST   /runtime/agents/{id}/deprecate

PATCH cannot change agent_id or status — use the lifecycle endpoints for status.

SDK usage

const agent = await runtime.registerAgent({
  agentId: "acme-radiology-copilot",
  name: "Acme Radiology Copilot",
  owner: "acme-health-ai",
  version: "1.0.0",
  clinicalDomain: "radiology",
  allowedTasks: ["radiology_follow_up_recommendation"],
  capabilities: ["summarize_findings"],
  modelProvider: "acme-ai",
  modelVersion: "v3",
  riskTier: "high",
});
await runtime.activateAgent("acme-radiology-copilot");

Seed agents (local development)

The engine seeds two agents on boot under the default tenant:

• discharge-summary-agent — active, backed by a real reference adapter
• radiology-follow-up-agent — draft, no adapter — demonstrates the lifecycle gate and is activated by Reference Integration B
• openai-discharge-summary-agent (Initiative 1/2/3, when OPENAI_API_KEY is configured) — active, linked to a seeded internal/demo Execution Profile backed by Giggle AI Innovation's own credentials — for demonstration only, never a real tenant's workload