An agent run has been going for eleven minutes. Is it working through a genuinely hard problem, or did a tool call hang and the loop is waiting on a socket that will never answer?
From outside there is no difference. Both are silence. This is the specific reason timeouts are harder for agents than for ordinary requests: the legitimate case can take a very long time, so a timeout generous enough to avoid killing real work is also generous enough to let a stuck run waste it.
What changed in 2026
- Long-horizon runs became normal. Agents that legitimately work for many minutes made the old "if it takes more than 30 seconds something is wrong" heuristic useless.
- Streaming became the progress signal. Distinguishing slow from stuck via token arrival rather than wall-clock time became standard practice.
- Task budgets arrived alongside timeouts. Token-denominated ceilings gave a second dimension of control — see agent token budgets.
- SDK defaults got documented better. The interaction between client timeouts and automatic retries, long a source of surprise, became something people check.
Timeout at every layer
| Layer |
Bounds |
Typical failure if missing |
| HTTP request |
One model call |
Socket hangs forever |
| Tool call |
One external operation |
A slow API stalls the loop |
| Agent step |
One think-act cycle |
One step consumes the whole run |
| Whole run |
The entire task |
A loop that never converges |
| User-facing |
What a person will wait for |
Someone stares at a spinner |
Most implementations set exactly one of these — usually the HTTP request — and are surprised when a run still hangs. A per-request timeout does nothing about a loop making two hundred perfectly fast calls.
The pair that matters most is per-step and per-run. Per-step catches a single stuck operation. Per-run catches non-convergence. Without both, a loop can either stall on one call or spin indefinitely on many fast ones, and each needs a different limit.
The retry multiplication trap
The most common surprise: SDK timeouts are usually per attempt, and most SDKs retry automatically by default.
A 10-minute timeout with two automatic retries is a 30-minute worst case. If your load balancer gives up at 60 seconds, or your serverless platform caps at 15 minutes, your carefully chosen timeout is not the constraint you thought.
Check three things: your client's default timeout, its default retry count, and whether you have added retries of your own on top. Layered retries multiply rather than add, and stacking your own logic over an SDK that already retries produces totals nobody intended.
Timeout units also differ between SDKs — some take seconds, some milliseconds — which is a small detail that produces spectacular misconfigurations in both directions.
Streaming as a liveness signal
The best available answer to "slow or stuck" is to stop guessing from elapsed time and watch for progress.
With streaming, tokens arrive continuously while the model generates. That gives you an inactivity timeout rather than a total timeout: if nothing has arrived in 60 seconds, something is wrong, regardless of whether the run has been going for two minutes or twenty. A legitimately long run keeps producing output; a hung one goes silent.
This is a strictly better signal, and it is why streaming is worth enabling even in backends where no human is watching the tokens.
For agent loops the same idea extends upward. Emit a progress event on each step — tool called, result received, step completed. An inactivity timeout on steps catches a loop stuck inside a single operation, which a total timeout would only catch much later. The spans from AI agent observability usually give you this for free.
Choosing the numbers
Measure rather than guess. Run representative tasks, record the distribution of step durations and total run times, and set limits above the legitimate tail rather than the mean.
Then differentiate by task class. A classification and a codebase migration should not share a timeout. Routing by expected task type and applying different ceilings is more effective than any single value, and it is usually a small amount of code.
Decide what a timeout means to the caller. Three options, and the choice matters: fail the request, return partial results with a clear marker that the run was cut short, or hand back a resumable handle. Partial results presented as complete are the worst outcome — worse than an error, because nobody knows to retry.
Common mistakes
- Only setting an HTTP timeout. Bounds one call, not the loop.
- Ignoring retry multiplication. Your real worst case is timeout × attempts.
- One global timeout for all tasks. Too tight for hard work, too loose for simple work.
- Total timeouts where inactivity timeouts belong. Kills legitimate long runs and tolerates hung ones.
- Returning partial results silently. Callers treat truncated work as complete.
- No cleanup on timeout. Abandoned tool calls, held locks, orphaned subagents.
- Timeout shorter than the platform's own limit. Then the platform's limit is what you actually have.
FAQ
What is a reasonable default?
There is not one, which is the honest answer. Measure your own distribution. What generalises is the structure: an inactivity timeout in the tens of seconds, a per-step limit above your observed tail, and a per-run limit set by what the caller will tolerate.
How does this relate to a task budget?
Timeouts bound wall-clock time; budgets bound token spend. A run can be fast and expensive or slow and cheap, so you generally want both — see agent token budgets.
Should a timed-out run be retried?
Only if you know it is retryable and idempotent. An agent that half-completed a set of writes before timing out should not simply be run again — see idempotency explained.
What about user-facing latency?
Different question with a different answer. A person will not wait ten minutes at a spinner. Either stream progress so the wait is legible, or make the operation asynchronous and notify on completion.
Where to go next
For the token-denominated companion to wall-clock limits, read agent token budgets. For the traces that make a hung run diagnosable, AI agent observability, and for resuming rather than restarting, agent replay and checkpoints.