{"post":{"slug":"agent-timeouts-explained-2026","title":"Agent Timeouts: Deciding When to Stop Waiting","excerpt":"A request that never returns is worse than one that fails. Agents make this hard because a slow turn and a stuck turn look identical from outside.","category":"ai","date":"August 12, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">A</span>n 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?\n\nFrom 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.\n\n## What changed in 2026\n\n- **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.\n- **Streaming became the progress signal.** Distinguishing slow from stuck via token arrival rather than wall-clock time became standard practice.\n- **Task budgets arrived alongside timeouts.** Token-denominated ceilings gave a second dimension of control — see [agent token budgets](/blog/agent-token-budgets-2026).\n- **SDK defaults got documented better.** The interaction between client timeouts and automatic retries, long a source of surprise, became something people check.\n\n## Timeout at every layer\n\n| Layer | Bounds | Typical failure if missing |\n| --- | --- | --- |\n| HTTP request | One model call | Socket hangs forever |\n| Tool call | One external operation | A slow API stalls the loop |\n| Agent step | One think-act cycle | One step consumes the whole run |\n| Whole run | The entire task | A loop that never converges |\n| User-facing | What a person will wait for | Someone stares at a spinner |\n\nMost 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.\n\nThe 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.\n\n## The retry multiplication trap\n\nThe most common surprise: SDK timeouts are usually per attempt, and most SDKs retry automatically by default.\n\nA 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.\n\nCheck 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.\n\nTimeout units also differ between SDKs — some take seconds, some milliseconds — which is a small detail that produces spectacular misconfigurations in both directions.\n\n## Streaming as a liveness signal\n\nThe best available answer to \"slow or stuck\" is to stop guessing from elapsed time and watch for progress.\n\nWith 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.\n\nThis is a strictly better signal, and it is why streaming is worth enabling even in backends where no human is watching the tokens.\n\nFor 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](/blog/ai-agent-observability-2026) usually give you this for free.\n\n## Choosing the numbers\n\nMeasure 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.\n\nThen 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.\n\nDecide 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.\n\n## Common mistakes\n\n- **Only setting an HTTP timeout.** Bounds one call, not the loop.\n- **Ignoring retry multiplication.** Your real worst case is timeout × attempts.\n- **One global timeout for all tasks.** Too tight for hard work, too loose for simple work.\n- **Total timeouts where inactivity timeouts belong.** Kills legitimate long runs and tolerates hung ones.\n- **Returning partial results silently.** Callers treat truncated work as complete.\n- **No cleanup on timeout.** Abandoned tool calls, held locks, orphaned subagents.\n- **Timeout shorter than the platform's own limit.** Then the platform's limit is what you actually have.\n\n## FAQ\n\n**What is a reasonable default?**\nThere 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.\n\n**How does this relate to a task budget?**\nTimeouts 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](/blog/agent-token-budgets-2026).\n\n**Should a timed-out run be retried?**\nOnly 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](/blog/idempotency-explained-2026).\n\n**What about user-facing latency?**\nDifferent 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.\n\n## Where to go next\n\nFor the token-denominated companion to wall-clock limits, read [agent token budgets](/blog/agent-token-budgets-2026). For the traces that make a hung run diagnosable, [AI agent observability](/blog/ai-agent-observability-2026), and for resuming rather than restarting, [agent replay and checkpoints](/blog/agent-replay-and-checkpoints-2026).","hue":210,"metaTitle":"Agent Timeouts: Deciding When to Stop Waiting","metaDescription":"How to set timeouts for AI agents, why per-step and per-run limits both matter, and how streaming distinguishes a slow turn from a hung one.","keywords":["agent timeout","llm request timeout","hung agent loop","streaming progress detection","timeout retry multiplication","agent reliability","long running agent runs","production ai operations 2026"],"tldr":["**A hung agent looks exactly like a thinking one** — which is why timeouts need a signal of progress, not just elapsed time.","**Set timeouts per step and for the whole run** — one long ceiling lets a loop burn the entire budget on one stuck call.","**SDK timeouts multiply by retries** — a 10-minute timeout with two retries is a 30-minute worst case nobody planned for.","**Stream to distinguish slow from stuck** — tokens arriving means progress; silence means something else.","**Skip:** a single global timeout for every task class. A classification and a migration do not belong under one number."],"readTime":"5 min read","wordCount":1068},"related":[{"slug":"agent-replay-and-checkpoints-2026","title":"Agent Replay and Checkpoints: Resuming Instead of Restarting","excerpt":"An agent fails at step forty of fifty. Restarting means paying for forty steps again and hoping the non-deterministic parts land the same way. Checkpoints make that unnecessary.","category":"ai","date":"August 17, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":214},{"slug":"context-compaction-explained-2026","title":"Context Compaction Explained: Surviving Long Agent Sessions","excerpt":"An agent that runs for hours will outgrow any context window. Compaction summarises the history in place so the session keeps going. Here is how it works and where it loses things.","category":"ai","date":"August 12, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":206},{"slug":"agent-memory-consolidation-2026","title":"Agent Memory Consolidation: Deciding What Is Worth Keeping","excerpt":"An agent that remembers everything is an agent whose memory is useless. Consolidation is the process of deciding what survives, and it is where most memory systems fail.","category":"ai","date":"August 16, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":208}],"sameCategory":[{"slug":"agent-cost-attribution-2026","title":"Agent Cost Attribution: Finding Where the Tokens Went","excerpt":"A single monthly API bill tells you that agents are expensive. It does not tell you which feature, which customer, or which retry loop is responsible. That gap is fixable.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":220},{"slug":"human-in-the-loop-agents-2026","title":"Human-in-the-Loop Agents: Where to Put the Approval Gate","excerpt":"Approve everything and the agent is a slow autocomplete. Approve nothing and you have handed irreversible actions to a system that can be talked into things.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":197},{"slug":"reasoning-effort-controls-2026","title":"Reasoning Effort Controls: Tuning How Hard a Model Thinks","excerpt":"Fixed thinking budgets gave way to effort levels, and the default is rarely the right setting. Here is how the dial behaves and where each level actually belongs.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":210},{"slug":"retrieval-metrics-explained-2026","title":"Retrieval Metrics: Measuring the Half of RAG That Fails","excerpt":"When a RAG system answers badly, the retrieval usually failed before the model ever spoke. Measuring generation quality alone hides that entirely.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":215}],"newer":{"slug":"able-account-explained-2026","title":"ABLE Accounts: Saving Without Losing Benefits","excerpt":"ABLE accounts let people with disabilities save above the asset limits that would otherwise disqualify them from means-tested benefits.","category":"finance","date":"August 12, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":316},"older":{"slug":"agentic-rag-explained-2026","title":"Agentic RAG Explained: Retrieval That Decides","excerpt":"Classic RAG retrieves once and hopes. Agentic RAG lets the model decide what to search, when to search again, and when it has enough. Here is how it works and what it costs.","category":"ai","date":"August 12, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":208}}