Integration Patterns

Three ways to integrate with the Runtime Control Engine, depending on how your application is architected.

Pattern 1: Synchronous control

Your application submits the Agent Run and waits inline for the runtime decision — the simplest pattern, and what the Quickstart demonstrates.

const result = await runtime.submitAgentRun({ /* ... */ });

if (result.control_action === "allow") {
  // safe to act on result.session.latest_run immediately
} else if (result.review_required) {
  // fall through to Pattern 2
} else if (result.blocked) {
  // surface to your own operator, do not act on the output
}

Use this when your application can afford to block on the HTTP call (evaluation is fast — evidence/policy/risk are all deterministic, in-memory computations) and when most of your traffic doesn't require human review.

Pattern 2: Human review flow

The Agent Run lands in waiting_for_human_review; your application stores the session_id and surfaces it to a reviewer through your own UI (or the Web Control Console), then later calls back to record the decision.

const result = await runtime.submitAgentRun({ /* ... */ });

if (result.session.current_state === "waiting_for_human_review") {
  await yourApp.notifyReviewer(result.session_id, result.decision_id);
  // ... later, once a human has decided ...
  await runtime.approveSession(result.session_id, { reviewerId, notes });
  // or: await runtime.rejectSession(...)
  // or: await runtime.retrySession(...)
}

This is the pattern demonstrated by Reference Integration A and the Quickstart.

Pattern 3: Asynchronous control (intended direction, not yet implemented)

For a fully decoupled architecture, the intended future pattern is: your application submits the Agent Run, immediately receives a run_id and session_id, and is later notified of the control decision via a webhook callback rather than polling.

This is not implemented today. execution_mode is already typed as "synchronous" | "asynchronous" on AgentRun as a forward-compatible placeholder, but every run in this version is "synchronous" — the full output is always available in the same call that creates the run. No webhook delivery mechanism exists yet. Do not build against asynchronous callbacks until this ships; poll GET /runtime/sessions/{id} or GET /runtime/agent-runs/{id} in the meantime if you need to check status from a separate process.

Choosing a pattern

	Pattern 1	Pattern 2	Pattern 3
Blocking on the initial call	Yes	Yes (until review outcome)	No — future
Needs your own reviewer UI/queue	No	Yes	Yes
Available today	Yes	Yes	No