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.Documentation Index
Fetch the complete documentation index at: https://docs.trulayer.ai/llms.txt
Use this file to discover all available pages before exploring further.
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. |
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 modeleval_score.toxicity > 0.7→ blockspan.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
retryactions a policy will execute on a single trace before automatically converting the next retry into anescalateaction 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 isretry. - 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).
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 becomedry-runwithin ~5 seconds (propagated via the SDK config refresh). shadowanddry-runpolicies 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.
HITL — Human in the loop
Control → HITL shows pending approvals.- Queue — one row per trace that hit an
escalateaction, 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.
owner can approve/reject. See Team settings for roles.
Auto-escalated traces
When aretry-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.