Skip to content

Errors and retries

Tool timeouts in agent loops: return a result or end the run

Set a fetch timeout inside the tool, a framework timeout around it and a run limit on top, and decide per layer whether the model sees a result or the run stops.

By Amaan Mcdonald, AgentFetch team · Published

This article was drafted with AI assistance from the sources listed below and edited and published by the AgentFetch team. Disclosure: the AgentFetch API, which this article mentions, is this site's own product.

Three timeout layers for one fetch tool
  1. 1Inside the toolThe HTTP client timeout, shortest of the three (20 seconds as a starting point). Your code writes the message the model reads.
  2. 2Around the toolThe framework tool timeout, a little longer (30 seconds). A backstop that returns a generic timeout result.
  3. 3Around the runA step or run limit, longer again. When it fires, the run ends and your orchestrator decides what happens next.

A fetch tool waits on someone else's server. Most pages answer quickly; now and then one does not answer at all, and the agent loop sits there until something gives up. Which layer gives up, and what the model is told when it does, decides whether the agent moves on to another source or the whole run dies on one slow page.

This post covers three frameworks as documented in November 2026: the OpenAI Agents SDK, Pydantic AI and the AI SDK. The pattern is the same in each.

Where should the timeout live?

Default: use three layers, each one longer than the one inside it. The HTTP client timeout lives inside your tool, the framework's tool timeout wraps the tool, and a step or run limit wraps the loop. As a starting point, try 20 seconds inside, 30 seconds around the tool, and a run limit sized to the whole task, then measure.

It stops working when the layers are the wrong way round. If the framework timeout fires first, your tool never gets to write its own message, and the model gets a generic one. If the run limit is shorter than one slow tool call, a single page ends the run.

What does the model see when a tool times out?

Default: let a timeout come back as a tool result, not an exception. All three frameworks support this.

  • OpenAI Agents SDK. Pass timeout to @function_tool. The default timeout_behavior is "error_as_result", which gives the model a timeout message such as Tool 'slow_lookup' timed out after 2 seconds. timeout_error_function lets you write your own text. Timeouts are supported only on async function tools.
  • Pydantic AI. Set Agent(tool_timeout=...) for every tool on the agent, or timeout= on one tool. When it expires, the model gets a retried tool result: 'Timed out after N seconds.'
  • AI SDK. Pass timeout: { toolMs } to generateText, with per-tool overrides under tools as {toolName}Ms. A tool that runs too long is aborted and comes back as a tool-error, so the model can respond or retry.

It stops working when the default message is all the model has. "Timed out after 30 seconds" names neither the URL nor a next step, and a model with nothing else to go on may simply call the same URL again.

Who should write the timeout message?

Default: your tool. Catch the HTTP client's timeout inside the tool and return one sentence the model can act on. The framework timeout stays as the backstop.

import httpx
from pydantic_ai import Agent

agent = Agent('openai:gpt-6.1-sol', tool_timeout=30)

@agent.tool_plain
async def fetch_page(url: str) -> str:
    """Fetch one public web page and return its text."""
    try:
        async with httpx.AsyncClient(timeout=20.0) as client:
            response = await client.get(url)
    except httpx.TimeoutException:
        return (
            f"TIMEOUT: {url} did not answer in time. "
            "Do not fetch this URL again in this task. "
            "Use another source or tell the user the page could not be read."
        )
    return response.text[:20000]

In the OpenAI Agents SDK, the same async function goes under @function_tool(timeout=30.0). A trace with the inner message looks like this:

step 3  tool_call  fetch_page(url="https://example.com/report")
        result     TIMEOUT: https://example.com/report did not answer in time.
                   Do not fetch this URL again in this task. ...
step 4  tool_call  fetch_page(url="https://example.org/report-summary")
        result     (page text)
step 5  answer     uses example.org, says example.com could not be read

It stops working when the HTTP client's timeout is not a wall-clock limit. HTTPX has four timeouts, one per phase (connect, read, write, pool), and its docs describe the default as 5 seconds of network inactivity. A server that keeps sending small pieces can hold the call longer than the number suggests, which is the case the framework backstop is for.

When should a timeout end the run?

Default: almost never at the tool layer. In the OpenAI Agents SDK, timeout_behavior="raise_exception" raises ToolTimeoutError, which carries tool_name and timeout_seconds, and the run fails. Use it for a tool the task cannot do without, and catch the error in your orchestrator.

