External Agent Runs

POST /runtime/agent-runs is the primary integration entry point for a third-party healthcare AI company's own clinical agent. The engine never executes your agent — it evaluates and governs the output you hand it.

Why agent_output must be structured, not a raw string

There is no NLP or claim-extraction step inside the engine. Every claim your agent makes must be submitted as an explicit, structured ClinicalClaim with a claim_id, claim_type, statement, and supporting_source_ids — the exact source ids from your source_references that support the claim. The Evidence Engine performs a deterministic set-membership check against those ids; it does not read or interpret narrative prose.

interface AgentOutput {
  identity: { agent_id; agent_version; model_provider; model_version; task_type };
  generated_at: string;
  narrative: string; // for display only — never evaluated
  claims: ClinicalClaim[];
  medication_recommendations: MedicationRecommendation[];
  discharge_instructions_present: boolean;
}

Registering and activating before submitting

submitAgentRun validates the agent exists and is active before evaluating anything — no allow_draft_agent escape hatch exists for external submissions (that's session-creation-only, for testing). Register and activate first — see Agent Registry.

New session vs. resubmission

Omit session_id to start a brand-new Runtime Session. Pass an existing session_id to submit a second (or third, ...) Agent Run into that same session — the pattern used after a retry. See Runtime Sessions.

What you get back

interface SubmitAgentRunResponse {
  run_id; session_id; decision_id;
  control_action: "allow" | "pause" | "require_human_review" | "block" | "retry" | "finalize" | null;
  session_state: ExecutionState;
  risk_score: number | null;
  risk_level: "low" | "medium" | "high" | null;
  review_required: boolean;
  blocked: boolean;
  policy_results: PolicyResult[];
  evidence_results: EvidenceResult | null;
  decision_replay_available: boolean;
  run: AgentRun;
  session: RuntimeSession;
}

Failure modes (nothing is persisted on any of these)

Status	Cause
404	Unknown agent_id
409	Agent is not active, or task_type isn't in the agent's allowed_tasks
400	Missing required fields

Worked examples

See Reference Integrations for three complete, runnable scenarios (human review, evidence-supported claim, and auto-finalized lower-risk output) and the Quickstart for the full lifecycle.