External Agent Runs

POST /runtime/agent-runs is the primary integration entry point for a third-party company's own AI 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 Claim 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: Claim[];
  recommendations: Recommendation[];
  required_sections: Record<string, boolean>;
}

interface Claim {
  claim_id: string;
  claim_type: string; // core: assertion, recommendation, instruction, follow_up, other; domains add more (e.g. diagnosis)
  statement: string;
  supporting_source_ids: string[];
}

interface Recommendation {
  recommendation_id: string;
  category: string; // e.g. "medication" (healthcare), "decline" or "credit_limit" (lending)
  item: string; // what is recommended
  instruction: string;
  rationale: string;
  value: number | null; // optional amount, compared by recommendation_value_above policies
  unit: string | null;
  supporting_source_ids: string[];
}

Policies read recommendations by category and required_sections by section name, so use the categories and sections your agent's domain defines. A section missing from required_sections counts as missing. A malformed agent_output is rejected with a 400 that lists every problem.

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.