Errors and retries
Stop conditions for agents that fetch: repeats, failure caps, steps
Add three stop rules to a fetching agent: no repeat of a failed URL, a failure cap per task and a step limit, with LangChain, AI SDK and Pydantic AI examples.
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.
- 1No repeat of a failed URLThe tool refuses a URL that already failed in this task and says why.
- 2A failure cap per taskAfter the cap, the tool tells the model to answer with the pages it has.
- 3A framework limitA tool-call or step limit ends the run if the model keeps going anyway.
- 4A message for the userYour code turns a hard stop into an answer, not a stack trace.
An agent that reads the web fails often, and on its own it rarely knows when to quit. LangChain's fault-tolerance guide puts it bluntly: "a confused agent can burn through your LLM API budget in minutes by looping on the same tool call." Retries inside one call are already capped in code, as the error-handling guide describes. This post covers the loop around them: when the agent should stop fetching, and who decides.
What is the default set of stop rules?
Use three rules per task: never fetch a URL that already failed in this task, stop fetching after a fixed number of failures, and keep a framework limit on tool calls or steps above both. It stops working when the three rules count different things, which is what most of the surprises below come down to.
The first two are a soft stop. The fetch tool refuses and tells the model why, and the model writes its answer from the pages it has. The third is a hard stop: the framework ends the run, and your code has to turn that into something the user can read. Without the soft stop, the agent tends to hit the hard one, and the user gets nothing.
How does the fetch tool enforce a soft stop?
Keep a small guard object per task and route every fetch through it. read_page is the shared function from the framework recipes guide: it returns ok with content, or ok: False with an error tag and a sentence.
class FetchGuard:
"""Stop rules for one task. Create a new guard for every task."""
def __init__(self, max_fetches=15, max_failures=5):
self.max_fetches = max_fetches
self.max_failures = max_failures
self.fetches = 0
self.failures = 0
self.failed = {} # url -> error tag
def fetch(self, url, read_page):
if url in self.failed:
return {"ok": False, "error": "ALREADY_FAILED",
"message": f"This URL already failed in this task ({self.failed[url]}). "
"Do not fetch it again. Use another source or answer with what you have."}
if self.fetches >= self.max_fetches or self.failures >= self.max_failures:
return {"ok": False, "error": "FETCH_BUDGET_SPENT",
"message": "No more fetches in this task. Answer with the pages you have "
"and say which ones you could not read."}
self.fetches += 1
result = read_page(url)
if not result["ok"]:
self.failures += 1
self.failed[url] = result["error"]
return result
def make_get_page(guard):
def get_page(url: str) -> dict:
"""Read one public web page and return its main content as Markdown."""
return guard.fetch(url, read_page)
return get_page
The limits of 15 fetches and 5 failures are starting points, not measured values. A trace of the soft stop: the agent fetches a page and gets CRAWL_NOT_FOUND; it tries the same path with a trailing slash and gets a second not-found; it asks for the first URL again and gets ALREADY_FAILED; it fetches the site's docs index, which works, and answers from that page.
It stops working when the guard lives longer than the task. A module-level guard shared by all users runs out of budget for everyone, so create it where the task starts.
Which hard limit does LangChain give you?
Put ToolCallLimitMiddleware on the fetch tool and ModelCallLimitMiddleware on the run, both passed to create_agent.
from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware, ToolCallLimitMiddleware
get_page = make_get_page(FetchGuard())
agent = create_agent(
model=model, # your chat model
tools=[get_page],
middleware=[
ToolCallLimitMiddleware(tool_name="get_page", run_limit=20),
ModelCallLimitMiddleware(run_limit=30),
],
)
The defaults are the surprising part. exit_behavior on the tool limiter defaults to continue: calls over the limit get an error message and the model keeps going, so on its own it is another soft stop. end stops the run, but only when a single tool is limited; if other tools have pending calls it raises NotImplementedError. error raises ToolCallLimitExceededError. The model limiter defaults to end, which ends the run cleanly.
It stops working when the agent spans several user messages. run_limit resets with each new user message; a cap for the whole conversation is thread_limit, and that needs a checkpointer.
How does the AI SDK stop a tool loop?
Set stopWhen explicitly. ToolLoopAgent stops after 20 steps by default, using isStepCount(20); pass an array and the loop ends when any one condition is met.
import { ToolLoopAgent, isStepCount, hasToolCall } from 'ai';
const agent = new ToolLoopAgent({
model, // your model
tools: { getPage, done },
stopWhen: [isStepCount(12), hasToolCall('done')],
});
hasToolCall('done') gives the model a clean exit: it calls a done tool when it has its answer. A custom condition receives steps, every step so far, and returns a boolean, so a failure count across steps fits there too. For a softer stop, prepareStep runs before each step and can change the active tools, so you can take the fetch tool away once the guard reports that the budget is spent.
It stops working when you switch agent types or helpers. isLoopFinished() removes the step limit, and WorkflowAgent.stream() has no default step limit at all.
What does Pydantic AI count?
Pass UsageLimits to the run and catch UsageLimitExceeded.
from pydantic_ai import Agent, UsageLimitExceeded, UsageLimits
try:
result = agent.run_sync(prompt, usage_limits=UsageLimits(request_limit=20, tool_calls_limit=15))
except UsageLimitExceeded:
result = None # tell the user the task ran out of steps
Read the counters closely. request_limit caps model turns and defaults to 50. tool_calls_limit caps successful tool invocations. The per-tool retry budget defaults to 1, but it is counted per tool name and resets on success, so a fetch tool that alternates between failing and working never runs out of it. When a budget does run out, the run raises UnexpectedModelBehavior. A ToolFailed result does not use the retry budget at all; the docs say such failures are bounded by UsageLimits.
It stops working when you rely on any one of these for failures. Only your own counter in the guard counts failed fetches per task.
Where this breaks
- Counters do not see transport retries. Pydantic AI notes that
UsageLimitsdoes not see SDK and transport retries. One tool call can be several HTTP attempts, so a call limit is not an attempt limit. - Free failures still cost tokens. With AgentFetch API, "Failed fetches cost 0 credits." The model still reads every error result and spends tokens on each one; the error tags are in the API reference.
- URL variants dodge the repeat rule. A trailing slash or a query string makes a new key. Normalize the URL before the lookup if your agent guesses variants.
- A hard stop with no message. An exception at the step limit is not an answer. Catch it and tell the user what was read and what could not be read.
Framework APIs here were checked against the LangChain, AI SDK and Pydantic AI docs in November 2026; they change often, so check them against the version you have installed.
Frequently asked questions
How do I stop an agent from fetching the same failed URL again?
Keep a per-task record of failed URLs in the fetch tool. When the model asks for one of them again, return a tool result that names the earlier error and tells it to use another source or answer with what it has, instead of fetching again.
What is the default step limit of the AI SDK ToolLoopAgent?
According to the AI SDK loop control docs, ToolLoopAgent stops after 20 steps by default, using isStepCount(20). An array of conditions stops the loop as soon as any one of them is met.
Does LangChain's ToolCallLimitMiddleware stop the agent when the limit is reached?
Not by default. Its exit_behavior defaults to continue, which returns an error message for each call over the limit and lets the model keep running. Set it to end or error if the run itself should stop.
Does Pydantic AI's tool_calls_limit count failed tool calls?
The Pydantic AI docs describe tool_calls_limit as a cap on successful tool invocations in a run. Failed fetches are better bounded by your own failure counter and by request_limit, which caps model turns and defaults to 50.
Sources
- Built-in middleware (LangChain docs) (Documentation)
- Fault tolerance (LangChain Deep Agents docs) (Documentation)
- Loop control (AI SDK docs) (Documentation)
- Retries (Pydantic AI docs) (Documentation)
- Agents (Pydantic AI docs) (Documentation)