Retry

Retry

Automatic retry with configurable backoff strategies for tool execution failures.

RetryConfig

Every tool has built-in retry support:

interface RetryConfig {
  maxAttempts?: number;       // Default: 3
  backoff?: BackoffStrategy;  // Default: 'exponential'
  baseDelay?: number;         // Default: 1000 (ms)
}

type BackoffStrategy = 'exponential' | 'linear' | 'fixed';

Defaults

If you don't configure retry, tools get these defaults:

Setting	Default
`maxAttempts`	3
`backoff`	`'exponential'`
`baseDelay`	1000ms

Backoff Strategies

Strategy	Delay Pattern	Example (base: 1000ms)
`exponential`	`baseDelay * 2^attempt`	1s, 2s, 4s
`linear`	`baseDelay * attempt`	1s, 2s, 3s
`fixed`	`baseDelay`	1s, 1s, 1s

Custom Retry Config

const apiTool = defineTool({
  name: 'external-api',
  description: 'Call an external API',
  input: z.object({ endpoint: z.string() }),
  output: z.object({ data: z.unknown() }),
  execute: async ({ endpoint }) => {
    const res = await fetch(endpoint);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return { data: await res.json() };
  },
  retry: {
    maxAttempts: 5,
    backoff: 'exponential',
    baseDelay: 2000,
  },
});

Disabling Retry

Set maxAttempts: 1 to disable retry:

const oneShot = defineTool({
  name: 'send-email',
  description: 'Send an email (no retry)',
  input: z.object({ to: z.string(), body: z.string() }),
  output: z.object({ sent: z.boolean() }),
  execute: async (input) => { /* ... */ },
  retry: { maxAttempts: 1 },
});

Next Steps

Caching — deduplicate identical calls
Compensating Actions — rollback on failure