Evaluate Channel Health • AI Agent SDK

</div>

This function is defined in the protocols module.

Evaluate channel health and return a reason.

Pure function that evaluates a HealthResult and determines the health reason based on various criteria.

Liveness is driven by passive inbound transport activity (`health.last_activity) rather than only an outbound probe, and the evaluator is aware of in-flight agent runs (health.active_runs`) so a busy channel is never mistaken for a dead socket:

• busy with recent inbound progress -&gt; `BUSY` (never restarted);
• busy but no progress beyond `stuck_after_seconds -> STUCK`;
• idle and inbound stale beyond `stale_after_seconds -> STALE_SOCKET`.

For the busy branch, “progress” is the most recent of inbound transport activity (`health.last_activity) and in-run progress (health.last_run_progress — tool calls, streamed draft edits, token output, or a periodic heartbeat). A single long agent run that streams output or emits tool events the whole time therefore stays BUSY indefinitely instead of being torn down mid-run once its wall-clock crosses stuck_after_seconds; only a run that emits nothing for stuck_after_seconds is flagged STUCK`.

Signature

def evaluate_channel_health(health: HealthResult, startup_grace_seconds: float, stale_after_seconds: float, stuck_after_seconds: float, current_time: Optional[float]) -> HealthReason

Parameters

Returns

Uses

• time.time

Source

Related Documentation