Breaking Change in `langgraph-prebuilt==1.0.2` Without Proper Version Constraints

[Valdegg]

Checked other resources

• [x] This is a bug, not a usage question. For questions, please use the LangChain Forum (https://forum.langchain.com/).
• [x] I added a clear and detailed title that summarizes the issue.
• [x] I read what a minimal reproducible example is (https://stackoverflow.com/help/minimal-reproducible-example).
• [x] I included a self-contained, minimal example that demonstrates the issue INCLUDING all the relevant imports. The code run AS IS to reproduce the issue.

Example Code

## Minimal Reproducible Example

### Environment Setup

pip install langgraph==1.0.1
# After Oct 29, 2025, this automatically pulls langgraph-prebuilt==1.0.2
pip show langgraph-prebuilt  # Verify version is 1.0.2


### Reproduction Code

Create a file `test_breaking_change.py`:


"""
Minimal reproducible example showing breaking change in langgraph-prebuilt 1.0.2
This code works with langgraph-prebuilt==1.0.1 but breaks with 1.0.2
"""
import asyncio
from typing import Union, Optional, Any

from langchain_core.messages import AnyMessage, AIMessage, HumanMessage, ToolMessage
from langchain_core.runnables import RunnableConfig
from langchain_core.tools import tool
from langgraph.prebuilt import ToolNode
from langgraph.store.base import BaseStore
from pydantic import BaseModel


# Define a simple tool
@tool
def add_numbers(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b


# Custom afunc implementation (common pattern for custom tool execution logic)
async def custom_afunc(
    input: Union[list[AnyMessage], dict[str, Any], BaseModel],
    config: RunnableConfig,
    *,
    store: Optional[BaseStore],
) -> Any:
    """
    Custom tool execution function.
    This signature works with langgraph-prebuilt 1.0.1
    but breaks with 1.0.2 which requires a 'runtime' parameter
    """
    print("Custom tool execution logic")
    
    # Get the default ToolNode to handle parsing and execution
    tools = [add_numbers]
    default_node = ToolNode(tools)
    
    # Parse input and execute
    tool_calls, input_type = default_node._parse_input(input, store)
    outputs = []
    for call in tool_calls:
        output = await default_node._arun_one(call, input_type, config)
        outputs.append(output)
    
    return outputs if input_type == "list" else {default_node.messages_key: outputs}


async def main():
    # Create a ToolNode and override afunc with custom implementation
    tools = [add_numbers]
    tools_node = ToolNode(tools)
    
    # This is where the issue occurs - overriding afunc
    tools_node.afunc = custom_afunc
    
    # Create a message with a tool call
    messages = [
        AIMessage(
            content="",
            tool_calls=[{
                "name": "add_numbers",
                "args": {"a": 5, "b": 3},
                "id": "call_123",
                "type": "tool_call",
            }]
        )
    ]
    
    config = RunnableConfig(configurable={})
    
    # This will fail with langgraph-prebuilt==1.0.2
    # TypeError: custom_afunc() got an unexpected keyword argument 'runtime'
    result = await tools_node.ainvoke({"messages": messages}, config)
    print(f"Result: {result}")


if __name__ == "__main__":
    asyncio.run(main())


### Run the Example


python test_breaking_change.py


### Expected Behavior (langgraph-prebuilt==1.0.1)

Custom tool execution logic
Result: {'messages': [ToolMessage(content='8', tool_call_id='call_123')]}


### Actual Behavior (langgraph-prebuilt==1.0.2)

Traceback (most recent call last):
  ...
TypeError: custom_afunc() got an unexpected keyword argument 'runtime'

Error Message and Stack Trace (if applicable)

Description

Breaking Change in langgraph-prebuilt==1.0.2 Without Proper Version Constraints

Summary

langgraph-prebuilt==1.0.2 (released Oct 29, 2025) introduced a breaking change by adding a required runtime parameter to ToolNode.afunc, but langgraph==1.0.1 does not constrain the langgraph-prebuilt dependency to prevent this incompatible version from being installed. This breaks any code that overrides afunc with a custom implementation.

The Problem

What Broke

When users install langgraph==1.0.1 after Oct 29, 2025, pip automatically installs langgraph-prebuilt==1.0.2, which contains a breaking signature change:

Before (1.0.1):

async def afunc(
    self,
    input: Union[list[AnyMessage], dict[str, Any], BaseModel],
    config: RunnableConfig,
    *,
    store: Optional[BaseStore],
) -> Any:

After (1.0.2):

async def afunc(
    self,
    input: Union[list[AnyMessage], dict[str, Any], BaseModel],
    config: RunnableConfig,
    *,
    store: Optional[BaseStore],
    runtime: ...,  # New required parameter
) -> Any:

Impact

Anyone who overrides ToolNode.afunc gets this error:

TypeError: ToolsManager._afunc() got an unexpected keyword argument 'runtime'

This affects code like:

tools_node = ToolNode(tools)
tools_node.afunc = custom_afunc  # Breaks if custom_afunc doesn't accept runtime

Reproduction

Environment

• langgraph==1.0.1 installed after Oct 29, 2025
• Results in langgraph-prebuilt==1.0.2 being pulled as a dependency

Code

from langgraph.prebuilt import ToolNode
from langchain_core.runnables import RunnableConfig
from langgraph.store.base import BaseStore
from typing import Union, Optional, Any
from langchain_core.messages import AnyMessage
from pydantic import BaseModel

async def custom_afunc(
    input: Union[list[AnyMessage], dict[str, Any], BaseModel],
    config: RunnableConfig,
    *,
    store: Optional[BaseStore],
) -> Any:
    # Custom implementation
    pass

tools_node = ToolNode([])
tools_node.afunc = custom_afunc
# Fails when invoked with: TypeError: custom_afunc() got an unexpected keyword argument 'runtime'

Root Cause

langgraph==1.0.1 has insufficiently constrained dependencies allowing patch versions of langgraph-prebuilt to introduce breaking changes.

Expected Behavior

According to semantic versioning:

• Patch versions (1.0.1 → 1.0.2) should only contain backwards-compatible bug fixes
• Breaking changes require a minor (1.0.x → 1.1.0) or major (1.x.x → 2.0.0) version bump

Suggested Fix

Option 1: Pin Dependencies (Immediate Fix)

Update langgraph==1.0.1 to constrain langgraph-prebuilt:

# In langgraph 1.0.1 setup.py or pyproject.toml
dependencies = [
    "langgraph-prebuilt>=1.0.0,<1.1.0",  # Prevent breaking patch versions
    # or even
    "langgraph-prebuilt==1.0.1",  # Exact pinning
]

Option 2: Version Breaking Changes Correctly (Proper Fix)

If the runtime parameter is needed, it should have been released as:

• langgraph==1.1.0 with langgraph-prebuilt==1.1.0

And make the parameter optional for backwards compatibility:

async def afunc(
    self,
    input: Union[list[AnyMessage], dict[str, Any], BaseModel],
    config: RunnableConfig,
    *,
    store: Optional[BaseStore],
    runtime: Optional[...] = None,  # Optional to maintain backwards compatibility
) -> Any:

Workaround for Users

Users can protect themselves by explicitly pinning in their requirements.txt:

langgraph==1.0.1
langgraph-prebuilt==1.0.1  # Explicit pin

Or make their override accept additional kwargs:

async def custom_afunc(
    input: Union[list[AnyMessage], dict[str, Any], BaseModel],
    config: RunnableConfig,
    *,
    store: Optional[BaseStore],
    **kwargs,  # Accept future parameters
) -> Any:
    # Implementation
    pass

Environment Details

• Python: 3.11
• langgraph: 1.0.1
• langgraph-prebuilt: 1.0.2 (installed automatically)
• OS: macOS (reproduced on multiple systems)

Additional Context

This issue caused production failures for teams that:

1. Had working code with langgraph==1.0.1 + langgraph-prebuilt==1.0.1
2. Rebuilt their environments after Oct 29, 2025
3. Got langgraph-prebuilt==1.0.2 automatically
4. Found their code suddenly broken without any changes on their end

The root issue is that langgraph as a package doesn't properly constrain its prebuilt dependency, allowing pip to resolve incompatible versions.

---

Request: Please either:

1. Update langgraph==1.0.1 to constrain langgraph-prebuilt dependencies appropriately
2. Release a new patch version langgraph==1.0.3 with proper constraints
3. Follow semantic versioning for breaking changes in future releases

System Info

System Information

OS: Darwin OS Version: Darwin Kernel Version 23.5.0: Wed May 1 20:12:58 PDT 2024; root:xnu-10063.121.3~5/RELEASE_ARM64_T6000 Python Version: 3.11.11 (main, Jan 27 2025, 13:39:23) [Clang 15.0.0 (clang-1500.3.9.4)]

Package Information

langchain_core: 1.0.0 langchain: 1.0.0 langchain_community: 0.4 langsmith: 0.4.37 langchain_anthropic: 1.0.0 langchain_classic: 1.0.0 langchain_mcp_adapters: 0.1.11 langchain_openai: 1.0.0 langchain_tavily: 0.2.12 langchain_text_splitters: 1.0.0 langgraph_api: 0.4.44 langgraph_cli: 0.4.4 langgraph_runtime_inmem: 0.14.1 langgraph_sdk: 0.2.9

Optional packages not installed

langserve

Other Dependencies

aiohttp: 3.12.15 anthropic: 0.72.0 async-timeout: 5.0.1 blockbuster: 1.5.25 claude-agent-sdk: Installed. No version info available. click: 8.3.0 cloudpickle: 3.1.1 cryptography: 44.0.3 dataclasses-json: 0.6.7 grpcio: 1.76.0 grpcio-tools: 1.76.0 httpx: 0.28.1 httpx-sse: 0.4.3 jsonpatch: 1.33 jsonschema-rs: 0.29.1 langchain-aws: Installed. No version info available. langchain-deepseek: Installed. No version info available. langchain-fireworks: Installed. No version info available. langchain-google-genai: Installed. No version info available. langchain-google-vertexai: Installed. No version info available. langchain-groq: Installed. No version info available. langchain-huggingface: Installed. No version info available. langchain-mistralai: Installed. No version info available. langchain-ollama: Installed. No version info available. langchain-perplexity: Installed. No version info available. langchain-together: Installed. No version info available. langchain-xai: Installed. No version info available. langgraph: 1.0.1 langgraph-checkpoint: 2.1.2 langsmith-pyo3: Installed. No version info available. mcp: 1.9.2 numpy: 2.3.4 openai: 1.109.1 openai-agents: Installed. No version info available. opentelemetry-api: 1.38.0 opentelemetry-exporter-otlp-proto-http: 1.38.0 opentelemetry-sdk: 1.38.0 orjson: 3.11.4 packaging: 25.0 protobuf: 6.33.0 pydantic: 2.11.7 pydantic-settings: 2.11.0 pyjwt: 2.10.1 pytest: Installed. No version info available. python-dotenv: 1.1.1 pyyaml: 6.0.3 PyYAML: 6.0.3 requests: 2.32.5 requests-toolbelt: 1.0.0 rich: 14.2.0 sqlalchemy: 2.0.44 SQLAlchemy: 2.0.44 sse-starlette: 2.1.3 starlette: 0.48.0 structlog: 25.5.0 tenacity: 9.1.2 tiktoken: 0.12.0 truststore: 0.10.4 typing-extensions: 4.14.1 uvicorn: 0.38.0 vcrpy: Installed. No version info available. watchfiles: 1.1.1 zstandard: 0.25.0

[nb-programmer]

I got different error that might be related to this change, in langgraph-supervisor package:

File "/usr/local/lib/python3.12/site-packages/langgraph_supervisor/supervisor.py", line 406, in create_supervisor
     tool_node = _prepare_tool_node(
                 ^^^^^^^^^^^^^^^^^^^
File "/usr/local/lib/python3.12/site-packages/langgraph_supervisor/supervisor.py", line 196, in _prepare_tool_node
     handle_tool_errors=input_tool_node.handle_tool_errors,
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'ToolNode' object has no attribute 'handle_tool_errors'. Did you mean: '_handle_tool_errors'?

Packages:

langchain                1.0.3
langchain-classic        1.0.0
langchain-community      0.4.1
langchain-core           1.0.2
langchain-openai         1.0.1
langchain-text-splitters 1.0.0
langgraph                1.0.2
langgraph-checkpoint     3.0.0
langgraph-prebuilt       1.0.2
langgraph-sdk            0.2.9
langgraph-supervisor     0.0.30

[sydney-runkle]

Thanks for the write up, this is related to https://github.com/langchain-ai/langgraph/issues/6397, will TAL today.

[eyurtsev]

There are two separate issues:

1. Overriding afunc -- this one we will not fix. You could view this as a breaking change associated with 1.0.0, but also the code is monkey patching and is basically a workaround some limitation of the library. This should've been resolved in a different way originally.
2. handle_tool_errors we can make public again cc @sydney-runkle

[denadai2]

I confirm that pinning langgraph-prebuilt==1.0.1 solves #6397