Retries and time limits

Retrying a step

Set retries on a tool or an agent step. It is the number of extra tries after the first one fails. The default is 0.

export const fetchPage = tool({
  input: z.object({ url: z.string() }),
  output: z.object({ html: z.string() }),
  retries: 3,
  timeoutMs: 10_000,
  run: async ({ url }, ctx) => {
    const res = await fetch(url, { signal: ctx.signal });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return { html: await res.text() };
  },
});
Wait between tries 200 ms, doubling each time, at most 30 s
ctx.attempt 1 on the first try, 2 on the next, and so on
ctx.key the same on every try; pass it to APIs that take an idempotency key
ctx.signal aborted when the try times out or the run is cancelled; pass it to fetch

Retried: any error your code throws, and a time-out.

Not retried: input that does not match the step’s input schema, and output that does not match its output schema. Trying again would give the same result.

When the tries run out, the run ends with status: 'failed' and error.node names the step. With a store, resume(runId, tools, {}, { store }) starts again at that step.

Time limits

timeoutMs on a step limits one try. Without it, the limit is 5 minutes. Change the default for a whole run:

await run(flow, tools, input, { limits: { timeoutMs: 30_000 } });

A time-out aborts ctx.signal. Code that ignores the signal keeps running in the background, so pass it on.

Agent steps

retries and timeoutMs work the same on agent steps. Separately, when a model’s answer does not match the output schema, the model is asked once more inside the same try. If it still does not fit, the step fails without further retries.

Loops are not retries

A loop in the diagram is part of the workflow, and every loop needs a cap:

flowchart TD
  draft --> score --> good{"score >= 8"}
  good -->|yes| publish
  good -->|no, max 5| draft

When the cap is reached the run fails, rather than looping forever.

Limits for a whole run

Pass limits to run() or resume():

Limit Default Meaning
maxSteps 10,000 most step executions in one run
timeoutMs 300,000 default limit for one try of one step
concurrency 5 items of a for-each block running at once
maxContextChars 5,000,000 largest shared data, as JSON

Watching retries

await run(flow, tools, input, {
  onEvent: (e) => {
    if (e.type === 'node.retry') console.warn(`${e.node} failed (try ${e.attempt}): ${e.error}`);
  },
});

Cancelling

Pass an AbortSignal as signal. Waiting between retries stops at once, and running steps see ctx.signal abort.