hitl_timeout

What this detector catches

The SDK's request_human_interventionhelper returns a handle the agent uses to await human response. When the handle's complete() is called with response_kind="timeout", the detector fires with the explicit-timeout signature. When the handle was opened with an SLA argument and the elapsed wait_duration_ms exceeded sla_seconds * 1000, the detector fires with the sla-exceeded signature at execution close. Both signatures can fire on the same execution — a multi-intervention run where one event timed out explicitly and another breached SLA produces two distinct failure_groups so neither cluster is suppressed. Result ordering is deterministic: explicit before sla_exceeded when both fire. The detector requires a positive SLA (sla_seconds > 0) for the SLA-exceeded path; without one, only the explicit path can fire.

Example failures it groups

• A content-moderation agent requests human review on ambiguous outputs. The moderator queue is overloaded and the 5-minute SLA expires. SLA-exceeded fires.
• A code-review agent escalates suspicious diffs to a human reviewer. The reviewer's Slack notification wasn't delivered (bot down); the customer's code calls complete(response_kind="timeout") after 10 minutes. Explicit-timeout fires.
• A customer-service agent escalates difficult cases to a human agent. The human agent took 2 hours; the SLA was 30 minutes. SLA-exceeded fires.

What to do when it fires

Open the failure-group detail page. The Playbook walks through the operational vs structural distinction: operational fixes are the most common (notification channel broken, reviewer queue overloaded, SLA tuned wrong for the actual reviewer cadence); structural fixes are harder but more durable (downgrade easier cases to auto-resolve, route harder cases to specialists, batch human reviews to amortize attention cost). Read 5-10 affected executions: if the same reviewer keeps timing out, that's an operational issue; if many reviewers are timing out, the SLA is unrealistic.

When NOT to investigate

• Off-hours batches where SLA-exceeded is expected (overnight queues, weekend handling). Configure the SLA to match your actual reviewer cadence rather than the synchronous response window.
• First-run after enabling HITL — if you just turned on the human-in-the-loop path, expect a spike while reviewers calibrate. Wait a week before treating timeouts as actionable.
• Multi-intervention executions handled by cascade where one intervention timed out but the agent successfully escalated to a second reviewer. The detector still fires on the timed-out intervention even when downstream recovery succeeded. If your operational pattern handles timeouts gracefully via cascade, the alert may be informational rather than actionable — use fire_modesto mute the mode you don't need to alert on.

Tunable thresholds + allowlist

One per-project knob via the Detector thresholds primitive: fire_modes (default ["explicit", "sla_exceeded"]; closed set — only those two strings are valid). Restrict to ["explicit"] to mute SLA-exceeded clusters when SLA tracking lives in a different system, or to ["sla_exceeded"] to mute the explicit-timeout cluster (rare — usually treated as control flow rather than an alert). Empty input or any value outside the closed set reverts the whole slice to the default. The sla_seconds itself is set per-handle in customer code via request_human_intervention(sla_seconds=...), not as a per-project threshold. The allowlist primitive does not currently support this detector.

Related docs

• hitl_rejection_spike — the HITL sibling that catches an unusually high fraction of human-rejected (or edited) outputs. hitl_timeout fires when humans don't respond; hitl_rejection_spike fires when humans respond but disagree.
• HITL SDK overview — the request_human_intervention + handle.complete API.