wrap_tool_call() — langchain Function Reference

Architecture documentation for the wrap_tool_call() function in types.py from the langchain codebase.

Function python LangChainCore Runnables calls 2 called by 1

Entity Profile

LangChainCore→ Runnables→ wrap_tool_call() — langchain Function Reference

Dependency Diagram

graph TD
  cee459c1_eb7f_c7cc_29a3_dacfd8fe243b["wrap_tool_call()"]
  949c7cf4_56fe_f3b4_cd89_9631a7e9cb1e["AgentMiddleware"]
  cee459c1_eb7f_c7cc_29a3_dacfd8fe243b -->|defined in| 949c7cf4_56fe_f3b4_cd89_9631a7e9cb1e
  0c14e03a_0bf4_13ec_9acc_ac8d8e0eed8d["wrap_tool_call()"]
  0c14e03a_0bf4_13ec_9acc_ac8d8e0eed8d -->|calls| cee459c1_eb7f_c7cc_29a3_dacfd8fe243b
  0c14e03a_0bf4_13ec_9acc_ac8d8e0eed8d["wrap_tool_call()"]
  cee459c1_eb7f_c7cc_29a3_dacfd8fe243b -->|calls| 0c14e03a_0bf4_13ec_9acc_ac8d8e0eed8d
  e2585731_77e3_b7bd_6c0a_772b884fe839["override()"]
  cee459c1_eb7f_c7cc_29a3_dacfd8fe243b -->|calls| e2585731_77e3_b7bd_6c0a_772b884fe839
  style cee459c1_eb7f_c7cc_29a3_dacfd8fe243b fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

libs/langchain_v1/langchain/agents/middleware/types.py lines 649–729

    def wrap_tool_call(
        self,
        request: ToolCallRequest,
        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
    ) -> ToolMessage | Command[Any]:
        """Intercept tool execution for retries, monitoring, or modification.

        Async version is `awrap_tool_call`

        Multiple middleware compose automatically (first defined = outermost).

        Exceptions propagate unless `handle_tool_errors` is configured on `ToolNode`.

        Args:
            request: Tool call request with call `dict`, `BaseTool`, state, and runtime.

                Access state via `request.state` and runtime via `request.runtime`.
            handler: `Callable` to execute the tool (can be called multiple times).

        Returns:
            `ToolMessage` or `Command` (the final result).

        The handler `Callable` can be invoked multiple times for retry logic.

        Each call to handler is independent and stateless.

        Examples:
            !!! example "Modify request before execution"

                ```python
                def wrap_tool_call(self, request, handler):
                    modified_call = {
                        **request.tool_call,
                        "args": {
                            **request.tool_call["args"],
                            "value": request.tool_call["args"]["value"] * 2,
                        },
                    }
                    request = request.override(tool_call=modified_call)
                    return handler(request)
                ```

            !!! example "Retry on error (call handler multiple times)"

                ```python
                def wrap_tool_call(self, request, handler):
                    for attempt in range(3):
                        try:
                            result = handler(request)
                            if is_valid(result):
                                return result
                        except Exception:
                            if attempt == 2:
                                raise
                    return result
                ```

            !!! example "Conditional retry based on response"

                ```python
                def wrap_tool_call(self, request, handler):
                    for attempt in range(3):
                        result = handler(request)
                        if isinstance(result, ToolMessage) and result.status != "error":
                            return result
                        if attempt < 2:
                            continue
                        return result
                ```
        """
        msg = (
            "Synchronous implementation of wrap_tool_call is not available. "
            "You are likely encountering this error because you defined only the async version "
            "(awrap_tool_call) and invoked your agent in a synchronous context "
            "(e.g., using `stream()` or `invoke()`). "
            "To resolve this, either: "
            "(1) subclass AgentMiddleware and implement the synchronous wrap_tool_call method, "
            "(2) use the @wrap_tool_call decorator on a standalone sync function, or "
            "(3) invoke your agent asynchronously using `astream()` or `ainvoke()`."
        )
        raise NotImplementedError(msg)