Guardrails
Runtime policies that halt or alert when agents exceed safety thresholds.
Guardrails
Guardrails are runtime policies that monitor your agent in real-time via WebSocket. When a policy is violated, the agent receives a HALT command — stopping execution before damage cascades.
Policy Types
| Type | Description |
|---|---|
cost_budget | Halt when cumulative cost exceeds threshold |
loop_detection | Halt when the same span name repeats N times |
context_overflow | Halt when total tokens exceed context window |
latency_budget | Halt when total execution time exceeds limit |
error_rate | Alert when error ratio exceeds threshold |
Creating a Policy
curl -X POST https://api.retraceai.tech/api/v1/guardrails \
-H "x-retrace-key: rt_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Cost Cap",
"policy_type": "cost_budget",
"config": { "threshold": 1.0, "min_threshold": 0.1, "max_threshold": 5.0 },
"action": "halt"
}'Actions
- halt — Sends HALT via WebSocket, agent stops immediately
- alert — Logs violation, continues execution
- throttle — Reduces processing rate
Adaptive Thresholds (LinUCB)
Enterprise plans include adaptive guardrails powered by a LinUCB contextual bandit. The system learns optimal thresholds per policy type from historical trigger data.
Set min_threshold and max_threshold in the policy config to bound the bandit's exploration range.
curl -X POST https://api.retraceai.tech/api/v1/guardrails/:id/adaptive-threshold \
-H "x-retrace-key: rt_live_..." \
-H "Content-Type: application/json" \
-d '{ "avg_cost": 0.5, "avg_duration": 3000, "span_count": 12, "error_rate": 0.1 }'Viewing Triggers
curl https://api.retraceai.tech/api/v1/guardrails/triggers \
-H "x-retrace-key: rt_live_..."CLI
retrace guardrails list --json
retrace guardrails create --name "Cost Cap" --type cost_budget --action halt --threshold 1.0
retrace guardrails triggers --limit 10