feat(langchain): tool retry middleware

[pokey]

Adds toolRetryMiddleware to automatically retry failed tool calls with configurable exponential backoff, exception filtering, and error handling.

Port of langchain-ai/langchain#33503

Example

import { createAgent, toolRetryMiddleware } from "langchain";

// Retry up to 3 times with exponential backoff
const retry = toolRetryMiddleware({
  maxRetries: 3,
  initialDelay: 1000,
  backoffFactor: 2.0,
});

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [searchTool, databaseTool],
  middleware: [retry],
});

// Tool failures are automatically retried
const result = await agent.invoke({
  messages: [{ role: "user", content: "Search for AI news" }],
});

For advanced usage with specific exception handling:

class TimeoutError extends Error {}

function shouldRetry(error: Error): boolean {
  // Only retry on 5xx errors or timeouts
  if (error.constructor.name === "HTTPError") {
    const statusCode = (error as any).statusCode;
    return 500 <= statusCode && statusCode < 600;
  }
  return error.constructor === TimeoutError;
}

const retry = toolRetryMiddleware({
  maxRetries: 4,
  retryOn: shouldRetry,
  tools: ["search_database"], // Only apply to specific tools
});

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8d975d1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pokey]

Just flagging that this is milliseconds, where python uses seconds. It is more common in js to use milliseconds, but I don't love the inconsistency with the Python version. Any opinions? We could name it initialDelayMs to make unit clearer if we decide to stick with milliseconds

[hntrl]

No super strong opinions, but would agree we should use ms.

[pokey]

Added Ms suffix to make it clearer

[hntrl]

No super strong opinions, but would agree we should use ms.

[hntrl]

might pay to be more strict here:

Suggested change

	const toolFilter: string[] | undefined = tools?.map((tool) =>
	typeof tool === "string" ? tool : (tool.name as string)
	);
	const toolFilter = tools?.reduce((acc, tool) => {
	if (typeof tool === "string") return [...acc, tool];
	else if ("name" in tool && typeof tool.name === "string") return [...acc, tool];
	else return acc;
	}, [] as string[]);

[pokey]

So we'd just silent drop tools that don't look right? Would it not be better to fail fast?

[hntrl]

Idk if it super matters. If that's something we do want to guard against, I'd say we need to throw a better error instead of just whatever comes out of accessing tool.name on a weird looking object

[pokey]

Throwing a better error sounds good to me. Any objection?

[pokey]

Ok feedback addressed and left some responses