feat(anthropic): support webfetch tool

Author: christian-bromann

libs/providers/langchain-anthropic/src/tools/index.ts

@@ -1,9 +1,11 @@
 import { memory_20250818 } from "./memory.js";
 import { webSearch_20250305 } from "./webSearch.js";
+import { webFetch_20250910 } from "./webFetch.js";
 
 export const tools = {
   memory_20250818,
   webSearch_20250305,
+  webFetch_20250910,
 };
 
 export type * from "./types.js";

libs/providers/langchain-anthropic/src/tools/tests/webFetch.int.test.ts

@@ -0,0 +1,96 @@
+import { expect, it, describe } from "vitest";
+import {
+  AIMessage,
+  AIMessageChunk,
+  HumanMessage,
+} from "@langchain/core/messages";
+import { concat } from "@langchain/core/utils/stream";
+
+import { ChatAnthropic } from "../../chat_models.js";
+import { webFetch_20250910 } from "../webFetch.js";
+
+const createModel = () =>
+  new ChatAnthropic({
+    model: "claude-sonnet-4-5",
+    temperature: 0,
+    clientOptions: {
+      defaultHeaders: {
+        "anthropic-beta": "web-fetch-2025-09-10",
+      },
+    },
+  });
+
+describe("Anthropic Web Fetch Tool Integration Tests", () => {
+  it("web fetch tool can be bound to ChatAnthropic and triggers server tool use", async () => {
+    const llm = createModel();
+    const llmWithWebFetch = llm.bindTools([
+      webFetch_20250910({ maxUses: 1, citations: { enabled: true } }),
+    ]);
+
+    const response = await llmWithWebFetch.invoke([
+      new HumanMessage(
+        "Please fetch and summarize the content at https://example.com"
+      ),
+    ]);
+
+    expect(response).toBeInstanceOf(AIMessage);
+    expect(Array.isArray(response.content)).toBe(true);
+
+    const contentBlocks = response.content as Array<{ type: string }>;
+    const hasServerToolUse = contentBlocks.some(
+      (block) => block.type === "server_tool_use"
+    );
+    const hasWebFetchResult = contentBlocks.some(
+      (block) => block.type === "web_fetch_tool_result"
+    );
+
+    expect(hasServerToolUse).toBe(true);
+    expect(hasWebFetchResult).toBe(true);
+    expect(
+      (response.content as Array<{ text: string }>).find(
+        (block) =>
+          block.text ===
+          "This domain is for use in documentation examples without needing permission."
+      )
+    );
+  }, 30000);
+
+  it("web fetch tool streaming works correctly", async () => {
+    const llm = createModel();
+    const llmWithWebFetch = llm.bindTools([
+      webFetch_20250910({ maxUses: 1, citations: { enabled: true } }),
+    ]);
+
+    const stream = await llmWithWebFetch.stream([
+      new HumanMessage(
+        "Please fetch and describe the content at https://example.com"
+      ),
+    ]);
+
+    let finalChunk: AIMessageChunk | undefined;
+    for await (const chunk of stream) {
+      if (!finalChunk) {
+        finalChunk = chunk;
+      } else {
+        finalChunk = concat(finalChunk, chunk);
+      }
+    }
+
+    expect(finalChunk).toBeDefined();
+    expect(finalChunk).toBeInstanceOf(AIMessageChunk);
+    expect(Array.isArray(finalChunk?.content)).toBe(true);
+    const contentBlocks = finalChunk?.content as Array<{ type: string }>;
+    const hasServerToolUse = contentBlocks.some(
+      (block) => block.type === "server_tool_use"
+    );
+
+    expect(hasServerToolUse).toBe(true);
+    expect(
+      (finalChunk?.content as Array<{ text: string }>).find(
+        (block) =>
+          block.text ===
+          "This domain is for use in documentation examples without needing permission."
+      )
+    );
+  }, 30000);
+});

libs/providers/langchain-anthropic/src/tools/tests/webFetch.test.ts

