feat(prebuilt): add support for handle_tool_errors with single exception type (#6021)

This PR extends the `ToolNode` `handle_tool_errors` property to also
accept a single exception type: `type[Exception]`.

Example:
```python
tool_node_with_error_handling = ToolNode(
    [tool1, tool2, tool3], handle_tool_errors=ValueError
).invoke(...)
"""A tool node that will only retry a failed tool call if a ValueError is raised"""
```

docs/docs/agents/multi-agent.md

@@ -367,13 +367,13 @@ To implement handoffs with `createReactAgent`, you need to:
 
 3.  Define a parent graph that contains individual agents as nodes:
 
-        ```typescript
-        import { StateGraph, MessagesZodState } from "@langchain/langgraph";
-        const multiAgentGraph = new StateGraph(MessagesZodState)
-          .addNode("flight_assistant", flightAssistant)
-          .addNode("hotel_assistant", hotelAssistant)
-          // ...
-        ```
+    ```typescript
+    import { StateGraph, MessagesZodState } from "@langchain/langgraph";
+    const multiAgentGraph = new StateGraph(MessagesZodState)
+      .addNode("flight_assistant", flightAssistant)
+      .addNode("hotel_assistant", hotelAssistant)
+      // ...
+    ```
 
     :::
 
@@ -619,7 +619,8 @@ for await (const chunk of multiAgentGraph.stream({
 3. Name of the agent or node to hand off to.
 4. Take the agent's messages and **add** them to the parent's **state** as part of the handoff. The next agent will see the parent state.
 5. Indicate to LangGraph that we need to navigate to agent node in a **parent** multi-agent graph.
-   :::
+
+:::
 
 !!! Note
 

docs/docs/concepts/mcp.md

@@ -6,7 +6,14 @@
 
 Install the `langchain-mcp-adapters` library to use MCP tools in LangGraph:
 
+:::python
 ```bash
 pip install langchain-mcp-adapters
 ```
+:::
 
+:::js
+```bash
+npm install @langchain/mcp-adapters
+```
+:::

docs/docs/how-tos/multi_agent.md

@@ -22,6 +22,7 @@ To set up communication between the agents in a multi-agent system you can use [
 
 To implement handoffs, you can return `Command` objects from your agent nodes or tools:
 
+:::python
 ```python
 from typing import Annotated
 from langchain_core.tools import tool, InjectedToolCallId
@@ -73,25 +74,109 @@ def create_handoff_tool(*, agent_name: str, description: str | None = None):
         commands = [tools_by_name[tool_call["name"]].invoke(tool_call) for tool_call in tool_calls]
         return commands
     ```
+:::
+
+:::js
+```typescript
+import { tool } from "@langchain/core/tools";
+import { Command, MessagesZodState } from "@langchain/langgraph";
+import { z } from "zod";
+
+function createHandoffTool({
+  agentName,
+  description,
+}: {
+  agentName: string;
+  description?: string;
+}) {
+  const name = `transfer_to_${agentName}`;
+  const toolDescription = description || `Transfer to ${agentName}`;
+
+  return tool(
+    async (_, config) => {
+      // (1)!
+      const state = config.state;
+      const toolCallId = config.toolCall.id;
+
+      const toolMessage = {
+        role: "tool" as const,
+        content: `Successfully transferred to ${agentName}`,
+        name: name,
+        tool_call_id: toolCallId,
+      };
+
+      return new Command({
+        // (3)!
+        goto: agentName,
+        // (4)!
+        update: { messages: [...state.messages, toolMessage] },
+        // (5)!
+        graph: Command.PARENT,
+      });
+    },
+    {
+      name,
+      description: toolDescription,
+      schema: z.object({}),
+    }
+  );
+}
+```
+
+1. Access the [state](../concepts/low_level.md#state) of the agent that is calling the handoff tool through the `config` parameter.
+2. The `Command` primitive allows specifying a state update and a node transition as a single operation, making it useful for implementing handoffs.
+3. Name of the agent or node to hand off to.
+4. Take the agent's messages and **add** them to the parent's **state** as part of the handoff. The next agent will see the parent state.
+5. Indicate to LangGraph that we need to navigate to agent node in a **parent** multi-agent graph.
+
+!!! tip
+
+    If you want to use tools that return `Command`, you can either use prebuilt @[`create_react_agent`][create_react_agent] / @[`ToolNode`][ToolNode] components, or implement your own tool-executing node that collects `Command` objects returned by the tools and returns a list of them, e.g.:
+    
+    ```typescript
+    const callTools = async (state) => {
+      // ...
+      const commands = await Promise.all(
+        toolCalls.map(toolCall => toolsByName[toolCall.name].invoke(toolCall))
+      );
+      return commands;
+    };
+    ```
+:::
 
 !!! Important
 
     This handoff implementation assumes that:
     
-      - each agent receives overall message history (across all agents) in the multi-agent system as its input. If you want more control over agent inputs, see [this section](#control-agent-inputs)
-      - each agent outputs its internal messages history to the overall message history of the multi-agent system. If you want more control over **how agent outputs are added**, wrap the agent in a separate node function:
+    - each agent receives overall message history (across all agents) in the multi-agent system as its input. If you want more control over agent inputs, see [this section](#control-agent-inputs)
+    - each agent outputs its internal messages history to the overall message history of the multi-agent system. If you want more control over **how agent outputs are added**, wrap the agent in a separate node function:
 
-        ```python
-        def call_hotel_assistant(state):
-            # return agent's final response,
-            # excluding inner monologue
-            response = hotel_assistant.invoke(state)
-            # highlight-next-line
-            return {"messages": response["messages"][-1]}
-        ```
+      :::python
+      ```python
+      def call_hotel_assistant(state):
+          # return agent's final response,
+          # excluding inner monologue
+          response = hotel_assistant.invoke(state)
+          # highlight-next-line
+          return {"messages": response["messages"][-1]}
+      ```
+      :::
+
+      :::js
+      ```typescript
+      const callHotelAssistant = async (state) => {
+        // return agent's final response,
+        // excluding inner monologue
+        const response = await hotelAssistant.invoke(state);
+        // highlight-next-line
+        return { messages: [response.messages.at(-1)] };
+      };
+      ```
+      :::
 
 ### Control agent inputs
 
+:::python
 You can use the @[`Send()`][Send] primitive to directly send data to the worker agents during the handoff. For example, you can request that the calling agent populate a task description for the next agent:
 
 ```python
@@ -129,6 +214,63 @@ def create_task_description_handoff_tool(
 
     return handoff_tool
 ```
+:::
+
+:::js
+You can use the @[`Send()`][Send] primitive to directly send data to the worker agents during the handoff. For example, you can request that the calling agent populate a task description for the next agent:
+
+```typescript
+import { tool } from "@langchain/core/tools";
+import { Command, Send, MessagesZodState } from "@langchain/langgraph";
+import { z } from "zod";
+
+function createTaskDescriptionHandoffTool({
+  agentName,
+  description,
+}: {
+  agentName: string;
+  description?: string;
+}) {
+  const name = `transfer_to_${agentName}`;
+  const toolDescription = description || `Ask ${agentName} for help.`;
+
+  return tool(
+    async (
+      { taskDescription },
+      config
+    ) => {
+      const state = config.state;
+      
+      const taskDescriptionMessage = {
+        role: "user" as const,
+        content: taskDescription,
+      };
+      const agentInput = {
+        ...state,
+        messages: [taskDescriptionMessage],
+      };
+      
+      return new Command({
+        // highlight-next-line
+        goto: [new Send(agentName, agentInput)],
+        graph: Command.PARENT,
+      });
+    },
+    {
+      name,
+      description: toolDescription,
+      schema: z.object({
+        taskDescription: z
+          .string()
+          .describe(
+            "Description of what the next agent should do, including all of the relevant context."
+          ),
+      }),
+    }
+  );
+}
+```
+:::
 
 See the multi-agent [supervisor](../tutorials/multi_agent/agent_supervisor.md#4-create-delegation-tasks) example for a full example of using @[`Send()`][Send] in handoffs.
 
@@ -136,6 +278,7 @@ See the multi-agent [supervisor](../tutorials/multi_agent/agent_supervisor.md#4-
 
 You can use handoffs in any agents built with LangGraph. We recommend using the prebuilt [agent](../agents/overview.md) or [`ToolNode`](./tool-calling.md#toolnode), as they natively support handoffs tools returning `Command`. Below is an example of how you can implement a multi-agent system for booking travel using handoffs:
 
+:::python
 ```python
 from langgraph.prebuilt import create_react_agent
 from langgraph.graph import StateGraph, START, MessagesState
@@ -176,9 +319,65 @@ multi_agent_graph = (
     .compile()
 )
 ```
+:::
+
+:::js
+```typescript
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+import { StateGraph, START, MessagesZodState } from "@langchain/langgraph";
+import { z } from "zod";
+
+function createHandoffTool({
+  agentName,
+  description,
+}: {
+  agentName: string;
+  description?: string;
+}) {
+  // same implementation as above
+  // ...
+  return new Command(/* ... */);
+}
+
+// Handoffs
+const transferToHotelAssistant = createHandoffTool({
+  agentName: "hotel_assistant",
+});
+const transferToFlightAssistant = createHandoffTool({
+  agentName: "flight_assistant",
+});
+
+// Define agents
+const flightAssistant = createReactAgent({
+  llm: model,
+  // highlight-next-line
+  tools: [/* ... */, transferToHotelAssistant],
+  // highlight-next-line
+  name: "flight_assistant",
+});
+
+const hotelAssistant = createReactAgent({
+  llm: model,
+  // highlight-next-line
+  tools: [/* ... */, transferToFlightAssistant],
+  // highlight-next-line
+  name: "hotel_assistant",
+});
+
+// Define multi-agent graph
+const multiAgentGraph = new StateGraph(MessagesZodState)
+  // highlight-next-line
+  .addNode("flight_assistant", flightAssistant)
+  // highlight-next-line
+  .addNode("hotel_assistant", hotelAssistant)
+  .addEdge(START, "flight_assistant")
+  .compile();
+```
+:::
 
 ??? example "Full example: Multi-agent system for booking travel"
 
+    :::python
     ```python
     from typing import Annotated
     from langchain_core.messages import convert_to_messages
@@ -323,6 +522,183 @@ multi_agent_graph = (
     3. Name of the agent or node to hand off to.
     4. Take the agent's messages and **add** them to the parent's **state** as part of the handoff. The next agent will see the parent state.
     5. Indicate to LangGraph that we need to navigate to agent node in a **parent** multi-agent graph.
+    :::
+
+    :::js
+    ```typescript
+    import { tool } from "@langchain/core/tools";
+    import { createReactAgent } from "@langchain/langgraph/prebuilt";
+    import { StateGraph, START, MessagesZodState, Command } from "@langchain/langgraph";
+    import { ChatAnthropic } from "@langchain/anthropic";
+    import { isBaseMessage } from "@langchain/core/messages";
+    import { z } from "zod";
+
+    // We'll use a helper to render the streamed agent outputs nicely
+    const prettyPrintMessages = (update: Record<string, any>) => {
+      // Handle tuple case with namespace
+      if (Array.isArray(update)) {
+        const [ns, updateData] = update;
+        // Skip parent graph updates in the printouts
+        if (ns.length === 0) {
+          return;
+        }
+
+        const graphId = ns[ns.length - 1].split(":")[0];
+        console.log(`Update from subgraph ${graphId}:\n`);
+        update = updateData;
+      }
+
+      for (const [nodeName, updateValue] of Object.entries(update)) {
+        console.log(`Update from node ${nodeName}:\n`);
+
+        const messages = updateValue.messages || [];
+        for (const message of messages) {
+          if (isBaseMessage(message)) {
+            const textContent =
+              typeof message.content === "string"
+                ? message.content
+                : JSON.stringify(message.content);
+            console.log(`${message.getType()}: ${textContent}`);
+          }
+        }
+        console.log("\n");
+      }
+    };
+
+    function createHandoffTool({
+      agentName,
+      description,
+    }: {
+      agentName: string;
+      description?: string;
+    }) {
+      const name = `transfer_to_${agentName}`;
+      const toolDescription = description || `Transfer to ${agentName}`;
+
+      return tool(
+        async (_, config) => {
+          // highlight-next-line
+          const state = config.state; // (1)!
+          const toolCallId = config.toolCall.id;
+
+          const toolMessage = {
+            role: "tool" as const,
+            content: `Successfully transferred to ${agentName}`,
+            name: name,
+            tool_call_id: toolCallId,
+          };
+
+          return new Command({
+            // highlight-next-line
+            goto: agentName, // (3)!
+            // highlight-next-line
+            update: { messages: [...state.messages, toolMessage] }, // (4)!
+            // highlight-next-line
+            graph: Command.PARENT, // (5)!
+          });
+        },
+        {
+          name,
+          description: toolDescription,
+          schema: z.object({}),
+        }
+      );
+    }
+
+    // Handoffs
+    const transferToHotelAssistant = createHandoffTool({
+      agentName: "hotel_assistant",
+      description: "Transfer user to the hotel-booking assistant.",
+    });
+
+    const transferToFlightAssistant = createHandoffTool({
+      agentName: "flight_assistant",
+      description: "Transfer user to the flight-booking assistant.",
+    });
+
+    // Simple agent tools
+    const bookHotel = tool(
+      async ({ hotelName }) => {
+        return `Successfully booked a stay at ${hotelName}.`;
+      },
+      {
+        name: "book_hotel",
+        description: "Book a hotel",
+        schema: z.object({
+          hotelName: z.string(),
+        }),
+      }
+    );
+
+    const bookFlight = tool(
+      async ({ fromAirport, toAirport }) => {
+        return `Successfully booked a flight from ${fromAirport} to ${toAirport}.`;
+      },
+      {
+        name: "book_flight",
+        description: "Book a flight",
+        schema: z.object({
+          fromAirport: z.string(),
+          toAirport: z.string(),
+        }),
+      }
+    );
+
+    const model = new ChatAnthropic({
+      model: "claude-3-5-sonnet-latest",
+    });
+
+    // Define agents
+    const flightAssistant = createReactAgent({
+      llm: model,
+      // highlight-next-line
+      tools: [bookFlight, transferToHotelAssistant],
+      prompt: "You are a flight booking assistant",
+      // highlight-next-line
+      name: "flight_assistant",
+    });
+
+    const hotelAssistant = createReactAgent({
+      llm: model,
+      // highlight-next-line
+      tools: [bookHotel, transferToFlightAssistant],
+      prompt: "You are a hotel booking assistant",
+      // highlight-next-line
+      name: "hotel_assistant",
+    });
+
+    // Define multi-agent graph
+    const multiAgentGraph = new StateGraph(MessagesZodState)
+      .addNode("flight_assistant", flightAssistant)
+      .addNode("hotel_assistant", hotelAssistant)
+      .addEdge(START, "flight_assistant")
+      .compile();
+
+    // Run the multi-agent graph
+    const stream = await multiAgentGraph.stream(
+      {
+        messages: [
+          {
+            role: "user",
+            content: "book a flight from BOS to JFK and a stay at McKittrick Hotel",
+          },
+        ],
+      },
+      // highlight-next-line
+      { subgraphs: true }
+    );
+
+    for await (const chunk of stream) {
+      prettyPrintMessages(chunk);
+    }
+    ```
+
+    1. Access agent's state
+    2. The `Command` primitive allows specifying a state update and a node transition as a single operation, making it useful for implementing handoffs.
+    3. Name of the agent or node to hand off to.
+    4. Take the agent's messages and **add** them to the parent's **state** as part of the handoff. The next agent will see the parent state.
+    5. Indicate to LangGraph that we need to navigate to agent node in a **parent** multi-agent graph.
+    :::
 
 ## Multi-turn conversation
 
@@ -333,6 +709,7 @@ The agents can then be implemented as nodes in a graph that executes agent steps
 1. **Wait for user input** to continue the conversation, or  
 2. **Route to another agent** (or back to itself, such as in a loop) via a [handoff](#handoffs)
 
+:::python
 ```python
 def human(state) -> Command[Literal["agent", "another_agent"]]:
     """A node for collecting user input."""
@@ -360,6 +737,44 @@ def agent(state) -> Command[Literal["agent", "another_agent", "human"]]:
     else:
         return Command(goto="human") # Go to human node
 ```
+:::
+
+:::js
+```typescript
+import { interrupt, Command } from "@langchain/langgraph";
+
+function human(state: MessagesState): Command {
+  const userInput: string = interrupt("Ready for user input.");
+
+  // Determine the active agent
+  const activeAgent = /* ... */;
+
+  return new Command({
+    update: {
+      messages: [{
+        role: "human",
+        content: userInput,
+      }]
+    },
+    goto: activeAgent,
+  });
+}
+
+function agent(state: MessagesState): Command {
+  // The condition for routing/halting can be anything, e.g. LLM tool call / structured output, etc.
+  const goto = getNextAgent(/* ... */); // 'agent' / 'anotherAgent'
+
+  if (goto) {
+    return new Command({
+      goto,
+      update: { myStateKey: "myStateValue" }
+    });
+  }
+
+  return new Command({ goto: "human" });
+}
+```
+:::
 
 ??? example "Full example: multi-agent system for travel recommendations"
 
@@ -370,6 +785,7 @@ def agent(state) -> Command[Literal["agent", "another_agent", "human"]]:
     * travel_advisor: can help with travel destination recommendations. Can ask hotel_advisor for help.
     * hotel_advisor: can help with hotel recommendations. Can ask travel_advisor for help.
 
+    :::python
     ```python
     from langchain_anthropic import ChatAnthropic
     from langgraph.graph import MessagesState, StateGraph, START
@@ -571,10 +987,267 @@ def agent(state) -> Command[Literal["agent", "another_agent", "human"]]:
     
     Would you like more specific information about any of these activities or would you like to know about other options in the area?
     ```
+    :::
+
+    :::js
+    ```typescript
+    import { ChatAnthropic } from "@langchain/anthropic";
+    import { StateGraph, START, MessagesZodState, Command, interrupt, MemorySaver } from "@langchain/langgraph";
+    import { createReactAgent } from "@langchain/langgraph/prebuilt";
+    import { tool } from "@langchain/core/tools";
+    import { z } from "zod";
+
+    const model = new ChatAnthropic({ model: "claude-3-5-sonnet-latest" });
+
+    const MultiAgentState = MessagesZodState.extend({
+      lastActiveAgent: z.string().optional(),
+    });
+
+    // Define travel advisor tools
+    const getTravelRecommendations = tool(
+      async () => {
+        // Placeholder implementation
+        return "Based on current trends, I recommend visiting Japan, Portugal, or New Zealand.";
+      },
+      {
+        name: "get_travel_recommendations",
+        description: "Get current travel destination recommendations",
+        schema: z.object({}),
+      }
+    );
+
+    const makeHandoffTool = (agentName: string) => {
+      return tool(
+        async (_, config) => {
+          const state = config.state;
+          const toolCallId = config.toolCall.id;
+
+          const toolMessage = {
+            role: "tool" as const,
+            content: `Successfully transferred to ${agentName}`,
+            name: `transfer_to_${agentName}`,
+            tool_call_id: toolCallId,
+          };
+
+          return new Command({
+            goto: agentName,
+            update: { messages: [...state.messages, toolMessage] },
+            graph: Command.PARENT,
+          });
+        },
+        {
+          name: `transfer_to_${agentName}`,
+          description: `Transfer to ${agentName}`,
+          schema: z.object({}),
+        }
+      );
+    };
+
+    const travelAdvisorTools = [
+      getTravelRecommendations,
+      makeHandoffTool("hotel_advisor"),
+    ];
+
+    const travelAdvisor = createReactAgent({
+      llm: model,
+      tools: travelAdvisorTools,
+      prompt: [
+        "You are a general travel expert that can recommend travel destinations (e.g. countries, cities, etc). ",
+        "If you need hotel recommendations, ask 'hotel_advisor' for help. ",
+        "You MUST include human-readable response before transferring to another agent."
+      ].join("")
+    });
+
+    const callTravelAdvisor = async (
+      state: z.infer<typeof MultiAgentState>
+    ): Promise<Command> => {
+      const response = await travelAdvisor.invoke(state);
+      const update = { ...response, lastActiveAgent: "travel_advisor" };
+      return new Command({ update, goto: "human" });
+    };
+
+    // Define hotel advisor tools
+    const getHotelRecommendations = tool(
+      async () => {
+        // Placeholder implementation
+        return "I recommend the Ritz-Carlton for luxury stays or boutique hotels for unique experiences.";
+      },
+      {
+        name: "get_hotel_recommendations",
+        description: "Get hotel recommendations for destinations",
+        schema: z.object({}),
+      }
+    );
+
+    const hotelAdvisorTools = [
+      getHotelRecommendations,
+      makeHandoffTool("travel_advisor"),
+    ];
+
+    const hotelAdvisor = createReactAgent({
+      llm: model,
+      tools: hotelAdvisorTools,
+      prompt: [
+        "You are a hotel expert that can provide hotel recommendations for a given destination. ",
+        "If you need help picking travel destinations, ask 'travel_advisor' for help.",
+        "You MUST include human-readable response before transferring to another agent."
+      ].join("")
+    });
+
+    const callHotelAdvisor = async (
+      state: z.infer<typeof MultiAgentState>
+    ): Promise<Command> => {
+      const response = await hotelAdvisor.invoke(state);
+      const update = { ...response, lastActiveAgent: "hotel_advisor" };
+      return new Command({ update, goto: "human" });
+    };
+
+    const humanNode = async (
+      state: z.infer<typeof MultiAgentState>
+    ): Promise<Command> => {
+      const userInput: string = interrupt("Ready for user input.");
+      const activeAgent = state.lastActiveAgent || "travel_advisor";
+
+      return new Command({
+        update: {
+          messages: [
+            {
+              role: "human",
+              content: userInput,
+            }
+          ]
+        },
+        goto: activeAgent,
+      });
+    };
+
+    const builder = new StateGraph(MultiAgentState)
+      .addNode("travel_advisor", callTravelAdvisor)
+      .addNode("hotel_advisor", callHotelAdvisor)
+      .addNode("human", humanNode)
+      .addEdge(START, "travel_advisor");
+
+    const checkpointer = new MemorySaver();
+    const graph = builder.compile({ checkpointer });
+    ```
+    
+    Let's test a multi turn conversation with this application.
+
+    ```typescript
+    import { v4 as uuidv4 } from "uuid";
+    import { Command } from "@langchain/langgraph";
+
+    const threadConfig = { configurable: { thread_id: uuidv4() } };
+
+    const inputs = [
+      // 1st round of conversation
+      {
+        messages: [
+          { role: "user", content: "i wanna go somewhere warm in the caribbean" }
+        ]
+      },
+      // Since we're using `interrupt`, we'll need to resume using the Command primitive.
+      // 2nd round of conversation
+      new Command({
+        resume: "could you recommend a nice hotel in one of the areas and tell me which area it is."
+      }),
+      // 3rd round of conversation
+      new Command({
+        resume: "i like the first one. could you recommend something to do near the hotel?"
+      }),
+    ];
+
+    for (const [idx, userInput] of inputs.entries()) {
+      console.log();
+      console.log(`--- Conversation Turn ${idx + 1} ---`);
+      console.log();
+      console.log(`User: ${JSON.stringify(userInput)}`);
+      console.log();
+      
+      for await (const update of await graph.stream(
+        userInput,
+        { ...threadConfig, streamMode: "updates" }
+      )) {
+        for (const [nodeId, value] of Object.entries(update)) {
+          if (value?.messages?.length) {
+            const lastMessage = value.messages.at(-1);
+            if (lastMessage?.getType?.() === "ai") {
+              console.log(`${nodeId}: ${lastMessage.content}`);
+            }
+          }
+        }
+      }
+    }
+    ```
+    
+    ```
+    --- Conversation Turn 1 ---
+    
+    User: {"messages":[{"role":"user","content":"i wanna go somewhere warm in the caribbean"}]}
+    
+    travel_advisor: Based on the recommendations, Aruba would be an excellent choice for your Caribbean getaway! Aruba is known as "One Happy Island" and offers:
+    - Year-round warm weather with consistent temperatures around 82°F (28°C)
+    - Beautiful white sand beaches like Eagle Beach and Palm Beach
+    - Clear turquoise waters perfect for swimming and snorkeling
+    - Minimal rainfall and location outside the hurricane belt
+    - A blend of Caribbean and Dutch culture
+    - Great dining options and nightlife
+    - Various water sports and activities
+    
+    Would you like me to get some specific hotel recommendations in Aruba for your stay? I can transfer you to our hotel advisor who can help with accommodations.
+    
+    --- Conversation Turn 2 ---
+    
+    User: Command { resume: 'could you recommend a nice hotel in one of the areas and tell me which area it is.' }
+    
+    hotel_advisor: Based on the recommendations, I can suggest two excellent options:
+    
+    1. The Ritz-Carlton, Aruba - Located in Palm Beach
+    - This luxury resort is situated in the vibrant Palm Beach area
+    - Known for its exceptional service and amenities
+    - Perfect if you want to be close to dining, shopping, and entertainment
+    - Features multiple restaurants, a casino, and a world-class spa
+    - Located on a pristine stretch of Palm Beach
+    
+    2. Bucuti & Tara Beach Resort - Located in Eagle Beach
+    - An adults-only boutique resort on Eagle Beach
+    - Known for being more intimate and peaceful
+    - Award-winning for its sustainability practices
+    - Perfect for a romantic getaway or peaceful vacation
+    - Located on one of the most beautiful beaches in the Caribbean
+    
+    Would you like more specific information about either of these properties or their locations?
+    
+    --- Conversation Turn 3 ---
+    
+    User: Command { resume: 'i like the first one. could you recommend something to do near the hotel?' }
+    
+    travel_advisor: Near the Ritz-Carlton in Palm Beach, here are some highly recommended activities:
+    
+    1. Visit the Palm Beach Plaza Mall - Just a short walk from the hotel, featuring shopping, dining, and entertainment
+    2. Try your luck at the Stellaris Casino - It's right in the Ritz-Carlton
+    3. Take a sunset sailing cruise - Many depart from the nearby pier
+    4. Visit the California Lighthouse - A scenic landmark just north of Palm Beach
+    5. Enjoy water sports at Palm Beach:
+       - Jet skiing
+       - Parasailing
+       - Snorkeling
+       - Stand-up paddleboarding
+    
+    Would you like more specific information about any of these activities or would you like to know about other options in the area?
+    ```
+    :::
 
 ## Prebuilt implementations
 
 LangGraph comes with prebuilt implementations of two of the most popular multi-agent architectures:
 
+:::python
 - [supervisor](../agents/multi-agent.md#supervisor) — individual agents are coordinated by a central supervisor agent. The supervisor controls all communication flow and task delegation, making decisions about which agent to invoke based on the current context and task requirements. You can use [`langgraph-supervisor`](https://github.com/langchain-ai/langgraph-supervisor-py) library to create a supervisor multi-agent systems.
-- [swarm](../agents/multi-agent.md#supervisor) — agents dynamically hand off control to one another based on their specializations. The system remembers which agent was last active, ensuring that on subsequent interactions, the conversation resumes with that agent. You can use [`langgraph-swarm`](https://github.com/langchain-ai/langgraph-swarm-py) library to create a swarm multi-agent systems. 
+- [swarm](../agents/multi-agent.md#supervisor) — agents dynamically hand off control to one another based on their specializations. The system remembers which agent was last active, ensuring that on subsequent interactions, the conversation resumes with that agent. You can use [`langgraph-swarm`](https://github.com/langchain-ai/langgraph-swarm-py) library to create a swarm multi-agent systems.
+:::
+
+:::js
+- [supervisor](../agents/multi-agent.md#supervisor) — individual agents are coordinated by a central supervisor agent. The supervisor controls all communication flow and task delegation, making decisions about which agent to invoke based on the current context and task requirements. You can use [`langgraph-supervisor`](https://github.com/langchain-ai/langgraph-supervisor-js) library to create a supervisor multi-agent systems.
+- [swarm](../agents/multi-agent.md#supervisor) — agents dynamically hand off control to one another based on their specializations. The system remembers which agent was last active, ensuring that on subsequent interactions, the conversation resumes with that agent. You can use [`langgraph-swarm`](https://github.com/langchain-ai/langgraph-swarm-js) library to create a swarm multi-agent systems.
+:::

docs/docs/how-tos/subgraph.md

@@ -9,11 +9,20 @@ When adding subgraphs, you need to define how the parent graph and the subgraph
 
 ## Setup
 
+:::python
 ```bash
 pip install -U langgraph
 ```
+:::
+
+:::js
+```bash
+npm install @langchain/langgraph
+```
+:::
 
 !!! tip "Set up LangSmith for LangGraph development"
+
     Sign up for [LangSmith](https://smith.langchain.com) to quickly spot issues and improve the performance of your LangGraph projects. LangSmith lets you use trace data to debug, test, and monitor your LLM apps built with LangGraph — read more about how to get started [here](https://docs.smith.langchain.com).
 
 ## Shared state schemas
@@ -22,6 +31,7 @@ A common case is for the parent graph and subgraph to communicate over a shared
 
 If your subgraph shares state keys with the parent graph, you can follow these steps to add it to your graph:
 
+:::python
 1. Define the subgraph workflow (`subgraph_builder` in the example below) and compile it
 2. Pass compiled subgraph to the `.add_node` method when defining the parent graph workflow
 
@@ -49,9 +59,41 @@ builder.add_node("node_1", subgraph)
 builder.add_edge(START, "node_1")
 graph = builder.compile()
 ```
+:::
+
+:::js
+1. Define the subgraph workflow (`subgraphBuilder` in the example below) and compile it
+2. Pass compiled subgraph to the `.addNode` method when defining the parent graph workflow
+
+```typescript
+import { StateGraph, START } from "@langchain/langgraph";
+import { z } from "zod";
+
+const State = z.object({
+  foo: z.string(),
+});
+
+// Subgraph
+const subgraphBuilder = new StateGraph(State)
+  .addNode("subgraphNode1", (state) => {
+    return { foo: "hi! " + state.foo };
+  })
+  .addEdge(START, "subgraphNode1");
+
+const subgraph = subgraphBuilder.compile();
+
+// Parent graph
+const builder = new StateGraph(State)
+  .addNode("node1", subgraph)
+  .addEdge(START, "node1");
+
+const graph = builder.compile();
+```
+:::
 
 ??? example "Full example: shared state schemas"
 
+    :::python
     ```python
     from typing_extensions import TypedDict
     from langgraph.graph.state import StateGraph, START
@@ -101,6 +143,61 @@ graph = builder.compile()
     {'node_1': {'foo': 'hi! foo'}}
     {'node_2': {'foo': 'hi! foobar'}}
     ```
+    :::
+
+    :::js
+    ```typescript
+    import { StateGraph, START } from "@langchain/langgraph";
+    import { z } from "zod";
+
+    // Define subgraph
+    const SubgraphState = z.object({
+      foo: z.string(),  // (1)! 
+      bar: z.string(),  // (2)!
+    });
+    
+    const subgraphBuilder = new StateGraph(SubgraphState)
+      .addNode("subgraphNode1", (state) => {
+        return { bar: "bar" };
+      })
+      .addNode("subgraphNode2", (state) => {
+        // note that this node is using a state key ('bar') that is only available in the subgraph
+        // and is sending update on the shared state key ('foo')
+        return { foo: state.foo + state.bar };
+      })
+      .addEdge(START, "subgraphNode1")
+      .addEdge("subgraphNode1", "subgraphNode2");
+    
+    const subgraph = subgraphBuilder.compile();
+    
+    // Define parent graph
+    const ParentState = z.object({
+      foo: z.string(),
+    });
+    
+    const builder = new StateGraph(ParentState)
+      .addNode("node1", (state) => {
+        return { foo: "hi! " + state.foo };
+      })
+      .addNode("node2", subgraph)
+      .addEdge(START, "node1")
+      .addEdge("node1", "node2");
+    
+    const graph = builder.compile();
+    
+    for await (const chunk of await graph.stream({ foo: "foo" })) {
+      console.log(chunk);
+    }
+    ```
+
+    3. This key is shared with the parent graph state
+    4. This key is private to the `SubgraphState` and is not visible to the parent graph
+    
+    ```
+    { node1: { foo: 'hi! foo' } }
+    { node2: { foo: 'hi! foobar' } }
+    ```
+    :::
 
 ## Different state schemas
 
@@ -108,6 +205,7 @@ For more complex systems you might want to define subgraphs that have a **comple
 
 If that's the case for your application, you need to define a node **function that invokes the subgraph**. This function needs to transform the input (parent) state to the subgraph state before invoking the subgraph, and transform the results back to the parent state before returning the state update from the node.
 
+:::python
 ```python
 from typing_extensions import TypedDict
 from langgraph.graph.state import StateGraph, START
@@ -142,9 +240,48 @@ graph = builder.compile()
 
 1. Transform the state to the subgraph state
 2. Transform response back to the parent state
+:::
+
+:::js
+```typescript
+import { StateGraph, START } from "@langchain/langgraph";
+import { z } from "zod";
+
+const SubgraphState = z.object({
+  bar: z.string(),
+});
+
+// Subgraph
+const subgraphBuilder = new StateGraph(SubgraphState)
+  .addNode("subgraphNode1", (state) => {
+    return { bar: "hi! " + state.bar };
+  })
+  .addEdge(START, "subgraphNode1");
+
+const subgraph = subgraphBuilder.compile();
+
+// Parent graph
+const State = z.object({
+  foo: z.string(),
+});
+
+const builder = new StateGraph(State)
+  .addNode("node1", async (state) => {
+    const subgraphOutput = await subgraph.invoke({ bar: state.foo }); // (1)!
+    return { foo: subgraphOutput.bar }; // (2)!
+  })
+  .addEdge(START, "node1");
+
+const graph = builder.compile();
+```
+
+1. Transform the state to the subgraph state
+2. Transform response back to the parent state
+:::
 
 ??? example "Full example: different state schemas"
 
+    :::python
     ```python
     from typing_extensions import TypedDict
     from langgraph.graph.state import StateGraph, START
@@ -200,11 +337,74 @@ graph = builder.compile()
     (('node_2:9c36dd0f-151a-cb42-cbad-fa2f851f9ab7',), {'grandchild_2': {'bar': 'hi! foobaz'}})
     ((), {'node_2': {'foo': 'hi! foobaz'}})
     ```
+    :::
+
+    :::js
+    ```typescript
+    import { StateGraph, START } from "@langchain/langgraph";
+    import { z } from "zod";
+
+    // Define subgraph
+    const SubgraphState = z.object({
+      // note that none of these keys are shared with the parent graph state
+      bar: z.string(),
+      baz: z.string(),
+    });
+    
+    const subgraphBuilder = new StateGraph(SubgraphState)
+      .addNode("subgraphNode1", (state) => {
+        return { baz: "baz" };
+      })
+      .addNode("subgraphNode2", (state) => {
+        return { bar: state.bar + state.baz };
+      })
+      .addEdge(START, "subgraphNode1")
+      .addEdge("subgraphNode1", "subgraphNode2");
+    
+    const subgraph = subgraphBuilder.compile();
+    
+    // Define parent graph
+    const ParentState = z.object({
+      foo: z.string(),
+    });
+    
+    const builder = new StateGraph(ParentState)
+      .addNode("node1", (state) => {
+        return { foo: "hi! " + state.foo };
+      })
+      .addNode("node2", async (state) => {
+        const response = await subgraph.invoke({ bar: state.foo }); // (1)!
+        return { foo: response.bar }; // (2)!
+      })
+      .addEdge(START, "node1")
+      .addEdge("node1", "node2");
+    
+    const graph = builder.compile();
+    
+    for await (const chunk of await graph.stream(
+      { foo: "foo" }, 
+      { subgraphs: true }
+    )) {
+      console.log(chunk);
+    }
+    ```
+
+    3. Transform the state to the subgraph state
+    4. Transform response back to the parent state
+
+    ```
+    [[], { node1: { foo: 'hi! foo' } }]
+    [['node2:9c36dd0f-151a-cb42-cbad-fa2f851f9ab7'], { subgraphNode1: { baz: 'baz' } }]
+    [['node2:9c36dd0f-151a-cb42-cbad-fa2f851f9ab7'], { subgraphNode2: { bar: 'hi! foobaz' } }]
+    [[], { node2: { foo: 'hi! foobaz' } }]
+    ```
+    :::
 
 ??? example "Full example: different state schemas (two levels of subgraphs)"
 
     This is an example with two levels of subgraphs: parent -> child -> grandchild.
 
+    :::python
     ```python
     # Grandchild graph
     from typing_extensions import TypedDict
@@ -288,14 +488,102 @@ graph = builder.compile()
     ((), {'child': {'my_key': 'hi Bob, how are you today?'}})
     ((), {'parent_2': {'my_key': 'hi Bob, how are you today? bye!'}})
     ```
+    :::
+
+    :::js
+    ```typescript
+    import { StateGraph, START, END } from "@langchain/langgraph";
+    import { z } from "zod";
+
+    // Grandchild graph
+    const GrandChildState = z.object({
+      myGrandchildKey: z.string(),
+    });
+    
+    const grandchild = new StateGraph(GrandChildState)
+      .addNode("grandchild1", (state) => {
+        // NOTE: child or parent keys will not be accessible here
+        return { myGrandchildKey: state.myGrandchildKey + ", how are you" };
+      })
+      .addEdge(START, "grandchild1")
+      .addEdge("grandchild1", END);
+    
+    const grandchildGraph = grandchild.compile();
+    
+    // Child graph
+    const ChildState = z.object({
+      myChildKey: z.string(),
+    });
+    
+    const child = new StateGraph(ChildState)
+      .addNode("child1", async (state) => {
+        // NOTE: parent or grandchild keys won't be accessible here
+        const grandchildGraphInput = { myGrandchildKey: state.myChildKey }; // (1)!
+        const grandchildGraphOutput = await grandchildGraph.invoke(grandchildGraphInput);
+        return { myChildKey: grandchildGraphOutput.myGrandchildKey + " today?" }; // (2)!
+      }) // (3)!
+      .addEdge(START, "child1")
+      .addEdge("child1", END);
+    
+    const childGraph = child.compile();
+    
+    // Parent graph
+    const ParentState = z.object({
+      myKey: z.string(),
+    });
+    
+    const parent = new StateGraph(ParentState)
+      .addNode("parent1", (state) => {
+        // NOTE: child or grandchild keys won't be accessible here
+        return { myKey: "hi " + state.myKey };
+      })
+      .addNode("child", async (state) => {
+        const childGraphInput = { myChildKey: state.myKey }; // (4)!
+        const childGraphOutput = await childGraph.invoke(childGraphInput);
+        return { myKey: childGraphOutput.myChildKey }; // (5)!
+      }) // (6)!
+      .addNode("parent2", (state) => {
+        return { myKey: state.myKey + " bye!" };
+      })
+      .addEdge(START, "parent1")
+      .addEdge("parent1", "child")
+      .addEdge("child", "parent2")
+      .addEdge("parent2", END);
+    
+    const parentGraph = parent.compile();
+    
+    for await (const chunk of await parentGraph.stream(
+      { myKey: "Bob" }, 
+      { subgraphs: true }
+    )) {
+      console.log(chunk);
+    }
+    ```
+
+    7. We're transforming the state from the child state channels (`myChildKey`) to the grandchild state channels (`myGrandchildKey`)
+    8. We're transforming the state from the grandchild state channels (`myGrandchildKey`) back to the child state channels (`myChildKey`)
+    9. We're passing a function here instead of just compiled graph (`grandchildGraph`)
+    10. We're transforming the state from the parent state channels (`myKey`) to the child state channels (`myChildKey`)
+    11. We're transforming the state from the child state channels (`myChildKey`) back to the parent state channels (`myKey`)
+    12. We're passing a function here instead of just a compiled graph (`childGraph`)
+
+    ```
+    [[], { parent1: { myKey: 'hi Bob' } }]
+    [['child:2e26e9ce-602f-862c-aa66-1ea5a4655e3b', 'child1:781bb3b1-3971-84ce-810b-acf819a03f9c'], { grandchild1: { myGrandchildKey: 'hi Bob, how are you' } }]
+    [['child:2e26e9ce-602f-862c-aa66-1ea5a4655e3b'], { child1: { myChildKey: 'hi Bob, how are you today?' } }]
+    [[], { child: { myKey: 'hi Bob, how are you today?' } }]
+    [[], { parent2: { myKey: 'hi Bob, how are you today? bye!' } }]
+    ```
+    :::
 
 ## Add persistence 
 
 You only need to **provide the checkpointer when compiling the parent graph**. LangGraph will automatically propagate the checkpointer to the child subgraphs.
 
+:::python
 ```python
 from langgraph.graph import START, StateGraph
-from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.checkpoint.memory import MemorySaver
 from typing_extensions import TypedDict
 
 class State(TypedDict):
@@ -317,20 +605,66 @@ builder = StateGraph(State)
 builder.add_node("node_1", subgraph)
 builder.add_edge(START, "node_1")
 
-checkpointer = InMemorySaver()
+checkpointer = MemorySaver()
 graph = builder.compile(checkpointer=checkpointer)
 ```    
+:::
 
-If you want the subgraph to **have its own memory**, you can compile it `with checkpointer=True`. This is useful in [multi-agent](../concepts/multi_agent.md) systems, if you want agents to keep track of their internal message histories:
+:::js
+```typescript
+import { StateGraph, START, MemorySaver } from "@langchain/langgraph";
+import { z } from "zod";
 
+const State = z.object({
+  foo: z.string(),
+});
+
+// Subgraph
+const subgraphBuilder = new StateGraph(State)
+  .addNode("subgraphNode1", (state) => {
+    return { foo: state.foo + "bar" };
+  })
+  .addEdge(START, "subgraphNode1");
+
+const subgraph = subgraphBuilder.compile();
+
+// Parent graph
+const builder = new StateGraph(State)
+  .addNode("node1", subgraph)
+  .addEdge(START, "node1");
+
+const checkpointer = new MemorySaver();
+const graph = builder.compile({ checkpointer });
+```    
+:::
+
+If you want the subgraph to **have its own memory**, you can compile it with the appropriate checkpointer option. This is useful in [multi-agent](../concepts/multi_agent.md) systems, if you want agents to keep track of their internal message histories:
+
+:::python
 ```python
 subgraph_builder = StateGraph(...)
 subgraph = subgraph_builder.compile(checkpointer=True)
 ```
+:::
+
+:::js
+```typescript
+const subgraphBuilder = new StateGraph(...)
+const subgraph = subgraphBuilder.compile({ checkpointer: true });
+```
+:::
 
 ## View subgraph state
 
-When you enable [persistence](../concepts/persistence.md), you can [inspect the graph state](../concepts/persistence.md#checkpoints) (checkpoint) via `graph.get_state(config)`. To view the subgraph state, you can use `graph.get_state(config, subgraphs=True)`.
+When you enable [persistence](../concepts/persistence.md), you can [inspect the graph state](../concepts/persistence.md#checkpoints) (checkpoint) via the appropriate method. To view the subgraph state, you can use the subgraphs option.
+
+:::python
+You can inspect the graph state via `graph.get_state(config)`. To view the subgraph state, you can use `graph.get_state(config, subgraphs=True)`.
+:::
+
+:::js
+You can inspect the graph state via `graph.getState(config)`. To view the subgraph state, you can use `graph.getState(config, { subgraphs: true })`.
+:::
 
 !!! important "Available **only** when interrupted"
 
@@ -338,9 +672,10 @@ When you enable [persistence](../concepts/persistence.md), you can [inspect the
 
 ??? example "View interrupted subgraph state"
 
+    :::python
     ```python
     from langgraph.graph import START, StateGraph
-    from langgraph.checkpoint.memory import InMemorySaver
+    from langgraph.checkpoint.memory import MemorySaver
     from langgraph.types import interrupt, Command
     from typing_extensions import TypedDict
     
@@ -365,7 +700,7 @@ When you enable [persistence](../concepts/persistence.md), you can [inspect the
     builder.add_node("node_1", subgraph)
     builder.add_edge(START, "node_1")
     
-    checkpointer = InMemorySaver()
+    checkpointer = MemorySaver()
     graph = builder.compile(checkpointer=checkpointer)
     
     config = {"configurable": {"thread_id": "1"}}
@@ -379,11 +714,53 @@ When you enable [persistence](../concepts/persistence.md), you can [inspect the
     ```
     
     1. This will be available only when the subgraph is interrupted. Once you resume the graph, you won't be able to access the subgraph state.
+    :::
+
+    :::js
+    ```typescript
+    import { StateGraph, START, MemorySaver, interrupt, Command } from "@langchain/langgraph";
+    import { z } from "zod";
+    
+    const State = z.object({
+      foo: z.string(),
+    });
+    
+    // Subgraph
+    const subgraphBuilder = new StateGraph(State)
+      .addNode("subgraphNode1", (state) => {
+        const value = interrupt("Provide value:");
+        return { foo: state.foo + value };
+      })
+      .addEdge(START, "subgraphNode1");
+    
+    const subgraph = subgraphBuilder.compile();
+    
+    // Parent graph
+    const builder = new StateGraph(State)
+      .addNode("node1", subgraph)
+      .addEdge(START, "node1");
+    
+    const checkpointer = new MemorySaver();
+    const graph = builder.compile({ checkpointer });
+    
+    const config = { configurable: { thread_id: "1" } };
+    
+    await graph.invoke({ foo: "" }, config);
+    const parentState = await graph.getState(config);
+    const subgraphState = (await graph.getState(config, { subgraphs: true })).tasks[0].state; // (1)!
+    
+    // resume the subgraph
+    await graph.invoke(new Command({ resume: "bar" }), config);
+    ```
+    
+    2. This will be available only when the subgraph is interrupted. Once you resume the graph, you won't be able to access the subgraph state.
+    :::
 
 ## Stream subgraph outputs
 
-To include outputs from subgraphs in the streamed outputs, you can set `subgraphs=True` in the `.stream()` method of the parent graph. This will stream outputs from both the parent graph and any subgraphs.
+To include outputs from subgraphs in the streamed outputs, you can set the subgraphs option in the stream method of the parent graph. This will stream outputs from both the parent graph and any subgraphs.
 
+:::python
 ```python
 for chunk in graph.stream(
     {"foo": "foo"},
@@ -394,9 +771,27 @@ for chunk in graph.stream(
 ```
 
 1. Set `subgraphs=True` to stream outputs from subgraphs.
+:::
+
+:::js
+```typescript
+for await (const chunk of await graph.stream(
+  { foo: "foo" },
+  {
+    subgraphs: true, // (1)!
+    streamMode: "updates",
+  }
+)) {
+  console.log(chunk);
+}
+```
+
+1. Set `subgraphs: true` to stream outputs from subgraphs.
+:::
 
 ??? example "Stream from subgraphs"
 
+    :::python
     ```python
     from typing_extensions import TypedDict
     from langgraph.graph.state import StateGraph, START
@@ -450,4 +845,66 @@ for chunk in graph.stream(
     (('node_2:e58e5673-a661-ebb0-70d4-e298a7fc28b7',), {'subgraph_node_1': {'bar': 'bar'}})
     (('node_2:e58e5673-a661-ebb0-70d4-e298a7fc28b7',), {'subgraph_node_2': {'foo': 'hi! foobar'}})
     ((), {'node_2': {'foo': 'hi! foobar'}})
-    
+    ```
+    :::
+
+    :::js
+    ```typescript
+    import { StateGraph, START } from "@langchain/langgraph";
+    import { z } from "zod";
+
+    // Define subgraph
+    const SubgraphState = z.object({
+      foo: z.string(),
+      bar: z.string(),
+    });
+    
+    const subgraphBuilder = new StateGraph(SubgraphState)
+      .addNode("subgraphNode1", (state) => {
+        return { bar: "bar" };
+      })
+      .addNode("subgraphNode2", (state) => {
+        // note that this node is using a state key ('bar') that is only available in the subgraph
+        // and is sending update on the shared state key ('foo')
+        return { foo: state.foo + state.bar };
+      })
+      .addEdge(START, "subgraphNode1")
+      .addEdge("subgraphNode1", "subgraphNode2");
+    
+    const subgraph = subgraphBuilder.compile();
+    
+    // Define parent graph
+    const ParentState = z.object({
+      foo: z.string(),
+    });
+    
+    const builder = new StateGraph(ParentState)
+      .addNode("node1", (state) => {
+        return { foo: "hi! " + state.foo };
+      })
+      .addNode("node2", subgraph)
+      .addEdge(START, "node1")
+      .addEdge("node1", "node2");
+    
+    const graph = builder.compile();
+
+    for await (const chunk of await graph.stream(
+      { foo: "foo" },
+      {
+        streamMode: "updates",
+        subgraphs: true, // (1)!
+      }
+    )) {
+      console.log(chunk);
+    }
+    ```
+  
+    2. Set `subgraphs: true` to stream outputs from subgraphs.
+
+    ```
+    [[], { node1: { foo: 'hi! foo' } }]
+    [['node2:e58e5673-a661-ebb0-70d4-e298a7fc28b7'], { subgraphNode1: { bar: 'bar' } }]
+    [['node2:e58e5673-a661-ebb0-70d4-e298a7fc28b7'], { subgraphNode2: { foo: 'hi! foobar' } }]
+    [[], { node2: { foo: 'hi! foobar' } }]
+    ```
+    :::

libs/checkpoint-postgres/uv.lock

@@ -329,6 +329,7 @@ dev = [
     { name = "pytest-asyncio" },
     { name = "pytest-mock" },
     { name = "pytest-watcher" },
+    { name = "redis" },
     { name = "ruff" },
 ]
 

libs/checkpoint-sqlite/uv.lock

@@ -341,6 +341,7 @@ dev = [
     { name = "pytest-asyncio" },
     { name = "pytest-mock" },
     { name = "pytest-watcher" },
+    { name = "redis" },
     { name = "ruff" },
 ]
 

libs/checkpoint/langgraph/cache/redis/__init__.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from langgraph.cache.base import BaseCache, FullKey, Namespace, ValueT
+from langgraph.checkpoint.serde.base import SerializerProtocol
+
+
+class RedisCache(BaseCache[ValueT]):
+    """Redis-based cache implementation with TTL support."""
+
+    def __init__(
+        self,
+        redis: Any,
+        *,
+        serde: SerializerProtocol | None = None,
+        prefix: str = "langgraph:cache:",
+    ) -> None:
+        """Initialize the cache with a Redis client.
+
+        Args:
+            redis: Redis client instance (sync or async)
+            serde: Serializer to use for values
+            prefix: Key prefix for all cached values
+        """
+        super().__init__(serde=serde)
+        self.redis = redis
+        self.prefix = prefix
+
+    def _make_key(self, ns: Namespace, key: str) -> str:
+        """Create a Redis key from namespace and key."""
+        ns_str = ":".join(ns) if ns else ""
+        return f"{self.prefix}{ns_str}:{key}" if ns_str else f"{self.prefix}{key}"
+
+    def _parse_key(self, redis_key: str) -> tuple[Namespace, str]:
+        """Parse a Redis key back to namespace and key."""
+        if not redis_key.startswith(self.prefix):
+            raise ValueError(
+                f"Key {redis_key} does not start with prefix {self.prefix}"
+            )
+
+        remaining = redis_key[len(self.prefix) :]
+        if ":" in remaining:
+            parts = remaining.split(":")
+            key = parts[-1]
+            ns_parts = parts[:-1]
+            return (tuple(ns_parts), key)
+        else:
+            return (tuple(), remaining)
+
+    def get(self, keys: Sequence[FullKey]) -> dict[FullKey, ValueT]:
+        """Get the cached values for the given keys."""
+        if not keys:
+            return {}
+
+        # Build Redis keys
+        redis_keys = [self._make_key(ns, key) for ns, key in keys]
+
+        # Get values from Redis using MGET
+        try:
+            raw_values = self.redis.mget(redis_keys)
+        except Exception:
+            # If Redis is unavailable, return empty dict
+            return {}
+
+        values: dict[FullKey, ValueT] = {}
+        for i, raw_value in enumerate(raw_values):
+            if raw_value is not None:
+                try:
+                    # Deserialize the value
+                    encoding, data = raw_value.split(b":", 1)
+                    values[keys[i]] = self.serde.loads_typed((encoding.decode(), data))
+                except Exception:
+                    # Skip corrupted entries
+                    continue
+
+        return values
+
+    async def aget(self, keys: Sequence[FullKey]) -> dict[FullKey, ValueT]:
+        """Asynchronously get the cached values for the given keys."""
+        return self.get(keys)
+
+    def set(self, mapping: Mapping[FullKey, tuple[ValueT, int | None]]) -> None:
+        """Set the cached values for the given keys and TTLs."""
+        if not mapping:
+            return
+
+        # Use pipeline for efficient batch operations
+        pipe = self.redis.pipeline()
+
+        for (ns, key), (value, ttl) in mapping.items():
+            redis_key = self._make_key(ns, key)
+            encoding, data = self.serde.dumps_typed(value)
+
+            # Store as "encoding:data" format
+            serialized_value = f"{encoding}:".encode() + data
+
+            if ttl is not None:
+                pipe.setex(redis_key, ttl, serialized_value)
+            else:
+                pipe.set(redis_key, serialized_value)
+
+        try:
+            pipe.execute()
+        except Exception:
+            # Silently fail if Redis is unavailable
+            pass
+
+    async def aset(self, mapping: Mapping[FullKey, tuple[ValueT, int | None]]) -> None:
+        """Asynchronously set the cached values for the given keys and TTLs."""
+        self.set(mapping)
+
+    def clear(self, namespaces: Sequence[Namespace] | None = None) -> None:
+        """Delete the cached values for the given namespaces.
+        If no namespaces are provided, clear all cached values."""
+        try:
+            if namespaces is None:
+                # Clear all keys with our prefix
+                pattern = f"{self.prefix}*"
+                keys = self.redis.keys(pattern)
+                if keys:
+                    self.redis.delete(*keys)
+            else:
+                # Clear specific namespaces
+                keys_to_delete = []
+                for ns in namespaces:
+                    ns_str = ":".join(ns) if ns else ""
+                    pattern = (
+                        f"{self.prefix}{ns_str}:*" if ns_str else f"{self.prefix}*"
+                    )
+                    keys = self.redis.keys(pattern)
+                    keys_to_delete.extend(keys)
+
+                if keys_to_delete:
+                    self.redis.delete(*keys_to_delete)
+        except Exception:
+            # Silently fail if Redis is unavailable
+            pass
+
+    async def aclear(self, namespaces: Sequence[Namespace] | None = None) -> None:
+        """Asynchronously delete the cached values for the given namespaces.
+        If no namespaces are provided, clear all cached values."""
+        self.clear(namespaces)

libs/checkpoint/pyproject.toml

@@ -32,6 +32,7 @@ dev = [
   "numpy",
   "pandas",
   "pandas-stubs>=2.2.2.240807",
+  "redis",
 ]
 
 [tool.hatch.build.targets.wheel]

libs/checkpoint/tests/test_redis_cache.py

@@ -0,0 +1,313 @@
+"""Unit tests for Redis cache implementation."""
+
+import time
+
+import pytest
+import redis
+
+from langgraph.cache.redis import RedisCache
+
+
+class TestRedisCache:
+    @pytest.fixture(autouse=True)
+    def setup(self):
+        """Set up test Redis client and cache."""
+        self.client = redis.Redis(
+            host="localhost", port=6379, db=0, decode_responses=False
+        )
+        try:
+            self.client.ping()
+        except redis.ConnectionError:
+            pytest.skip("Redis server not available")
+
+        self.cache = RedisCache(self.client, prefix="test:cache:")
+
+        # Clean up before each test
+        self.client.flushdb()
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        try:
+            self.client.flushdb()
+        except Exception:
+            pass
+
+    def test_basic_set_and_get(self):
+        """Test basic set and get operations."""
+        keys = [(("graph", "node"), "key1")]
+        values = {keys[0]: ({"result": 42}, None)}
+
+        # Set value
+        self.cache.set(values)
+
+        # Get value
+        result = self.cache.get(keys)
+        assert len(result) == 1
+        assert result[keys[0]] == {"result": 42}
+
+    def test_batch_operations(self):
+        """Test batch set and get operations."""
+        keys = [
+            (("graph", "node1"), "key1"),
+            (("graph", "node2"), "key2"),
+            (("other", "node"), "key3"),
+        ]
+        values = {
+            keys[0]: ({"result": 1}, None),
+            keys[1]: ({"result": 2}, 60),  # With TTL
+            keys[2]: ({"result": 3}, None),
+        }
+
+        # Set values
+        self.cache.set(values)
+
+        # Get all values
+        result = self.cache.get(keys)
+        assert len(result) == 3
+        assert result[keys[0]] == {"result": 1}
+        assert result[keys[1]] == {"result": 2}
+        assert result[keys[2]] == {"result": 3}
+
+    def test_ttl_behavior(self):
+        """Test TTL (time-to-live) functionality."""
+        key = (("graph", "node"), "ttl_key")
+        values = {key: ({"data": "expires_soon"}, 1)}  # 1 second TTL
+
+        # Set with TTL
+        self.cache.set(values)
+
+        # Should be available immediately
+        result = self.cache.get([key])
+        assert len(result) == 1
+        assert result[key] == {"data": "expires_soon"}
+
+        # Wait for expiration
+        time.sleep(1.1)
+
+        # Should be expired
+        result = self.cache.get([key])
+        assert len(result) == 0
+
+    def test_namespace_isolation(self):
+        """Test that different namespaces are isolated."""
+        key1 = (("graph1", "node"), "same_key")
+        key2 = (("graph2", "node"), "same_key")
+
+        values = {key1: ({"graph": 1}, None), key2: ({"graph": 2}, None)}
+
+        self.cache.set(values)
+
+        result = self.cache.get([key1, key2])
+        assert result[key1] == {"graph": 1}
+        assert result[key2] == {"graph": 2}
+
+    def test_clear_all(self):
+        """Test clearing all cached values."""
+        keys = [(("graph", "node1"), "key1"), (("graph", "node2"), "key2")]
+        values = {keys[0]: ({"result": 1}, None), keys[1]: ({"result": 2}, None)}
+
+        self.cache.set(values)
+
+        # Verify data exists
+        result = self.cache.get(keys)
+        assert len(result) == 2
+
+        # Clear all
+        self.cache.clear()
+
+        # Verify data is gone
+        result = self.cache.get(keys)
+        assert len(result) == 0
+
+    def test_clear_by_namespace(self):
+        """Test clearing cached values by namespace."""
+        keys = [
+            (("graph1", "node"), "key1"),
+            (("graph2", "node"), "key2"),
+            (("graph1", "other"), "key3"),
+        ]
+        values = {
+            keys[0]: ({"result": 1}, None),
+            keys[1]: ({"result": 2}, None),
+            keys[2]: ({"result": 3}, None),
+        }
+
+        self.cache.set(values)
+
+        # Clear only graph1 namespace
+        self.cache.clear([("graph1", "node"), ("graph1", "other")])
+
+        # graph1 should be cleared, graph2 should remain
+        result = self.cache.get(keys)
+        assert len(result) == 1
+        assert result[keys[1]] == {"result": 2}
+
+    def test_empty_operations(self):
+        """Test behavior with empty keys/values."""
+        # Empty get
+        result = self.cache.get([])
+        assert result == {}
+
+        # Empty set
+        self.cache.set({})  # Should not raise error
+
+    def test_nonexistent_keys(self):
+        """Test getting keys that don't exist."""
+        keys = [(("graph", "node"), "nonexistent")]
+        result = self.cache.get(keys)
+        assert len(result) == 0
+
+    @pytest.mark.asyncio
+    async def test_async_operations(self):
+        """Test async set and get operations with sync Redis client."""
+        # Create sync Redis client and cache (like main integration tests)
+        client = redis.Redis(
+            host="localhost", port=6379, db=1, decode_responses=False
+        )
+        try:
+            client.ping()
+        except Exception:
+            pytest.skip("Redis not available")
+
+        cache = RedisCache(client, prefix="test:async:")
+
+        keys = [(("graph", "node"), "async_key")]
+        values = {keys[0]: ({"async": True}, None)}
+
+        # Async set (delegates to sync)
+        await cache.aset(values)
+
+        # Async get (delegates to sync)
+        result = await cache.aget(keys)
+        assert len(result) == 1
+        assert result[keys[0]] == {"async": True}
+
+        # Cleanup
+        client.flushdb()
+
+    @pytest.mark.asyncio
+    async def test_async_clear(self):
+        """Test async clear operations with sync Redis client."""
+        # Create sync Redis client and cache (like main integration tests)
+        client = redis.Redis(
+            host="localhost", port=6379, db=1, decode_responses=False
+        )
+        try:
+            client.ping()
+        except Exception:
+            pytest.skip("Redis not available")
+
+        cache = RedisCache(client, prefix="test:async:")
+
+        keys = [(("graph", "node"), "key")]
+        values = {keys[0]: ({"data": "test"}, None)}
+
+        await cache.aset(values)
+
+        # Verify data exists
+        result = await cache.aget(keys)
+        assert len(result) == 1
+
+        # Clear all (delegates to sync)
+        await cache.aclear()
+
+        # Verify data is gone
+        result = await cache.aget(keys)
+        assert len(result) == 0
+
+        # Cleanup
+        client.flushdb()
+
+    def test_redis_unavailable_get(self):
+        """Test behavior when Redis is unavailable during get operations."""
+        # Create cache with non-existent Redis server
+        bad_client = redis.Redis(
+            host="nonexistent", port=9999, socket_connect_timeout=0.1
+        )
+        cache = RedisCache(bad_client, prefix="test:cache:")
+
+        keys = [(("graph", "node"), "key")]
+        result = cache.get(keys)
+
+        # Should return empty dict when Redis unavailable
+        assert result == {}
+
+    def test_redis_unavailable_set(self):
+        """Test behavior when Redis is unavailable during set operations."""
+        # Create cache with non-existent Redis server
+        bad_client = redis.Redis(
+            host="nonexistent", port=9999, socket_connect_timeout=0.1
+        )
+        cache = RedisCache(bad_client, prefix="test:cache:")
+
+        keys = [(("graph", "node"), "key")]
+        values = {keys[0]: ({"data": "test"}, None)}
+
+        # Should not raise exception when Redis unavailable
+        cache.set(values)  # Should silently fail
+
+    @pytest.mark.asyncio
+    async def test_redis_unavailable_async(self):
+        """Test async behavior when Redis is unavailable."""
+        # Create sync cache with non-existent Redis server (like main integration tests)
+        bad_client = redis.Redis(
+            host="nonexistent", port=9999, socket_connect_timeout=0.1
+        )
+        cache = RedisCache(bad_client, prefix="test:cache:")
+
+        keys = [(("graph", "node"), "key")]
+        values = {keys[0]: ({"data": "test"}, None)}
+
+        # Should return empty dict for get (delegates to sync)
+        result = await cache.aget(keys)
+        assert result == {}
+
+        # Should not raise exception for set (delegates to sync)
+        await cache.aset(values)  # Should silently fail
+
+    def test_corrupted_data_handling(self):
+        """Test handling of corrupted data in Redis."""
+        # Set some valid data first
+        keys = [(("graph", "node"), "valid_key")]
+        values = {keys[0]: ({"data": "valid"}, None)}
+        self.cache.set(values)
+
+        # Manually insert corrupted data
+        corrupted_key = self.cache._make_key(("graph", "node"), "corrupted_key")
+        self.client.set(corrupted_key, b"invalid:data:format:too:many:colons")
+
+        # Should skip corrupted entry and return only valid ones
+        all_keys = [keys[0], (("graph", "node"), "corrupted_key")]
+        result = self.cache.get(all_keys)
+
+        assert len(result) == 1
+        assert result[keys[0]] == {"data": "valid"}
+
+    def test_key_parsing_edge_cases(self):
+        """Test key parsing with edge cases."""
+        # Test empty namespace
+        key1 = ((), "empty_ns")
+        values = {key1: ({"data": "empty_ns"}, None)}
+        self.cache.set(values)
+        result = self.cache.get([key1])
+        assert result[key1] == {"data": "empty_ns"}
+
+        # Test namespace with special characters
+        key2 = (("graph:with:colons", "node-with-dashes"), "key_with_underscores")
+        values = {key2: ({"data": "special_chars"}, None)}
+        self.cache.set(values)
+        result = self.cache.get([key2])
+        assert result[key2] == {"data": "special_chars"}
+
+    def test_large_data_serialization(self):
+        """Test handling of large data objects."""
+        # Create a large data structure
+        large_data = {"large_list": list(range(1000)), "nested": {"data": "x" * 1000}}
+        key = (("graph", "node"), "large_key")
+        values = {key: (large_data, None)}
+
+        self.cache.set(values)
+        result = self.cache.get([key])
+
+        assert len(result) == 1
+        assert result[key] == large_data

libs/checkpoint/uv.lock

@@ -32,6 +32,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a1/ee/48ca1a7c89ffec8b6a0c5d02b89c305671d5ffd8d3c94acf8b8c408575bb/anyio-4.9.0-py3-none-any.whl", hash = "sha256:9f76d541cad6e36af7beb62e978876f3b41e3e04f2c1fbf0884604c0a9c4d93c", size = 100916, upload-time = "2025-03-17T00:02:52.713Z" },
 ]
 
+[[package]]
+name = "async-timeout"
+version = "5.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a5/ae/136395dfbfe00dfc94da3f3e136d0b13f394cba8f4841120e34226265780/async_timeout-5.0.1.tar.gz", hash = "sha256:d9321a7a3d5a6a5e187e824d2fa0793ce379a202935782d555d6e9d2735677d3", size = 9274, upload-time = "2024-11-06T16:41:39.6Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fe/ba/e2081de779ca30d473f21f5b30e0e737c438205440784c7dfc81efc2b029/async_timeout-5.0.1-py3-none-any.whl", hash = "sha256:39e3809566ff85354557ec2398b55e096c8364bacac9405a7a1fa429e77fe76c", size = 6233, upload-time = "2024-11-06T16:41:37.9Z" },
+]
+
 [[package]]
 name = "certifi"
 version = "2025.7.9"
@@ -345,6 +354,7 @@ dev = [
     { name = "pytest-asyncio" },
     { name = "pytest-mock" },
     { name = "pytest-watcher" },
+    { name = "redis" },
     { name = "ruff" },
 ]
 
@@ -366,6 +376,7 @@ dev = [
     { name = "pytest-asyncio" },
     { name = "pytest-mock" },
     { name = "pytest-watcher" },
+    { name = "redis" },
     { name = "ruff" },
 ]
 
@@ -1153,6 +1164,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/19/87/5124b1c1f2412bb95c59ec481eaf936cd32f0fe2a7b16b97b81c4c017a6a/PyYAML-6.0.2-cp39-cp39-win_amd64.whl", hash = "sha256:39693e1f8320ae4f43943590b49779ffb98acb81f788220ea932a6b6c51004d8", size = 162312, upload-time = "2024-08-06T20:33:49.073Z" },
 ]
 
+[[package]]
+name = "redis"
+version = "6.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "async-timeout", marker = "python_full_version < '3.11.3'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/21/cd/030274634a1a052b708756016283ea3d84e91ae45f74d7f5dcf55d753a0f/redis-6.3.0.tar.gz", hash = "sha256:3000dbe532babfb0999cdab7b3e5744bcb23e51923febcfaeb52c8cfb29632ef", size = 4647275, upload-time = "2025-08-05T08:12:31.648Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/df/a7/2fe45801534a187543fc45d28b3844d84559c1589255bc2ece30d92dc205/redis-6.3.0-py3-none-any.whl", hash = "sha256:92f079d656ded871535e099080f70fab8e75273c0236797126ac60242d638e9b", size = 280018, upload-time = "2025-08-05T08:12:30.093Z" },
+]
+
 [[package]]
 name = "requests"
 version = "2.32.4"

libs/langgraph/Makefile

@@ -37,11 +37,11 @@ coverage:
 		--cov-report xml \
 		--cov-report term-missing:skip-covered
 
-start-postgres:
-	docker compose -f tests/compose-postgres.yml up -V --force-recreate --wait --remove-orphans
+start-services:
+	docker compose -f tests/compose-postgres.yml -f tests/compose-redis.yml up -V --force-recreate --wait --remove-orphans
 
-stop-postgres:
-	docker compose -f tests/compose-postgres.yml down -v
+stop-services:
+	docker compose -f tests/compose-postgres.yml -f tests/compose-redis.yml down -v
 
 start-dev-server:
 	LOG_LEVEL=warning uv run langgraph dev --config tests/example_app/langgraph.json --no-browser & echo "$$!" > .devserver.pid
@@ -60,11 +60,11 @@ NO_DOCKER ?= $(sh command -v docker >/dev/null 2>&1 && echo "false" || echo "tru
 
 test:
 	if [ "$(NO_DOCKER)" = "false" ]; then \
-		make start-postgres &&\
+		make start-services &&\
 		make start-dev-server &&\
 		uv run pytest $(TEST); \
 		EXIT_CODE=$$?; \
-		make stop-postgres; \
+		make stop-services; \
 		make stop-dev-server; \
 		exit $$EXIT_CODE; \
 	else \
@@ -74,11 +74,11 @@ test:
 	fi
 
 test_parallel:
-	make start-postgres &&\
+	make start-services &&\
 	make start-dev-server &&\
 	uv run pytest -n auto --dist worksteal $(TEST); \
 	EXIT_CODE=$$?; \
-	make stop-postgres; \
+	make stop-services; \
 	make stop-dev-server; \
 	exit $$EXIT_CODE
 
@@ -93,11 +93,11 @@ MAXFAIL_ARGS := $(if $(MAXFAIL),--maxfail $(MAXFAIL),)
 XDIST_ARGS := $(if $(WORKERS),-x $(XDIST_ARGS),)
 
 test_watch:
-	make start-postgres &&\
+	make start-services &&\
 	make start-dev-server &&\
 	uv run ptw . -- --ff -vv $(XDIST_ARGS) $(MAXFAIL_ARGS) $(TEST); \
 	EXIT_CODE=$$?; \
-	make stop-postgres; \
+	make stop-services; \
 	make stop-dev-server; \
 	exit $$EXIT_CODE
 

libs/langgraph/bench/react_agent.py

@@ -10,7 +10,7 @@ from langchain_core.outputs import ChatGeneration, ChatResult
 from langchain_core.tools import StructuredTool
 
 from langgraph.checkpoint.base import BaseCheckpointSaver
-from langgraph.prebuilt.chat_agent_executor import create_react_agent
+from langgraph.prebuilt.chat_agent_executor import create_agent
 from langgraph.pregel import Pregel
 
 
@@ -60,7 +60,7 @@ def react_agent(n_tools: int, checkpointer: Optional[BaseCheckpointSaver]) -> Pr
         ]
     )
 
-    return create_react_agent(model, [tool], checkpointer=checkpointer)
+    return create_agent(model, [tool], checkpointer=checkpointer)
 
 
 if __name__ == "__main__":

libs/langgraph/pyproject.toml

@@ -49,6 +49,7 @@ dev = [
     "types-requests",
     "pycryptodome",
     "langgraph-cli[inmem]",
+    "redis",
 ]
 
 [tool.uv]

libs/langgraph/tests/compose-redis.yml

@@ -0,0 +1,16 @@
+name: langgraph-tests
+services:
+  redis-test:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: redis-cli ping
+      start_period: 10s
+      timeout: 1s
+      retries: 5
+      interval: 5s
+      start_interval: 1s
+    tmpfs:
+      - /data  # Use tmpfs for faster testing

libs/langgraph/tests/conftest.py

@@ -3,10 +3,12 @@ from collections.abc import AsyncIterator, Iterator
 from uuid import UUID
 
 import pytest
+import redis
 from pytest_mock import MockerFixture
 
 from langgraph.cache.base import BaseCache
 from langgraph.cache.memory import InMemoryCache
+from langgraph.cache.redis import RedisCache
 from langgraph.cache.sqlite import SqliteCache
 from langgraph.checkpoint.base import BaseCheckpointSaver
 from langgraph.store.base import BaseStore
@@ -55,12 +57,34 @@ def durability(request: pytest.FixtureRequest) -> Durability:
     return request.param
 
 
-@pytest.fixture(scope="function", params=["sqlite", "memory"])
+@pytest.fixture(
+    scope="function",
+    params=["sqlite", "memory"] if NO_DOCKER else ["sqlite", "memory", "redis"],
+)
 def cache(request: pytest.FixtureRequest) -> Iterator[BaseCache]:
     if request.param == "sqlite":
         yield SqliteCache(path=":memory:")
     elif request.param == "memory":
         yield InMemoryCache()
+    elif request.param == "redis":
+        # Get worker ID for parallel test isolation
+        worker_id = getattr(request.config, "workerinput", {}).get("workerid", "master")
+        
+        redis_client = redis.Redis(
+            host="localhost", port=6379, db=0, decode_responses=False
+        )
+        # Use worker-specific prefix to avoid cache pollution between parallel tests
+        cache = RedisCache(redis_client, prefix=f"test:cache:{worker_id}:")
+        yield cache
+
+        try:
+            # Only clear keys with our specific prefix
+            pattern = f"test:cache:{worker_id}:*"
+            keys = redis_client.keys(pattern)
+            if keys:
+                redis_client.delete(*keys)
+        except Exception:
+            pass
     else:
         raise ValueError(f"Unknown cache type: {request.param}")
 

libs/langgraph/uv.lock

@@ -119,6 +119,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/03/49/d10027df9fce941cb8184e78a02857af36360d33e1721df81c5ed2179a1a/async_lru-2.0.5-py3-none-any.whl", hash = "sha256:ab95404d8d2605310d345932697371a5f40def0487c03d6d0ad9138de52c9943", size = 6069, upload-time = "2025-03-16T17:25:35.422Z" },
 ]
 
+[[package]]
+name = "async-timeout"
+version = "5.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a5/ae/136395dfbfe00dfc94da3f3e136d0b13f394cba8f4841120e34226265780/async_timeout-5.0.1.tar.gz", hash = "sha256:d9321a7a3d5a6a5e187e824d2fa0793ce379a202935782d555d6e9d2735677d3", size = 9274, upload-time = "2024-11-06T16:41:39.6Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fe/ba/e2081de779ca30d473f21f5b30e0e737c438205440784c7dfc81efc2b029/async_timeout-5.0.1-py3-none-any.whl", hash = "sha256:39e3809566ff85354557ec2398b55e096c8364bacac9405a7a1fa429e77fe76c", size = 6233, upload-time = "2024-11-06T16:41:37.9Z" },
+]
+
 [[package]]
 name = "attrs"
 version = "25.3.0"
@@ -1225,6 +1234,7 @@ dev = [
     { name = "pytest-repeat" },
     { name = "pytest-watcher" },
     { name = "pytest-xdist", extra = ["psutil"] },
+    { name = "redis" },
     { name = "ruff" },
     { name = "syrupy" },
     { name = "types-requests" },
@@ -1263,6 +1273,7 @@ dev = [
     { name = "pytest-repeat" },
     { name = "pytest-watcher" },
     { name = "pytest-xdist", extras = ["psutil"] },
+    { name = "redis" },
     { name = "ruff" },
     { name = "syrupy" },
     { name = "types-requests" },
@@ -1326,6 +1337,7 @@ dev = [
     { name = "pytest-asyncio" },
     { name = "pytest-mock" },
     { name = "pytest-watcher" },
+    { name = "redis" },
     { name = "ruff" },
 ]
 
@@ -2628,6 +2640,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/51/8b/619a9ee2fa4d3c724fbadde946427735ade64da03894b071bbdc3b789d83/pyzmq-27.0.0-pp39-pypy39_pp73-win_amd64.whl", hash = "sha256:096af9e133fec3a72108ddefba1e42985cb3639e9de52cfd336b6fc23aa083e9", size = 544715, upload-time = "2025-06-13T14:09:05.579Z" },
 ]
 
+[[package]]
+name = "redis"
+version = "6.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "async-timeout", marker = "python_full_version < '3.11.3'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/21/cd/030274634a1a052b708756016283ea3d84e91ae45f74d7f5dcf55d753a0f/redis-6.3.0.tar.gz", hash = "sha256:3000dbe532babfb0999cdab7b3e5744bcb23e51923febcfaeb52c8cfb29632ef", size = 4647275, upload-time = "2025-08-05T08:12:31.648Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/df/a7/2fe45801534a187543fc45d28b3844d84559c1589255bc2ece30d92dc205/redis-6.3.0-py3-none-any.whl", hash = "sha256:92f079d656ded871535e099080f70fab8e75273c0236797126ac60242d638e9b", size = 280018, upload-time = "2025-08-05T08:12:30.093Z" },
+]
+
 [[package]]
 name = "referencing"
 version = "0.36.2"

libs/prebuilt/Makefile

@@ -7,11 +7,11 @@ all: help
 # TESTING AND COVERAGE
 ######################
 
-start-postgres:
-	docker compose -f tests/compose-postgres.yml up -V --force-recreate --wait --remove-orphans
+start-services:
+	docker compose -f tests/compose-postgres.yml -f tests/compose-redis.yml up -V --force-recreate --wait --remove-orphans
 
-stop-postgres:
-	docker compose -f tests/compose-postgres.yml down -v
+stop-services:
+	docker compose -f tests/compose-postgres.yml -f tests/compose-redis.yml down -v
 
 TEST ?= .
 
@@ -19,15 +19,15 @@ test-fast:
 	LANGGRAPH_TEST_FAST=1 uv run pytest $(TEST)
 
 test:
-	make start-postgres && LANGGRAPH_TEST_FAST=0 uv run pytest $(TEST); \
+	make start-services && LANGGRAPH_TEST_FAST=0 uv run pytest $(TEST); \
 	EXIT_CODE=$$?; \
-	make stop-postgres; \
+	make stop-services; \
 	exit $$EXIT_CODE
 
 test_watch:
-	make start-postgres && LANGGRAPH_TEST_FAST=0 uv run ptw $(TEST); \
+	make start-services && LANGGRAPH_TEST_FAST=0 uv run ptw $(TEST); \
 	EXIT_CODE=$$?; \
-	make stop-postgres; \
+	make stop-services; \
 	exit $$EXIT_CODE
 
 ######################

libs/prebuilt/langgraph/prebuilt/_internal/_typing.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import Awaitable, Callable, TypeVar, Union
+
+from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+SyncOrAsync = Callable[P, Union[R, Awaitable[R]]]

libs/prebuilt/langgraph/prebuilt/responses.py

@@ -0,0 +1,397 @@
+"""Types for setting agent response formats."""
+
+from __future__ import annotations
+
+import sys
+import uuid
+from dataclasses import dataclass, is_dataclass
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    Literal,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+)
+
+from langchain_core.messages import AIMessage
+from langchain_core.tools import BaseTool, StructuredTool
+from pydantic import BaseModel, TypeAdapter
+from typing_extensions import Self, is_typeddict
+
+# Supported schema types: Pydantic models, dataclasses, TypedDict, JSON schema dicts
+SchemaT = TypeVar("SchemaT")
+
+
+if sys.version_info >= (3, 10):
+    from types import UnionType
+else:
+    UnionType = Union
+
+SchemaKind = Literal["pydantic", "dataclass", "typeddict", "json_schema"]
+
+
+class StructuredOutputError(Exception):
+    """Base class for structured output errors."""
+
+
+class MultipleStructuredOutputsError(StructuredOutputError):
+    """Raised when model returns multiple structured output tool calls when only one is expected."""
+
+    def __init__(self, tool_names: list[str]):
+        self.tool_names = tool_names
+        super().__init__(
+            f"Model incorrectly returned multiple structured responses ({', '.join(tool_names)}) when only one is expected."
+        )
+
+
+class StructuredOutputParsingError(StructuredOutputError):
+    """Raised when structured output tool call arguments fail to parse according to the schema."""
+
+    def __init__(self, tool_name: str, parse_error: Exception):
+        self.tool_name = tool_name
+        self.parse_error = parse_error
+        super().__init__(
+            f"Failed to parse structured output for tool '{tool_name}': {parse_error}."
+        )
+
+
+def _parse_with_schema(
+    schema: Union[type[SchemaT], dict], schema_kind: SchemaKind, data: dict[str, Any]
+) -> Any:
+    """Parse data using for any supported schema type.
+
+    Args:
+        schema: The schema type (Pydantic model, dataclass, or TypedDict)
+        data: The data to parse
+
+    Returns:
+        The parsed instance according to the schema type
+
+    Raises:
+        ValueError: If parsing fails
+    """
+    if schema_kind == "json_schema":
+        return data
+    else:
+        try:
+            adapter: TypeAdapter[SchemaT] = TypeAdapter(schema)
+            return adapter.validate_python(data)
+        except Exception as e:
+            schema_name = getattr(schema, "__name__", str(schema))
+            raise ValueError(f"Failed to parse data to {schema_name}: {e}") from e
+
+
+@dataclass(init=False)
+class _SchemaSpec(Generic[SchemaT]):
+    """Describes a structured output schema."""
+
+    schema: type[SchemaT]
+    """The schema for the response, can be a Pydantic model, dataclass, TypedDict, or JSON schema dict."""
+
+    name: str
+    """Name of the schema, used for tool calling.
+    
+    If not provided, the name will be the model name or "response_format" if it's a JSON schema.
+    """
+
+    description: str
+    """Custom description of the schema. 
+    
+    If not provided, provided will use the model's docstring.
+    """
+
+    schema_kind: SchemaKind
+    """The kind of schema."""
+
+    json_schema: dict[str, Any]
+    """JSON schema associated with the schema."""
+
+    strict: bool = False
+    """Whether to enforce strict validation of the schema."""
+
+    def __init__(
+        self,
+        schema: type[SchemaT],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        strict: bool = False,
+    ) -> None:
+        """Initialize SchemaSpec with schema and optional parameters."""
+        self.schema = schema
+
+        if name:
+            self.name = name
+        elif isinstance(schema, dict):
+            self.name = str(
+                schema.get("title", f"response_format_{str(uuid.uuid4())[:4]}")
+            )
+        else:
+            self.name = str(
+                getattr(schema, "__name__", f"response_format_{str(uuid.uuid4())[:4]}")
+            )
+
+        self.description = description or (
+            schema.get("description", "")
+            if isinstance(schema, dict)
+            else getattr(schema, "__doc__", None) or ""
+        )
+
+        self.strict = strict
+
+        if isinstance(schema, dict):
+            self.schema_kind = "json_schema"
+            self.json_schema = schema
+        elif isinstance(schema, type) and issubclass(schema, BaseModel):
+            self.schema_kind = "pydantic"
+            self.json_schema = schema.model_json_schema()
+        elif is_dataclass(schema):
+            self.schema_kind = "dataclass"
+            self.json_schema = TypeAdapter(schema).json_schema()
+        elif is_typeddict(schema):
+            self.schema_kind = "typeddict"
+            self.json_schema = TypeAdapter(schema).json_schema()
+        else:
+            raise ValueError(
+                f"Unsupported schema type: {type(schema)}. "
+                f"Supported types: Pydantic models, dataclasses, TypedDicts, and JSON schema dicts."
+            )
+
+
+@dataclass(init=False)
+class ToolOutput(Generic[SchemaT]):
+    """Use a tool calling strategy for model responses."""
+
+    schema: type[SchemaT]
+    """Schema for the tool calls."""
+
+    schema_specs: list[_SchemaSpec[SchemaT]]
+    """Schema specs for the tool calls."""
+
+    tool_message_content: str | None
+    """The content of the tool message to be returned when the model calls an artificial structured output tool."""
+
+    handle_errors: Union[
+        bool,
+        str,
+        type[Exception],
+        tuple[type[Exception], ...],
+        Callable[[Exception], str],
+    ]
+    """Error handling strategy for structured output via ToolOutput. Default is True.
+    
+    - True: Catch all errors with default error template
+    - str: Catch all errors with this custom message
+    - type[Exception]: Only catch this exception type with default message
+    - tuple[type[Exception], ...]: Only catch these exception types with default message
+    - Callable[[Exception], str]: Custom function that returns error message
+    - False: No retry, let exceptions propagate
+    """
+
+    def __init__(
+        self,
+        schema: type[SchemaT],
+        tool_message_content: str | None = None,
+        handle_errors: Union[
+            bool,
+            str,
+            type[Exception],
+            tuple[type[Exception], ...],
+            Callable[[Exception], str],
+        ] = True,
+    ) -> None:
+        """Initialize ToolOutput with schemas, tool message content, and error handling strategy."""
+        self.schema = schema
+        self.tool_message_content = tool_message_content
+        self.handle_errors = handle_errors
+
+        def _iter_variants(schema: Any) -> Iterable[Any]:
+            """Yield leaf variants from Union and JSON Schema oneOf."""
+
+            if get_origin(schema) in (UnionType, Union):
+                for arg in get_args(schema):
+                    yield from _iter_variants(arg)
+                return
+
+            if isinstance(schema, dict) and "oneOf" in schema:
+                for sub in schema.get("oneOf", []):
+                    yield from _iter_variants(sub)
+                return
+
+            yield schema
+
+        self.schema_specs = [_SchemaSpec(s) for s in _iter_variants(schema)]
+
+
+@dataclass(init=False)
+class NativeOutput(Generic[SchemaT]):
+    """Use the model provider's native structured output method."""
+
+    schema: type[SchemaT]
+    """Schema for native mode."""
+
+    schema_spec: _SchemaSpec[SchemaT]
+    """Schema spec for native mode."""
+
+    def __init__(
+        self,
+        schema: type[SchemaT],
+    ) -> None:
+        self.schema = schema
+        self.schema_spec = _SchemaSpec(schema)
+
+    def to_model_kwargs(self) -> dict[str, Any]:
+        # OpenAI:
+        # - see https://platform.openai.com/docs/guides/structured-outputs
+        response_format = {
+            "type": "json_schema",
+            "json_schema": {
+                "name": self.schema_spec.name,
+                "schema": self.schema_spec.json_schema,
+            },
+        }
+        return {"response_format": response_format}
+
+
+@dataclass
+class OutputToolBinding(Generic[SchemaT]):
+    """Information for tracking structured output tool metadata.
+
+    This contains all necessary information to handle structured responses
+    generated via tool calls, including the original schema, its type classification,
+    and the corresponding tool implementation used by the tools strategy.
+    """
+
+    schema: type[SchemaT]
+    """The original schema provided for structured output (Pydantic model, dataclass, TypedDict, or JSON schema dict)."""
+
+    schema_kind: SchemaKind
+    """Classification of the schema type for proper response construction."""
+
+    tool: BaseTool
+    """LangChain tool instance created from the schema for model binding."""
+
+    @classmethod
+    def from_schema_spec(cls, schema_spec: _SchemaSpec[SchemaT]) -> Self:
+        """Create an OutputToolBinding instance from a SchemaSpec.
+
+        Args:
+            schema_spec: The SchemaSpec to convert
+
+        Returns:
+            An OutputToolBinding instance with the appropriate tool created
+        """
+        return cls(
+            schema=schema_spec.schema,
+            schema_kind=schema_spec.schema_kind,
+            tool=StructuredTool(
+                args_schema=schema_spec.json_schema,
+                name=schema_spec.name,
+                description=schema_spec.description,
+            ),
+        )
+
+    def parse(self, tool_args: dict[str, Any]) -> SchemaT:
+        """Parse tool arguments according to the schema.
+
+        Args:
+            tool_args: The arguments from the tool call
+
+        Returns:
+            The parsed response according to the schema type
+
+        Raises:
+            ValueError: If parsing fails
+        """
+        return _parse_with_schema(self.schema, self.schema_kind, tool_args)
+
+
+@dataclass
+class NativeOutputBinding(Generic[SchemaT]):
+    """Information for tracking native structured output metadata.
+
+    This contains all necessary information to handle structured responses
+    generated via native provider output, including the original schema,
+    its type classification, and parsing logic for provider-enforced JSON.
+    """
+
+    schema: type[SchemaT]
+    """The original schema provided for structured output (Pydantic model, dataclass, TypedDict, or JSON schema dict)."""
+
+    schema_kind: SchemaKind
+    """Classification of the schema type for proper response construction."""
+
+    @classmethod
+    def from_schema_spec(cls, schema_spec: _SchemaSpec[SchemaT]) -> Self:
+        """Create a NativeOutputBinding instance from a SchemaSpec.
+
+        Args:
+            schema_spec: The SchemaSpec to convert
+
+        Returns:
+            A NativeOutputBinding instance for parsing native structured output
+        """
+        return cls(
+            schema=schema_spec.schema,
+            schema_kind=schema_spec.schema_kind,
+        )
+
+    def parse(self, response: AIMessage) -> SchemaT:
+        """Parse AIMessage content according to the schema.
+
+        Args:
+            response: The AI message containing the structured output
+
+        Returns:
+            The parsed response according to the schema
+
+        Raises:
+            ValueError: If text extraction, JSON parsing or schema validation fails
+        """
+        # Extract text content from AIMessage and parse as JSON
+        raw_text = self._extract_text_content_from_message(response)
+
+        import json
+
+        try:
+            data = json.loads(raw_text)
+        except Exception as e:
+            schema_name = getattr(self.schema, "__name__", "response_format")
+            raise ValueError(
+                f"Native structured output expected valid JSON for {schema_name}, but parsing failed: {e}."
+            ) from e
+
+        # Parse according to schema
+        return _parse_with_schema(self.schema, self.schema_kind, data)
+
+    def _extract_text_content_from_message(self, message: AIMessage) -> str:
+        """Extract text content from an AIMessage.
+
+        Args:
+            message: The AI message to extract text from
+
+        Returns:
+            The extracted text content
+        """
+        content = message.content
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts: list[str] = []
+            for c in content:
+                if isinstance(c, dict):
+                    if c.get("type") == "text" and "text" in c:
+                        parts.append(str(c["text"]))
+                    elif "content" in c and isinstance(c["content"], str):
+                        parts.append(c["content"])
+                else:
+                    parts.append(str(c))
+            return "".join(parts)
+        return str(content)
+
+
+ResponseFormat = Union[ToolOutput[SchemaT], NativeOutput[SchemaT]]

libs/prebuilt/langgraph/prebuilt/tool_node.py

@@ -31,6 +31,8 @@ Typical Usage:
     ```
 """
 
+from __future__ import annotations
+
 import asyncio
 import inspect
 import json
@@ -68,7 +70,7 @@ from langchain_core.tools.base import (
     TOOL_MESSAGE_BLOCK_TYPES,
     get_all_basemodel_annotations,
 )
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 from typing_extensions import Annotated, get_args, get_origin
 
 from langgraph._internal._runnable import RunnableCallable
@@ -81,6 +83,8 @@ INVALID_TOOL_NAME_ERROR_TEMPLATE = (
     "Error: {requested_tool} is not a valid tool, try one of [{available_tools}]."
 )
 TOOL_CALL_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."
+TOOL_EXECUTION_ERROR_TEMPLATE = "Error executing tool '{tool_name}' with kwargs {tool_kwargs} with error:\n {error}\n Please fix the error and try again."
+TOOL_INVOCATION_ERROR_TEMPLATE = "Error invoking tool '{tool_name}' with kwargs {tool_kwargs} with error:\n {error}\n Please fix the error and try again."
 
 
 def msg_content_output(output: Any) -> Union[str, list[dict]]:
@@ -122,6 +126,30 @@ def msg_content_output(output: Any) -> Union[str, list[dict]]:
             return str(output)
 
 
+class ToolInvocationError(Exception):
+    """Exception raised when a tool invocation fails due to invalid arguments."""
+
+    def __init__(self, tool_name: str, error: Exception, tool_kwargs: dict[str, Any]):
+        self.message = TOOL_INVOCATION_ERROR_TEMPLATE.format(
+            tool_name=tool_name, tool_kwargs=tool_kwargs, error=error
+        )
+        self.tool_name = tool_name
+        self.tool_kwargs = tool_kwargs
+        self.error = error
+        super().__init__(self.message)
+
+
+def _default_handle_tool_errors(e: Exception) -> str:
+    """Default error handler for tool errors.
+
+    If the tool is a tool invocation error, return its message.
+    Otherwise, raise the error.
+    """
+    if isinstance(e, ToolInvocationError):
+        return e.message
+    raise e
+
+
 def _handle_tool_error(
     e: Exception,
     *,
@@ -129,6 +157,7 @@ def _handle_tool_error(
         bool,
         str,
         Callable[..., str],
+        type[Exception],
         tuple[type[Exception], ...],
     ],
 ) -> str:
@@ -156,12 +185,14 @@ def _handle_tool_error(
         The tuple case is handled by the caller through exception type checking,
         not by this function directly.
     """
-    if isinstance(flag, (bool, tuple)):
+    if isinstance(flag, (bool, tuple)) or (
+        isinstance(flag, type) and issubclass(flag, Exception)
+    ):
         content = TOOL_CALL_ERROR_TEMPLATE.format(error=repr(e))
     elif isinstance(flag, str):
         content = flag
     elif callable(flag):
-        content = flag(e)
+        content = flag(e)  # type: ignore [assignment, call-arg]
     else:
         raise ValueError(
             f"Got unexpected type of `handle_tool_error`. Expected bool, str "
@@ -237,39 +268,69 @@ def _infer_handled_types(handler: Callable[..., str]) -> tuple[type[Exception],
 
 
 class ToolNode(RunnableCallable):
-    """A node that runs the tools called in the last AIMessage.
+    """A node for executing tools in LangGraph workflows.
 
-    It can be used either in StateGraph with a "messages" state key (or a custom key passed via ToolNode's 'messages_key').
-    If multiple tool calls are requested, they will be run in parallel. The output will be
-    a list of ToolMessages, one for each tool call.
+    Handles tool execution patterns including function calls, state injection,
+    persistent storage, and control flow. Manages parallel execution,
+    error handling.
 
-    Tool calls can also be passed directly as a list of `ToolCall` dicts.
+    Input Formats:
+        1. Graph state with `messages` key that has a list of messages:
+           - Common representation for agentic workflows
+           - Supports custom messages key via ``messages_key`` parameter
+
+        2. **Message List**: ``[AIMessage(..., tool_calls=[...])]``
+           - List of messages with tool calls in the last AIMessage
+
+        3. **Direct Tool Calls**: ``[{"name": "tool", "args": {...}, "id": "1", "type": "tool_call"}]``
+           - Bypasses message parsing for direct tool execution
+           - For programmatic tool invocation and testing
+
+    Output Formats:
+        Output format depends on input type and tool behavior:
+
+        **For Regular tools**:
+        - Dict input → ``{"messages": [ToolMessage(...)]}``
+        - List input → ``[ToolMessage(...)]``
+
+        **For Command tools**:
+        - Returns ``[Command(...)]`` or mixed list with regular tool outputs
+        - Commands can update state, trigger navigation, or send messages
 
     Args:
-        tools: A sequence of tools that can be invoked by this node. Tools can be
-            BaseTool instances or plain functions that will be converted to tools.
+        tools: A sequence of tools that can be invoked by this node. Supports:
+            - **BaseTool instances**: Tools with schemas and metadata
+            - **Plain functions**: Automatically converted to tools with inferred schemas
         name: The name identifier for this node in the graph. Used for debugging
             and visualization. Defaults to "tools".
         tags: Optional metadata tags to associate with the node for filtering
             and organization. Defaults to None.
         handle_tool_errors: Configuration for error handling during tool execution.
-            Defaults to True. Supports multiple strategies:
+            Supports multiple strategies:
 
-            - True: Catch all errors and return a ToolMessage with the default
+            - **True**: Catch all errors and return a ToolMessage with the default
               error template containing the exception details.
-            - str: Catch all errors and return a ToolMessage with this custom
+            - **str**: Catch all errors and return a ToolMessage with this custom
               error message string.
-            - tuple[type[Exception], ...]: Only catch exceptions of the specified
+            - **type[Exception]**: Only catch exceptions with the specified type and return the default error message for it.
+            - **tuple[type[Exception], ...]**: Only catch exceptions with the specified
               types and return default error messages for them.
-            - Callable[..., str]: Catch exceptions matching the callable's signature
+            - **Callable[..., str]**: Catch exceptions matching the callable's signature
               and return the string result of calling it with the exception.
-            - False: Disable error handling entirely, allowing exceptions to propagate.
+            - **False**: Disable error handling entirely, allowing exceptions to
+              propagate.
+
+            Defaults to a callable that:
+                - catches tool invocation errors (due to invalid arguments provided by the model) and returns a descriptive error message
+                - ignores tool execution errors (they will be re-raised)
 
         messages_key: The key in the state dictionary that contains the message list.
-            This same key will be used for the output ToolMessages. Defaults to "messages".
+            This same key will be used for the output ToolMessages.
+            Defaults to "messages".
+            Allows custom state schemas with different message field names.
 
-    Example:
-        Basic usage with simple tools:
+    Examples:
+        Basic usage:
 
         ```python
         from langgraph.prebuilt import ToolNode
@@ -283,38 +344,31 @@ class ToolNode(RunnableCallable):
         tool_node = ToolNode([calculator])
         ```
 
-        Custom error handling:
+        State injection:
 
         ```python
-        def handle_math_errors(e: ZeroDivisionError) -> str:
-            return "Cannot divide by zero!"
+        from typing_extensions import Annotated
+        from langgraph.prebuilt import InjectedState
 
-        tool_node = ToolNode([calculator], handle_tool_errors=handle_math_errors)
+        @tool
+        def context_tool(query: str, state: Annotated[dict, InjectedState]) -> str:
+            \"\"\"Some tool that uses state.\"\"\"
+            return f"Query: {query}, Messages: {len(state['messages'])}"
+
+        tool_node = ToolNode([context_tool])
         ```
 
-        Direct tool call execution:
+        Error handling:
 
         ```python
-        tool_calls = [{"name": "calculator", "args": {"a": 5, "b": 3}, "id": "1", "type": "tool_call"}]
-        result = tool_node.invoke(tool_calls)
+        def handle_errors(e: ValueError) -> str:
+            return "Invalid input provided"
+
+        tool_node = ToolNode([my_tool], handle_tool_errors=handle_errors)
         ```
-
-    Note:
-        The ToolNode expects input in one of three formats:
-        1. A dictionary with a messages key containing a list of messages
-        2. A list of messages directly
-        3. A list of tool call dictionaries
-
-        When using message formats, the last message must be an AIMessage with
-        tool_calls populated. The node automatically extracts and processes these
-        tool calls concurrently.
-
-        For advanced use cases involving state injection or store access, tools
-        can be annotated with InjectedState or InjectedStore to receive graph
-        context automatically.
     """
 
-    name: str = "ToolNode"
+    name: str = "tools"
 
     def __init__(
         self,
@@ -323,8 +377,8 @@ class ToolNode(RunnableCallable):
         name: str = "tools",
         tags: Optional[list[str]] = None,
         handle_tool_errors: Union[
-            bool, str, Callable[..., str], tuple[type[Exception], ...]
-        ] = True,
+            bool, str, Callable[..., str], type[Exception], tuple[type[Exception], ...]
+        ] = _default_handle_tool_errors,
         messages_key: str = "messages",
     ) -> None:
         """Initialize the ToolNode with the provided tools and configuration.
@@ -337,17 +391,24 @@ class ToolNode(RunnableCallable):
             messages_key: State key containing messages.
         """
         super().__init__(self._func, self._afunc, name=name, tags=tags, trace=False)
-        self.tools_by_name: dict[str, BaseTool] = {}
-        self.tool_to_state_args: dict[str, dict[str, Optional[str]]] = {}
-        self.tool_to_store_arg: dict[str, Optional[str]] = {}
-        self.handle_tool_errors = handle_tool_errors
-        self.messages_key = messages_key
-        for tool_ in tools:
-            if not isinstance(tool_, BaseTool):
-                tool_ = create_tool(tool_)
-            self.tools_by_name[tool_.name] = tool_
-            self.tool_to_state_args[tool_.name] = _get_state_args(tool_)
-            self.tool_to_store_arg[tool_.name] = _get_store_arg(tool_)
+        self._tools_by_name: dict[str, BaseTool] = {}
+        self._tool_to_state_args: dict[str, dict[str, Optional[str]]] = {}
+        self._tool_to_store_arg: dict[str, Optional[str]] = {}
+        self._handle_tool_errors = handle_tool_errors
+        self._messages_key = messages_key
+        for tool in tools:
+            if not isinstance(tool, BaseTool):
+                tool_ = create_tool(cast(Type[BaseTool], tool))
+            else:
+                tool_ = tool
+            self._tools_by_name[tool_.name] = tool_
+            self._tool_to_state_args[tool_.name] = _get_state_args(tool_)
+            self._tool_to_store_arg[tool_.name] = _get_store_arg(tool_)
+
+    @property
+    def tools_by_name(self) -> dict[str, BaseTool]:
+        """Mapping from tool name to BaseTool instance."""
+        return self._tools_by_name
 
     def _func(
         self,
@@ -390,14 +451,14 @@ class ToolNode(RunnableCallable):
 
     def _combine_tool_outputs(
         self,
-        outputs: list[ToolMessage],
+        outputs: list[Union[ToolMessage, Command]],
         input_type: Literal["list", "dict", "tool_calls"],
     ) -> list[Union[Command, list[ToolMessage], dict[str, list[ToolMessage]]]]:
         # preserve existing behavior for non-command tool outputs for backwards
         # compatibility
         if not any(isinstance(output, Command) for output in outputs):
             # TypedDict, pydantic, dataclass, etc. should all be able to load from dict
-            return outputs if input_type == "list" else {self.messages_key: outputs}
+            return outputs if input_type == "list" else {self._messages_key: outputs}
 
         # LangGraph will automatically handle list of Command and non-command node
         # updates
@@ -425,7 +486,7 @@ class ToolNode(RunnableCallable):
                     combined_outputs.append(output)
             else:
                 combined_outputs.append(
-                    [output] if input_type == "list" else {self.messages_key: [output]}
+                    [output] if input_type == "list" else {self._messages_key: [output]}
                 )
 
         if parent_command:
@@ -437,13 +498,19 @@ class ToolNode(RunnableCallable):
         call: ToolCall,
         input_type: Literal["list", "dict", "tool_calls"],
         config: RunnableConfig,
-    ) -> ToolMessage:
+    ) -> Union[ToolMessage, Command]:
         """Run a single tool call synchronously."""
         if invalid_tool_message := self._validate_tool_call(call):
             return invalid_tool_message
+
         try:
             call_args = {**call, **{"type": "tool_call"}}
-            response = self.tools_by_name[call["name"]].invoke(call_args, config)
+            tool = self.tools_by_name[call["name"]]
+
+            try:
+                response = tool.invoke(call_args, config)
+            except ValidationError as exc:
+                raise ToolInvocationError(call["name"], exc, call["args"])
 
         # GraphInterrupt is a special exception that will always be raised.
         # It can be triggered in the following scenarios,
@@ -455,20 +522,27 @@ class ToolNode(RunnableCallable):
         except GraphBubbleUp as e:
             raise e
         except Exception as e:
-            if isinstance(self.handle_tool_errors, tuple):
-                handled_types: tuple = self.handle_tool_errors
-            elif callable(self.handle_tool_errors):
-                handled_types = _infer_handled_types(self.handle_tool_errors)
+            handled_types: tuple[type[Exception], ...]
+            if isinstance(self._handle_tool_errors, type) and issubclass(
+                self._handle_tool_errors, Exception
+            ):
+                handled_types = (self._handle_tool_errors,)
+            elif isinstance(self._handle_tool_errors, tuple):
+                handled_types = self._handle_tool_errors
+            elif callable(self._handle_tool_errors) and not isinstance(
+                self._handle_tool_errors, type
+            ):
+                handled_types = _infer_handled_types(self._handle_tool_errors)
             else:
                 # default behavior is catching all exceptions
                 handled_types = (Exception,)
 
             # Unhandled
-            if not self.handle_tool_errors or not isinstance(e, handled_types):
+            if not self._handle_tool_errors or not isinstance(e, handled_types):
                 raise e
             # Handled
             else:
-                content = _handle_tool_error(e, flag=self.handle_tool_errors)
+                content = _handle_tool_error(e, flag=self._handle_tool_errors)
             return ToolMessage(
                 content=content,
                 name=call["name"],
@@ -493,14 +567,19 @@ class ToolNode(RunnableCallable):
         call: ToolCall,
         input_type: Literal["list", "dict", "tool_calls"],
         config: RunnableConfig,
-    ) -> ToolMessage:
+    ) -> Union[ToolMessage, Command]:
         """Run a single tool call asynchronously."""
         if invalid_tool_message := self._validate_tool_call(call):
             return invalid_tool_message
 
         try:
             call_args = {**call, **{"type": "tool_call"}}
-            response = await self.tools_by_name[call["name"]].ainvoke(call_args, config)
+            tool = self.tools_by_name[call["name"]]
+
+            try:
+                response = await tool.ainvoke(call_args, config)
+            except ValidationError as exc:
+                raise ToolInvocationError(call["name"], exc, call["args"])
 
         # GraphInterrupt is a special exception that will always be raised.
         # It can be triggered in the following scenarios,
@@ -512,20 +591,27 @@ class ToolNode(RunnableCallable):
         except GraphBubbleUp as e:
             raise e
         except Exception as e:
-            if isinstance(self.handle_tool_errors, tuple):
-                handled_types: tuple = self.handle_tool_errors
-            elif callable(self.handle_tool_errors):
-                handled_types = _infer_handled_types(self.handle_tool_errors)
+            handled_types: tuple[type[Exception], ...]
+            if isinstance(self._handle_tool_errors, type) and issubclass(
+                self._handle_tool_errors, Exception
+            ):
+                handled_types = (self._handle_tool_errors,)
+            elif isinstance(self._handle_tool_errors, tuple):
+                handled_types = self._handle_tool_errors
+            elif callable(self._handle_tool_errors) and not isinstance(
+                self._handle_tool_errors, type
+            ):
+                handled_types = _infer_handled_types(self._handle_tool_errors)
             else:
                 # default behavior is catching all exceptions
                 handled_types = (Exception,)
 
             # Unhandled
-            if not self.handle_tool_errors or not isinstance(e, handled_types):
+            if not self._handle_tool_errors or not isinstance(e, handled_types):
                 raise e
             # Handled
             else:
-                content = _handle_tool_error(e, flag=self.handle_tool_errors)
+                content = _handle_tool_error(e, flag=self._handle_tool_errors)
 
             return ToolMessage(
                 content=content,
@@ -564,9 +650,11 @@ class ToolNode(RunnableCallable):
             else:
                 input_type = "list"
                 messages = input
-        elif isinstance(input, dict) and (messages := input.get(self.messages_key, [])):
+        elif isinstance(input, dict) and (
+            messages := input.get(self._messages_key, [])
+        ):
             input_type = "dict"
-        elif messages := getattr(input, self.messages_key, []):
+        elif messages := getattr(input, self._messages_key, []):
             # Assume dataclass-like state that can coerce from dict
             input_type = "dict"
         else:
@@ -586,10 +674,12 @@ class ToolNode(RunnableCallable):
         return tool_calls, input_type
 
     def _validate_tool_call(self, call: ToolCall) -> Optional[ToolMessage]:
-        if (requested_tool := call["name"]) not in self.tools_by_name:
+        requested_tool = call["name"]
+        if requested_tool not in self.tools_by_name:
+            all_tool_names = list(self.tools_by_name.keys())
             content = INVALID_TOOL_NAME_ERROR_TEMPLATE.format(
                 requested_tool=requested_tool,
-                available_tools=", ".join(self.tools_by_name.keys()),
+                available_tools=", ".join(all_tool_names),
             )
             return ToolMessage(
                 content, name=requested_tool, tool_call_id=call["id"], status="error"
@@ -606,15 +696,15 @@ class ToolNode(RunnableCallable):
             BaseModel,
         ],
     ) -> ToolCall:
-        state_args = self.tool_to_state_args[tool_call["name"]]
+        state_args = self._tool_to_state_args[tool_call["name"]]
         if state_args and isinstance(input, list):
             required_fields = list(state_args.values())
             if (
                 len(required_fields) == 1
-                and required_fields[0] == self.messages_key
+                and required_fields[0] == self._messages_key
                 or required_fields[0] is None
             ):
-                input = {self.messages_key: input}
+                input = {self._messages_key: input}
             else:
                 err_msg = (
                     f"Invalid input to ToolNode. Tool {tool_call['name']} requires "
@@ -645,7 +735,7 @@ class ToolNode(RunnableCallable):
     def _inject_store(
         self, tool_call: ToolCall, store: Optional[BaseStore]
     ) -> ToolCall:
-        store_arg = self.tool_to_store_arg[tool_call["name"]]
+        store_arg = self._tool_to_store_arg[tool_call["name"]]
         if not store_arg:
             return tool_call
 
@@ -722,15 +812,15 @@ class ToolNode(RunnableCallable):
             # input type is dict when ToolNode is invoked with a dict input (e.g. {"messages": [AIMessage(..., tool_calls=[...])]})
             if input_type not in ("dict", "tool_calls"):
                 raise ValueError(
-                    f"Tools can provide a dict in Command.update only when using dict with '{self.messages_key}' key as ToolNode input, "
+                    f"Tools can provide a dict in Command.update only when using dict with '{self._messages_key}' key as ToolNode input, "
                     f"got: {command.update} for tool '{call['name']}'"
                 )
 
             updated_command = deepcopy(command)
             state_update = cast(dict[str, Any], updated_command.update) or {}
-            messages_update = state_update.get(self.messages_key, [])
+            messages_update = state_update.get(self._messages_key, [])
         elif isinstance(command.update, list):
-            # input type is list when ToolNode is invoked with a list input (e.g. [AIMessage(..., tool_calls=[...])])
+            # Input type is list when ToolNode is invoked with a list input (e.g. [AIMessage(..., tool_calls=[...])])
             if input_type != "list":
                 raise ValueError(
                     f"Tools can provide a list of messages in Command.update only when using list of messages as ToolNode input, "

libs/prebuilt/tests/__snapshots__/test_react_agent_graph.ambr

@@ -1,5 +1,5 @@
 # serializer version: 1
-# name: test_react_agent_graph_structure[None-None-None-tools0]
+# name: test_react_agent_graph_structure[None-None-tools0]
   '''
   graph TD;
   	__start__ --> agent;
@@ -7,7 +7,7 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[None-None-None-tools1]
+# name: test_react_agent_graph_structure[None-None-tools1]
   '''
   graph TD;
   	__start__ --> agent;
@@ -17,7 +17,7 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[None-None-pre_model_hook-tools0]
+# name: test_react_agent_graph_structure[None-pre_model_hook-tools0]
   '''
   graph TD;
   	__start__ --> pre_model_hook;
@@ -26,7 +26,7 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[None-None-pre_model_hook-tools1]
+# name: test_react_agent_graph_structure[None-pre_model_hook-tools1]
   '''
   graph TD;
   	__start__ --> pre_model_hook;
@@ -37,7 +37,7 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[None-post_model_hook-None-tools0]
+# name: test_react_agent_graph_structure[post_model_hook-None-tools0]
   '''
   graph TD;
   	__start__ --> agent;
@@ -46,7 +46,7 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[None-post_model_hook-None-tools1]
+# name: test_react_agent_graph_structure[post_model_hook-None-tools1]
   '''
   graph TD;
   	__start__ --> agent;
@@ -58,7 +58,7 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[None-post_model_hook-pre_model_hook-tools0]
+# name: test_react_agent_graph_structure[post_model_hook-pre_model_hook-tools0]
   '''
   graph TD;
   	__start__ --> pre_model_hook;
@@ -68,7 +68,7 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[None-post_model_hook-pre_model_hook-tools1]
+# name: test_react_agent_graph_structure[post_model_hook-pre_model_hook-tools1]
   '''
   graph TD;
   	__start__ --> pre_model_hook;
@@ -81,93 +81,3 @@
   
   '''
 # ---
-# name: test_react_agent_graph_structure[ResponseFormat-None-None-tools0]
-  '''
-  graph TD;
-  	__start__ --> agent;
-  	agent --> generate_structured_response;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---
-# name: test_react_agent_graph_structure[ResponseFormat-None-None-tools1]
-  '''
-  graph TD;
-  	__start__ --> agent;
-  	agent -.-> generate_structured_response;
-  	agent -.-> tools;
-  	tools --> agent;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---
-# name: test_react_agent_graph_structure[ResponseFormat-None-pre_model_hook-tools0]
-  '''
-  graph TD;
-  	__start__ --> pre_model_hook;
-  	agent --> generate_structured_response;
-  	pre_model_hook --> agent;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---
-# name: test_react_agent_graph_structure[ResponseFormat-None-pre_model_hook-tools1]
-  '''
-  graph TD;
-  	__start__ --> pre_model_hook;
-  	agent -.-> generate_structured_response;
-  	agent -.-> tools;
-  	pre_model_hook --> agent;
-  	tools --> pre_model_hook;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---
-# name: test_react_agent_graph_structure[ResponseFormat-post_model_hook-None-tools0]
-  '''
-  graph TD;
-  	__start__ --> agent;
-  	agent --> post_model_hook;
-  	post_model_hook --> generate_structured_response;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---
-# name: test_react_agent_graph_structure[ResponseFormat-post_model_hook-None-tools1]
-  '''
-  graph TD;
-  	__start__ --> agent;
-  	agent --> post_model_hook;
-  	post_model_hook -.-> agent;
-  	post_model_hook -.-> generate_structured_response;
-  	post_model_hook -.-> tools;
-  	tools --> agent;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---
-# name: test_react_agent_graph_structure[ResponseFormat-post_model_hook-pre_model_hook-tools0]
-  '''
-  graph TD;
-  	__start__ --> pre_model_hook;
-  	agent --> post_model_hook;
-  	post_model_hook --> generate_structured_response;
-  	pre_model_hook --> agent;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---
-# name: test_react_agent_graph_structure[ResponseFormat-post_model_hook-pre_model_hook-tools1]
-  '''
-  graph TD;
-  	__start__ --> pre_model_hook;
-  	agent --> post_model_hook;
-  	post_model_hook -.-> generate_structured_response;
-  	post_model_hook -.-> pre_model_hook;
-  	post_model_hook -.-> tools;
-  	pre_model_hook --> agent;
-  	tools --> pre_model_hook;
-  	generate_structured_response --> __end__;
-  
-  '''
-# ---

libs/prebuilt/tests/compose-redis.yml

@@ -0,0 +1,16 @@
+name: langgraph-tests-redis
+services:
+  redis-test:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: redis-cli ping
+      start_period: 10s
+      timeout: 1s
+      retries: 5
+      interval: 5s
+      start_interval: 1s
+    tmpfs:
+      - /data  # Use tmpfs for faster testing

libs/prebuilt/tests/model.py

@@ -1,7 +1,10 @@
+import json
+from dataclasses import asdict, is_dataclass
 from typing import (
     Any,
     Callable,
     Dict,
+    Generic,
     List,
     Literal,
     Optional,
@@ -18,16 +21,16 @@ from langchain_core.messages import (
     ToolCall,
 )
 from langchain_core.outputs import ChatGeneration, ChatResult
-from langchain_core.runnables import Runnable, RunnableLambda
+from langchain_core.runnables import Runnable
 from langchain_core.tools import BaseTool
 from pydantic import BaseModel
 
-from langgraph.prebuilt.chat_agent_executor import StructuredResponse
+from langgraph.prebuilt.chat_agent_executor import StructuredResponseT
 
 
-class FakeToolCallingModel(BaseChatModel):
-    tool_calls: Optional[list[list[ToolCall]]] = None
-    structured_response: Optional[StructuredResponse] = None
+class FakeToolCallingModel(BaseChatModel, Generic[StructuredResponseT]):
+    tool_calls: Optional[Union[list[list[ToolCall]], list[list[dict]]]] = None
+    structured_response: Optional[StructuredResponseT] = None
     index: int = 0
     tool_style: Literal["openai", "anthropic"] = "openai"
 
@@ -39,15 +42,36 @@ class FakeToolCallingModel(BaseChatModel):
         **kwargs: Any,
     ) -> ChatResult:
         """Top Level call"""
-        messages_string = "-".join([m.content for m in messages])
-        tool_calls = (
-            self.tool_calls[self.index % len(self.tool_calls)]
-            if self.tool_calls
-            else []
-        )
-        message = AIMessage(
-            content=messages_string, id=str(self.index), tool_calls=tool_calls.copy()
-        )
+        rf = kwargs.get("response_format")
+        is_native = isinstance(rf, dict) and rf.get("type") == "json_schema"
+
+        if self.tool_calls:
+            if is_native:
+                tool_calls = (
+                    self.tool_calls[self.index]
+                    if self.index < len(self.tool_calls)
+                    else []
+                )
+            else:
+                tool_calls = self.tool_calls[self.index % len(self.tool_calls)]
+        else:
+            tool_calls = []
+
+        if is_native and not tool_calls:
+            if isinstance(self.structured_response, BaseModel):
+                content_obj = self.structured_response.model_dump()
+            elif is_dataclass(self.structured_response):
+                content_obj = asdict(self.structured_response)
+            elif isinstance(self.structured_response, dict):
+                content_obj = self.structured_response
+            message = AIMessage(content=json.dumps(content_obj), id=str(self.index))
+        else:
+            messages_string = "-".join([m.content for m in messages])
+            message = AIMessage(
+                content=messages_string,
+                id=str(self.index),
+                tool_calls=tool_calls.copy(),
+            )
         self.index += 1
         return ChatResult(generations=[ChatGeneration(message=message)])
 
@@ -55,14 +79,6 @@ class FakeToolCallingModel(BaseChatModel):
     def _llm_type(self) -> str:
         return "fake-tool-call-model"
 
-    def with_structured_output(
-        self, schema: Type[BaseModel]
-    ) -> Runnable[LanguageModelInput, StructuredResponse]:
-        if self.structured_response is None:
-            raise ValueError("Structured response is not set")
-
-        return RunnableLambda(lambda x: self.structured_response)
-
     def bind_tools(
         self,
         tools: Sequence[Union[Dict[str, Any], Type[BaseModel], Callable, BaseTool]],

libs/prebuilt/tests/specifications/responses.json

@@ -0,0 +1,87 @@
+[
+    {
+      "name": "updated structured response",
+      "responseFormat": [
+        {
+          "title": "role_schema_structured_output",
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "role": { "type": "string" }
+          },
+          "required": ["name", "role"]
+        },
+        {
+          "title": "department_schema_structured_output",
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "department": { "type": "string" }
+          },
+          "required": ["name", "department"]
+        }
+      ],
+      "assertionsByInvocation": [
+        {
+          "prompt": "What is the role of Sabine?",
+          "toolsWithExpectedCalls": {
+            "getEmployeeRole": 1,
+            "getEmployeeDepartment": 0
+          },
+          "expectedLastMessage": "Returning structured response: {'name': 'Sabine', 'role': 'Developer'}",
+          "expectedStructuredResponse": { "name": "Sabine", "role": "Developer" },
+          "llmRequestCount": 2
+        },
+        {
+          "prompt": "In which department does Henrik work?",
+          "toolsWithExpectedCalls": {
+            "getEmployeeRole": 1,
+            "getEmployeeDepartment": 1
+          },
+          "expectedLastMessage": "Returning structured response: {'name': 'Henrik', 'department': 'IT'}",
+          "expectedStructuredResponse": { "name": "Henrik", "department": "IT" },
+          "llmRequestCount": 4
+        }
+      ]
+    },
+    {
+      "name": "asking for information that does not fit into the response format",
+      "responseFormat": [
+        {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "role": { "type": "string" }
+            },
+            "required": ["name", "role"]
+          }
+        },
+        {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "department": { "type": "string" }
+            },
+            "required": ["name", "department"]
+          }
+        }
+      ],
+      "assertionsByInvocation": [
+        {
+          "prompt": "How much does Saskia earn?",
+          "toolsWithExpectedCalls": {
+            "getEmployeeRole": 1,
+            "getEmployeeDepartment": 0
+          },
+          "expectedLastMessage": "Returning structured response: {'name': 'Saskia', 'role': 'Software Engineer'}",
+          "expectedStructuredResponse": {
+            "name": "Saskia",
+            "role": "Software Engineer"
+          },
+          "llmRequestCount": 2
+        }
+      ]
+    }
+  ]

libs/prebuilt/tests/specifications/return_direct.json

@@ -0,0 +1,48 @@
+[
+  {
+    "name": "Scenario: NO return_direct, NO response_format",
+    "returnDirect": false,
+    "responseFormat": null,
+    "expectedToolCalls": 10,
+    "expectedLastMessage": "Attempts: 10",
+    "expectedStructuredResponse": null
+  },
+  {
+    "name": "Scenario: NO return_direct, YES response_format",
+    "returnDirect": false,
+    "responseFormat": {
+      "type": "object",
+      "properties": {
+        "attempts": { "type": "number" },
+        "succeeded": { "type": "boolean" }
+      },
+      "required": ["attempts", "succeeded"]
+    },
+    "expectedToolCalls": 10,
+    "expectedLastMessage": "Returning structured response: {'attempts': 10, 'succeeded': True}",
+    "expectedStructuredResponse": { "attempts": 10, "succeeded": true }
+  },
+  {
+    "name": "Scenario: YES return_direct, NO response_format",
+    "returnDirect": true,
+    "responseFormat": null,
+    "expectedToolCalls": 1,
+    "expectedLastMessage": "{\"status\": \"pending\", \"attempts\": 1}",
+    "expectedStructuredResponse": null
+  },
+  {
+    "name": "Scenario: YES return_direct, YES response_format",
+    "returnDirect": true,
+    "responseFormat": {
+      "type": "object",
+      "properties": {
+        "attempts": { "type": "number" },
+        "succeeded": { "type": "boolean" }
+      },
+      "required": ["attempts", "succeeded"]
+    },
+    "expectedToolCalls": 1,
+    "expectedLastMessage": "{\"status\": \"pending\", \"attempts\": 1}",
+    "expectedStructuredResponse": null
+  }
+]

libs/prebuilt/tests/test_deprecation.py

@@ -14,7 +14,7 @@ class Config(TypedDict):
 @pytest.mark.filterwarnings("ignore:`get_config_jsonschema` is deprecated")
 def test_config_schema_deprecation() -> None:
     with pytest.warns(
-        LangGraphDeprecatedSinceV10,
+        DeprecationWarning,
         match="`config_schema` is deprecated and will be removed. Please use `context_schema` instead.",
     ):
         agent = create_react_agent(FakeToolCallingModel(), [], config_schema=Config)

libs/prebuilt/tests/test_react_agent.py

@@ -1,14 +1,9 @@
 import dataclasses
 import inspect
-import json
-from functools import partial
 from typing import (
     Annotated,
-    List,
     Literal,
     Optional,
-    Type,
-    TypeVar,
     Union,
 )
 
@@ -16,7 +11,6 @@ import pytest
 from langchain_core.language_models import BaseChatModel
 from langchain_core.messages import (
     AIMessage,
-    AnyMessage,
     HumanMessage,
     MessageLikeRepresentation,
     RemoveMessage,
@@ -25,27 +19,22 @@ from langchain_core.messages import (
     ToolMessage,
 )
 from langchain_core.runnables import RunnableConfig, RunnableLambda
-from langchain_core.tools import InjectedToolCallId, ToolException
+from langchain_core.tools import BaseTool, InjectedToolCallId, ToolException
 from langchain_core.tools import tool as dec_tool
 from pydantic import BaseModel, Field
-from pydantic.v1 import BaseModel as BaseModelV1
 from typing_extensions import TypedDict
 
 from langgraph.checkpoint.base import BaseCheckpointSaver
-from langgraph.config import get_stream_writer
-from langgraph.graph import START, MessagesState, StateGraph, add_messages
+from langgraph.graph import START, MessagesState, StateGraph
 from langgraph.graph.message import REMOVE_ALL_MESSAGES
 from langgraph.prebuilt import (
     ToolNode,
     create_react_agent,
-    tools_condition,
 )
 from langgraph.prebuilt.chat_agent_executor import (
     AgentState,
     AgentStatePydantic,
-    StateSchemaType,
-    _get_model,
-    _should_bind_tools,
+    StateT,
     _validate_chat_history,
 )
 from langgraph.prebuilt.tool_node import (
@@ -184,7 +173,7 @@ def test_runnable_prompt():
 
 
 @pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
-def test_prompt_with_store(version: str):
+def test_prompt_with_store(version: Literal["v1", "v2"]):
     def add(a: int, b: int):
         """Adds a and b"""
         return a + b
@@ -275,7 +264,7 @@ async def test_prompt_with_store_async():
 @pytest.mark.parametrize("tool_style", ["openai", "anthropic"])
 @pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
 @pytest.mark.parametrize("include_builtin", [True, False])
-def test_model_with_tools(tool_style: str, version: str, include_builtin: bool):
+def test_model_with_tools(tool_style: str, version: str, include_builtin: bool) -> None:
     model = FakeToolCallingModel(tool_style=tool_style)
 
     @dec_tool
@@ -288,7 +277,7 @@ def test_model_with_tools(tool_style: str, version: str, include_builtin: bool):
         """Tool 2 docstring."""
         return f"Tool 2: {some_val}"
 
-    tools = [tool1, tool2]
+    tools: list[BaseTool | dict] = [tool1, tool2]
     if include_builtin:
         tools.append(
             {
@@ -306,45 +295,12 @@ def test_model_with_tools(tool_style: str, version: str, include_builtin: bool):
             }
         )
     # check valid agent constructor
-    agent = create_react_agent(
-        model.bind_tools(tools),
-        tools,
-        version=version,
-    )
-    result = agent.nodes["tools"].invoke(
-        {
-            "messages": [
-                AIMessage(
-                    "hi?",
-                    tool_calls=[
-                        {
-                            "name": "tool1",
-                            "args": {"some_val": 2},
-                            "id": "some 1",
-                        },
-                        {
-                            "name": "tool2",
-                            "args": {"some_val": 2},
-                            "id": "some 2",
-                        },
-                    ],
-                )
-            ]
-        }
-    )
-    tool_messages: ToolMessage = result["messages"][-2:]
-    for tool_message in tool_messages:
-        assert tool_message.type == "tool"
-        assert tool_message.content in {"Tool 1: 2", "Tool 2: 2"}
-        assert tool_message.tool_call_id in {"some 1", "some 2"}
-
-    # test mismatching tool lengths
     with pytest.raises(ValueError):
-        create_react_agent(model.bind_tools([tool1]), [tool1, tool2])
-
-    # test missing bound tools
-    with pytest.raises(ValueError):
-        create_react_agent(model.bind_tools([tool1]), [tool2])
+        create_react_agent(
+            model.bind_tools(tools),
+            tools,
+            version=version,
+        )
 
 
 def test__validate_messages():
@@ -478,27 +434,46 @@ def test_react_agent_with_structured_response(version: str) -> None:
     class WeatherResponse(BaseModel):
         temperature: float = Field(description="The temperature in fahrenheit")
 
-    tool_calls = [[{"args": {}, "id": "1", "name": "get_weather"}], []]
+    tool_calls = [
+        [{"args": {}, "id": "1", "name": "get_weather"}],
+        [{"name": "WeatherResponse", "id": "2", "args": {"temperature": 75}}],
+    ]
 
     def get_weather():
         """Get the weather"""
         return "The weather is sunny and 75°F."
 
     expected_structured_response = WeatherResponse(temperature=75)
-    model = FakeToolCallingModel(
+    model = FakeToolCallingModel[WeatherResponse](
         tool_calls=tool_calls, structured_response=expected_structured_response
     )
-    for response_format in (WeatherResponse, ("Meow", WeatherResponse)):
-        agent = create_react_agent(
-            model,
-            [get_weather],
-            response_format=response_format,
-            version=version,
-        )
-        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
-        assert response["structured_response"] == expected_structured_response
-        assert len(response["messages"]) == 4
-        assert response["messages"][-2].content == "The weather is sunny and 75°F."
+    agent = create_react_agent(
+        model,
+        [get_weather],
+        response_format=WeatherResponse,
+        version=version,
+    )
+    response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+    assert response["structured_response"] == expected_structured_response
+    assert len(response["messages"]) == 5
+
+    # Check message types in message history
+    msg_types = [m.type for m in response["messages"]]
+    assert msg_types == [
+        "human",  # "What's the weather?"
+        "ai",  # "What's the weather?"
+        "tool",  # "The weather is sunny and 75°F."
+        "ai",  # structured response
+        "tool",  # artificial tool message
+    ]
+
+    assert [m.content for m in response["messages"]] == [
+        "What's the weather?",
+        "What's the weather?",
+        "The weather is sunny and 75°F.",
+        "What's the weather?-What's the weather?-The weather is sunny and 75°F.",
+        "Returning structured response: {'temperature': 75.0}",
+    ]
 
 
 class CustomState(AgentState):
@@ -514,7 +489,7 @@ class CustomStatePydantic(AgentStatePydantic):
 def test_react_agent_update_state(
     sync_checkpointer: BaseCheckpointSaver,
     version: Literal["v1", "v2"],
-    state_schema: StateSchemaType,
+    state_schema: StateT,
 ) -> None:
     @dec_tool
     def get_user_name(tool_call_id: Annotated[str, InjectedToolCallId]):
@@ -654,124 +629,6 @@ def test_react_agent_parallel_tool_calls(
         assert get_weather_execution_count == 1
 
 
-class _InjectStateSchema(TypedDict):
-    messages: list
-    foo: str
-
-
-class _InjectedStatePydanticSchema(BaseModelV1):
-    messages: list
-    foo: str
-
-
-class _InjectedStatePydanticV2Schema(BaseModel):
-    messages: list
-    foo: str
-
-
-@dataclasses.dataclass
-class _InjectedStateDataclassSchema:
-    messages: list
-    foo: str
-
-
-T = TypeVar("T")
-
-
-@pytest.mark.parametrize(
-    "schema_",
-    [
-        _InjectStateSchema,
-        _InjectedStatePydanticSchema,
-        _InjectedStatePydanticV2Schema,
-        _InjectedStateDataclassSchema,
-    ],
-)
-def test_tool_node_inject_state(schema_: Type[T]) -> None:
-    def tool1(some_val: int, state: Annotated[T, InjectedState]) -> str:
-        """Tool 1 docstring."""
-        if isinstance(state, dict):
-            return state["foo"]
-        else:
-            return getattr(state, "foo")
-
-    def tool2(some_val: int, state: Annotated[T, InjectedState()]) -> str:
-        """Tool 2 docstring."""
-        if isinstance(state, dict):
-            return state["foo"]
-        else:
-            return getattr(state, "foo")
-
-    def tool3(
-        some_val: int,
-        foo: Annotated[str, InjectedState("foo")],
-        msgs: Annotated[List[AnyMessage], InjectedState("messages")],
-    ) -> str:
-        """Tool 1 docstring."""
-        return foo
-
-    def tool4(
-        some_val: int, msgs: Annotated[List[AnyMessage], InjectedState("messages")]
-    ) -> str:
-        """Tool 1 docstring."""
-        return msgs[0].content
-
-    node = ToolNode([tool1, tool2, tool3, tool4])
-    for tool_name in ("tool1", "tool2", "tool3"):
-        tool_call = {
-            "name": tool_name,
-            "args": {"some_val": 1},
-            "id": "some 0",
-            "type": "tool_call",
-        }
-        msg = AIMessage("hi?", tool_calls=[tool_call])
-        result = node.invoke(schema_(**{"messages": [msg], "foo": "bar"}))
-        tool_message = result["messages"][-1]
-        assert tool_message.content == "bar", f"Failed for tool={tool_name}"
-
-        if tool_name == "tool3":
-            failure_input = None
-            try:
-                failure_input = schema_(**{"messages": [msg], "notfoo": "bar"})
-            except Exception:
-                pass
-            if failure_input is not None:
-                with pytest.raises(KeyError):
-                    node.invoke(failure_input)
-
-                with pytest.raises(ValueError):
-                    node.invoke([msg])
-        else:
-            failure_input = None
-            try:
-                failure_input = schema_(**{"messages": [msg], "notfoo": "bar"})
-            except Exception:
-                # We'd get a validation error from pydantic state and wouldn't make it to the node
-                # anyway
-                pass
-            if failure_input is not None:
-                messages_ = node.invoke(failure_input)
-                tool_message = messages_["messages"][-1]
-                assert "KeyError" in tool_message.content
-                tool_message = node.invoke([msg])[-1]
-                assert "KeyError" in tool_message.content
-
-    tool_call = {
-        "name": "tool4",
-        "args": {"some_val": 1},
-        "id": "some 0",
-        "type": "tool_call",
-    }
-    msg = AIMessage("hi?", tool_calls=[tool_call])
-    result = node.invoke(schema_(**{"messages": [msg], "foo": ""}))
-    tool_message = result["messages"][-1]
-    assert tool_message.content == "hi?"
-
-    result = node.invoke([msg])
-    tool_message = result[-1]
-    assert tool_message.content == "hi?"
-
-
 class AgentStateExtraKey(AgentState):
     foo: int
 
@@ -785,7 +642,7 @@ class AgentStateExtraKeyPydantic(AgentStatePydantic):
     "state_schema", [AgentStateExtraKey, AgentStateExtraKeyPydantic]
 )
 def test_create_react_agent_inject_vars(
-    version: Literal["v1", "v2"], state_schema: StateSchemaType
+    version: Literal["v1", "v2"], state_schema: StateT
 ) -> None:
     """Test that the agent can inject state and store into tool functions."""
     store = InMemoryStore()
@@ -837,135 +694,6 @@ def test_create_react_agent_inject_vars(
     assert result["foo"] == 2
 
 
-def test_tool_node_inject_store() -> None:
-    store = InMemoryStore()
-    namespace = ("test",)
-
-    def tool1(some_val: int, store: Annotated[BaseStore, InjectedStore()]) -> str:
-        """Tool 1 docstring."""
-        store_val = store.get(namespace, "test_key").value["foo"]
-        return f"Some val: {some_val}, store val: {store_val}"
-
-    def tool2(some_val: int, store: Annotated[BaseStore, InjectedStore()]) -> str:
-        """Tool 2 docstring."""
-        store_val = store.get(namespace, "test_key").value["foo"]
-        return f"Some val: {some_val}, store val: {store_val}"
-
-    def tool3(
-        some_val: int,
-        bar: Annotated[str, InjectedState("bar")],
-        store: Annotated[BaseStore, InjectedStore()],
-    ) -> str:
-        """Tool 3 docstring."""
-        store_val = store.get(namespace, "test_key").value["foo"]
-        return f"Some val: {some_val}, store val: {store_val}, state val: {bar}"
-
-    node = ToolNode([tool1, tool2, tool3], handle_tool_errors=True)
-    store.put(namespace, "test_key", {"foo": "bar"})
-
-    class State(MessagesState):
-        bar: str
-
-    builder = StateGraph(State)
-    builder.add_node("tools", node)
-    builder.add_edge(START, "tools")
-    graph = builder.compile(store=store)
-
-    for tool_name in ("tool1", "tool2"):
-        tool_call = {
-            "name": tool_name,
-            "args": {"some_val": 1},
-            "id": "some 0",
-            "type": "tool_call",
-        }
-        msg = AIMessage("hi?", tool_calls=[tool_call])
-        node_result = node.invoke({"messages": [msg]}, store=store)
-        graph_result = graph.invoke({"messages": [msg]})
-        for result in (node_result, graph_result):
-            result["messages"][-1]
-            tool_message = result["messages"][-1]
-            assert tool_message.content == "Some val: 1, store val: bar", (
-                f"Failed for tool={tool_name}"
-            )
-
-    tool_call = {
-        "name": "tool3",
-        "args": {"some_val": 1},
-        "id": "some 0",
-        "type": "tool_call",
-    }
-    msg = AIMessage("hi?", tool_calls=[tool_call])
-    node_result = node.invoke({"messages": [msg], "bar": "baz"}, store=store)
-    graph_result = graph.invoke({"messages": [msg], "bar": "baz"})
-    for result in (node_result, graph_result):
-        result["messages"][-1]
-        tool_message = result["messages"][-1]
-        assert tool_message.content == "Some val: 1, store val: bar, state val: baz", (
-            f"Failed for tool={tool_name}"
-        )
-
-    # test injected store without passing store to compiled graph
-    failing_graph = builder.compile()
-    with pytest.raises(ValueError):
-        failing_graph.invoke({"messages": [msg], "bar": "baz"})
-
-
-def test_tool_node_ensure_utf8() -> None:
-    @dec_tool
-    def get_day_list(days: list[str]) -> list[str]:
-        """choose days"""
-        return days
-
-    data = ["星期一", "水曜日", "목요일", "Friday"]
-    tools = [get_day_list]
-    tool_calls = [ToolCall(name=get_day_list.name, args={"days": data}, id="test_id")]
-    outputs: list[ToolMessage] = ToolNode(tools).invoke(
-        [AIMessage(content="", tool_calls=tool_calls)]
-    )
-    assert outputs[0].content == json.dumps(data, ensure_ascii=False)
-
-
-def test_tool_node_messages_key() -> None:
-    @dec_tool
-    def add(a: int, b: int):
-        """Adds a and b."""
-        return a + b
-
-    model = FakeToolCallingModel(
-        tool_calls=[[ToolCall(name=add.name, args={"a": 1, "b": 2}, id="test_id")]]
-    )
-
-    class State(TypedDict):
-        subgraph_messages: Annotated[list[AnyMessage], add_messages]
-
-    def call_model(state: State):
-        response = model.invoke(state["subgraph_messages"])
-        model.tool_calls = []
-        return {"subgraph_messages": response}
-
-    builder = StateGraph(State)
-    builder.add_node("agent", call_model)
-    builder.add_node("tools", ToolNode([add], messages_key="subgraph_messages"))
-    builder.add_conditional_edges(
-        "agent", partial(tools_condition, messages_key="subgraph_messages")
-    )
-    builder.add_edge(START, "agent")
-    builder.add_edge("tools", "agent")
-
-    graph = builder.compile()
-    result = graph.invoke({"subgraph_messages": [HumanMessage(content="hi")]})
-    assert result["subgraph_messages"] == [
-        _AnyIdHumanMessage(content="hi"),
-        AIMessage(
-            content="hi",
-            id="0",
-            tool_calls=[ToolCall(name=add.name, args={"a": 1, "b": 2}, id="test_id")],
-        ),
-        _AnyIdToolMessage(content="3", name=add.name, tool_call_id="test_id"),
-        AIMessage(content="hi-hi-3", id="1"),
-    ]
-
-
 @pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
 async def test_return_direct(version: str) -> None:
     @dec_tool(return_direct=True)
@@ -1182,60 +910,6 @@ def test_react_with_subgraph_tools(
     ]
 
 
-def test_tool_node_stream_writer() -> None:
-    @dec_tool
-    def streaming_tool(x: int) -> str:
-        """Do something with writer."""
-        my_writer = get_stream_writer()
-        for value in ["foo", "bar", "baz"]:
-            my_writer({"custom_tool_value": value})
-
-        return x
-
-    tool_node = ToolNode([streaming_tool])
-    graph = (
-        StateGraph(MessagesState)
-        .add_node("tools", tool_node)
-        .add_edge(START, "tools")
-        .compile()
-    )
-
-    tool_call = {
-        "name": "streaming_tool",
-        "args": {"x": 1},
-        "id": "1",
-        "type": "tool_call",
-    }
-    inputs = {
-        "messages": [AIMessage("", tool_calls=[tool_call])],
-    }
-
-    assert list(graph.stream(inputs, stream_mode="custom")) == [
-        {"custom_tool_value": "foo"},
-        {"custom_tool_value": "bar"},
-        {"custom_tool_value": "baz"},
-    ]
-    assert list(graph.stream(inputs, stream_mode=["custom", "updates"])) == [
-        ("custom", {"custom_tool_value": "foo"}),
-        ("custom", {"custom_tool_value": "bar"}),
-        ("custom", {"custom_tool_value": "baz"}),
-        (
-            "updates",
-            {
-                "tools": {
-                    "messages": [
-                        _AnyIdToolMessage(
-                            content="1",
-                            name="streaming_tool",
-                            tool_call_id="1",
-                        ),
-                    ],
-                },
-            },
-        ),
-    ]
-
-
 @pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
 def test_react_agent_subgraph_streaming_sync(version: Literal["v1", "v2"]) -> None:
     """Test React agent streaming when used as a subgraph node sync version"""
@@ -1491,69 +1165,6 @@ def test_tool_node_node_interrupt(
     )
 
 
-@pytest.mark.parametrize("tool_style", ["openai", "anthropic"])
-def test_should_bind_tools(tool_style: str) -> None:
-    @dec_tool
-    def some_tool(some_val: int) -> str:
-        """Tool docstring."""
-        return "meow"
-
-    @dec_tool
-    def some_other_tool(some_val: int) -> str:
-        """Tool docstring."""
-        return "meow"
-
-    model = FakeToolCallingModel(tool_style=tool_style)
-    # should bind when a regular model
-    assert _should_bind_tools(model, [])
-    assert _should_bind_tools(model, [some_tool])
-
-    # should bind when a seq
-    seq = model | RunnableLambda(lambda message: message)
-    assert _should_bind_tools(seq, [])
-    assert _should_bind_tools(seq, [some_tool])
-
-    # should not bind when a model with tools
-    assert not _should_bind_tools(model.bind_tools([some_tool]), [some_tool])
-    # should not bind when a seq with tools
-    seq_with_tools = model.bind_tools([some_tool]) | RunnableLambda(
-        lambda message: message
-    )
-    assert not _should_bind_tools(seq_with_tools, [some_tool])
-
-    # should raise on invalid inputs
-    with pytest.raises(ValueError):
-        _should_bind_tools(model.bind_tools([some_tool]), [])
-    with pytest.raises(ValueError):
-        _should_bind_tools(model.bind_tools([some_tool]), [some_other_tool])
-    with pytest.raises(ValueError):
-        _should_bind_tools(model.bind_tools([some_tool]), [some_tool, some_other_tool])
-
-
-def test_get_model() -> None:
-    model = FakeToolCallingModel(tool_calls=[])
-    assert _get_model(model) == model
-
-    @dec_tool
-    def some_tool(some_val: int) -> str:
-        """Tool docstring."""
-        return "meow"
-
-    model_with_tools = model.bind_tools([some_tool])
-    assert _get_model(model_with_tools) == model
-
-    seq = model | RunnableLambda(lambda message: message)
-    assert _get_model(seq) == model
-
-    seq_with_tools = model.bind_tools([some_tool]) | RunnableLambda(
-        lambda message: message
-    )
-    assert _get_model(seq_with_tools) == model
-
-    with pytest.raises(TypeError):
-        _get_model(RunnableLambda(lambda message: message))
-
-
 @pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
 def test_dynamic_model_basic(version: str) -> None:
     """Test basic dynamic model functionality."""
@@ -1730,9 +1341,17 @@ def test_dynamic_model_with_structured_response(version: str) -> None:
         confidence: float
 
     def dynamic_model(state, runtime: Runtime):
-        expected_response = TestResponse(message="dynamic response", confidence=0.9)
         return FakeToolCallingModel(
-            tool_calls=[], structured_response=expected_response
+            tool_calls=[
+                [
+                    ToolCall(
+                        name="TestResponse",
+                        args={"message": "dynamic response", "confidence": 0.9},
+                        id="1",
+                        type="tool_call",
+                    )
+                ]
+            ],
         )
 
     agent = create_react_agent(
@@ -1997,16 +1616,16 @@ def test_post_model_hook_with_structured_output() -> None:
     class WeatherResponse(BaseModel):
         temperature: float = Field(description="The temperature in fahrenheit")
 
-    tool_calls = [[{"args": {}, "id": "1", "name": "get_weather"}]]
+    tool_calls: list[list[ToolCall]] = [
+        [{"args": {}, "id": "1", "name": "get_weather"}],
+        [{"args": {"temperature": 75}, "id": "2", "name": "WeatherResponse"}],
+    ]
 
     def get_weather():
         """Get the weather"""
         return "The weather is sunny and 75°F."
 
     expected_structured_response = WeatherResponse(temperature=75)
-    model = FakeToolCallingModel(
-        tool_calls=tool_calls, structured_response=expected_structured_response
-    )
 
     class State(AgentState):
         flag: bool
@@ -2015,6 +1634,7 @@ def test_post_model_hook_with_structured_output() -> None:
     def post_model_hook(state: State) -> Union[dict[str, bool], Command]:
         return {"flag": True}
 
+    model = FakeToolCallingModel(tool_calls=tool_calls)
     agent = create_react_agent(
         model,
         [get_weather],
@@ -2024,7 +1644,6 @@ def test_post_model_hook_with_structured_output() -> None:
     )
 
     assert "post_model_hook" in agent.nodes
-    assert "generate_structured_response" in agent.nodes
 
     response = agent.invoke(
         {"messages": [HumanMessage("What's the weather?")], "flag": False}
@@ -2032,10 +1651,19 @@ def test_post_model_hook_with_structured_output() -> None:
     assert response["flag"] is True
     assert response["structured_response"] == expected_structured_response
 
+    # Reset the state of the model
+    model = FakeToolCallingModel(tool_calls=tool_calls)
+    agent = create_react_agent(
+        model,
+        [get_weather],
+        response_format=WeatherResponse,
+        post_model_hook=post_model_hook,
+        state_schema=State,
+    )
+
     events = list(
         agent.stream({"messages": [HumanMessage("What's the weather?")], "flag": False})
     )
-    assert "generate_structured_response" in events[-1]
     assert events == [
         {
             "agent": {
@@ -2044,7 +1672,7 @@ def test_post_model_hook_with_structured_output() -> None:
                         content="What's the weather?",
                         additional_kwargs={},
                         response_metadata={},
-                        id="2",
+                        id="0",
                         tool_calls=[
                             {
                                 "name": "get_weather",
@@ -2065,7 +1693,7 @@ def test_post_model_hook_with_structured_output() -> None:
                         content="The weather is sunny and 75°F.",
                         name="get_weather",
                         tool_call_id="1",
-                    ),
+                    )
                 ]
             }
         },
@@ -2076,25 +1704,26 @@ def test_post_model_hook_with_structured_output() -> None:
                         content="What's the weather?-What's the weather?-The weather is sunny and 75°F.",
                         additional_kwargs={},
                         response_metadata={},
-                        id="3",
+                        id="1",
                         tool_calls=[
                             {
-                                "name": "get_weather",
-                                "args": {},
-                                "id": "1",
+                                "name": "WeatherResponse",
+                                "args": {"temperature": 75},
+                                "id": "2",
                                 "type": "tool_call",
                             }
                         ],
-                    )
-                ]
+                    ),
+                    _AnyIdToolMessage(
+                        content="Returning structured response: {'temperature': 75.0}",
+                        name="WeatherResponse",
+                        tool_call_id="2",
+                    ),
+                ],
+                "structured_response": WeatherResponse(temperature=75.0),
             }
         },
         {"post_model_hook": {"flag": True}},
-        {
-            "generate_structured_response": {
-                "structured_response": WeatherResponse(temperature=75.0)
-            }
-        },
     ]
 
 
@@ -2102,7 +1731,7 @@ def test_post_model_hook_with_structured_output() -> None:
     "state_schema", [AgentStateExtraKey, AgentStateExtraKeyPydantic]
 )
 def test_create_react_agent_inject_vars_with_post_model_hook(
-    state_schema: StateSchemaType,
+    state_schema: StateT,
 ) -> None:
     store = InMemoryStore()
     namespace = ("test",)
@@ -2157,3 +1786,40 @@ def test_create_react_agent_inject_vars_with_post_model_hook(
         AIMessage("hi-hi-6", id="1"),
     ]
     assert result["foo"] == 2
+
+
+@pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
+def test_response_format_using_tool_choice(version: Literal["v1", "v2"]) -> None:
+    """Test response format using tool choice."""
+
+    class WeatherResponse(BaseModel):
+        temperature: float = Field(description="The temperature in fahrenheit")
+
+    tool_calls: list[list[ToolCall]] = [
+        [{"args": {}, "id": "1", "name": "get_weather"}],
+        [{"args": {"temperature": "75"}, "id": "2", "name": "WeatherResponse"}],
+    ]
+
+    def get_weather() -> str:
+        """Get the weather"""
+        return "The weather is sunny and 75°F."
+
+    expected_structured_response = WeatherResponse(temperature=75)
+    model = FakeToolCallingModel(tool_calls=tool_calls)
+    agent = create_react_agent(
+        model,
+        [get_weather],
+        response_format=WeatherResponse,
+        version=version,
+    )
+    response = agent.invoke(
+        {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "What's the weather?",
+                }
+            ]
+        }
+    )
+    assert response.get("structured_response") == expected_structured_response

libs/prebuilt/tests/test_react_agent_graph.py

@@ -34,19 +34,25 @@ class ResponseFormat(BaseModel):
 @pytest.mark.parametrize("tools", [[], [tool]])
 @pytest.mark.parametrize("pre_model_hook", [None, pre_model_hook])
 @pytest.mark.parametrize("post_model_hook", [None, post_model_hook])
-@pytest.mark.parametrize("response_format", [None, ResponseFormat])
 def test_react_agent_graph_structure(
     snapshot: SnapshotAssertion,
     tools: list[Callable],
     pre_model_hook: Union[Callable, None],
     post_model_hook: Union[Callable, None],
-    response_format: Union[type[BaseModel], None],
 ) -> None:
     agent = create_react_agent(
         model,
         tools=tools,
         pre_model_hook=pre_model_hook,
         post_model_hook=post_model_hook,
-        response_format=response_format,
     )
-    assert agent.get_graph().draw_mermaid(with_styles=False) == snapshot
+    try:
+        assert agent.get_graph().draw_mermaid(with_styles=False) == snapshot
+    except Exception as e:
+        raise ValueError(
+            "The graph structure has changed. Please update the snapshot."
+            "Configuration used:\n"
+            f"tools: {tools}, "
+            f"pre_model_hook: {pre_model_hook}, "
+            f"post_model_hook: {post_model_hook}, "
+        ) from e

libs/prebuilt/tests/test_response_format.py

@@ -0,0 +1,793 @@
+"""Test suite for create_react_agent with structured output response_format permutations."""
+
+from dataclasses import dataclass
+from typing import Union
+
+import pytest
+from langchain_core.messages import HumanMessage
+from pydantic import BaseModel, Field
+from typing_extensions import TypedDict
+
+from langgraph.prebuilt import create_react_agent
+from langgraph.prebuilt.responses import (
+    MultipleStructuredOutputsError,
+    NativeOutput,
+    StructuredOutputParsingError,
+    ToolOutput,
+)
+from tests.model import FakeToolCallingModel
+
+try:
+    from langchain_openai import ChatOpenAI
+except ImportError:
+    skip_openai_integration_tests = True
+else:
+    skip_openai_integration_tests = False
+
+
+# Test data models
+class WeatherBaseModel(BaseModel):
+    """Weather response."""
+
+    temperature: float = Field(description="The temperature in fahrenheit")
+    condition: str = Field(description="Weather condition")
+
+
+@dataclass
+class WeatherDataclass:
+    """Weather response."""
+
+    temperature: float
+    condition: str
+
+
+class WeatherTypedDict(TypedDict):
+    """Weather response."""
+
+    temperature: float
+    condition: str
+
+
+weather_json_schema = {
+    "type": "object",
+    "properties": {
+        "temperature": {"type": "number", "description": "Temperature in fahrenheit"},
+        "condition": {"type": "string", "description": "Weather condition"},
+    },
+    "title": "weather_schema",
+    "required": ["temperature", "condition"],
+}
+
+
+class LocationResponse(BaseModel):
+    city: str = Field(description="The city name")
+    country: str = Field(description="The country name")
+
+
+class LocationTypedDict(TypedDict):
+    city: str
+    country: str
+
+
+location_json_schema = {
+    "type": "object",
+    "properties": {
+        "city": {"type": "string", "description": "The city name"},
+        "country": {"type": "string", "description": "The country name"},
+    },
+    "title": "location_schema",
+    "required": ["city", "country"],
+}
+
+
+def get_weather() -> str:
+    """Get the weather."""
+
+    return "The weather is sunny and 75°F."
+
+
+def get_location() -> str:
+    """Get the current location."""
+
+    return "You are in New York, USA."
+
+
+# Standardized test data
+WEATHER_DATA = {"temperature": 75.0, "condition": "sunny"}
+LOCATION_DATA = {"city": "New York", "country": "USA"}
+
+# Standardized expected responses
+EXPECTED_WEATHER_PYDANTIC = WeatherBaseModel(**WEATHER_DATA)
+EXPECTED_WEATHER_DATACLASS = WeatherDataclass(**WEATHER_DATA)
+EXPECTED_WEATHER_DICT: WeatherTypedDict = {"temperature": 75.0, "condition": "sunny"}
+EXPECTED_LOCATION = LocationResponse(**LOCATION_DATA)
+EXPECTED_LOCATION_DICT: LocationTypedDict = {"city": "New York", "country": "USA"}
+
+
+class TestResponseFormatAsModel:
+    def test_pydantic_model(self) -> None:
+        """Test response_format as Pydantic model."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=WeatherBaseModel
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+        assert len(response["messages"]) == 5
+
+    def test_dataclass(self) -> None:
+        """Test response_format as dataclass."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "WeatherDataclass",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=WeatherDataclass
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DATACLASS
+        assert len(response["messages"]) == 5
+
+    def test_typed_dict(self) -> None:
+        """Test response_format as TypedDict."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "WeatherTypedDict",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=WeatherTypedDict
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DICT
+        assert len(response["messages"]) == 5
+
+    def test_json_schema(self) -> None:
+        """Test response_format as JSON schema."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "weather_schema",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=weather_json_schema
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DICT
+        assert len(response["messages"]) == 5
+
+
+class TestResponseFormatAsToolOutput:
+    def test_pydantic_model(self) -> None:
+        """Test response_format as ToolOutput with Pydantic model."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=ToolOutput(WeatherBaseModel)
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+        assert len(response["messages"]) == 5
+
+    def test_dataclass(self) -> None:
+        """Test response_format as ToolOutput with dataclass."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "WeatherDataclass",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=ToolOutput(WeatherDataclass)
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DATACLASS
+        assert len(response["messages"]) == 5
+
+    def test_typed_dict(self) -> None:
+        """Test response_format as ToolOutput with TypedDict."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "WeatherTypedDict",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=ToolOutput(WeatherTypedDict)
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DICT
+        assert len(response["messages"]) == 5
+
+    def test_json_schema(self) -> None:
+        """Test response_format as ToolOutput with JSON schema."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "weather_schema",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=ToolOutput(weather_json_schema)
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DICT
+        assert len(response["messages"]) == 5
+
+    def test_union_of_json_schemas(self) -> None:
+        """Test response_format as ToolOutput with union of JSON schemas."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "weather_schema",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model,
+            [get_weather, get_location],
+            response_format=ToolOutput(
+                {"oneOf": [weather_json_schema, location_json_schema]}
+            ),
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DICT
+        assert len(response["messages"]) == 5
+
+        # Test with LocationResponse
+        tool_calls_location = [
+            [{"args": {}, "id": "1", "name": "get_location"}],
+            [
+                {
+                    "name": "location_schema",
+                    "id": "2",
+                    "args": LOCATION_DATA,
+                }
+            ],
+        ]
+
+        model_location = FakeToolCallingModel(tool_calls=tool_calls_location)
+
+        agent_location = create_react_agent(
+            model_location,
+            [get_weather, get_location],
+            response_format=ToolOutput(
+                {"oneOf": [weather_json_schema, location_json_schema]}
+            ),
+        )
+        response_location = agent_location.invoke(
+            {"messages": [HumanMessage("Where am I?")]}
+        )
+
+        assert response_location["structured_response"] == EXPECTED_LOCATION_DICT
+        assert len(response_location["messages"]) == 5
+
+    def test_union_of_types(self) -> None:
+        """Test response_format as ToolOutput with Union of various types."""
+        # Test with WeatherBaseModel
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                }
+            ],
+        ]
+
+        model = FakeToolCallingModel[Union[WeatherBaseModel, LocationResponse]](
+            tool_calls=tool_calls
+        )
+
+        agent = create_react_agent(
+            model,
+            [get_weather, get_location],
+            response_format=ToolOutput(Union[WeatherBaseModel, LocationResponse]),
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+        assert len(response["messages"]) == 5
+
+        # Test with LocationResponse
+        tool_calls_location = [
+            [{"args": {}, "id": "1", "name": "get_location"}],
+            [
+                {
+                    "name": "LocationResponse",
+                    "id": "2",
+                    "args": LOCATION_DATA,
+                }
+            ],
+        ]
+
+        model_location = FakeToolCallingModel(tool_calls=tool_calls_location)
+
+        agent_location = create_react_agent(
+            model_location,
+            [get_weather, get_location],
+            response_format=ToolOutput(Union[WeatherBaseModel, LocationResponse]),
+        )
+        response_location = agent_location.invoke(
+            {"messages": [HumanMessage("Where am I?")]}
+        )
+
+        assert response_location["structured_response"] == EXPECTED_LOCATION
+        assert len(response_location["messages"]) == 5
+
+    def test_multiple_structured_outputs_error_without_retry(self) -> None:
+        """Test that MultipleStructuredOutputsError is raised when model returns multiple structured tool calls without retry."""
+        tool_calls = [
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "1",
+                    "args": WEATHER_DATA,
+                },
+                {
+                    "name": "LocationResponse",
+                    "id": "2",
+                    "args": LOCATION_DATA,
+                },
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model,
+            [],
+            response_format=ToolOutput(
+                Union[WeatherBaseModel, LocationResponse],
+                handle_errors=False,
+            ),
+        )
+
+        with pytest.raises(
+            MultipleStructuredOutputsError,
+            match=".*WeatherBaseModel.*LocationResponse.*",
+        ):
+            agent.invoke({"messages": [HumanMessage("Give me weather and location")]})
+
+    def test_multiple_structured_outputs_with_retry(self) -> None:
+        """Test that retry handles multiple structured output tool calls."""
+        tool_calls = [
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "1",
+                    "args": WEATHER_DATA,
+                },
+                {
+                    "name": "LocationResponse",
+                    "id": "2",
+                    "args": LOCATION_DATA,
+                },
+            ],
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "3",
+                    "args": WEATHER_DATA,
+                },
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model,
+            [],
+            response_format=ToolOutput(
+                Union[WeatherBaseModel, LocationResponse],
+                handle_errors=True,
+            ),
+        )
+
+        response = agent.invoke({"messages": [HumanMessage("Give me weather")]})
+
+        # HumanMessage, AIMessage, ToolMessage, ToolMessage, AI, ToolMessage
+        assert len(response["messages"]) == 6
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+
+    def test_structured_output_parsing_error_without_retry(self) -> None:
+        """Test that StructuredOutputParsingError is raised when tool args fail to parse without retry."""
+        tool_calls = [
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "1",
+                    "args": {"invalid": "data"},
+                },
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model,
+            [],
+            response_format=ToolOutput(
+                WeatherBaseModel,
+                handle_errors=False,
+            ),
+        )
+
+        with pytest.raises(
+            StructuredOutputParsingError,
+            match=".*WeatherBaseModel.*",
+        ):
+            agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+    def test_structured_output_parsing_error_with_retry(self) -> None:
+        """Test that retry handles parsing errors for structured output."""
+        tool_calls = [
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "1",
+                    "args": {"invalid": "data"},
+                },
+            ],
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                },
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model,
+            [],
+            response_format=ToolOutput(
+                WeatherBaseModel,
+                handle_errors=(StructuredOutputParsingError,),
+            ),
+        )
+
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        # HumanMessage, AIMessage, ToolMessage, AIMessage, ToolMessage
+        assert len(response["messages"]) == 5
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+
+    def test_retry_with_custom_function(self) -> None:
+        """Test retry with custom message generation."""
+        tool_calls = [
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "1",
+                    "args": WEATHER_DATA,
+                },
+                {
+                    "name": "LocationResponse",
+                    "id": "2",
+                    "args": LOCATION_DATA,
+                },
+            ],
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "3",
+                    "args": WEATHER_DATA,
+                },
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        def custom_message(exception: Exception) -> str:
+            if isinstance(exception, MultipleStructuredOutputsError):
+                return "Custom error: Multiple outputs not allowed"
+            return "Custom error"
+
+        agent = create_react_agent(
+            model,
+            [],
+            response_format=ToolOutput(
+                Union[WeatherBaseModel, LocationResponse],
+                handle_errors=custom_message,
+            ),
+        )
+
+        response = agent.invoke({"messages": [HumanMessage("Give me weather")]})
+
+        # HumanMessage, AIMessage, ToolMessage, ToolMessage, AI, ToolMessage
+        assert len(response["messages"]) == 6
+        assert (
+            response["messages"][2].content
+            == "Custom error: Multiple outputs not allowed"
+        )
+        assert (
+            response["messages"][3].content
+            == "Custom error: Multiple outputs not allowed"
+        )
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+
+    def test_retry_with_custom_string_message(self) -> None:
+        """Test retry with custom static string message."""
+        tool_calls = [
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "1",
+                    "args": {"invalid": "data"},
+                },
+            ],
+            [
+                {
+                    "name": "WeatherBaseModel",
+                    "id": "2",
+                    "args": WEATHER_DATA,
+                },
+            ],
+        ]
+
+        model = FakeToolCallingModel(tool_calls=tool_calls)
+
+        agent = create_react_agent(
+            model,
+            [],
+            response_format=ToolOutput(
+                WeatherBaseModel,
+                handle_errors="Please provide valid weather data with temperature and condition.",
+            ),
+        )
+
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert len(response["messages"]) == 5
+        assert (
+            response["messages"][2].content
+            == "Please provide valid weather data with temperature and condition."
+        )
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+
+
+class TestResponseFormatAsNativeOutput:
+    def test_pydantic_model(self) -> None:
+        """Test response_format as NativeOutput with Pydantic model."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+        ]
+
+        model = FakeToolCallingModel[WeatherBaseModel](
+            tool_calls=tool_calls, structured_response=EXPECTED_WEATHER_PYDANTIC
+        )
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=NativeOutput(WeatherBaseModel)
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+        assert len(response["messages"]) == 4
+
+    def test_dataclass(self) -> None:
+        """Test response_format as NativeOutput with dataclass."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+        ]
+
+        model = FakeToolCallingModel[WeatherDataclass](
+            tool_calls=tool_calls, structured_response=EXPECTED_WEATHER_DATACLASS
+        )
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=NativeOutput(WeatherDataclass)
+        )
+        response = agent.invoke(
+            {"messages": [HumanMessage("What's the weather?")]},
+        )
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DATACLASS
+        assert len(response["messages"]) == 4
+
+    def test_typed_dict(self) -> None:
+        """Test response_format as NativeOutput with TypedDict."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+        ]
+
+        model = FakeToolCallingModel[WeatherTypedDict](
+            tool_calls=tool_calls, structured_response=EXPECTED_WEATHER_DICT
+        )
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=NativeOutput(WeatherTypedDict)
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DICT
+        assert len(response["messages"]) == 4
+
+    def test_json_schema(self) -> None:
+        """Test response_format as NativeOutput with JSON schema."""
+        tool_calls = [
+            [{"args": {}, "id": "1", "name": "get_weather"}],
+        ]
+
+        model = FakeToolCallingModel[dict](
+            tool_calls=tool_calls, structured_response=EXPECTED_WEATHER_DICT
+        )
+
+        agent = create_react_agent(
+            model, [get_weather], response_format=NativeOutput(weather_json_schema)
+        )
+        response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+        assert response["structured_response"] == EXPECTED_WEATHER_DICT
+        assert len(response["messages"]) == 4
+
+
+def test_union_of_types() -> None:
+    """Test response_format as NativeOutput with Union (if supported)."""
+    tool_calls = [
+        [{"args": {}, "id": "1", "name": "get_weather"}],
+        [
+            {
+                "name": "WeatherBaseModel",
+                "id": "2",
+                "args": WEATHER_DATA,
+            }
+        ],
+    ]
+
+    model = FakeToolCallingModel[Union[WeatherBaseModel, LocationResponse]](
+        tool_calls=tool_calls, structured_response=EXPECTED_WEATHER_PYDANTIC
+    )
+
+    agent = create_react_agent(
+        model,
+        [get_weather, get_location],
+        response_format=ToolOutput(Union[WeatherBaseModel, LocationResponse]),
+    )
+    response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+    assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC
+    assert len(response["messages"]) == 5
+
+
+@pytest.mark.skipif(
+    skip_openai_integration_tests, reason="OpenAI integration tests are disabled."
+)
+def test_inference_to_native_output() -> None:
+    """Test that native output is inferred when a model supports it."""
+    model = ChatOpenAI(model="gpt-5")
+    agent = create_react_agent(
+        model,
+        prompt="You are a helpful weather assistant. Please call the get_weather tool, then use the WeatherReport tool to generate the final response.",
+        tools=[get_weather],
+        response_format=WeatherBaseModel,
+    )
+    response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+    assert isinstance(response["structured_response"], WeatherBaseModel)
+    assert response["structured_response"].temperature == 75.0
+    assert response["structured_response"].condition.lower() == "sunny"
+    assert len(response["messages"]) == 4
+
+    assert [m.type for m in response["messages"]] == [
+        "human",  # "What's the weather?"
+        "ai",  # "What's the weather?"
+        "tool",  # "The weather is sunny and 75°F."
+        "ai",  # structured response
+    ]
+
+
+@pytest.mark.skipif(
+    skip_openai_integration_tests, reason="OpenAI integration tests are disabled."
+)
+def test_inference_to_tool_output() -> None:
+    """Test that tool output is inferred when a model supports it."""
+    model = ChatOpenAI(model="gpt-4")
+    agent = create_react_agent(
+        model,
+        prompt="You are a helpful weather assistant. Please call the get_weather tool, then use the WeatherReport tool to generate the final response.",
+        tools=[get_weather],
+        response_format=ToolOutput(WeatherBaseModel),
+    )
+    response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})
+
+    assert isinstance(response["structured_response"], WeatherBaseModel)
+    assert response["structured_response"].temperature == 75.0
+    assert response["structured_response"].condition.lower() == "sunny"
+    assert len(response["messages"]) == 5
+
+    assert [m.type for m in response["messages"]] == [
+        "human",  # "What's the weather?"
+        "ai",  # "What's the weather?"
+        "tool",  # "The weather is sunny and 75°F."
+        "ai",  # structured response
+        "tool",  # artificial tool message
+    ]

libs/prebuilt/tests/test_responses.py

@@ -0,0 +1,154 @@
+"""Unit tests for langgraph.prebuilt.responses module."""
+
+from typing import Union
+
+import pytest
+from pydantic import BaseModel
+
+from langgraph.prebuilt.responses import (
+    OutputToolBinding,
+    ToolOutput,
+    _SchemaSpec,
+)
+
+
+class _TestModel(BaseModel):
+    """A test model for structured output."""
+
+    name: str
+    age: int
+    email: str = "default@example.com"
+
+
+class CustomModel(BaseModel):
+    """Custom model with a custom docstring."""
+
+    value: float
+    description: str
+
+
+class EmptyDocModel(BaseModel):
+    # No custom docstring, should have no description in tool
+    data: str
+
+
+class TestUsingToolStrategy:
+    """Test UsingToolStrategy dataclass."""
+
+    def test_basic_creation(self):
+        """Test basic UsingToolStrategy creation."""
+        strategy = ToolOutput(schema=_TestModel)
+        assert strategy.schema == _TestModel
+        assert strategy.tool_message_content is None
+        assert len(strategy.schema_specs) == 1
+
+    def test_multiple_schemas(self):
+        """Test UsingToolStrategy with multiple schemas."""
+        strategy = ToolOutput(schema=Union[_TestModel, CustomModel])
+        assert len(strategy.schema_specs) == 2
+        assert strategy.schema_specs[0].schema == _TestModel
+        assert strategy.schema_specs[1].schema == CustomModel
+
+    def test_schema_with_tool_message_content(self):
+        """Test UsingToolStrategy with tool message content."""
+        strategy = ToolOutput(schema=_TestModel, tool_message_content="custom message")
+        assert strategy.schema == _TestModel
+        assert strategy.tool_message_content == "custom message"
+        assert len(strategy.schema_specs) == 1
+
+
+class TestOutputToolBinding:
+    """Test OutputToolBinding dataclass and its methods."""
+
+    def test_from_schema_spec_basic(self):
+        """Test basic OutputToolBinding creation from SchemaSpec."""
+        schema_spec = _SchemaSpec(schema=_TestModel)
+        tool_binding = OutputToolBinding.from_schema_spec(schema_spec)
+
+        assert tool_binding.schema == _TestModel
+        assert tool_binding.schema_kind == "pydantic"
+        assert tool_binding.tool is not None
+        assert tool_binding.tool.name == "_TestModel"
+
+    def test_from_schema_spec_with_custom_name(self):
+        """Test OutputToolBinding creation with custom name."""
+        schema_spec = _SchemaSpec(schema=_TestModel, name="custom_tool_name")
+        tool_binding = OutputToolBinding.from_schema_spec(schema_spec)
+        assert tool_binding.tool.name == "custom_tool_name"
+
+    def test_from_schema_spec_with_custom_description(self):
+        """Test OutputToolBinding creation with custom description."""
+        schema_spec = _SchemaSpec(
+            schema=_TestModel, description="Custom tool description"
+        )
+        tool_binding = OutputToolBinding.from_schema_spec(schema_spec)
+
+        assert tool_binding.tool.description == "Custom tool description"
+
+    def test_from_schema_spec_with_model_docstring(self):
+        """Test OutputToolBinding creation using model docstring as description."""
+        schema_spec = _SchemaSpec(schema=CustomModel)
+        tool_binding = OutputToolBinding.from_schema_spec(schema_spec)
+
+        assert tool_binding.tool.description == "Custom model with a custom docstring."
+
+    @pytest.mark.skip(
+        reason="Need to fix bug in langchain-core for inheritance of doc-strings."
+    )
+    def test_from_schema_spec_empty_docstring(self):
+        """Test OutputToolBinding creation with model that has default docstring."""
+
+        # Create a model with the same docstring as BaseModel
+        class DefaultDocModel(BaseModel):
+            # This should have the same docstring as BaseModel
+            pass
+
+        schema_spec = _SchemaSpec(schema=DefaultDocModel)
+        tool_binding = OutputToolBinding.from_schema_spec(schema_spec)
+
+        # Should use empty description when model has default BaseModel docstring
+        assert tool_binding.tool.description == ""
+
+    def test_parse_payload_pydantic_success(self):
+        """Test successful parsing for Pydantic model."""
+        schema_spec = _SchemaSpec(schema=_TestModel)
+        tool_binding = OutputToolBinding.from_schema_spec(schema_spec)
+
+        tool_args = {"name": "John", "age": 30}
+        result = tool_binding.parse(tool_args)
+
+        assert isinstance(result, _TestModel)
+        assert result.name == "John"
+        assert result.age == 30
+        assert result.email == "default@example.com"  # default value
+
+    def test_parse_payload_pydantic_validation_error(self):
+        """Test parsing failure for invalid Pydantic data."""
+        schema_spec = _SchemaSpec(schema=_TestModel)
+        tool_binding = OutputToolBinding.from_schema_spec(schema_spec)
+
+        # Missing required field 'name'
+        tool_args = {"age": 30}
+
+        with pytest.raises(ValueError, match="Failed to parse data to _TestModel"):
+            tool_binding.parse(tool_args)
+
+
+class TestEdgeCases:
+    """Test edge cases and error conditions."""
+
+    def test_empty_schemas_list(self) -> None:
+        """Test UsingToolStrategy with empty schemas list."""
+        strategy = ToolOutput(EmptyDocModel)
+        assert len(strategy.schema_specs) == 1
+
+    @pytest.mark.skip(
+        reason="Need to fix bug in langchain-core for inheritance of doc-strings."
+    )
+    def test_base_model_doc_constant(self) -> None:
+        """Test that BASE_MODEL_DOC constant is set correctly."""
+        binding = OutputToolBinding.from_schema_spec(_SchemaSpec(EmptyDocModel))
+        assert binding.tool.name == "EmptyDocModel"
+        assert (
+            binding.tool.description[:5] == ""
+        )  # Should be empty for default docstring

libs/prebuilt/tests/test_responses_spec.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+from unittest.mock import MagicMock
+
+import httpx
+import pytest
+from langchain_core.messages import HumanMessage
+from langchain_core.tools import tool
+from pydantic import BaseModel, create_model
+
+from langgraph.prebuilt import create_react_agent
+from langgraph.prebuilt.responses import ToolOutput
+from tests.utils import BaseSchema, load_spec
+
+try:
+    from langchain_openai import ChatOpenAI
+except ImportError:
+    skip_openai_integration_tests = True
+else:
+    skip_openai_integration_tests = False
+
+AGENT_PROMPT = "You are an HR assistant."
+
+
+class ToolCalls(BaseSchema):
+    get_employee_role: int
+    get_employee_department: int
+
+
+class AssertionByInvocation(BaseSchema):
+    prompt: str
+    tools_with_expected_calls: ToolCalls
+    expected_last_message: str
+    expected_structured_response: Optional[Dict[str, Any]]
+    llm_request_count: int
+
+
+class TestCase(BaseSchema):
+    name: str
+    response_format: Union[Dict[str, Any], List[Dict[str, Any]]]
+    assertions_by_invocation: List[AssertionByInvocation]
+
+
+class Employee(BaseModel):
+    name: str
+    role: str
+    department: str
+
+
+EMPLOYEES: list[Employee] = [
+    Employee(name="Sabine", role="Developer", department="IT"),
+    Employee(name="Henrik", role="Product Manager", department="IT"),
+    Employee(name="Jessica", role="HR", department="People"),
+]
+
+TEST_CASES = load_spec("responses", as_model=TestCase)
+
+
+def _make_tool(fn, *, name: str, description: str):
+    mock = MagicMock(side_effect=lambda *, name: fn(name=name))
+    InputModel = create_model(f"{name}_input", name=(str, ...))
+
+    @tool(name, description=description, args_schema=InputModel)
+    def _wrapped(name: str):
+        return mock(name=name)
+
+    return {"tool": _wrapped, "mock": mock}
+
+
+@pytest.mark.skipif(
+    skip_openai_integration_tests, reason="OpenAI integration tests are disabled."
+)
+@pytest.mark.parametrize("case", TEST_CASES, ids=[c.name for c in TEST_CASES])
+def test_responses_integration_matrix(case: TestCase) -> None:
+    if case.name == "asking for information that does not fit into the response format":
+        pytest.xfail(
+            "currently failing due to undefined behavior when model cannot conform to any of the structured response formats."
+        )
+
+    def get_employee_role(*, name: str) -> Optional[str]:
+        for e in EMPLOYEES:
+            if e.name == name:
+                return e.role
+        return None
+
+    def get_employee_department(*, name: str) -> Optional[str]:
+        for e in EMPLOYEES:
+            if e.name == name:
+                return e.department
+        return None
+
+    role_tool = _make_tool(
+        get_employee_role,
+        name="get_employee_role",
+        description="Get the employee role by name",
+    )
+    dept_tool = _make_tool(
+        get_employee_department,
+        name="get_employee_department",
+        description="Get the employee department by name",
+    )
+
+    response_format_spec = case.response_format
+    if isinstance(response_format_spec, dict):
+        response_format_spec = [response_format_spec]
+    # Unwrap nested schema objects
+    response_format_spec = [item.get("schema", item) for item in response_format_spec]
+    if len(response_format_spec) == 1:
+        tool_output = ToolOutput(response_format_spec[0])
+    else:
+        tool_output = ToolOutput({"oneOf": response_format_spec})
+
+    llm_request_count = 0
+
+    for assertion in case.assertions_by_invocation:
+
+        def on_request(request: httpx.Request) -> None:
+            nonlocal llm_request_count
+            llm_request_count += 1
+
+        http_client = httpx.Client(
+            event_hooks={"request": [on_request]},
+        )
+
+        model = ChatOpenAI(
+            model="gpt-4o",
+            temperature=0,
+            http_client=http_client,
+        )
+
+        agent = create_react_agent(
+            model,
+            tools=[role_tool["tool"], dept_tool["tool"]],
+            prompt=AGENT_PROMPT,
+            response_format=tool_output,
+        )
+
+        result = agent.invoke({"messages": [HumanMessage(assertion.prompt)]})
+
+        # Count tool calls
+        assert (
+            role_tool["mock"].call_count
+            == assertion.tools_with_expected_calls.get_employee_role
+        )
+        assert (
+            dept_tool["mock"].call_count
+            == assertion.tools_with_expected_calls.get_employee_department
+        )
+
+        # Count LLM calls
+        assert llm_request_count == assertion.llm_request_count
+
+        # Check last message content
+        last_message = result["messages"][-1]
+        assert last_message.content == assertion.expected_last_message
+
+        # Check structured response
+        structured_response_json = result["structured_response"]
+        assert structured_response_json == assertion.expected_structured_response

libs/prebuilt/tests/test_return_direct_spec.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from unittest.mock import MagicMock
+
+import pytest
+from langchain_core.messages import HumanMessage
+from langchain_core.tools import tool
+
+from langgraph.prebuilt import create_react_agent
+from langgraph.prebuilt.responses import ToolOutput
+from tests.utils import BaseSchema, load_spec
+
+try:
+    from langchain_openai import ChatOpenAI
+except ImportError:
+    skip_openai_integration_tests = True
+else:
+    skip_openai_integration_tests = False
+
+AGENT_PROMPT = """
+You are a strict polling bot.
+
+- Only use the "poll_job" tool until it returns { status: "succeeded" }.
+- If status is "pending", call the tool again. Do not produce a final answer.
+- When it is "succeeded", return exactly: "Attempts: <number>" with no extra text.
+"""
+
+
+class TestCase(BaseSchema):
+    name: str
+    return_direct: bool
+    response_format: Optional[Dict[str, Any]]
+    expected_tool_calls: int
+    expected_last_message: str
+    expected_structured_response: Optional[Dict[str, Any]]
+
+
+TEST_CASES = load_spec("return_direct", as_model=TestCase)
+
+
+def _make_tool(return_direct: bool):
+    attempts = 0
+
+    def _side_effect():
+        nonlocal attempts
+        attempts += 1
+        return {
+            "status": "succeeded" if attempts >= 10 else "pending",
+            "attempts": attempts,
+        }
+
+    mock = MagicMock(side_effect=_side_effect)
+
+    @tool(
+        "pollJob",
+        description=(
+            "Check the status of a long-running job. "
+            "Returns { status: 'pending' | 'succeeded', attempts: number }."
+        ),
+        return_direct=return_direct,
+    )
+    def _wrapped():
+        return mock()
+
+    return {"tool": _wrapped, "mock": mock}
+
+
+@pytest.mark.skipif(
+    skip_openai_integration_tests, reason="OpenAI integration tests are disabled."
+)
+@pytest.mark.parametrize("case", TEST_CASES, ids=[c.name for c in TEST_CASES])
+def test_return_direct_integration_matrix(case: TestCase) -> None:
+    poll_tool = _make_tool(case.return_direct)
+
+    model = ChatOpenAI(
+        model="gpt-4o",
+        temperature=0,
+    )
+
+    if case.response_format:
+        agent = create_react_agent(
+            model,
+            tools=[poll_tool["tool"]],
+            prompt=AGENT_PROMPT,
+            response_format=ToolOutput(case.response_format),
+        )
+    else:
+        agent = create_react_agent(
+            model,
+            tools=[poll_tool["tool"]],
+            prompt=AGENT_PROMPT,
+        )
+
+    result = agent.invoke(
+        {
+            "messages": [
+                HumanMessage(
+                    "Poll the job until it's done and tell me how many attempts it took."
+                )
+            ]
+        }
+    )
+
+    # Count tool calls
+    assert poll_tool["mock"].call_count == case.expected_tool_calls
+
+    # Check last message content
+    last_message = result["messages"][-1]
+    assert last_message.content == case.expected_last_message
+
+    # Check structured response
+    if case.expected_structured_response is not None:
+        structured_response_json = result["structured_response"]
+        assert structured_response_json == case.expected_structured_response
+    else:
+        assert "structured_response" not in result

libs/prebuilt/tests/test_tool_node.py

@@ -1,25 +1,49 @@
+import dataclasses
+import json
+from functools import partial
 from typing import (
     Annotated,
     Any,
+    List,
+    Type,
+    TypeVar,
     Union,
 )
 
 import pytest
 from langchain_core.messages import (
     AIMessage,
+    AnyMessage,
+    HumanMessage,
     RemoveMessage,
+    ToolCall,
     ToolMessage,
 )
 from langchain_core.tools import BaseTool, ToolException
 from langchain_core.tools import tool as dec_tool
-from pydantic import BaseModel, ValidationError
-from pydantic.v1 import ValidationError as ValidationErrorV1
+from pydantic import BaseModel
+from pydantic.v1 import BaseModel as BaseModelV1
+from typing_extensions import TypedDict
 
+from langgraph.config import get_stream_writer
 from langgraph.errors import GraphBubbleUp, GraphInterrupt
-from langgraph.graph.message import REMOVE_ALL_MESSAGES
-from langgraph.prebuilt import ToolNode
-from langgraph.prebuilt.tool_node import TOOL_CALL_ERROR_TEMPLATE
+from langgraph.graph import START, MessagesState, StateGraph
+from langgraph.graph.message import REMOVE_ALL_MESSAGES, add_messages
+from langgraph.prebuilt import (
+    ToolNode,
+)
+from langgraph.prebuilt.tool_node import (
+    TOOL_CALL_ERROR_TEMPLATE,
+    InjectedState,
+    InjectedStore,
+    ToolInvocationError,
+    tools_condition,
+)
+from langgraph.store.base import BaseStore
+from langgraph.store.memory import InMemoryStore
 from langgraph.types import Command, Send
+from tests.messages import _AnyIdHumanMessage, _AnyIdToolMessage
+from tests.model import FakeToolCallingModel
 
 pytestmark = pytest.mark.anyio
 
@@ -62,7 +86,8 @@ def tool5(some_val: int):
 tool5.handle_tool_error = "foo"
 
 
-async def test_tool_node():
+async def test_tool_node() -> None:
+    """Test tool node."""
     result = ToolNode([tool1]).invoke(
         {
             "messages": [
@@ -154,7 +179,7 @@ async def test_tool_node():
     assert tool_message.tool_call_id == "some 3"
 
 
-async def test_tool_node_tool_call_input():
+async def test_tool_node_tool_call_input() -> None:
     # Single tool call
     tool_call_1 = {
         "name": "tool1",
@@ -195,17 +220,67 @@ async def test_tool_node_tool_call_input():
     ]
 
 
-async def test_tool_node_error_handling():
-    def handle_all(e: Union[ValueError, ToolException, ValidationError]):
+def test_tool_node_error_handling_default_invocation() -> None:
+    tn = ToolNode([tool1])
+    result = tn.invoke(
+        {
+            "messages": [
+                AIMessage(
+                    "hi?",
+                    tool_calls=[
+                        {
+                            "name": "tool1",
+                            "args": {"invalid": 0, "args": "foo"},
+                            "id": "some id",
+                        },
+                    ],
+                )
+            ]
+        }
+    )
+
+    assert all(m.type == "tool" for m in result["messages"])
+    assert all(m.status == "error" for m in result["messages"])
+    assert (
+        "Error invoking tool 'tool1' with kwargs {'invalid': 0, 'args': 'foo'} with error:\n"
+        in result["messages"][0].content
+    )
+
+
+def test_tool_node_error_handling_default_exception() -> None:
+    tn = ToolNode([tool1])
+    with pytest.raises(ValueError):
+        tn.invoke(
+            {
+                "messages": [
+                    AIMessage(
+                        "hi?",
+                        tool_calls=[
+                            {
+                                "name": "tool1",
+                                "args": {"some_val": 0, "some_other_val": "foo"},
+                                "id": "some id",
+                            },
+                        ],
+                    )
+                ]
+            }
+        )
+
+
+async def test_tool_node_error_handling() -> None:
+    def handle_all(e: Union[ValueError, ToolException, ToolInvocationError]):
         return TOOL_CALL_ERROR_TEMPLATE.format(error=repr(e))
 
     # test catching all exceptions, via:
     # - handle_tool_errors = True
+    # - passing a single exception
     # - passing a tuple of all exceptions
     # - passing a callable with all exceptions in the signature
     for handle_tool_errors in (
         True,
-        (ValueError, ToolException, ValidationError),
+        Exception,
+        (ValueError, ToolException, ToolInvocationError),
         handle_all,
     ):
         result_error = await ToolNode(
@@ -257,7 +332,7 @@ async def test_tool_node_error_handling():
         assert result_error["messages"][2].tool_call_id == "another id"
 
 
-async def test_tool_node_error_handling_callable():
+async def test_tool_node_error_handling_callable() -> None:
     def handle_value_error(e: ValueError):
         return "Value error"
 
@@ -388,7 +463,7 @@ async def test_tool_node_handle_tool_errors_false():
     assert str(exc_info.value) == "Test error"
 
     # test validation errors get raised if handle_tool_errors is False
-    with pytest.raises((ValidationError, ValidationErrorV1)):
+    with pytest.raises((ToolInvocationError)):
         ToolNode([tool1], handle_tool_errors=False).invoke(
             {
                 "messages": [
@@ -1156,3 +1231,304 @@ async def test_tool_node_command_remove_all_messages():
     command = result[0]
     assert isinstance(command, Command)
     assert command.update == {"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES)]}
+
+
+class _InjectStateSchema(TypedDict):
+    messages: list
+    foo: str
+
+
+class _InjectedStatePydanticSchema(BaseModelV1):
+    messages: list
+    foo: str
+
+
+class _InjectedStatePydanticV2Schema(BaseModel):
+    messages: list
+    foo: str
+
+
+@dataclasses.dataclass
+class _InjectedStateDataclassSchema:
+    messages: list
+    foo: str
+
+
+T = TypeVar("T")
+
+
+@pytest.mark.parametrize(
+    "schema_",
+    [
+        _InjectStateSchema,
+        _InjectedStatePydanticSchema,
+        _InjectedStatePydanticV2Schema,
+        _InjectedStateDataclassSchema,
+    ],
+)
+def test_tool_node_inject_state(schema_: Type[T]) -> None:
+    def tool1(some_val: int, state: Annotated[T, InjectedState]) -> str:
+        """Tool 1 docstring."""
+        if isinstance(state, dict):
+            return state["foo"]
+        else:
+            return getattr(state, "foo")
+
+    def tool2(some_val: int, state: Annotated[T, InjectedState()]) -> str:
+        """Tool 2 docstring."""
+        if isinstance(state, dict):
+            return state["foo"]
+        else:
+            return getattr(state, "foo")
+
+    def tool3(
+        some_val: int,
+        foo: Annotated[str, InjectedState("foo")],
+        msgs: Annotated[List[AnyMessage], InjectedState("messages")],
+    ) -> str:
+        """Tool 1 docstring."""
+        return foo
+
+    def tool4(
+        some_val: int, msgs: Annotated[List[AnyMessage], InjectedState("messages")]
+    ) -> str:
+        """Tool 1 docstring."""
+        return msgs[0].content
+
+    node = ToolNode([tool1, tool2, tool3, tool4], handle_tool_errors=True)
+    for tool_name in ("tool1", "tool2", "tool3"):
+        tool_call = {
+            "name": tool_name,
+            "args": {"some_val": 1},
+            "id": "some 0",
+            "type": "tool_call",
+        }
+        msg = AIMessage("hi?", tool_calls=[tool_call])
+        result = node.invoke(schema_(**{"messages": [msg], "foo": "bar"}))
+        tool_message = result["messages"][-1]
+        assert tool_message.content == "bar", f"Failed for tool={tool_name}"
+
+        if tool_name == "tool3":
+            failure_input = None
+            try:
+                failure_input = schema_(**{"messages": [msg], "notfoo": "bar"})
+            except Exception:
+                pass
+            if failure_input is not None:
+                with pytest.raises(KeyError):
+                    node.invoke(failure_input)
+
+                with pytest.raises(ValueError):
+                    node.invoke([msg])
+        else:
+            failure_input = None
+            try:
+                failure_input = schema_(**{"messages": [msg], "notfoo": "bar"})
+            except Exception:
+                # We'd get a validation error from pydantic state and wouldn't make it to the node
+                # anyway
+                pass
+            if failure_input is not None:
+                messages_ = node.invoke(failure_input)
+                tool_message = messages_["messages"][-1]
+                assert "KeyError" in tool_message.content
+                tool_message = node.invoke([msg])[-1]
+                assert "KeyError" in tool_message.content
+
+    tool_call = {
+        "name": "tool4",
+        "args": {"some_val": 1},
+        "id": "some 0",
+        "type": "tool_call",
+    }
+    msg = AIMessage("hi?", tool_calls=[tool_call])
+    result = node.invoke(schema_(**{"messages": [msg], "foo": ""}))
+    tool_message = result["messages"][-1]
+    assert tool_message.content == "hi?"
+
+    result = node.invoke([msg])
+    tool_message = result[-1]
+    assert tool_message.content == "hi?"
+
+
+def test_tool_node_inject_store() -> None:
+    store = InMemoryStore()
+    namespace = ("test",)
+
+    def tool1(some_val: int, store: Annotated[BaseStore, InjectedStore()]) -> str:
+        """Tool 1 docstring."""
+        store_val = store.get(namespace, "test_key").value["foo"]
+        return f"Some val: {some_val}, store val: {store_val}"
+
+    def tool2(some_val: int, store: Annotated[BaseStore, InjectedStore()]) -> str:
+        """Tool 2 docstring."""
+        store_val = store.get(namespace, "test_key").value["foo"]
+        return f"Some val: {some_val}, store val: {store_val}"
+
+    def tool3(
+        some_val: int,
+        bar: Annotated[str, InjectedState("bar")],
+        store: Annotated[BaseStore, InjectedStore()],
+    ) -> str:
+        """Tool 3 docstring."""
+        store_val = store.get(namespace, "test_key").value["foo"]
+        return f"Some val: {some_val}, store val: {store_val}, state val: {bar}"
+
+    node = ToolNode([tool1, tool2, tool3], handle_tool_errors=True)
+    store.put(namespace, "test_key", {"foo": "bar"})
+
+    class State(MessagesState):
+        bar: str
+
+    builder = StateGraph(State)
+    builder.add_node("tools", node)
+    builder.add_edge(START, "tools")
+    graph = builder.compile(store=store)
+
+    for tool_name in ("tool1", "tool2"):
+        tool_call = {
+            "name": tool_name,
+            "args": {"some_val": 1},
+            "id": "some 0",
+            "type": "tool_call",
+        }
+        msg = AIMessage("hi?", tool_calls=[tool_call])
+        node_result = node.invoke({"messages": [msg]}, store=store)
+        graph_result = graph.invoke({"messages": [msg]})
+        for result in (node_result, graph_result):
+            result["messages"][-1]
+            tool_message = result["messages"][-1]
+            assert tool_message.content == "Some val: 1, store val: bar", (
+                f"Failed for tool={tool_name}"
+            )
+
+    tool_call = {
+        "name": "tool3",
+        "args": {"some_val": 1},
+        "id": "some 0",
+        "type": "tool_call",
+    }
+    msg = AIMessage("hi?", tool_calls=[tool_call])
+    node_result = node.invoke({"messages": [msg], "bar": "baz"}, store=store)
+    graph_result = graph.invoke({"messages": [msg], "bar": "baz"})
+    for result in (node_result, graph_result):
+        result["messages"][-1]
+        tool_message = result["messages"][-1]
+        assert tool_message.content == "Some val: 1, store val: bar, state val: baz", (
+            f"Failed for tool={tool_name}"
+        )
+
+    # test injected store without passing store to compiled graph
+    failing_graph = builder.compile()
+    with pytest.raises(ValueError):
+        failing_graph.invoke({"messages": [msg], "bar": "baz"})
+
+
+def test_tool_node_ensure_utf8() -> None:
+    @dec_tool
+    def get_day_list(days: list[str]) -> list[str]:
+        """choose days"""
+        return days
+
+    data = ["星期一", "水曜日", "목요일", "Friday"]
+    tools = [get_day_list]
+    tool_calls = [ToolCall(name=get_day_list.name, args={"days": data}, id="test_id")]
+    outputs: list[ToolMessage] = ToolNode(tools).invoke(
+        [AIMessage(content="", tool_calls=tool_calls)]
+    )
+    assert outputs[0].content == json.dumps(data, ensure_ascii=False)
+
+
+def test_tool_node_messages_key() -> None:
+    @dec_tool
+    def add(a: int, b: int):
+        """Adds a and b."""
+        return a + b
+
+    model = FakeToolCallingModel(
+        tool_calls=[[ToolCall(name=add.name, args={"a": 1, "b": 2}, id="test_id")]]
+    )
+
+    class State(TypedDict):
+        subgraph_messages: Annotated[list[AnyMessage], add_messages]
+
+    def call_model(state: State):
+        response = model.invoke(state["subgraph_messages"])
+        model.tool_calls = []
+        return {"subgraph_messages": response}
+
+    builder = StateGraph(State)
+    builder.add_node("agent", call_model)
+    builder.add_node("tools", ToolNode([add], messages_key="subgraph_messages"))
+    builder.add_conditional_edges(
+        "agent", partial(tools_condition, messages_key="subgraph_messages")
+    )
+    builder.add_edge(START, "agent")
+    builder.add_edge("tools", "agent")
+
+    graph = builder.compile()
+    result = graph.invoke({"subgraph_messages": [HumanMessage(content="hi")]})
+    assert result["subgraph_messages"] == [
+        _AnyIdHumanMessage(content="hi"),
+        AIMessage(
+            content="hi",
+            id="0",
+            tool_calls=[ToolCall(name=add.name, args={"a": 1, "b": 2}, id="test_id")],
+        ),
+        _AnyIdToolMessage(content="3", name=add.name, tool_call_id="test_id"),
+        AIMessage(content="hi-hi-3", id="1"),
+    ]
+
+
+def test_tool_node_stream_writer() -> None:
+    @dec_tool
+    def streaming_tool(x: int) -> str:
+        """Do something with writer."""
+        my_writer = get_stream_writer()
+        for value in ["foo", "bar", "baz"]:
+            my_writer({"custom_tool_value": value})
+
+        return x
+
+    tool_node = ToolNode([streaming_tool])
+    graph = (
+        StateGraph(MessagesState)
+        .add_node("tools", tool_node)
+        .add_edge(START, "tools")
+        .compile()
+    )
+
+    tool_call = {
+        "name": "streaming_tool",
+        "args": {"x": 1},
+        "id": "1",
+        "type": "tool_call",
+    }
+    inputs = {
+        "messages": [AIMessage("", tool_calls=[tool_call])],
+    }
+
+    assert list(graph.stream(inputs, stream_mode="custom")) == [
+        {"custom_tool_value": "foo"},
+        {"custom_tool_value": "bar"},
+        {"custom_tool_value": "baz"},
+    ]
+    assert list(graph.stream(inputs, stream_mode=["custom", "updates"])) == [
+        ("custom", {"custom_tool_value": "foo"}),
+        ("custom", {"custom_tool_value": "bar"}),
+        ("custom", {"custom_tool_value": "baz"}),
+        (
+            "updates",
+            {
+                "tools": {
+                    "messages": [
+                        _AnyIdToolMessage(
+                            content="1",
+                            name="streaming_tool",
+                            tool_call_id="1",
+                        ),
+                    ],
+                },
+            },
+        ),
+    ]

libs/prebuilt/tests/utils.py

@@ -0,0 +1,22 @@
+import json
+from pathlib import Path
+from typing import Type
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class BaseSchema(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+def load_spec(spec_name: str, as_model: Type[BaseModel]) -> list[BaseModel]:
+    with (Path(__file__).parent / "specifications" / f"{spec_name}.json").open(
+        "r", encoding="utf-8"
+    ) as f:
+        data = json.load(f)
+        return [as_model(**item) for item in data]

libs/prebuilt/uv.lock

@@ -359,6 +359,7 @@ dev = [
     { name = "pytest-repeat" },
     { name = "pytest-watcher" },
     { name = "pytest-xdist", extras = ["psutil"] },
+    { name = "redis" },
     { name = "ruff" },
     { name = "syrupy" },
     { name = "types-requests" },
@@ -392,6 +393,7 @@ dev = [
     { name = "pytest-asyncio" },
     { name = "pytest-mock" },
     { name = "pytest-watcher" },
+    { name = "redis" },
     { name = "ruff" },
 ]