[langchan-core] Breaking change: Tool with argument tool_call_id forces `invoke` to use different call pattern

[cristianocca]

Checked other resources

• This is a bug, not a usage question.
• I added a clear and descriptive title that summarizes this issue.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangChain rather than my code.
• The bug is not resolved by updating to the latest stable version of LangChain (or the specific integration package).
• This is not related to the langchain-community package.
• I posted a self-contained, minimal, reproducible example. A maintainer can copy it and run it AS IS.

Package (Required)

• langchain
• langchain-openai
• langchain-anthropic
• langchain-classic
• langchain-core
• langchain-cli
• langchain-model-profiles
• langchain-tests
• langchain-text-splitters
• langchain-chroma
• langchain-deepseek
• langchain-exa
• langchain-fireworks
• langchain-groq
• langchain-huggingface
• langchain-mistralai
• langchain-nomic
• langchain-ollama
• langchain-perplexity
• langchain-prompty
• langchain-qdrant
• langchain-xai
• Other / not sure / general

Example Code (Python)

# Tool definition 
@tool(name, description=description)
def handoff_tool(
    task_description: Annotated[
        str,
        "some argument",
    ],
    state: Annotated[Any, InjectedState],
    tool_call_id: Annotated[str, InjectedToolArg],
) -> SomeModel:
    ....


# Tool call
tool.invoke(
    {"task_description": "Test task", "state": some_state, "tool_call_id": "test-id"}
)

# With langchain 1.0.5 -- works

# With langchain >= 1.0.6 -- raises exception

raises from https://github.com/langchain-ai/langchain/pull/33999/files


msg = (
    "When tool includes an InjectedToolCallId "
    "argument, tool must always be invoked with a full "
    "model ToolCall of the form: {'args': {...}, "
    "'name': '...', 'type': 'tool_call', "
    "'tool_call_id': '...'}"
)
raise ValueError(msg)

Error Message and Stack Trace (if applicable)

E                       ValueError: When tool includes an InjectedToolCallId argument, tool must always be invoked with a full model ToolCall of the form: {'args': {...}, 'name': '...', 'type': 'tool_call', 'tool_call_id': '...'}

Description

When upgrading from langchain 1.0.5 to 1.1.0 there is a breaking change in how tools are invoked.

Breaking change was added in https://github.com/langchain-ai/langchain/pull/33999/files

Addressing the error is not possible as well (without significant refactor), as using "type": "tool_call" forces the tool to always return strings which is not backwards compatible. We have implemented a custom tool node that allows returning arbitrary objects from tools and coerces it to string using custom logic (i.e., serializing json, invoking custom model methods, etc).

As this was a breaking change, it would be great to keep it in a major version.

System Info

System Information
------------------
> OS:  Darwin
> OS Version:  Darwin Kernel Version 24.6.0: Wed Oct 15 21:12:06 PDT 2025; root:xnu-11417.140.69.703.14~1/RELEASE_ARM64_T6000
> Python Version:  3.12.11 (main, Jun  3 2025, 15:41:47) [Clang 17.0.0 (clang-1700.0.13.3)]

Package Information
-------------------
> langchain_core: 1.0.5
> langchain: 1.0.5
> langchain_community: 0.4.1
> langsmith: 0.4.49
> langchain_aws: 1.0.0
> langchain_classic: 1.0.0
> langchain_text_splitters: 1.0.0
> langgraph_checkpoint_aws: 1.0.1
> langgraph_sdk: 0.2.10

Optional packages not installed
-------------------------------
> langserve

Other Dependencies
------------------
> aiohttp: 3.13.2
> boto3: 1.42.0
> dataclasses-json: 0.6.7
> httpx: 0.28.1
> httpx-sse: 0.4.3
> jsonpatch: 1.33
> langgraph: 1.0.4
> langgraph-checkpoint: 3.0.1
> numpy: 2.3.2
> 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
> pydantic: 2.12.5
> pydantic-settings: 2.12.0
> pytest: 9.0.1
> PyYAML: 6.0.3
> pyyaml: 6.0.3
> requests: 2.32.5
> requests-toolbelt: 1.0.0
> SQLAlchemy: 2.0.44
> sqlalchemy: 2.0.44
> tenacity: 9.1.2
> typing-extensions: 4.15.0
> typing_extensions: 4.15.0
> zstandard: 0.25.0

[TECH-NINJA06]

I'll try working on this

[ccurme]

Thanks for reporting this. Is it tractable to move the custom serialization logic into the tool? Interested to hear more about your use-case.

[sydney-runkle]

Thanks for the report, this was an unintended change.

Admittedly I think ideally we would only support the structured tool call invocation, but given that this was supported pre 1.1, we can issue a fix.

I've opened #34185 and we can release it in an upcoming patch today.

[sydney-runkle]

What happens on 1.0.5 when you have the following

@tool(name, description=description)
def handoff_tool(
    task_description: Annotated[
        str,
        "some argument",
    ],
    state: Annotated[Any, InjectedState],
    tool_call_id: Annotated[str, InjectedToolCallId],  # note, injected tool call id here
) -> SomeModel:

My guess is that it doesn't work, and if that's the case, then I don't think we need to fix this, bc the intended behavior w/ tool call ids is that they're passed as part of an official tool call...

[cristianocca]

Thank you for the quick response time!

Only supporting the structured call makes sense, it’s actually a bit confusing why both options are available right now, and without testing this can put you in weird situations.

However, I would still like a way for the tool not auto serialize everything to string and support returning the function return value as is for use cases where the output has custom serialization and processing before it’s passed into the next LLM call.

Our use case is pretty simple, we return pedantic models, strings, or dicts. We then do some data processing like redaction, logging, filtering, and ultimately serialize it to string using either pydantic or json (but may change it to toon or other formats). This is a slightly different use case than the one returning both strings and artifacts (and doing so will mean refactoring every single tool).

I hope this helps, let me know if you want more info.

[sydney-runkle]

I think I'm still ok w/ merging my PR w/ the fix bc we should go ahead and inject everything in tool_input, but perhaps in v2 we will clean all of this up more and be more strict :)

[cristianocca]

That’s a fair point; if you use InjectedToolCallId it will not work (and fail with the same error). However we are using InjectedToolArg and doing our injection logic (not using ToolNode), so it works and the parameter could be called tool_id or something else and it would still work. It’s the fact that the new change targets any argument called tool_call_id and raises an error that’s breaking.