@@ -0,0 +1,93 @@
+import { expect, it, describe } from "vitest";
+import { webFetch_20250910 } from "../webFetch.js";
+
+describe("Anthropic Web Fetch Tool Unit Tests", () => {
+  it("webFetch_20250910 creates a valid tool definition with no options", () => {
+    expect(webFetch_20250910()).toMatchInlineSnapshot(`
+      {
+        "allowed_domains": undefined,
+        "blocked_domains": undefined,
+        "cache_control": undefined,
+        "citations": undefined,
+        "max_content_tokens": undefined,
+        "max_uses": undefined,
+        "name": "web_fetch",
+        "type": "web_fetch_20250910",
+      }
+    `);
+  });
+
+  it("webFetch_20250910 creates a valid tool definition with all options", () => {
+    expect(
+      webFetch_20250910({
+        maxUses: 5,
+        allowedDomains: ["example.com", "docs.example.com"],
+        cacheControl: { type: "ephemeral" },
+        citations: { enabled: true },
+        maxContentTokens: 50000,
+      })
+    ).toMatchInlineSnapshot(`
+      {
+        "allowed_domains": [
+          "example.com",
+          "docs.example.com",
+        ],
+        "blocked_domains": undefined,
+        "cache_control": {
+          "type": "ephemeral",
+        },
+        "citations": {
+          "enabled": true,
+        },
+        "max_content_tokens": 50000,
+        "max_uses": 5,
+        "name": "web_fetch",
+        "type": "web_fetch_20250910",
+      }
+    `);
+  });
+
+  it("webFetch_20250910 creates a valid tool definition with blocked domains", () => {
+    expect(
+      webFetch_20250910({
+        maxUses: 10,
+        blockedDomains: ["private.example.com", "internal.example.com"],
+      })
+    ).toMatchInlineSnapshot(`
+      {
+        "allowed_domains": undefined,
+        "blocked_domains": [
+          "private.example.com",
+          "internal.example.com",
+        ],
+        "cache_control": undefined,
+        "citations": undefined,
+        "max_content_tokens": undefined,
+        "max_uses": 10,
+        "name": "web_fetch",
+        "type": "web_fetch_20250910",
+      }
+    `);
+  });
+
+  it("webFetch_20250910 creates a valid tool definition with citations disabled", () => {
+    expect(
+      webFetch_20250910({
+        citations: { enabled: false },
+      })
+    ).toMatchInlineSnapshot(`
+      {
+        "allowed_domains": undefined,
+        "blocked_domains": undefined,
+        "cache_control": undefined,
+        "citations": {
+          "enabled": false,
+        },
+        "max_content_tokens": undefined,
+        "max_uses": undefined,
+        "name": "web_fetch",
+        "type": "web_fetch_20250910",
+      }
+    `);
+  });
+});

libs/providers/langchain-anthropic/src/tools/webFetch.ts

@@ -0,0 +1,106 @@
+import Anthropic from "@anthropic-ai/sdk";
+
+/**
+ * Options for the web fetch tool.
+ */
+interface WebFetch20250910Options {
+  /**
+   * Maximum number of times the tool can be used in the API request.
+   */
+  maxUses?: number;
+  /**
+   * If provided, only these domains will be fetched. Cannot be used
+   * alongside `blockedDomains`.
+   */
+  allowedDomains?: string[];
+  /**
+   * If provided, these domains will never be fetched. Cannot be used
+   * alongside `allowedDomains`.
+   */
+  blockedDomains?: string[];
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cacheControl?: Anthropic.Beta.BetaCacheControlEphemeral;
+  /**
+   * Enable citations for fetched content. Unlike web search where citations
+   * are always enabled, citations are optional for web fetch.
+   */
+  citations?: {
+    enabled: boolean;
+  };
+  /**
+   * Maximum content length in tokens. If the fetched content exceeds this limit,
+   * it will be truncated. This helps control token usage when fetching large documents.
+   */
+  maxContentTokens?: number;
+}
+
+/**
+ * Creates a web fetch tool that allows Claude to retrieve full content from specified
+ * web pages and PDF documents. Claude can only fetch URLs that have been explicitly
+ * provided by the user or that come from previous web search or web fetch results.
+ *
+ * @warning Enabling the web fetch tool in environments where Claude processes untrusted
+ * input alongside sensitive data poses data exfiltration risks. We recommend only using
+ * this tool in trusted environments or when handling non-sensitive data.
+ *
+ * @note This tool requires the beta header `web-fetch-2025-09-10` in API requests.
+ *
+ * @see {@link https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-fetch-tool | Anthropic Web Fetch Documentation}
+ * @param options - Configuration options for the web fetch tool
+ * @returns A web fetch tool definition to be passed to the Anthropic API
+ *
+ * @example
+ * ```typescript
+ * import { ChatAnthropic, tools } from "@langchain/anthropic";
+ *
+ * const model = new ChatAnthropic({
+ *   model: "claude-sonnet-4-5-20250929",
+ * });
+ *
+ * // Basic usage - fetch content from a URL
+ * const response = await model.invoke(
+ *   "Please analyze the content at https://example.com/article",
+ *   { tools: [tools.webFetch_20250910()] }
+ * );
+ *
+ * // With options
+ * const responseWithOptions = await model.invoke(
+ *   "Summarize this research paper: https://arxiv.org/abs/2024.12345",
+ *   {
+ *     tools: [tools.webFetch_20250910({
+ *       maxUses: 5,
+ *       allowedDomains: ["arxiv.org", "example.com"],
+ *       citations: { enabled: true },
+ *       maxContentTokens: 50000,
+ *     })],
+ *   }
+ * );
+ *
+ * // Combined with web search for comprehensive information gathering
+ * const combinedResponse = await model.invoke(
+ *   "Find recent articles about quantum computing and analyze the most relevant one",
+ *   {
+ *     tools: [
+ *       tools.webSearch_20250305({ maxUses: 3 }),
+ *       tools.webFetch_20250910({ maxUses: 5, citations: { enabled: true } }),
+ *     ],
+ *   }
+ * );
+ * ```
+ */
+export function webFetch_20250910(
+  options?: WebFetch20250910Options
+): Anthropic.Beta.BetaWebFetchTool20250910 {
+  return {
+    type: "web_fetch_20250910",
+    name: "web_fetch",
+    max_uses: options?.maxUses,
+    allowed_domains: options?.allowedDomains,
+    blocked_domains: options?.blockedDomains,
+    cache_control: options?.cacheControl,
+    citations: options?.citations,
+    max_content_tokens: options?.maxContentTokens,
+  };
+}