feat(anthropic): support code execution tool

Author: christian-bromann

libs/providers/langchain-anthropic/README.md

@@ -454,6 +454,58 @@ const computer = tools.computer_20251124({
 
 For more information, see [Anthropic's Computer Use documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use).
 
+### Code Execution Tool
+
+The code execution tool (`codeExecution_20250825`) allows Claude to run Bash commands and manipulate files in a secure, sandboxed environment. Claude can analyze data, create visualizations, perform calculations, and process files.
+
+When this tool is provided, Claude automatically gains access to:
+
+- **Bash commands** - Execute shell commands for system operations
+- **File operations** - Create, view, and edit files directly
+
+```typescript
+import { ChatAnthropic, tools } from "@langchain/anthropic";
+
+const llm = new ChatAnthropic({
+  model: "claude-sonnet-4-5-20250929",
+});
+
+// Basic usage - calculations and data analysis
+const response = await llm.invoke(
+  "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
+  { tools: [tools.codeExecution_20250825()] }
+);
+
+// File operations and visualization
+const response2 = await llm.invoke(
+  "Create a matplotlib visualization of sales data and save it as chart.png",
+  { tools: [tools.codeExecution_20250825()] }
+);
+```
+
+Container reuse for multi-step workflows:
+
+```typescript
+// First request - creates a container
+const response1 = await llm.invoke("Write a random number to /tmp/number.txt", {
+  tools: [tools.codeExecution_20250825()],
+});
+
+// Extract container ID from response for reuse
+const containerId = response1.response_metadata?.container?.id;
+
+// Second request - reuse container to access the file
+const response2 = await llm.invoke(
+  "Read /tmp/number.txt and calculate its square",
+  {
+    tools: [tools.codeExecution_20250825()],
+    container: containerId,
+  }
+);
+```
+
+For more information, see [Anthropic's Code Execution Tool documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/code-execution-tool).
+
 ## Development
 
 To develop the Anthropic package, you'll need to follow these instructions:

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

@@ -0,0 +1,78 @@
+import Anthropic from "@anthropic-ai/sdk";
+
+/**
+ * Options for the code execution tool.
+ */
+interface CodeExecution20250825Options {
+  /**
+   * Create a cache control breakpoint at this content block.
+   */
+  cacheControl?: Anthropic.Beta.BetaCacheControlEphemeral;
+}
+
+/**
+ * Creates a code execution tool that allows Claude to run Bash commands and manipulate files
+ * in a secure, sandboxed environment. Claude can analyze data, create visualizations,
+ * perform calculations, and process files.
+ *
+ * When this tool is provided, Claude automatically gains access to:
+ * - **Bash commands**: Execute shell commands for system operations
+ * - **File operations**: Create, view, and edit files directly
+ *
+ * @note This tool requires the beta header `code-execution-2025-08-25` in API requests.
+ *
+ * @see {@link https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/code-execution-tool | Anthropic Code Execution Documentation}
+ * @param options - Configuration options for the code execution tool
+ * @returns A code execution 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 - calculations and data analysis
+ * const response = await model.invoke(
+ *   "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
+ *   { tools: [tools.codeExecution_20250825()] }
+ * );
+ *
+ * // File operations and visualization
+ * const response2 = await model.invoke(
+ *   "Create a matplotlib visualization of sales data and save it as chart.png",
+ *   { tools: [tools.codeExecution_20250825()] }
+ * );
+ * ```
+ *
+ * @example Container reuse
+ * ```typescript
+ * // First request - creates a container
+ * const response1 = await model.invoke(
+ *   "Write a random number to /tmp/number.txt",
+ *   { tools: [tools.codeExecution_20250825()] }
+ * );
+ *
+ * // Extract container ID from response for reuse
+ * const containerId = response1.response_metadata?.container?.id;
+ *
+ * // Second request - reuse container to access the file
+ * const response2 = await model.invoke(
+ *   "Read /tmp/number.txt and calculate its square",
+ *   {
+ *     tools: [tools.codeExecution_20250825()],
+ *     // Pass container ID to reuse the same environment
+ *   }
+ * );
+ * ```
+ */
+export function codeExecution_20250825(
+  options?: CodeExecution20250825Options
+): Anthropic.Beta.BetaCodeExecutionTool20250825 {
+  return {
+    type: "code_execution_20250825",
+    name: "code_execution",
+    cache_control: options?.cacheControl,
+  };
+}

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

@@ -7,6 +7,7 @@ import {
 } from "./toolSearch.js";
 import { textEditor_20250728 } from "./textEditor.js";
 import { computer_20251124, computer_20250124 } from "./computer.js";
+import { codeExecution_20250825 } from "./codeExecution.js";
 
 export const tools = {
   memory_20250818,
@@ -17,6 +18,7 @@ export const tools = {
   textEditor_20250728,
   computer_20251124,
   computer_20250124,
+  codeExecution_20250825,
 };
 
 export type * from "./types.js";

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

@@ -0,0 +1,125 @@
+import { expect, it, describe } from "vitest";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+
+import { ChatAnthropic } from "../../chat_models.js";
+import { codeExecution_20250825 } from "../codeExecution.js";
+
+const createModel = () =>
+  new ChatAnthropic({
+    model: "claude-sonnet-4-5",
+    temperature: 0,
+  });
+
+describe("Anthropic Code Execution Tool Integration Tests", () => {
+  it("code execution tool can be bound to ChatAnthropic and performs calculations", async () => {
+    const llm = createModel();
+    const llmWithCodeExecution = llm.bindTools([codeExecution_20250825()]);
+
+    const response = await llmWithCodeExecution.invoke([
+      new HumanMessage(
+        "Calculate the mean of [1, 2, 3, 4, 5]. Just give me the number."
+      ),
+    ]);
+
+    expect(response).toBeInstanceOf(AIMessage);
+    expect(Array.isArray(response.content)).toBe(true);
+
+    const contentBlocks = response.content as Array<{ type: string }>;
+
+    // Should have server_tool_use for code execution
+    const hasServerToolUse = contentBlocks.some(
+      (block) => block.type === "server_tool_use"
+    );
+
+    // Should have code execution result
+    const hasCodeExecutionResult = contentBlocks.some(
+      (block) =>
+        block.type === "bash_code_execution_tool_result" ||
+        block.type === "text_editor_code_execution_tool_result"
+    );
+
+    expect(hasServerToolUse).toBe(true);
+    expect(hasCodeExecutionResult).toBe(true);
+
+    const [toolUse, toolResult, result] = response.content;
+    expect(toolUse).toEqual(
+      expect.objectContaining({
+        type: "server_tool_use",
+        id: expect.any(String),
+        name: "bash_code_execution",
+        input: {
+          command:
+            'python3 -c "print(sum([1, 2, 3, 4, 5]) / len([1, 2, 3, 4, 5]))"',
+        },
+      })
+    );
+    expect(toolResult).toEqual(
+      expect.objectContaining({
+        type: "bash_code_execution_tool_result",
+        tool_use_id: expect.any(String),
+        content: expect.objectContaining({
+          type: "bash_code_execution_result",
+          stdout: "3.0\n",
+          stderr: "",
+          return_code: 0,
+          content: [],
+        }),
+      })
+    );
+    expect(result).toEqual(
+      expect.objectContaining({
+        type: "text",
+        text: expect.any(String),
+      })
+    );
+  }, 60000);
+
+  it("code execution tool supports container reuse across requests", async () => {
+    const llm = createModel();
+
+    // First request - creates a container and writes a file
+    const response1 = await llm.invoke(
+      "Write the number 7 to /tmp/number.txt using bash. Just do it, no explanation needed.",
+      {
+        tools: [codeExecution_20250825()],
+      }
+    );
+
+    expect(response1).toBeInstanceOf(AIMessage);
+
+    // Extract container ID from response for reuse
+    const containerId = (
+      response1.response_metadata?.container as { id?: string } | undefined
+    )?.id;
+    expect(containerId).toBeDefined();
+    expect(typeof containerId).toBe("string");
+
+    // Second request - reuse container to access the file
+    const response2 = await llm.invoke(
+      "Read /tmp/number.txt and calculate its square. Just give me the result.",
+      {
+        tools: [codeExecution_20250825()],
+        container: containerId,
+      }
+    );
+
+    expect(response2).toBeInstanceOf(AIMessage);
+
+    // The response should contain code execution results
+    const contentBlocks = response2.content as Array<{ type: string }>;
+    const hasCodeExecutionResult = contentBlocks.some(
+      (block) =>
+        block.type === "bash_code_execution_tool_result" ||
+        block.type === "text_editor_code_execution_tool_result"
+    );
+    expect(hasCodeExecutionResult).toBe(true);
+
+    // The final text response should contain 49 (7 squared)
+    const textBlock = contentBlocks.find((block) => block.type === "text") as {
+      type: string;
+      text: string;
+    };
+    expect(textBlock).toBeDefined();
+    expect(textBlock.text).toContain("49");
+  }, 120000);
+});

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

@@ -0,0 +1,32 @@
+import { expect, it, describe } from "vitest";
+import { codeExecution_20250825 } from "../codeExecution.js";
+
+describe("Anthropic Code Execution Tool Unit Tests", () => {
+  describe("codeExecution_20250825", () => {
+    it("creates a valid code execution tool with no options", () => {
+      expect(codeExecution_20250825()).toMatchInlineSnapshot(`
+        {
+          "cache_control": undefined,
+          "name": "code_execution",
+          "type": "code_execution_20250825",
+        }
+      `);
+    });
+
+    it("creates a valid code execution tool with cache control", () => {
+      expect(
+        codeExecution_20250825({
+          cacheControl: { type: "ephemeral" },
+        })
+      ).toMatchInlineSnapshot(`
+        {
+          "cache_control": {
+            "type": "ephemeral",
+          },
+          "name": "code_execution",
+          "type": "code_execution_20250825",
+        }
+      `);
+    });
+  });
+});

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

@@ -55,4 +55,5 @@ export const ANTHROPIC_TOOL_BETAS: Record<string, string> = {
   tool_search_tool_bm25_20251119: "advanced-tool-use-2025-11-20",
   memory_20250818: "context-management-2025-06-27",
   web_fetch_20250910: "web-fetch-2025-09-10",
+  code_execution_20250825: "code-execution-2025-08-25",
 };