For everything else, put the hard stop on the outside. Pydantic AI's run methods take timeout= and raise RunTimedOut, which keeps the completed messages available through all_messages(), so the orchestrator can still report what the agent found. In the AI SDK, totalMs covers the whole call and stepMs covers one complete step, including model generation, retries and local tool execution. So stepMs must be longer than your longest tool timeout, or the step limit fires first.

It stops working when the loop keeps going after repeated timeouts. A timeout as a result does not stop a model from trying ten more slow pages. Pair it with a failure cap, as in stop conditions for agents that fetch.

How do timeouts and retries interact?

Default: count a timeout as a failure, not as a reason to retry. In Pydantic AI a tool timeout is a retry and uses that tool's retry budget. The default budget is 1, and once it is used up the run raises UnexpectedModelBehavior. So a page that times out twice in a row can end the run even though you meant the timeout to be harmless.

If you want the model to move on rather than try again, catch the timeout in the tool and return a plain result, as above. Pydantic AI also has ToolFailed, which records a result with outcome='failed', does not use the retry budget and tells the model to adapt rather than correct the call. Repeated failures are then bounded by UsageLimits instead.

It stops working when retries live in two places. If your HTTP client or SDK retries inside the tool, the framework timeout has to cover every attempt plus the backoff, or the framework cancels the call mid-retry and the two layers fight. The error handling field guide has the wider retry rules.

What changes with a fetch API behind the tool?

Default: the fetch API's own time limit becomes your innermost layer. With AgentFetch API, livecrawlTimeout is a request option you set in code, not a parameter the model chooses, and a URL that runs out of time comes back with the per-URL tag CRAWL_LIVECRAWL_TIMEOUT (see the API reference). Failed fetches cost 0 credits.

It stops working when the framework timeout ignores what happens after the fast fetch. Over REST and the SDKs, browser fallback is on by default, so a page the fast fetch cannot read in time may be rendered in a real browser instead. Leave room for that in the tool timeout. For the MCP client side of the same question, fetchmcp.net covers the client settings that end a slow fetch.

Where this breaks

  • Sync tools are not stopped. Pydantic AI enforces the deadline around the await. A plain def tool keeps running in its worker thread until it finishes, after the model has already got its timeout result, so write fetch tools as async def.
  • Your own TimeoutError is ambiguous. In Pydantic AI, a bare TimeoutError raised by your tool turns into the same 'Timed out after N seconds.' result when a tool timeout is configured, even if the deadline never passed. Without one, it propagates out of the run. Catch it and return or raise something explicit.
  • MCP tools sit outside these settings. Pydantic AI's tool timeouts are enforced by FunctionToolset only; MCP tools and other toolsets need a limit at the server or transport. Its MCPToolset(read_timeout=...) defaults to 300 seconds, far longer than most agents should wait for one page.
  • Numbers drift. The 20 and 30 second values here are starting points, not measurements. Log how long your fetch tool actually takes and set the layers from that.

Frequently asked questions

Should a tool timeout end the agent run?

Usually not. A timeout on one page is a normal result: return it to the model with one sentence saying what to do next. Stop the run only at the outer layer, with a step or run time limit, or when the same tool keeps timing out.

What does the OpenAI Agents SDK do when a function tool times out?

With timeout set on an async function tool, the default timeout_behavior is error_as_result, which gives the model a timeout message. Setting timeout_behavior to raise_exception raises ToolTimeoutError and the run fails. Timeouts work only for async function tools.

Does a tool timeout count as a retry in Pydantic AI?

Yes. When a tool timeout expires, the model gets a retried tool result saying 'Timed out after N seconds.' and it uses up that tool's retry budget. The default budget is 1, and an exhausted budget raises UnexpectedModelBehavior.

Why set a timeout inside the tool if the framework already has one?

Because the inner timeout lets your code write the message: which URL timed out and what the model should do instead. The framework's default message names at most the tool and the number of seconds, so keep it as a backstop that fires a little later.

Sources

  1. OpenAI Agents SDK: Tools (Documentation)
  2. Pydantic AI: Timeouts (Documentation)
  3. Pydantic AI: Retries (Documentation)
  4. AI SDK Core: Settings (Documentation)
  5. HTTPX: Timeouts (Documentation)