Control

Automated actions, policies, HITL approvals, and the kill-switch.

The Control page is TruLayer’s closed-loop surface: define what should happen when a trace matches a condition (retry, fall back to a safer model, block the response, or escalate to a human), roll actions out gradually, and pull the emergency brake if something goes wrong.

Control actions

An action is the unit of automation. Every policy fires one action when its trigger matches.

Action	What it does
retry	Re-invoke the same model with the same input, up to N attempts. Records a retry span under the original trace.
fallback	Re-invoke a different model (usually cheaper or more conservative) with the same input.
block	Return a static safe response to the end user (configurable text). The original unsafe output is still stored as an evidence span.
escalate	Park the trace in the HITL queue; do not return to the user until approved.

Actions are invoked at response time by the TruLayer SDK when a policy matches. The SDK returns the post-action output; your app doesn’t need to know whether a retry or fallback fired.

Policies

Policies glue triggers to actions. Create one from Control → Policies → New policy.

Fields:

• Name — shown in audit logs.
• Scope — project, environment, model, and optional metadata filter.
• Trigger — evaluator score or rule match. The most common shape:
  • eval_score.hallucination < 0.5 → fallback to a stricter model
  • eval_score.toxicity > 0.7 → block
  • span.error_type = "rate_limit" → retry with backoff
• Action — one of the four above, with action-specific parameters (retry count, fallback model id, block text, HITL queue).
• Max retry depth — integer 1–10, default 3. Controls how many retry actions a policy will execute on a single trace before automatically converting the next retry into an escalate action and routing the trace to the HITL pending-approval queue. Once the depth cap is reached, no further retries occur for that policy on that trace — a human must approve or reject it instead. Raise the cap to allow more automatic retries; lower it to escalate sooner. This field only applies to policies whose action type is retry.
• Rollout % — integer 0–100. Policy evaluates on 100% of matching traces but only fires the action on this fraction. Use for canaries.
• Mode — dry-run (logs what it would have done, does nothing), shadow (fires alongside the original response, does not replace it), enforce (default — action replaces the response).

Every policy evaluation records a policy_evaluation event on the trace so you can audit what fired when.

Kill-switch

Control → Kill-switch is an owner-only emergency halt.

When engaged:

• All enforce-mode policies become dry-run within ~5 seconds (propagated via the SDK config refresh).
• shadow and dry-run policies continue to run as normal.
• A banner appears across the dashboard until the kill-switch is released.
• Every API key is notified via a one-time email to the workspace owner.

Use it when a bad policy is causing more harm than the underlying issue. Release it from the same page; the scope of the halt is logged in the audit trail.

HITL — Human in the loop

Control → HITL shows pending approvals.

• Queue — one row per trace that hit an escalate action, with the original input, the proposed output, and the triggering policy. Sorted oldest-first.
• Approve / Reject — Approving releases the output to the end user; rejecting sends the configured block response and attaches the reject reason to the trace as metadata. Both actions are logged.
• Reviewer notes — free-text attached to the trace for downstream analysis.
• SLA timer — each queue item shows time-in-queue. Configure a hard timeout per policy (default 5 minutes) that auto-rejects if no reviewer acts.

Only users with role owner can approve/reject. See Team settings for roles.

Auto-escalated traces

When a retry-action policy hits its max_retry_depth cap, the control loop automatically converts the retry into an escalation. These traces appear in the HITL queue with escalation_reason: "retry_threshold_exceeded" in the action metadata, alongside the retry_count that triggered escalation.

Use the escalation reason to distinguish automatically routed traces from manually configured escalate-action policies. See the remediation diffs guide for full details on configuring max_retry_depth.

Audit trail

Every policy creation, edit, rollout change, kill-switch engagement, and HITL decision is recorded in Control → Audit log. Export to CSV for SOC 2 reviews.