The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(langchain): revamped `create_react_agent` (#32705)
Sydney Runkle18db07c29288
diff --git a/libs/langchain_v1/Makefile b/libs/langchain_v1/Makefileindex 885a56cf7b..bb07973f2b 100644--- a/libs/langchain_v1/Makefile+++ b/libs/langchain_v1/Makefile@@ -1,4 +1,4 @@-.PHONY: all clean docs_build docs_clean docs_linkcheck api_docs_build api_docs_clean api_docs_linkcheck format lint test tests test_watch integration_tests help extended_tests+.PHONY: all clean docs_build docs_clean docs_linkcheck api_docs_build api_docs_clean api_docs_linkcheck format lint test tests test_watch integration_tests help extended_tests start_services stop_services# Default target executed when no arguments are given to make.all: help@@ -7,6 +7,12 @@ all: help# TESTING AND COVERAGE######################+start_services:+ docker compose -f tests/unit_tests/agents/compose-postgres.yml -f tests/unit_tests/agents/compose-redis.yml up -V --force-recreate --wait --remove-orphans++stop_services:+ docker compose -f tests/unit_tests/agents/compose-postgres.yml -f tests/unit_tests/agents/compose-redis.yml down -v+# Define a variable for the test file path.TEST_FILE ?= tests/unit_tests/@@ -21,17 +27,32 @@ coverage:--cov-report term-missing:skip-covered \$(TEST_FILE)-test tests:- uv run --group test pytest -n auto --disable-socket --allow-unix-socket $(TEST_FILE)+test:+ make start_services && LANGGRAPH_TEST_FAST=0 uv run --group test pytest -n auto --disable-socket --allow-unix-socket $(TEST_FILE) --cov-report term-missing:skip-covered; \+ EXIT_CODE=$$?; \+ make stop_services; \+ exit $$EXIT_CODE++test_fast:+ LANGGRAPH_TEST_FAST=1 uv run --group test pytest -n auto --disable-socket --allow-unix-socket $(TEST_FILE)extended_tests:- uv run --group test pytest --disable-socket --allow-unix-socket --only-extended tests/unit_tests+ make start_services && LANGGRAPH_TEST_FAST=0 uv run --group test pytest --disable-socket --allow-unix-socket --only-extended tests/unit_tests; \+ EXIT_CODE=$$?; \+ make stop_services; \+ exit $$EXIT_CODEtest_watch:- uv run --group test ptw --snapshot-update --now . -- -x --disable-socket --allow-unix-socket --disable-warnings tests/unit_tests+ make start_services && LANGGRAPH_TEST_FAST=0 uv run --group test ptw --snapshot-update --now . -- -x --disable-socket --allow-unix-socket --disable-warnings tests/unit_tests; \+ EXIT_CODE=$$?; \+ make stop_services; \+ exit $$EXIT_CODEtest_watch_extended:- uv run --group test ptw --snapshot-update --now . -- -x --disable-socket --allow-unix-socket --only-extended tests/unit_tests+ make start_services && LANGGRAPH_TEST_FAST=0 uv run --group test ptw --snapshot-update --now . -- -x --disable-socket --allow-unix-socket --only-extended tests/unit_tests; \+ EXIT_CODE=$$?; \+ make stop_services; \+ exit $$EXIT_CODEintegration_tests:uv run --group test --group test_integration pytest tests/integration_tests@@ -87,7 +108,8 @@ help:@echo 'spell_fix - run codespell on the project and fix the errors'@echo '-- TESTS --'@echo 'coverage - run unit tests and generate coverage report'- @echo 'test - run unit tests'+ @echo 'test - run unit tests with all services'+ @echo 'test_fast - run unit tests with in-memory services only'@echo 'tests - run unit tests (alias for "make test")'@echo 'test TEST_FILE=<test_file> - run all tests in file'@echo 'extended_tests - run only extended unit tests'diff --git a/libs/langchain_v1/langchain/agents/__init__.py b/libs/langchain_v1/langchain/agents/__init__.pynew file mode 100644index 0000000000..f3c10ee29e--- /dev/null+++ b/libs/langchain_v1/langchain/agents/__init__.py@@ -0,0 +1,10 @@+"""langgraph.prebuilt exposes a higher-level API for creating and executing agents and tools."""++from langchain.agents.react_agent import AgentState, create_react_agent+from langchain.agents.tool_node import ToolNode++__all__ = [+ "AgentState",+ "ToolNode",+ "create_react_agent",+]diff --git a/libs/langchain_v1/langchain/agents/_internal/__init__.py b/libs/langchain_v1/langchain/agents/_internal/__init__.pynew file mode 100644index 0000000000..b4ff9ac2ba--- /dev/null+++ b/libs/langchain_v1/langchain/agents/_internal/__init__.py@@ -0,0 +1 @@+"""Internal utilities for agents."""diff --git a/libs/langchain_v1/langchain/agents/_internal/_typing.py b/libs/langchain_v1/langchain/agents/_internal/_typing.pynew file mode 100644index 0000000000..36989c6ce2--- /dev/null+++ b/libs/langchain_v1/langchain/agents/_internal/_typing.py@@ -0,0 +1,13 @@+"""Typing utilities for agents."""++from __future__ import annotations++from collections.abc import Awaitable, Callable+from typing import TypeVar, Union++from typing_extensions import ParamSpec++P = ParamSpec("P")+R = TypeVar("R")++SyncOrAsync = Callable[P, Union[R, Awaitable[R]]]diff --git a/libs/langchain_v1/langchain/agents/interrupt.py b/libs/langchain_v1/langchain/agents/interrupt.pynew file mode 100644index 0000000000..fda6936377--- /dev/null+++ b/libs/langchain_v1/langchain/agents/interrupt.py@@ -0,0 +1,92 @@+"""Interrupt types to use with agent inbox like setups."""++from typing import Literal, Union++from typing_extensions import TypedDict+++class HumanInterruptConfig(TypedDict):+ """Configuration that defines what actions are allowed for a human interrupt.++ This controls the available interaction options when the graph is paused for human input.++ Attributes:+ allow_ignore: Whether the human can choose to ignore/skip the current step+ allow_respond: Whether the human can provide a text response/feedback+ allow_edit: Whether the human can edit the provided content/state+ allow_accept: Whether the human can accept/approve the current state+ """++ allow_ignore: bool+ allow_respond: bool+ allow_edit: bool+ allow_accept: bool+++class ActionRequest(TypedDict):+ """Represents a request for human action within the graph execution.++ Contains the action type and any associated arguments needed for the action.++ Attributes:+ action: The type or name of action being requested (e.g., "Approve XYZ action")+ args: Key-value pairs of arguments needed for the action+ """++ action: str+ args: dict+++class HumanInterrupt(TypedDict):+ """Represents an interrupt triggered by the graph that requires human intervention.++ This is passed to the `interrupt` function when execution is paused for human input.++ Attributes:+ action_request: The specific action being requested from the human+ config: Configuration defining what actions are allowed+ description: Optional detailed description of what input is needed++ Example:+ ```python+ # Extract a tool call from the state and create an interrupt request+ request = HumanInterrupt(+ action_request=ActionRequest(+ action="run_command", # The action being requested+ args={"command": "ls", "args": ["-l"]} # Arguments for the action+ ),+ config=HumanInterruptConfig(+ allow_ignore=True, # Allow skipping this step+ allow_respond=True, # Allow text feedback+ allow_edit=False, # Don't allow editing+ allow_accept=True # Allow direct acceptance+ ),+ description="Please review the command before execution"+ )+ # Send the interrupt request and get the response+ response = interrupt([request])[0]+ ```+ """++ action_request: ActionRequest+ config: HumanInterruptConfig+ description: str | None+++class HumanResponse(TypedDict):+ """The response provided by a human to an interrupt, which is returned when graph execution resumes.++ Attributes:+ type: The type of response:+ - "accept": Approves the current state without changes+ - "ignore": Skips/ignores the current step+ - "response": Provides text feedback or instructions+ - "edit": Modifies the current state/content+ args: The response payload:+ - None: For ignore/accept actions+ - str: For text responses+ - ActionRequest: For edit actions with updated content+ """++ type: Literal["accept", "ignore", "response", "edit"]+ args: Union[None, str, ActionRequest]diff --git a/libs/langchain_v1/langchain/agents/react_agent.py b/libs/langchain_v1/langchain/agents/react_agent.pynew file mode 100644index 0000000000..045d92e97d--- /dev/null+++ b/libs/langchain_v1/langchain/agents/react_agent.py@@ -0,0 +1,1175 @@+from __future__ import annotations++import inspect+from collections.abc import Awaitable, Callable, Sequence+from dataclasses import asdict, is_dataclass+from typing import (+ TYPE_CHECKING,+ Annotated,+ Any,+ Generic,+ Literal,+ Union,+ cast,+ get_type_hints,+)+from warnings import warn++from langchain_core.language_models import (+ BaseChatModel,+ LanguageModelInput,+ LanguageModelLike,+)+from langchain_core.messages import (+ AIMessage,+ AnyMessage,+ BaseMessage,+ SystemMessage,+ ToolCall,+ ToolMessage,+)+from langchain_core.runnables import (+ Runnable,+ RunnableConfig,+)+from langgraph._internal._runnable import RunnableCallable, RunnableLike+from langgraph._internal._typing import MISSING+from langgraph.errors import ErrorCode, create_error_message+from langgraph.graph import END, StateGraph+from langgraph.graph.message import add_messages+from langgraph.managed import RemainingSteps # noqa: TC002+from langgraph.types import Checkpointer, Command, Send+from langgraph.typing import ContextT, StateT+from pydantic import BaseModel+from typing_extensions import NotRequired, TypedDict, TypeVar++from langchain.agents.structured_output import (+ MultipleStructuredOutputsError,+ OutputToolBinding,+ ProviderStrategy,+ ProviderStrategyBinding,+ ResponseFormat,+ StructuredOutputValidationError,+ ToolStrategy,+)+from langchain.agents.tool_node import ToolNode+from langchain.chat_models import init_chat_model++if TYPE_CHECKING:+ from langchain_core.tools import BaseTool+ from langgraph.graph.state import CompiledStateGraph+ from langgraph.runtime import Runtime+ from langgraph.store.base import BaseStore++ from langchain.agents._internal._typing import (+ SyncOrAsync,+ )++StructuredResponseT = TypeVar("StructuredResponseT", default=None)++STRUCTURED_OUTPUT_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."+++class AgentState(TypedDict):+ """The state of the agent."""++ messages: Annotated[Sequence[BaseMessage], add_messages]++ remaining_steps: NotRequired[RemainingSteps]+++class AgentStatePydantic(BaseModel):+ """The state of the agent."""++ messages: Annotated[Sequence[BaseMessage], add_messages]++ remaining_steps: RemainingSteps = 25+++class AgentStateWithStructuredResponse(AgentState, Generic[StructuredResponseT]):+ """The state of the agent with a structured response."""++ structured_response: StructuredResponseT+++class AgentStateWithStructuredResponsePydantic(AgentStatePydantic, Generic[StructuredResponseT]):+ """The state of the agent with a structured response."""++ structured_response: StructuredResponseT+++PROMPT_RUNNABLE_NAME = "Prompt"++Prompt = Union[+ SystemMessage,+ str,+ Callable[[StateT], LanguageModelInput],+ Runnable[StateT, LanguageModelInput],+]+++def _get_state_value(state: StateT, key: str, default: Any = None) -> Any:+ return state.get(key, default) if isinstance(state, dict) else getattr(state, key, default)+++def _get_prompt_runnable(prompt: Prompt | None) -> Runnable:+ prompt_runnable: Runnable+ if prompt is None:+ prompt_runnable = RunnableCallable(+ lambda state: _get_state_value(state, "messages"), name=PROMPT_RUNNABLE_NAME+ )+ elif isinstance(prompt, str):+ _system_message: BaseMessage = SystemMessage(content=prompt)+ prompt_runnable = RunnableCallable(+ lambda state: [_system_message, *_get_state_value(state, "messages")],+ name=PROMPT_RUNNABLE_NAME,+ )+ elif isinstance(prompt, SystemMessage):+ prompt_runnable = RunnableCallable(+ lambda state: [prompt, *_get_state_value(state, "messages")],+ name=PROMPT_RUNNABLE_NAME,+ )+ elif inspect.iscoroutinefunction(prompt):+ prompt_runnable = RunnableCallable(+ None,+ prompt,+ name=PROMPT_RUNNABLE_NAME,+ )+ elif callable(prompt):+ prompt_runnable = RunnableCallable(+ prompt,+ name=PROMPT_RUNNABLE_NAME,+ )+ elif isinstance(prompt, Runnable):+ prompt_runnable = prompt+ else:+ msg = f"Got unexpected type for `prompt`: {type(prompt)}"+ raise ValueError(msg)++ return prompt_runnable+++def _validate_chat_history(+ messages: Sequence[BaseMessage],+) -> None:+ """Validate that all tool calls in AIMessages have a corresponding ToolMessage."""+ all_tool_calls = [+ tool_call+ for message in messages+ if isinstance(message, AIMessage)+ for tool_call in message.tool_calls+ ]+ tool_call_ids_with_results = {+ message.tool_call_id for message in messages if isinstance(message, ToolMessage)+ }+ tool_calls_without_results = [+ tool_call+ for tool_call in all_tool_calls+ if tool_call["id"] not in tool_call_ids_with_results+ ]+ if not tool_calls_without_results:+ return++ error_message = create_error_message(+ message="Found AIMessages with tool_calls that do not have a corresponding ToolMessage. "+ f"Here are the first few of those tool calls: {tool_calls_without_results[:3]}.\n\n"+ "Every tool call (LLM requesting to call a tool) in the message history MUST have a corresponding ToolMessage "+ "(result of a tool invocation to return to the LLM) - this is required by most LLM providers.",+ error_code=ErrorCode.INVALID_CHAT_HISTORY,+ )+ raise ValueError(error_message)+++class _AgentBuilder(Generic[StateT, ContextT, StructuredResponseT]):+ """Internal builder class for constructing and agent."""++ def __init__(+ self,+ model: Union[+ str,+ BaseChatModel,+ SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel],+ ],+ tools: Union[Sequence[Union[BaseTool, Callable, dict[str, Any]]], ToolNode],+ *,+ prompt: Prompt | None = None,+ response_format: ResponseFormat[StructuredResponseT] | None = None,+ pre_model_hook: RunnableLike | None = None,+ post_model_hook: RunnableLike | None = None,+ state_schema: type[StateT] | None = None,+ context_schema: type[ContextT] | None = None,+ version: Literal["v1", "v2"] = "v2",+ name: str | None = None,+ store: BaseStore | None = None,+ ) -> None:+ self.model = model+ self.tools = tools+ self.prompt = prompt+ self.response_format = response_format+ self.pre_model_hook = pre_model_hook+ self.post_model_hook = post_model_hook+ self.state_schema = state_schema+ self.context_schema = context_schema+ self.version = version+ self.name = name+ self.store = store++ if isinstance(model, Runnable) and not isinstance(model, BaseChatModel):+ msg = (+ "Expected `model` to be a BaseChatModel or a string, got {type(model)}."+ "The `model` parameter should not have pre-bound tools, simply pass the model and tools separately."+ )+ raise ValueError(msg)++ self._setup_tools()+ self._setup_state_schema()+ self._setup_structured_output()+ self._setup_model()++ def _setup_tools(self) -> None:+ """Setup tool-related attributes."""+ if isinstance(self.tools, ToolNode):+ self._tool_classes = list(self.tools.tools_by_name.values())+ self._tool_node = self.tools+ self._llm_builtin_tools = []+ else:+ self._llm_builtin_tools = [t for t in self.tools if isinstance(t, dict)]+ self._tool_node = ToolNode([t for t in self.tools if not isinstance(t, dict)])+ self._tool_classes = list(self._tool_node.tools_by_name.values())++ self._should_return_direct = {t.name for t in self._tool_classes if t.return_direct}+ self._tool_calling_enabled = len(self._tool_classes) > 0++ def _setup_structured_output(self) -> None:+ """Set up structured output tracking for "tools" and "native" strategies.++ "tools" strategy for structured output:+ 1. Converting response format schemas to LangChain tools+ 2. Creating metadata for proper response reconstruction+ 3. Handling both Pydantic models and dict schemas++ "native" strategy for structured output:+ 1. Capturing the schema reference for later parsing+ 2. Binding provider-native response_format kwargs at model bind time+ 3. Parsing provider-enforced structured output directly into the schema+ """+ self.structured_output_tools: dict[str, OutputToolBinding[StructuredResponseT]] = {}+ self.native_output_binding: ProviderStrategyBinding[StructuredResponseT] | None = None++ if self.response_format is not None:+ response_format = self.response_format++ if isinstance(response_format, ToolStrategy):+ # check if response_format.schema is a union+ for response_schema in response_format.schema_specs:+ structured_tool_info = OutputToolBinding.from_schema_spec(response_schema)+ self.structured_output_tools[structured_tool_info.tool.name] = (+ structured_tool_info+ )+ elif isinstance(response_format, ProviderStrategy):+ # Use native strategy - create ProviderStrategyBinding for parsing+ self.native_output_binding = ProviderStrategyBinding.from_schema_spec(+ response_format.schema_spec+ )+ else:+ # This shouldn't happen with the new ResponseFormat type, but keeping for safety+ msg = (+ f"Unsupported response_format type: {type(response_format)}. "+ f"Expected ToolStrategy."+ )+ raise ValueError(msg)++ def _setup_state_schema(self) -> None:+ """Setup state schema with validation."""+ if self.state_schema is not None:+ required_keys = {"messages", "remaining_steps"}+ if self.response_format is not None:+ required_keys.add("structured_response")++ schema_keys = set(get_type_hints(self.state_schema))+ if missing_keys := required_keys - schema_keys:+ msg = f"Missing required key(s) {missing_keys} in state_schema"+ raise ValueError(msg)++ self._final_state_schema = self.state_schema+ else:+ self._final_state_schema = (+ AgentStateWithStructuredResponse # type: ignore[assignment]+ if self.response_format is not None+ else AgentState+ )++ def _handle_structured_response_tool_calls(self, response: AIMessage) -> Command | None:+ """Handle tool calls that match structured output tools using the tools strategy.++ Args:+ response: The AI message containing potential tool calls++ Returns:+ Command with structured response update if found, None otherwise++ Raises:+ MultipleStructuredOutputsError: If multiple structured responses are returned and error handling is disabled+ StructuredOutputParsingError: If parsing fails and error handling is disabled+ """+ if not isinstance(self.response_format, ToolStrategy) or not response.tool_calls:+ return None++ structured_tool_calls = [+ tool_call+ for tool_call in response.tool_calls+ if tool_call["name"] in self.structured_output_tools+ ]++ if not structured_tool_calls:+ return None++ if len(structured_tool_calls) > 1:+ return self._handle_multiple_structured_outputs(response, structured_tool_calls)++ return self._handle_single_structured_output(response, structured_tool_calls[0])++ def _handle_multiple_structured_outputs(+ self,+ response: AIMessage,+ structured_tool_calls: list[ToolCall],+ ) -> Command:+ """Handle multiple structured output tool calls."""+ tool_names = [tool_call["name"] for tool_call in structured_tool_calls]+ exception = MultipleStructuredOutputsError(tool_names)++ should_retry, error_message = self._handle_structured_output_error(exception)++ if not should_retry:+ raise exception++ tool_messages = [+ ToolMessage(+ content=error_message,+ tool_call_id=tool_call["id"],+ name=tool_call["name"],+ )+ for tool_call in structured_tool_calls+ ]++ return Command(+ update={"messages": [response, *tool_messages]},+ goto="agent",+ )++ def _handle_single_structured_output(+ self,+ response: AIMessage,+ tool_call: Any,+ ) -> Command:+ """Handle a single structured output tool call."""+ structured_tool_binding = self.structured_output_tools[tool_call["name"]]++ try:+ structured_response = structured_tool_binding.parse(tool_call["args"])++ if isinstance(structured_response, BaseModel):+ structured_response_dict = structured_response.model_dump()+ elif is_dataclass(structured_response):+ structured_response_dict = asdict(structured_response) # type: ignore[arg-type]+ else:+ structured_response_dict = cast("dict", structured_response)++ tool_message_content = (+ self.response_format.tool_message_content+ if isinstance(self.response_format, ToolStrategy)+ and self.response_format.tool_message_content+ else f"Returning structured response: {structured_response_dict}"+ )++ return Command(+ update={+ "messages": [+ response,+ ToolMessage(+ content=tool_message_content,+ tool_call_id=tool_call["id"],+ name=tool_call["name"],+ ),+ ],+ "structured_response": structured_response,+ }+ )+ except Exception as exc: # noqa: BLE001+ exception = StructuredOutputValidationError(tool_call["name"], exc)++ should_retry, error_message = self._handle_structured_output_error(exception)++ if not should_retry:+ raise exception++ return Command(+ update={+ "messages": [+ response,+ ToolMessage(+ content=error_message,+ tool_call_id=tool_call["id"],+ name=tool_call["name"],+ ),+ ],+ },+ goto="agent",+ )++ def _handle_structured_output_error(+ self,+ exception: Exception,+ ) -> tuple[bool, str]:+ """Handle structured output error.++ Returns (should_retry, retry_tool_message).+ """+ handle_errors = cast("ToolStrategy", self.response_format).handle_errors++ if handle_errors is False:+ return False, ""+ if handle_errors is True:+ return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))+ if isinstance(handle_errors, str):+ return True, handle_errors+ if isinstance(handle_errors, type) and issubclass(handle_errors, Exception):+ if isinstance(exception, handle_errors):+ return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))+ return False, ""+ if isinstance(handle_errors, tuple):+ if any(isinstance(exception, exc_type) for exc_type in handle_errors):+ return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))+ return False, ""+ if callable(handle_errors):+ return True, handle_errors(exception) # type: ignore[call-arg, return-value]+ return False, ""++ def _apply_native_output_binding(self, model: LanguageModelLike) -> LanguageModelLike:+ """If native output is configured, bind provider-native kwargs onto the model."""+ if not isinstance(self.response_format, ProviderStrategy):+ return model+ kwargs = self.response_format.to_model_kwargs()+ return model.bind(**kwargs)++ def _handle_structured_response_native(self, response: AIMessage) -> Command | None:+ """If native output is configured and there are no tool calls, parse using ProviderStrategyBinding."""+ if self.native_output_binding is None:+ return None+ if response.tool_calls:+ # if the model chooses to call tools, we let the normal flow handle it+ return None++ structured_response = self.native_output_binding.parse(response)++ return Command(update={"messages": [response], "structured_response": structured_response})++ def _setup_model(self) -> None:+ """Setup model-related attributes."""+ self._is_dynamic_model = not isinstance(self.model, (str, Runnable)) and callable(+ self.model+ )+ self._is_async_dynamic_model = self._is_dynamic_model and inspect.iscoroutinefunction(+ self.model+ )++ if not self._is_dynamic_model:+ model = self.model+ if isinstance(model, str):+ model = init_chat_model(model)++ # Collect all tools: regular tools + structured output tools+ structured_output_tools = list(self.structured_output_tools.values())+ all_tools = (+ self._tool_classes+ + self._llm_builtin_tools+ + [info.tool for info in structured_output_tools]+ )++ if len(all_tools) > 0:+ # Check if we need to force tool use for structured output+ tool_choice = None+ if self.response_format is not None and isinstance(+ self.response_format, ToolStrategy+ ):+ tool_choice = "any"++ if tool_choice:+ model = cast("BaseChatModel", model).bind_tools( # type: ignore[assignment]+ all_tools, tool_choice=tool_choice+ )+ # If native output is configured, bind tools with strict=True. Required for OpenAI.+ elif isinstance(self.response_format, ProviderStrategy):+ model = cast("BaseChatModel", model).bind_tools( # type: ignore[assignment]+ all_tools, strict=True+ )+ else:+ model = cast("BaseChatModel", model).bind_tools(all_tools) # type: ignore[assignment]++ # bind native structured-output kwargs+ model = self._apply_native_output_binding(model) # type: ignore[assignment, arg-type]++ # Extract just the model part for direct invocation+ self._static_model: Runnable | None = model # type: ignore[assignment]+ else:+ self._static_model = None++ def _resolve_model(self, state: StateT, runtime: Runtime[ContextT]) -> LanguageModelLike:+ """Resolve the model to use, handling both static and dynamic models."""+ if self._is_dynamic_model:+ dynamic_model = self.model(state, runtime) # type: ignore[operator, arg-type]+ return self._apply_native_output_binding(dynamic_model) # type: ignore[arg-type]+ return self._static_model # type: ignore[return-value]++ async def _aresolve_model(self, state: StateT, runtime: Runtime[ContextT]) -> LanguageModelLike:+ """Async resolve the model to use, handling both static and dynamic models."""+ if self._is_async_dynamic_model:+ dynamic_model = cast(+ "Callable[[StateT, Runtime[ContextT]], Awaitable[BaseChatModel]]",+ self.model,+ )+ return await dynamic_model(state, runtime)+ if self._is_dynamic_model:+ dynamic_model = self.model(state, runtime) # type: ignore[arg-type, assignment, operator]+ return self._apply_native_output_binding(dynamic_model) # type: ignore[arg-type]+ return self._static_model # type: ignore[return-value]++ def create_model_node(self) -> RunnableCallable:+ """Create the 'agent' node that calls the LLM."""++ def _get_model_input_state(state: StateT) -> StateT:+ if self.pre_model_hook is not None:+ messages = _get_state_value(state, "llm_input_messages") or _get_state_value(+ state, "messages"+ )+ error_msg = (+ f"Expected input to call_model to have 'llm_input_messages' "+ f"or 'messages' key, but got {state}"+ )+ else:+ messages = _get_state_value(state, "messages")+ error_msg = f"Expected input to call_model to have 'messages' key, but got {state}"++ if messages is None:+ raise ValueError(error_msg)++ _validate_chat_history(messages)++ if isinstance(self._final_state_schema, type) and issubclass(+ self._final_state_schema, BaseModel+ ):+ # we're passing messages under `messages` key, as this+ # is expected by the prompt+ state.messages = messages # type: ignore[union-attr]+ else:+ state["messages"] = messages # type: ignore[index]+ return state++ def _are_more_steps_needed(state: StateT, response: BaseMessage) -> bool:+ has_tool_calls = isinstance(response, AIMessage) and response.tool_calls+ all_tools_return_direct = (+ all(call["name"] in self._should_return_direct for call in response.tool_calls)+ if isinstance(response, AIMessage)+ else False+ )+ remaining_steps = _get_state_value(state, "remaining_steps", None)+ return (+ remaining_steps is not None # type: ignore[return-value]+ and (+ (remaining_steps < 1 and all_tools_return_direct)+ or (remaining_steps < 2 and has_tool_calls)+ )+ )++ def call_model(+ state: StateT, runtime: Runtime[ContextT], config: RunnableConfig+ ) -> dict[str, Any] | Command:+ """Call the model with the current state and return the response."""+ if self._is_async_dynamic_model:+ msg = (+ "Async model callable provided but agent invoked synchronously. "+ "Use agent.ainvoke() or agent.astream(), or provide a sync model callable."+ )+ raise RuntimeError(msg)++ model_input = _get_model_input_state(state)+ model = self._resolve_model(state, runtime)++ # Get prompt runnable and invoke it first to prepare messages+ prompt_runnable = _get_prompt_runnable(self.prompt)+ prepared_messages = prompt_runnable.invoke(model_input, config)++ # Then invoke the model with the prepared messages+ response = cast("AIMessage", model.invoke(prepared_messages, config))+ response.name = self.name++ if _are_more_steps_needed(state, response):+ return {+ "messages": [+ AIMessage(+ id=response.id,+ content="Sorry, need more steps to process this request.",+ )+ ]+ }++ # Check if any tool calls match structured output tools+ structured_command = self._handle_structured_response_tool_calls(response)+ if structured_command:+ return structured_command++ # Native structured output+ native_command = self._handle_structured_response_native(response)+ if native_command:+ return native_command++ return {"messages": [response]}++ async def acall_model(+ state: StateT, runtime: Runtime[ContextT], config: RunnableConfig+ ) -> dict[str, Any] | Command:+ """Call the model with the current state and return the response."""+ model_input = _get_model_input_state(state)++ model = await self._aresolve_model(state, runtime)++ # Get prompt runnable and invoke it first to prepare messages+ prompt_runnable = _get_prompt_runnable(self.prompt)+ prepared_messages = await prompt_runnable.ainvoke(model_input, config)++ # Then invoke the model with the prepared messages+ response = cast(+ "AIMessage",+ await model.ainvoke(prepared_messages, config),+ )+ response.name = self.name+ if _are_more_steps_needed(state, response):+ return {+ "messages": [+ AIMessage(+ id=response.id,+ content="Sorry, need more steps to process this request.",+ )+ ]+ }++ # Check if any tool calls match structured output tools+ structured_command = self._handle_structured_response_tool_calls(response)+ if structured_command:+ return structured_command++ # Native structured output+ native_command = self._handle_structured_response_native(response)+ if native_command:+ return native_command++ return {"messages": [response]}++ return RunnableCallable(call_model, acall_model)++ def _get_input_schema(self) -> type[StateT]:+ """Get input schema for model node."""+ if self.pre_model_hook is not None:+ if isinstance(self._final_state_schema, type) and issubclass(+ self._final_state_schema, BaseModel+ ):+ from pydantic import create_model++ return create_model(+ "CallModelInputSchema",+ llm_input_messages=(list[AnyMessage], ...),+ __base__=self._final_state_schema,+ )++ class CallModelInputSchema(self._final_state_schema): # type: ignore[name-defined, misc]+ llm_input_messages: list[AnyMessage]++ return CallModelInputSchema+ return self._final_state_schema++ def create_model_router(self) -> Callable[[StateT], Union[str, list[Send]]]:+ """Create routing function for model node conditional edges."""++ def should_continue(state: StateT) -> Union[str, list[Send]]:+ messages = _get_state_value(state, "messages")+ last_message = messages[-1]++ # Check if the last message is a ToolMessage from a structured tool.+ # This condition exists to support structured output via tools.+ # Once a tool has been called for structured output, we skip+ # tool execution and go to END (if there is no post_model_hook).+ if (+ isinstance(last_message, ToolMessage)+ and last_message.name in self.structured_output_tools+ ):+ return END++ if isinstance(last_message, ToolMessage):+ return END++ if not isinstance(last_message, AIMessage) or not last_message.tool_calls:+ if self.post_model_hook is not None:+ return "post_model_hook"+ return END+ if self.version == "v1":+ return "tools"+ if self.version == "v2":+ if self.post_model_hook is not None:+ return "post_model_hook"+ tool_calls = [+ self._tool_node.inject_tool_args(call, state, self.store) # type: ignore[arg-type]+ for call in last_message.tool_calls+ ]+ return [Send("tools", [tool_call]) for tool_call in tool_calls]+ return None++ return should_continue++ def create_post_model_hook_router(+ self,+ ) -> Callable[[StateT], Union[str, list[Send]]]:+ """Create a routing function for post_model_hook node conditional edges."""++ def post_model_hook_router(state: StateT) -> Union[str, list[Send]]:+ messages = _get_state_value(state, "messages")++ # Check if the last message is a ToolMessage from a structured tool.+ # This condition exists to support structured output via tools.+ # Once a tool has been called for structured output, we skip+ # tool execution and go to END (if there is no post_model_hook).+ last_message = messages[-1]+ if (+ isinstance(last_message, ToolMessage)+ and last_message.name in self.structured_output_tools+ ):+ return END++ tool_messages = [m.tool_call_id for m in messages if isinstance(m, ToolMessage)]+ last_ai_message = next(m for m in reversed(messages) if isinstance(m, AIMessage))+ pending_tool_calls = [+ c for c in last_ai_message.tool_calls if c["id"] not in tool_messages+ ]++ if pending_tool_calls:+ pending_tool_calls = [+ self._tool_node.inject_tool_args(call, state, self.store) # type: ignore[arg-type]+ for call in pending_tool_calls+ ]+ return [Send("tools", [tool_call]) for tool_call in pending_tool_calls]+ if isinstance(messages[-1], ToolMessage):+ return self._get_entry_point()+ return END++ return post_model_hook_router++ def create_tools_router(self) -> Callable[[StateT], str] | None:+ """Create a routing function for tools node conditional edges."""+ if not self._should_return_direct:+ return None++ def route_tool_responses(state: StateT) -> str:+ messages = _get_state_value(state, "messages")+ for m in reversed(messages):+ if not isinstance(m, ToolMessage):+ break+ if m.name in self._should_return_direct:+ return END++ if (+ isinstance(m, AIMessage)+ and m.tool_calls+ and any(call["name"] in self._should_return_direct for call in m.tool_calls)+ ):+ return END++ return self._get_entry_point()++ return route_tool_responses++ def _get_entry_point(self) -> str:+ """Get the workflow entry point."""+ return "pre_model_hook" if self.pre_model_hook else "agent"++ def _get_model_paths(self) -> list[str]:+ """Get possible edge destinations from model node."""+ paths = []+ if self._tool_calling_enabled:+ paths.append("tools")+ if self.post_model_hook:+ paths.append("post_model_hook")+ else:+ paths.append(END)++ return paths++ def _get_post_model_hook_paths(self) -> list[str]:+ """Get possible edge destinations from post_model_hook node."""+ paths = []+ if self._tool_calling_enabled:+ paths = [self._get_entry_point(), "tools"]+ paths.append(END)+ return paths++ def build(self) -> StateGraph[StateT, ContextT]:+ """Build the agent workflow graph (uncompiled)."""+ workflow = StateGraph(+ state_schema=self._final_state_schema,+ context_schema=self.context_schema,+ )++ # Set entry point+ workflow.set_entry_point(self._get_entry_point())++ # Add nodes+ workflow.add_node("agent", self.create_model_node(), input_schema=self._get_input_schema())++ if self._tool_calling_enabled:+ workflow.add_node("tools", self._tool_node)++ if self.pre_model_hook:+ workflow.add_node("pre_model_hook", self.pre_model_hook) # type: ignore[arg-type]++ if self.post_model_hook:+ workflow.add_node("post_model_hook", self.post_model_hook) # type: ignore[arg-type]++ # Add edges+ if self.pre_model_hook:+ workflow.add_edge("pre_model_hook", "agent")++ if self.post_model_hook:+ workflow.add_edge("agent", "post_model_hook")+ post_hook_paths = self._get_post_model_hook_paths()+ if len(post_hook_paths) == 1:+ # No need for a conditional edge if there's only one path+ workflow.add_edge("post_model_hook", post_hook_paths[0])+ else:+ workflow.add_conditional_edges(+ "post_model_hook",+ self.create_post_model_hook_router(),+ path_map=post_hook_paths,+ )+ else:+ model_paths = self._get_model_paths()+ if len(model_paths) == 1:+ # No need for a conditional edge if there's only one path+ workflow.add_edge("agent", model_paths[0])+ else:+ workflow.add_conditional_edges(+ "agent",+ self.create_model_router(),+ path_map=model_paths,+ )++ if self._tool_calling_enabled:+ # In some cases, tools can return directly. In these cases+ # we add a conditional edge from the tools node to the END node+ # instead of going to the entry point.+ tools_router = self.create_tools_router()+ if tools_router:+ workflow.add_conditional_edges(+ "tools",+ tools_router,+ path_map=[self._get_entry_point(), END],+ )+ else:+ workflow.add_edge("tools", self._get_entry_point())++ return workflow+++def _supports_native_structured_output(+ model: Union[str, BaseChatModel, SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel]],+) -> bool:+ """Check if a model supports native structured output.++ TODO: replace with more robust model profiles.+ """+ model_name: str | None = None+ if isinstance(model, str):+ model_name = model+ elif isinstance(model, BaseChatModel):+ model_name = getattr(model, "model_name", None)++ return (+ "grok" in model_name.lower()+ or any(part in model_name for part in ["gpt-5", "gpt-4.1", "gpt-oss", "o3-pro", "o3-mini"])+ if model_name+ else False+ )+++def create_react_agent( # noqa: D417+ model: Union[+ str,+ BaseChatModel,+ SyncOrAsync[[StateT, Runtime[ContextT]], BaseChatModel],+ ],+ tools: Union[Sequence[Union[BaseTool, Callable, dict[str, Any]]], ToolNode],+ *,+ prompt: Prompt | None = None,+ response_format: Union[+ ToolStrategy[StructuredResponseT],+ ProviderStrategy[StructuredResponseT],+ type[StructuredResponseT],+ ]+ | None = None,+ pre_model_hook: RunnableLike | None = None,+ post_model_hook: RunnableLike | None = None,+ state_schema: type[StateT] | None = None,+ context_schema: type[ContextT] | None = None,+ checkpointer: Checkpointer | None = None,+ store: BaseStore | None = None,+ interrupt_before: list[str] | None = None,+ interrupt_after: list[str] | None = None,+ debug: bool = False,+ version: Literal["v1", "v2"] = "v2",+ name: str | None = None,+ **deprecated_kwargs: Any,+) -> CompiledStateGraph[StateT, ContextT]:+ """Creates an agent graph that calls tools in a loop until a stopping condition is met.++ For more details on using `create_react_agent`, visit [Agents](https://langchain-ai.github.io/langgraph/agents/overview/) documentation.++ Args:+ model: The language model for the agent. Supports static and dynamic+ model selection.++ - **Static model**: A chat model instance (e.g., `ChatOpenAI()`) or+ string identifier (e.g., `"openai:gpt-4"`)+ - **Dynamic model**: A callable with signature+ `(state, runtime) -> BaseChatModel` that returns different models+ based on runtime context+ If the model has tools bound via `.bind_tools()` or other configurations,+ the return type should be a Runnable[LanguageModelInput, BaseMessage]+ Coroutines are also supported, allowing for asynchronous model selection.++ Dynamic functions receive graph state and runtime, enabling+ context-dependent model selection. Must return a `BaseChatModel`+ instance. For tool calling, bind tools using `.bind_tools()`.+ Bound tools must be a subset of the `tools` parameter.++ Dynamic model example:+ ```python+ from dataclasses import dataclass++ @dataclass+ class ModelContext:+ model_name: str = "gpt-3.5-turbo"++ # Instantiate models globally+ gpt4_model = ChatOpenAI(model="gpt-4")+ gpt35_model = ChatOpenAI(model="gpt-3.5-turbo")++ def select_model(state: AgentState, runtime: Runtime[ModelContext]) -> ChatOpenAI:+ model_name = runtime.context.model_name+ model = gpt4_model if model_name == "gpt-4" else gpt35_model+ return model.bind_tools(tools)+ ```++ !!! note "Dynamic Model Requirements"+ Ensure returned models have appropriate tools bound via+ `.bind_tools()` and support required functionality. Bound tools+ must be a subset of those specified in the `tools` parameter.++ tools: A list of tools or a ToolNode instance.+ If an empty list is provided, the agent will consist of a single LLM node without tool calling.+ prompt: An optional prompt for the LLM. Can take a few different forms:++ - str: This is converted to a SystemMessage and added to the beginning of the list of messages in state["messages"].+ - SystemMessage: this is added to the beginning of the list of messages in state["messages"].+ - Callable: This function should take in full graph state and the output is then passed to the language model.+ - Runnable: This runnable should take in full graph state and the output is then passed to the language model.++ response_format: An optional UsingToolStrategy configuration for structured responses.++ If provided, the agent will handle structured output via tool calls during the normal conversation flow.+ When the model calls a structured output tool, the response will be captured and returned in the 'structured_response' state key.+ If not provided, `structured_response` will not be present in the output state.++ The UsingToolStrategy should contain:+ - schemas: A sequence of ResponseSchema objects that define the structured output format+ - tool_choice: Either "required" or "auto" to control when structured output is used++ Each ResponseSchema contains:+ - schema: A Pydantic model that defines the structure+ - name: Optional custom name for the tool (defaults to model name)+ - description: Optional custom description (defaults to model docstring)+ - strict: Whether to enforce strict validation++ !!! Important+ `response_format` requires the model to support tool calling++ !!! Note+ Structured responses are handled directly in the model call node via tool calls, eliminating the need for separate structured response nodes.++ pre_model_hook: An optional node to add before the `agent` node (i.e., the node that calls the LLM).+ Useful for managing long message histories (e.g., message trimming, summarization, etc.).+ Pre-model hook must be a callable or a runnable that takes in current graph state and returns a state update in the form of+ ```python+ # At least one of `messages` or `llm_input_messages` MUST be provided+ {+ # If provided, will UPDATE the `messages` in the state+ "messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), ...],+ # If provided, will be used as the input to the LLM,+ # and will NOT UPDATE `messages` in the state+ "llm_input_messages": [...],+ # Any other state keys that need to be propagated+ ...+ }+ ```++ !!! Important+ At least one of `messages` or `llm_input_messages` MUST be provided and will be used as an input to the `agent` node.+ The rest of the keys will be added to the graph state.++ !!! Warning+ If you are returning `messages` in the pre-model hook, you should OVERWRITE the `messages` key by doing the following:++ ```python+ {+ "messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), *new_messages]+ ...+ }+ ```+ post_model_hook: An optional node to add after the `agent` node (i.e., the node that calls the LLM).+ Useful for implementing human-in-the-loop, guardrails, validation, or other post-processing.+ Post-model hook must be a callable or a runnable that takes in current graph state and returns a state update.++ !!! Note+ Only available with `version="v2"`.+ state_schema: An optional state schema that defines graph state.+ Must have `messages` and `remaining_steps` keys.+ Defaults to `AgentState` that defines those two keys.+ context_schema: An optional schema for runtime context.+ checkpointer: An optional checkpoint saver object. This is used for persisting+ the state of the graph (e.g., as chat memory) for a single thread (e.g., a single conversation).+ store: An optional store object. This is used for persisting data+ across multiple threads (e.g., multiple conversations / users).+ interrupt_before: An optional list of node names to interrupt before.+ Should be one of the following: "agent", "tools".+ This is useful if you want to add a user confirmation or other interrupt before taking an action.+ interrupt_after: An optional list of node names to interrupt after.+ Should be one of the following: "agent", "tools".+ This is useful if you want to return directly or run additional processing on an output.+ debug: A flag indicating whether to enable debug mode.+ version: Determines the version of the graph to create.+ Can be one of:++ - `"v1"`: The tool node processes a single message. All tool+ calls in the message are executed in parallel within the tool node.+ - `"v2"`: The tool node processes a tool call.+ Tool calls are distributed across multiple instances of the tool+ node using the [Send](https://langchain-ai.github.io/langgraph/concepts/low_level/#send)+ API.+ name: An optional name for the CompiledStateGraph.+ This name will be automatically used when adding ReAct agent graph to another graph as a subgraph node -+ particularly useful for building multi-agent systems.++ !!! warning "`config_schema` Deprecated"+ The `config_schema` parameter is deprecated in v0.6.0 and support will be removed in v2.0.0.+ Please use `context_schema` instead to specify the schema for run-scoped context.+++ Returns:+ A compiled LangChain runnable that can be used for chat interactions.++ The "agent" node calls the language model with the messages list (after applying the prompt).+ If the resulting AIMessage contains `tool_calls`, the graph will then call the ["tools"][langgraph.prebuilt.tool_node.ToolNode].+ The "tools" node executes the tools (1 tool per `tool_call`) and adds the responses to the messages list+ as `ToolMessage` objects. The agent node then calls the language model again.+ The process repeats until no more `tool_calls` are present in the response.+ The agent then returns the full list of messages as a dictionary containing the key "messages".++ ``` mermaid+ sequenceDiagram+ participant U as User+ participant A as LLM+ participant T as Tools+ U->>A: Initial input+ Note over A: Prompt + LLM+ loop while tool_calls present+ A->>T: Execute tools+ T-->>A: ToolMessage for each tool_calls+ end+ A->>U: Return final state+ ```++ Example:+ ```python+ from langchain.agents import create_react_agent++ def check_weather(location: str) -> str:+ '''Return the weather forecast for the specified location.'''+ return f"It's always sunny in {location}"++ graph = create_react_agent(+ "anthropic:claude-3-7-sonnet-latest",+ tools=[check_weather],+ prompt="You are a helpful assistant",+ )+ inputs = {"messages": [{"role": "user", "content": "what is the weather in sf"}]}+ for chunk in graph.stream(inputs, stream_mode="updates"):+ print(chunk)+ ```+ """+ # Handle deprecated config_schema parameter+ if (config_schema := deprecated_kwargs.pop("config_schema", MISSING)) is not MISSING:+ warn(+ "`config_schema` is deprecated and will be removed. Please use `context_schema` instead.",+ category=DeprecationWarning,+ stacklevel=2,+ )+ if context_schema is None:+ context_schema = config_schema++ if len(deprecated_kwargs) > 0:+ msg = f"create_react_agent() got unexpected keyword arguments: {deprecated_kwargs}"+ raise TypeError(msg)++ if response_format and not isinstance(response_format, (ToolStrategy, ProviderStrategy)):+ if _supports_native_structured_output(model):+ response_format = ProviderStrategy(+ schema=response_format,+ )+ else:+ response_format = ToolStrategy(+ schema=response_format,+ )+ elif isinstance(response_format, tuple) and len(response_format) == 2:+ msg = "Passing a 2-tuple as response_format is no longer supported. "+ raise ValueError(msg)++ # Create and configure the agent builder+ builder = _AgentBuilder(+ model=model,+ tools=tools,+ prompt=prompt,+ response_format=cast("Union[ResponseFormat[StructuredResponseT], None]", response_format),+ pre_model_hook=pre_model_hook,+ post_model_hook=post_model_hook,+ state_schema=state_schema,+ context_schema=context_schema,+ version=version,+ name=name,+ store=store,+ )++ # Build and compile the workflow+ workflow = builder.build()+ return workflow.compile( # type: ignore[return-value]+ checkpointer=checkpointer,+ store=store,+ interrupt_before=interrupt_before,+ interrupt_after=interrupt_after,+ debug=debug,+ name=name,+ )+++__all__ = [+ "AgentState",+ "AgentStatePydantic",+ "AgentStateWithStructuredResponse",+ "AgentStateWithStructuredResponsePydantic",+ "create_react_agent",+]diff --git a/libs/langchain_v1/langchain/agents/structured_output.py b/libs/langchain_v1/langchain/agents/structured_output.pynew file mode 100644index 0000000000..dbbd3eef60--- /dev/null+++ b/libs/langchain_v1/langchain/agents/structured_output.py@@ -0,0 +1,403 @@+"""Types for setting agent response formats."""++from __future__ import annotations++import uuid+from dataclasses import dataclass, is_dataclass+from types import UnionType+from typing import (+ TYPE_CHECKING,+ Any,+ Generic,+ Literal,+ TypeVar,+ Union,+ get_args,+ get_origin,+)++from langchain_core.tools import BaseTool, StructuredTool+from pydantic import BaseModel, TypeAdapter+from typing_extensions import Self, is_typeddict++if TYPE_CHECKING:+ from collections.abc import Callable, Iterable++ from langchain_core.messages import AIMessage++# Supported schema types: Pydantic models, dataclasses, TypedDict, JSON schema dicts+SchemaT = TypeVar("SchemaT")++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]) -> None:+ """Initialize MultipleStructuredOutputsError.++ Args:+ tool_names: The names of the tools called for structured output.+ """+ self.tool_names = tool_names++ super().__init__(+ f"Model incorrectly returned multiple structured responses ({', '.join(tool_names)}) when only one is expected."+ )+++class StructuredOutputValidationError(StructuredOutputError):+ """Raised when structured output tool call arguments fail to parse according to the schema."""++ def __init__(self, tool_name: str, source: Exception) -> None:+ """Initialize StructuredOutputValidationError.++ Args:+ tool_name: The name of the tool that failed.+ source: The exception that occurred.+ """+ self.tool_name = tool_name+ self.source = source+ super().__init__(f"Failed to parse structured output for tool '{tool_name}': {source}.")+++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)+ schema_kind: One of "pydantic", "dataclass", "typeddict", or "json_schema"+ 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+ try:+ adapter: TypeAdapter[SchemaT] = TypeAdapter(schema)+ return adapter.validate_python(data)+ except Exception as e:+ schema_name = getattr(schema, "__name__", str(schema))+ msg = f"Failed to parse data to {schema_name}: {e}"+ raise ValueError(msg) 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:+ msg = (+ f"Unsupported schema type: {type(schema)}. "+ f"Supported types: Pydantic models, dataclasses, TypedDicts, and JSON schema dicts."+ )+ raise ValueError(msg)+++@dataclass(init=False)+class ToolStrategy(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 ToolStrategy. 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 ToolStrategy 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 ProviderStrategy(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:+ """Initialize ProviderStrategy with schema."""+ self.schema = schema+ self.schema_spec = _SchemaSpec(schema)++ def to_model_kwargs(self) -> dict[str, Any]:+ """Convert to kwargs to bind to a model to force structured output."""+ # 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 ProviderStrategyBinding(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 ProviderStrategyBinding instance from a SchemaSpec.++ Args:+ schema_spec: The SchemaSpec to convert++ Returns:+ A ProviderStrategyBinding 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")+ msg = f"Native structured output expected valid JSON for {schema_name}, but parsing failed: {e}."+ raise ValueError(msg) 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[ToolStrategy[SchemaT], ProviderStrategy[SchemaT]]diff --git a/libs/langchain_v1/langchain/agents/tool_node.py b/libs/langchain_v1/langchain/agents/tool_node.pynew file mode 100644index 0000000000..185a74a291--- /dev/null+++ b/libs/langchain_v1/langchain/agents/tool_node.py@@ -0,0 +1,1174 @@+"""Tool execution node for LangGraph workflows.++This module provides prebuilt functionality for executing tools in LangGraph.++Tools are functions that models can call to interact with external systems,+APIs, databases, or perform computations.++The module implements several key design patterns:+- Parallel execution of multiple tool calls for efficiency+- Robust error handling with customizable error messages+- State injection for tools that need access to graph state+- Store injection for tools that need persistent storage+- Command-based state updates for advanced control flow++Key Components:+ ToolNode: Main class for executing tools in LangGraph workflows+ InjectedState: Annotation for injecting graph state into tools+ InjectedStore: Annotation for injecting persistent store into tools+ tools_condition: Utility function for conditional routing based on tool calls++Typical Usage:+ ```python+ from langchain_core.tools import tool+ from langchain.agents import ToolNode++ @tool+ def my_tool(x: int) -> str:+ return f"Result: {x}"++ tool_node = ToolNode([my_tool])+ ```+"""++from __future__ import annotations++import asyncio+import inspect+import json+from copy import copy, deepcopy+from dataclasses import replace+from typing import (+ TYPE_CHECKING,+ Annotated,+ Any,+ Literal,+ Optional,+ Union,+ cast,+ get_args,+ get_origin,+ get_type_hints,+)++from langchain_core.messages import (+ AIMessage,+ AnyMessage,+ RemoveMessage,+ ToolCall,+ ToolMessage,+ convert_to_messages,+)+from langchain_core.runnables.config import (+ get_config_list,+ get_executor_for_config,+)+from langchain_core.tools import BaseTool, InjectedToolArg+from langchain_core.tools import tool as create_tool+from langchain_core.tools.base import (+ TOOL_MESSAGE_BLOCK_TYPES,+ get_all_basemodel_annotations,+)+from langgraph._internal._runnable import RunnableCallable+from langgraph.errors import GraphBubbleUp+from langgraph.graph.message import REMOVE_ALL_MESSAGES+from langgraph.types import Command, Send+from pydantic import BaseModel, ValidationError++if TYPE_CHECKING:+ from collections.abc import Callable, Sequence++ from langchain_core.runnables import RunnableConfig+ from langgraph.store.base import BaseStore++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]]:+ """Convert tool output to valid message content format.++ LangChain ToolMessages accept either string content or a list of content blocks.+ This function ensures tool outputs are properly formatted for message consumption+ by attempting to preserve structured data when possible, falling back to JSON+ serialization or string conversion.++ Args:+ output: The raw output from a tool execution. Can be any type.++ Returns:+ Either a string representation of the output or a list of content blocks+ if the output is already in the correct format for structured content.++ Note:+ This function prioritizes backward compatibility by defaulting to JSON+ serialization rather than supporting all possible message content formats.+ """+ if isinstance(output, str) or (+ isinstance(output, list)+ and all(isinstance(x, dict) and x.get("type") in TOOL_MESSAGE_BLOCK_TYPES for x in output)+ ):+ return output+ # Technically a list of strings is also valid message content, but it's+ # not currently well tested that all chat models support this.+ # And for backwards compatibility we want to make sure we don't break+ # any existing ToolNode usage.+ try:+ return json.dumps(output, ensure_ascii=False)+ except Exception: # noqa: BLE001+ return str(output)+++class ToolInvocationError(Exception):+ """Exception raised when a tool invocation fails due to invalid arguments."""++ def __init__(+ self, tool_name: str, source: ValidationError, tool_kwargs: dict[str, Any]+ ) -> None:+ """Initialize the ToolInvocationError.++ Args:+ tool_name: The name of the tool that failed.+ source: The exception that occurred.+ tool_kwargs: The keyword arguments that were passed to the tool.+ """+ self.message = TOOL_INVOCATION_ERROR_TEMPLATE.format(+ tool_name=tool_name, tool_kwargs=tool_kwargs, error=source+ )+ self.tool_name = tool_name+ self.tool_kwargs = tool_kwargs+ self.source = source+ 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,+ *,+ flag: Union[+ bool,+ str,+ Callable[..., str],+ type[Exception],+ tuple[type[Exception], ...],+ ],+) -> str:+ """Generate error message content based on exception handling configuration.++ This function centralizes error message generation logic, supporting different+ error handling strategies configured via the ToolNode's handle_tool_errors+ parameter.++ Args:+ e: The exception that occurred during tool execution.+ flag: Configuration for how to handle the error. Can be:+ - bool: If True, use default error template+ - str: Use this string as the error message+ - Callable: Call this function with the exception to get error message+ - tuple: Not used in this context (handled by caller)++ Returns:+ A string containing the error message to include in the ToolMessage.++ Raises:+ ValueError: If flag is not one of the supported types.++ Note:+ The tuple case is handled by the caller through exception type checking,+ not by this function directly.+ """+ 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) # type: ignore [assignment, call-arg]+ else:+ msg = (+ f"Got unexpected type of `handle_tool_error`. Expected bool, str "+ f"or callable. Received: {flag}"+ )+ raise ValueError(msg)+ return content+++def _infer_handled_types(handler: Callable[..., str]) -> tuple[type[Exception], ...]:+ """Infer exception types handled by a custom error handler function.++ This function analyzes the type annotations of a custom error handler to determine+ which exception types it's designed to handle. This enables type-safe error handling+ where only specific exceptions are caught and processed by the handler.++ Args:+ handler: A callable that takes an exception and returns an error message string.+ The first parameter (after self/cls if present) should be type-annotated+ with the exception type(s) to handle.++ Returns:+ A tuple of exception types that the handler can process. Returns (Exception,)+ if no specific type information is available for backward compatibility.++ Raises:+ ValueError: If the handler's annotation contains non-Exception types or+ if Union types contain non-Exception types.++ Note:+ This function supports both single exception types and Union types for+ handlers that need to handle multiple exception types differently.+ """+ sig = inspect.signature(handler)+ params = list(sig.parameters.values())+ if params:+ # If it's a method, the first argument is typically 'self' or 'cls'+ if params[0].name in ["self", "cls"] and len(params) == 2:+ first_param = params[1]+ else:+ first_param = params[0]++ type_hints = get_type_hints(handler)+ if first_param.name in type_hints:+ origin = get_origin(first_param.annotation)+ if origin is Union:+ args = get_args(first_param.annotation)+ if all(issubclass(arg, Exception) for arg in args):+ return tuple(args)+ msg = (+ "All types in the error handler error annotation must be "+ "Exception types. For example, "+ "`def custom_handler(e: Union[ValueError, TypeError])`. "+ f"Got '{first_param.annotation}' instead."+ )+ raise ValueError(msg)++ exception_type = type_hints[first_param.name]+ if Exception in exception_type.__mro__:+ return (exception_type,)+ msg = (+ f"Arbitrary types are not supported in the error handler "+ f"signature. Please annotate the error with either a "+ f"specific Exception type or a union of Exception types. "+ "For example, `def custom_handler(e: ValueError)` or "+ "`def custom_handler(e: Union[ValueError, TypeError])`. "+ f"Got '{exception_type}' instead."+ )+ raise ValueError(msg)++ # If no type information is available, return (Exception,)+ # for backwards compatibility.+ return (Exception,)+++class ToolNode(RunnableCallable):+ """A node for executing tools in LangGraph workflows.++ Handles tool execution patterns including function calls, state injection,+ persistent storage, and control flow. Manages parallel execution,+ error handling.++ 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. 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.+ Supports multiple strategies:++ - **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+ error message string.+ - **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+ and return the string result of calling it with the exception.+ - **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".+ Allows custom state schemas with different message field names.++ Examples:+ Basic usage:++ ```python+ from langchain.agents import ToolNode+ from langchain_core.tools import tool++ @tool+ def calculator(a: int, b: int) -> int:+ \"\"\"Add two numbers.\"\"\"+ return a + b++ tool_node = ToolNode([calculator])+ ```++ State injection:++ ```python+ from typing_extensions import Annotated+ from langgraph.agents.tool_node import InjectedState++ @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])+ ```++ Error handling:++ ```python+ def handle_errors(e: ValueError) -> str:+ return "Invalid input provided"++ tool_node = ToolNode([my_tool], handle_tool_errors=handle_errors)+ ```+ """++ name: str = "tools"++ def __init__(+ self,+ tools: Sequence[Union[BaseTool, Callable]],+ *,+ name: str = "tools",+ tags: list[str] | None = None,+ handle_tool_errors: Union[+ 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.++ Args:+ tools: Sequence of tools to make available for execution.+ name: Node name for graph identification.+ tags: Optional metadata tags.+ handle_tool_errors: Error handling configuration.+ 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, str | None]] = {}+ self._tool_to_store_arg: dict[str, str | None] = {}+ 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,+ input: Union[+ list[AnyMessage],+ dict[str, Any],+ BaseModel,+ ],+ config: RunnableConfig,+ *,+ store: Optional[BaseStore], # noqa: UP045+ ) -> Any:+ tool_calls, input_type = self._parse_input(input, store)+ config_list = get_config_list(config, len(tool_calls))+ input_types = [input_type] * len(tool_calls)+ with get_executor_for_config(config) as executor:+ outputs = [*executor.map(self._run_one, tool_calls, input_types, config_list)]++ return self._combine_tool_outputs(outputs, input_type)++ async def _afunc(+ self,+ input: Union[+ list[AnyMessage],+ dict[str, Any],+ BaseModel,+ ],+ config: RunnableConfig,+ *,+ store: Optional[BaseStore], # noqa: UP045+ ) -> Any:+ tool_calls, input_type = self._parse_input(input, store)+ outputs = await asyncio.gather(+ *(self._arun_one(call, input_type, config) for call in tool_calls)+ )++ return self._combine_tool_outputs(outputs, input_type)++ def _combine_tool_outputs(+ self,+ 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} # type: ignore[return-value, return-value]++ # LangGraph will automatically handle list of Command and non-command node+ # updates+ combined_outputs: list[Command | list[ToolMessage] | dict[str, list[ToolMessage]]] = []++ # combine all parent commands with goto into a single parent command+ parent_command: Command | None = None+ for output in outputs:+ if isinstance(output, Command):+ if (+ output.graph is Command.PARENT+ and isinstance(output.goto, list)+ and all(isinstance(send, Send) for send in output.goto)+ ):+ if parent_command:+ parent_command = replace(+ parent_command,+ goto=cast("list[Send]", parent_command.goto) + output.goto,+ )+ else:+ parent_command = Command(graph=Command.PARENT, goto=output.goto)+ else:+ combined_outputs.append(output)+ else:+ combined_outputs.append(+ [output] if input_type == "list" else {self._messages_key: [output]}+ )++ if parent_command:+ combined_outputs.append(parent_command)+ return combined_outputs++ def _run_one(+ self,+ call: ToolCall,+ input_type: Literal["list", "dict", "tool_calls"],+ config: RunnableConfig,+ ) -> 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"}+ 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"]) from exc++ # GraphInterrupt is a special exception that will always be raised.+ # It can be triggered in the following scenarios,+ # Where GraphInterrupt(GraphBubbleUp) is raised from an `interrupt` invocation most commonly:+ # (1) a GraphInterrupt is raised inside a tool+ # (2) a GraphInterrupt is raised inside a graph node for a graph called as a tool+ # (3) a GraphInterrupt is raised when a subgraph is interrupted inside a graph called as a tool+ # (2 and 3 can happen in a "supervisor w/ tools" multi-agent architecture)+ except GraphBubbleUp:+ raise+ except Exception as e:+ 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):+ raise+ # Handled+ content = _handle_tool_error(e, flag=self._handle_tool_errors)+ return ToolMessage(+ content=content,+ name=call["name"],+ tool_call_id=call["id"],+ status="error",+ )++ if isinstance(response, Command):+ return self._validate_tool_command(response, call, input_type)+ if isinstance(response, ToolMessage):+ response.content = cast("Union[str, list]", msg_content_output(response.content))+ return response+ msg = f"Tool {call['name']} returned unexpected type: {type(response)}"+ raise TypeError(msg)++ async def _arun_one(+ self,+ call: ToolCall,+ input_type: Literal["list", "dict", "tool_calls"],+ config: RunnableConfig,+ ) -> 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"}+ 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"]) from exc++ # GraphInterrupt is a special exception that will always be raised.+ # It can be triggered in the following scenarios,+ # Where GraphInterrupt(GraphBubbleUp) is raised from an `interrupt` invocation most commonly:+ # (1) a GraphInterrupt is raised inside a tool+ # (2) a GraphInterrupt is raised inside a graph node for a graph called as a tool+ # (3) a GraphInterrupt is raised when a subgraph is interrupted inside a graph called as a tool+ # (2 and 3 can happen in a "supervisor w/ tools" multi-agent architecture)+ except GraphBubbleUp:+ raise+ except Exception as e:+ 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):+ raise+ # Handled+ content = _handle_tool_error(e, flag=self._handle_tool_errors)++ return ToolMessage(+ content=content,+ name=call["name"],+ tool_call_id=call["id"],+ status="error",+ )++ if isinstance(response, Command):+ return self._validate_tool_command(response, call, input_type)+ if isinstance(response, ToolMessage):+ response.content = cast("Union[str, list]", msg_content_output(response.content))+ return response+ msg = f"Tool {call['name']} returned unexpected type: {type(response)}"+ raise TypeError(msg)++ def _parse_input(+ self,+ input: Union[+ list[AnyMessage],+ dict[str, Any],+ BaseModel,+ ],+ store: BaseStore | None,+ ) -> tuple[list[ToolCall], Literal["list", "dict", "tool_calls"]]:+ input_type: Literal["list", "dict", "tool_calls"]+ if isinstance(input, list):+ if isinstance(input[-1], dict) and input[-1].get("type") == "tool_call":+ input_type = "tool_calls"+ tool_calls = cast("list[ToolCall]", input)+ return tool_calls, input_type+ input_type = "list"+ messages = input+ elif isinstance(input, dict) and (messages := input.get(self._messages_key, [])):+ input_type = "dict"+ elif messages := getattr(input, self._messages_key, []):+ # Assume dataclass-like state that can coerce from dict+ input_type = "dict"+ else:+ msg = "No message found in input"+ raise ValueError(msg)++ try:+ latest_ai_message = next(m for m in reversed(messages) if isinstance(m, AIMessage))+ except StopIteration:+ msg = "No AIMessage found in input"+ raise ValueError(msg)++ tool_calls = [+ self.inject_tool_args(call, input, store) for call in latest_ai_message.tool_calls+ ]+ return tool_calls, input_type++ def _validate_tool_call(self, call: ToolCall) -> ToolMessage | None:+ 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(all_tool_names),+ )+ return ToolMessage(+ content, name=requested_tool, tool_call_id=call["id"], status="error"+ )+ return None++ def _inject_state(+ self,+ tool_call: ToolCall,+ input: Union[+ list[AnyMessage],+ dict[str, Any],+ BaseModel,+ ],+ ) -> ToolCall:+ 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+ ) or required_fields[0] is None:+ input = {self._messages_key: input}+ else:+ err_msg = (+ f"Invalid input to ToolNode. Tool {tool_call['name']} requires "+ f"graph state dict as input."+ )+ if any(state_field for state_field in state_args.values()):+ required_fields_str = ", ".join(f for f in required_fields if f)+ err_msg += f" State should contain fields {required_fields_str}."+ raise ValueError(err_msg)++ if isinstance(input, dict):+ tool_state_args = {+ tool_arg: input[state_field] if state_field else input+ for tool_arg, state_field in state_args.items()+ }+ else:+ tool_state_args = {+ tool_arg: getattr(input, state_field) if state_field else input+ for tool_arg, state_field in state_args.items()+ }++ tool_call["args"] = {+ **tool_call["args"],+ **tool_state_args,+ }+ return tool_call++ def _inject_store(self, tool_call: ToolCall, store: BaseStore | None) -> ToolCall:+ store_arg = self._tool_to_store_arg[tool_call["name"]]+ if not store_arg:+ return tool_call++ if store is None:+ msg = (+ "Cannot inject store into tools with InjectedStore annotations - "+ "please compile your graph with a store."+ )+ raise ValueError(msg)++ tool_call["args"] = {+ **tool_call["args"],+ store_arg: store,+ }+ return tool_call++ def inject_tool_args(+ self,+ tool_call: ToolCall,+ input: Union[+ list[AnyMessage],+ dict[str, Any],+ BaseModel,+ ],+ store: BaseStore | None,+ ) -> ToolCall:+ """Inject graph state and store into tool call arguments.++ This method enables tools to access graph context that should not be controlled+ by the model. Tools can declare dependencies on graph state or persistent storage+ using InjectedState and InjectedStore annotations. This method automatically+ identifies these dependencies and injects the appropriate values.++ The injection process preserves the original tool call structure while adding+ the necessary context arguments. This allows tools to be both model-callable+ and context-aware without exposing internal state management to the model.++ Args:+ tool_call: The tool call dictionary to augment with injected arguments.+ Must contain 'name', 'args', 'id', and 'type' fields.+ input: The current graph state to inject into tools requiring state access.+ Can be a message list, state dictionary, or BaseModel instance.+ store: The persistent store instance to inject into tools requiring storage.+ Will be None if no store is configured for the graph.++ Returns:+ A new ToolCall dictionary with the same structure as the input but with+ additional arguments injected based on the tool's annotation requirements.++ Raises:+ ValueError: If a tool requires store injection but no store is provided,+ or if state injection requirements cannot be satisfied.++ Note:+ This method is automatically called during tool execution but can also+ be used manually when working with the Send API or custom routing logic.+ The injection is performed on a copy of the tool call to avoid mutating+ the original.+ """+ if tool_call["name"] not in self.tools_by_name:+ return tool_call++ tool_call_copy: ToolCall = copy(tool_call)+ tool_call_with_state = self._inject_state(tool_call_copy, input)+ return self._inject_store(tool_call_with_state, store)++ def _validate_tool_command(+ self,+ command: Command,+ call: ToolCall,+ input_type: Literal["list", "dict", "tool_calls"],+ ) -> Command:+ if isinstance(command.update, dict):+ # 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"):+ msg = (+ 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']}'"+ )+ raise ValueError(msg)++ updated_command = deepcopy(command)+ state_update = cast("dict[str, Any]", updated_command.update) or {}+ 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=[...])])+ if input_type != "list":+ msg = (+ f"Tools can provide a list of messages in Command.update only when using list of messages as ToolNode input, "+ f"got: {command.update} for tool '{call['name']}'"+ )+ raise ValueError(msg)++ updated_command = deepcopy(command)+ messages_update = updated_command.update+ else:+ return command++ # convert to message objects if updates are in a dict format+ messages_update = convert_to_messages(messages_update)++ # no validation needed if all messages are being removed+ if messages_update == [RemoveMessage(id=REMOVE_ALL_MESSAGES)]:+ return updated_command++ has_matching_tool_message = False+ for message in messages_update:+ if not isinstance(message, ToolMessage):+ continue++ if message.tool_call_id == call["id"]:+ message.name = call["name"]+ has_matching_tool_message = True++ # validate that we always have a ToolMessage matching the tool call in+ # Command.update if command is sent to the CURRENT graph+ if updated_command.graph is None and not has_matching_tool_message:+ example_update = (+ '`Command(update={"messages": [ToolMessage("Success", tool_call_id=tool_call_id), ...]}, ...)`'+ if input_type == "dict"+ else '`Command(update=[ToolMessage("Success", tool_call_id=tool_call_id), ...], ...)`'+ )+ msg = (+ f"Expected to have a matching ToolMessage in Command.update for tool '{call['name']}', got: {messages_update}. "+ "Every tool call (LLM requesting to call a tool) in the message history MUST have a corresponding ToolMessage. "+ f"You can fix it by modifying the tool to return {example_update}."+ )+ raise ValueError(msg)+ return updated_command+++def tools_condition(+ state: Union[list[AnyMessage], dict[str, Any], BaseModel],+ messages_key: str = "messages",+) -> Literal["tools", "__end__"]:+ """Conditional routing function for tool-calling workflows.++ This utility function implements the standard conditional logic for ReAct-style+ agents: if the last AI message contains tool calls, route to the tool execution+ node; otherwise, end the workflow. This pattern is fundamental to most tool-calling+ agent architectures.++ The function handles multiple state formats commonly used in LangGraph applications,+ making it flexible for different graph designs while maintaining consistent behavior.++ Args:+ state: The current graph state to examine for tool calls. Supported formats:+ - Dictionary containing a messages key (for StateGraph)+ - BaseModel instance with a messages attribute+ messages_key: The key or attribute name containing the message list in the state.+ This allows customization for graphs using different state schemas.+ Defaults to "messages".++ Returns:+ Either "tools" if tool calls are present in the last AI message, or "__end__"+ to terminate the workflow. These are the standard routing destinations for+ tool-calling conditional edges.++ Raises:+ ValueError: If no messages can be found in the provided state format.++ Example:+ Basic usage in a ReAct agent:++ ```python+ from langgraph.graph import StateGraph+ from langgraph.agents.tool_node import ToolNode, tools_condition+ from typing_extensions import TypedDict++ class State(TypedDict):+ messages: list++ graph = StateGraph(State)+ graph.add_node("llm", call_model)+ graph.add_node("tools", ToolNode([my_tool]))+ graph.add_conditional_edges(+ "llm",+ tools_condition, # Routes to "tools" or "__end__"+ {"tools": "tools", "__end__": "__end__"}+ )+ ```++ Custom messages key:++ ```python+ def custom_condition(state):+ return tools_condition(state, messages_key="chat_history")+ ```++ Note:+ This function is designed to work seamlessly with ToolNode and standard+ LangGraph patterns. It expects the last message to be an AIMessage when+ tool calls are present, which is the standard output format for tool-calling+ language models.+ """+ if isinstance(state, list):+ ai_message = state[-1]+ elif (isinstance(state, dict) and (messages := state.get(messages_key, []))) or (+ messages := getattr(state, messages_key, [])+ ):+ ai_message = messages[-1]+ else:+ msg = f"No messages found in input state to tool_edge: {state}"+ raise ValueError(msg)+ if hasattr(ai_message, "tool_calls") and len(ai_message.tool_calls) > 0:+ return "tools"+ return "__end__"+++class InjectedState(InjectedToolArg):+ """Annotation for injecting graph state into tool arguments.++ This annotation enables tools to access graph state without exposing state+ management details to the language model. Tools annotated with InjectedState+ receive state data automatically during execution while remaining invisible+ to the model's tool-calling interface.++ Args:+ field: Optional key to extract from the state dictionary. If None, the entire+ state is injected. If specified, only that field's value is injected.+ This allows tools to request specific state components rather than+ processing the full state structure.++ Example:+ ```python+ from typing import List+ from typing_extensions import Annotated, TypedDict++ from langchain_core.messages import BaseMessage, AIMessage+ from langchain_core.tools import tool++ from langgraph.agents.tool_node import InjectedState, ToolNode+++ class AgentState(TypedDict):+ messages: List[BaseMessage]+ foo: str++ @tool+ def state_tool(x: int, state: Annotated[dict, InjectedState]) -> str:+ '''Do something with state.'''+ if len(state["messages"]) > 2:+ return state["foo"] + str(x)+ else:+ return "not enough messages"++ @tool+ def foo_tool(x: int, foo: Annotated[str, InjectedState("foo")]) -> str:+ '''Do something else with state.'''+ return foo + str(x + 1)++ node = ToolNode([state_tool, foo_tool])++ tool_call1 = {"name": "state_tool", "args": {"x": 1}, "id": "1", "type": "tool_call"}+ tool_call2 = {"name": "foo_tool", "args": {"x": 1}, "id": "2", "type": "tool_call"}+ state = {+ "messages": [AIMessage("", tool_calls=[tool_call1, tool_call2])],+ "foo": "bar",+ }+ node.invoke(state)+ ```++ ```pycon+ [+ ToolMessage(content='not enough messages', name='state_tool', tool_call_id='1'),+ ToolMessage(content='bar2', name='foo_tool', tool_call_id='2')+ ]+ ```++ Note:+ - InjectedState arguments are automatically excluded from tool schemas+ presented to language models+ - ToolNode handles the injection process during execution+ - Tools can mix regular arguments (controlled by the model) with injected+ arguments (controlled by the system)+ - State injection occurs after the model generates tool calls but before+ tool execution+ """++ def __init__(self, field: str | None = None) -> None:+ """Initialize the InjectedState annotation."""+ self.field = field+++class InjectedStore(InjectedToolArg):+ """Annotation for injecting persistent store into tool arguments.++ This annotation enables tools to access LangGraph's persistent storage system+ without exposing storage details to the language model. Tools annotated with+ InjectedStore receive the store instance automatically during execution while+ remaining invisible to the model's tool-calling interface.++ The store provides persistent, cross-session data storage that tools can use+ for maintaining context, user preferences, or any other data that needs to+ persist beyond individual workflow executions.++ !!! Warning+ `InjectedStore` annotation requires `langchain-core >= 0.3.8`++ Example:+ ```python+ from typing_extensions import Annotated+ from langchain_core.tools import tool+ from langgraph.store.memory import InMemoryStore+ from langgraph.agents.tool_node import InjectedStore, ToolNode++ @tool+ def save_preference(+ key: str,+ value: str,+ store: Annotated[Any, InjectedStore()]+ ) -> str:+ \"\"\"Save user preference to persistent storage.\"\"\"+ store.put(("preferences",), key, value)+ return f"Saved {key} = {value}"++ @tool+ def get_preference(+ key: str,+ store: Annotated[Any, InjectedStore()]+ ) -> str:+ \"\"\"Retrieve user preference from persistent storage.\"\"\"+ result = store.get(("preferences",), key)+ return result.value if result else "Not found"+ ```++ Usage with ToolNode and graph compilation:++ ```python+ from langgraph.graph import StateGraph+ from langgraph.store.memory import InMemoryStore++ store = InMemoryStore()+ tool_node = ToolNode([save_preference, get_preference])++ graph = StateGraph(State)+ graph.add_node("tools", tool_node)+ compiled_graph = graph.compile(store=store) # Store is injected automatically+ ```++ Cross-session persistence:++ ```python+ # First session+ result1 = graph.invoke({"messages": [HumanMessage("Save my favorite color as blue")]})++ # Later session - data persists+ result2 = graph.invoke({"messages": [HumanMessage("What's my favorite color?")]})+ ```++ Note:+ - InjectedStore arguments are automatically excluded from tool schemas+ presented to language models+ - The store instance is automatically injected by ToolNode during execution+ - Tools can access namespaced storage using the store's get/put methods+ - Store injection requires the graph to be compiled with a store instance+ - Multiple tools can share the same store instance for data consistency+ """+++def _is_injection(type_arg: Any, injection_type: type[Union[InjectedState, InjectedStore]]) -> bool:+ """Check if a type argument represents an injection annotation.++ This utility function determines whether a type annotation indicates that+ an argument should be injected with state or store data. It handles both+ direct annotations and nested annotations within Union or Annotated types.++ Args:+ type_arg: The type argument to check for injection annotations.+ injection_type: The injection type to look for (InjectedState or InjectedStore).++ Returns:+ True if the type argument contains the specified injection annotation.+ """+ if isinstance(type_arg, injection_type) or (+ isinstance(type_arg, type) and issubclass(type_arg, injection_type)+ ):+ return True+ origin_ = get_origin(type_arg)+ if origin_ is Union or origin_ is Annotated:+ return any(_is_injection(ta, injection_type) for ta in get_args(type_arg))+ return False+++def _get_state_args(tool: BaseTool) -> dict[str, str | None]:+ """Extract state injection mappings from tool annotations.++ This function analyzes a tool's input schema to identify arguments that should+ be injected with graph state. It processes InjectedState annotations to build+ a mapping of tool argument names to state field names.++ Args:+ tool: The tool to analyze for state injection requirements.++ Returns:+ A dictionary mapping tool argument names to state field names. If a field+ name is None, the entire state should be injected for that argument.+ """+ full_schema = tool.get_input_schema()+ tool_args_to_state_fields: dict = {}++ for name, type_ in get_all_basemodel_annotations(full_schema).items():+ injections = [+ type_arg for type_arg in get_args(type_) if _is_injection(type_arg, InjectedState)+ ]+ if len(injections) > 1:+ msg = (+ "A tool argument should not be annotated with InjectedState more than "+ f"once. Received arg {name} with annotations {injections}."+ )+ raise ValueError(msg)+ if len(injections) == 1:+ injection = injections[0]+ if isinstance(injection, InjectedState) and injection.field:+ tool_args_to_state_fields[name] = injection.field+ else:+ tool_args_to_state_fields[name] = None+ else:+ pass+ return tool_args_to_state_fields+++def _get_store_arg(tool: BaseTool) -> str | None:+ """Extract store injection argument from tool annotations.++ This function analyzes a tool's input schema to identify the argument that+ should be injected with the graph store. Only one store argument is supported+ per tool.++ Args:+ tool: The tool to analyze for store injection requirements.++ Returns:+ The name of the argument that should receive the store injection, or None+ if no store injection is required.++ Raises:+ ValueError: If a tool argument has multiple InjectedStore annotations.+ """+ full_schema = tool.get_input_schema()+ for name, type_ in get_all_basemodel_annotations(full_schema).items():+ injections = [+ type_arg for type_arg in get_args(type_) if _is_injection(type_arg, InjectedStore)+ ]+ if len(injections) > 1:+ msg = (+ "A tool argument should not be annotated with InjectedStore more than "+ f"once. Received arg {name} with annotations {injections}."+ )+ raise ValueError(msg)+ if len(injections) == 1:+ return name++ return Nonediff --git a/libs/langchain_v1/langchain/chat_models/base.py b/libs/langchain_v1/langchain/chat_models/base.pyindex f222aa1b86..f9ae98e436 100644--- a/libs/langchain_v1/langchain/chat_models/base.py+++ b/libs/langchain_v1/langchain/chat_models/base.py@@ -13,7 +13,7 @@ from typing import ()from langchain_core.language_models import BaseChatModel, LanguageModelInput-from langchain_core.messages import AnyMessage, BaseMessage+from langchain_core.messages import AIMessage, AnyMessagefrom langchain_core.runnables import Runnable, RunnableConfig, ensure_configfrom typing_extensions import override@@ -915,7 +915,7 @@ class _ConfigurableModel(Runnable[LanguageModelInput, Any]):self,tools: Sequence[Union[dict[str, Any], type[BaseModel], Callable, BaseTool]],**kwargs: Any,- ) -> Runnable[LanguageModelInput, BaseMessage]:+ ) -> Runnable[LanguageModelInput, AIMessage]:return self.__getattr__("bind_tools")(tools, **kwargs)# Explicitly added to satisfy downstream linters.diff --git a/libs/langchain_v1/pyproject.toml b/libs/langchain_v1/pyproject.tomlindex b05002d4c2..f471a309b5 100644--- a/libs/langchain_v1/pyproject.toml+++ b/libs/langchain_v1/pyproject.toml@@ -52,11 +52,11 @@ test = ["pytest-socket>=0.6.0","syrupy>=4.0.2","pytest-xdist>=3.6.1",- "blockbuster>=1.5.18","langchain-tests","langchain-text-splitters","langchain-openai","toml>=0.10.2",+ "pytest-mock"]codespell = ["codespell<3.0.0,>=2.2.0"]lint = [@@ -94,6 +94,7 @@ strict_bytes = "True"ignore_missing_imports = "True"enable_error_code = "deprecated"report_deprecated_as_note = "True"+exclude = ["tests/unit_tests/agents/*", "tests/integration_tests/agents/*"]# TODO: activate for 'strict' checkingdisallow_untyped_calls = "False"@@ -135,14 +136,24 @@ flake8-annotations.allow-star-arg-any = true"D", # Documentation rules"PLC0415", # Imports should be at the top. Not always desirable for tests]+"langchain/agents/*" = [+ "ANN401", # we use Any right now, need to narrow+ "E501", # line too long, needs to fix+ "A002", # input is shadowing builtin+ "A001", # input is shadowing builtin+ "B904", # use from for exceptions+ "PLR2004", # magic values are fine for this case+ "C901", # too complex+ "TRY004", # type error exception+ "PLR0912", # too many branches+ "PLR0911", # too many return statements+]+"tests/unit_tests/agents/*" = ["ALL"]+"tests/integration_tests/agents/*" = ["ALL"][tool.ruff.lint.extend-per-file-ignores]"scripts/check_imports.py" = ["ALL"]-"langchain/globals.py" = [- "PLW"-]-"langchain/chat_models/base.py" = ["ANN","C901",diff --git a/libs/langchain_v1/tests/integration_tests/agents/__init__.py b/libs/langchain_v1/tests/integration_tests/agents/__init__.pynew file mode 100644index 0000000000..6c212a0b69--- /dev/null+++ b/libs/langchain_v1/tests/integration_tests/agents/__init__.py@@ -0,0 +1 @@+"""Integration tests for the agents module."""diff --git a/libs/langchain_v1/tests/integration_tests/agents/test_response_format.py b/libs/langchain_v1/tests/integration_tests/agents/test_response_format.pynew file mode 100644index 0000000000..6836cc692c--- /dev/null+++ b/libs/langchain_v1/tests/integration_tests/agents/test_response_format.py@@ -0,0 +1,79 @@+import pytest+from langchain_core.messages import HumanMessage+from pydantic import BaseModel, Field++from langchain.agents import create_react_agent+from langchain.agents.structured_output import ToolStrategy+++class WeatherBaseModel(BaseModel):+ """Weather response."""++ temperature: float = Field(description="The temperature in fahrenheit")+ condition: str = Field(description="Weather condition")+++def get_weather(city: str) -> str: # noqa: ARG001+ """Get the weather for a city."""+ return "The weather is sunny and 75°F."++[email protected]("langchain_openai")+def test_inference_to_native_output() -> None:+ """Test that native output is inferred when a model supports it."""+ from langchain_openai import ChatOpenAI++ 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+ ]++[email protected]("langchain_openai")+def test_inference_to_tool_output() -> None:+ """Test that tool output is inferred when a model supports it."""+ from langchain_openai import ChatOpenAI++ 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=ToolStrategy(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+ ]diff --git a/libs/langchain_v1/tests/unit_tests/agents/__init__.py b/libs/langchain_v1/tests/unit_tests/agents/__init__.pynew file mode 100644index 0000000000..e69de29bb2diff --git a/libs/langchain_v1/tests/unit_tests/agents/__snapshots__/test_react_agent_graph.ambr b/libs/langchain_v1/tests/unit_tests/agents/__snapshots__/test_react_agent_graph.ambrnew file mode 100644index 0000000000..49e40649e5--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/__snapshots__/test_react_agent_graph.ambr@@ -0,0 +1,83 @@+# serializer version: 1+# name: test_react_agent_graph_structure[None-None-tools0]+ '''+ graph TD;+ __start__ --> agent;+ agent --> __end__;++ '''+# ---+# name: test_react_agent_graph_structure[None-None-tools1]+ '''+ graph TD;+ __start__ --> agent;+ agent -.-> __end__;+ agent -.-> tools;+ tools --> agent;++ '''+# ---+# name: test_react_agent_graph_structure[None-pre_model_hook-tools0]+ '''+ graph TD;+ __start__ --> pre_model_hook;+ pre_model_hook --> agent;+ agent --> __end__;++ '''+# ---+# name: test_react_agent_graph_structure[None-pre_model_hook-tools1]+ '''+ graph TD;+ __start__ --> pre_model_hook;+ agent -.-> __end__;+ agent -.-> tools;+ pre_model_hook --> agent;+ tools --> pre_model_hook;++ '''+# ---+# name: test_react_agent_graph_structure[post_model_hook-None-tools0]+ '''+ graph TD;+ __start__ --> agent;+ agent --> post_model_hook;+ post_model_hook --> __end__;++ '''+# ---+# name: test_react_agent_graph_structure[post_model_hook-None-tools1]+ '''+ graph TD;+ __start__ --> agent;+ agent --> post_model_hook;+ post_model_hook -.-> __end__;+ post_model_hook -.-> agent;+ post_model_hook -.-> tools;+ tools --> agent;++ '''+# ---+# name: test_react_agent_graph_structure[post_model_hook-pre_model_hook-tools0]+ '''+ graph TD;+ __start__ --> pre_model_hook;+ agent --> post_model_hook;+ pre_model_hook --> agent;+ post_model_hook --> __end__;++ '''+# ---+# name: test_react_agent_graph_structure[post_model_hook-pre_model_hook-tools1]+ '''+ graph TD;+ __start__ --> pre_model_hook;+ agent --> post_model_hook;+ post_model_hook -.-> __end__;+ post_model_hook -.-> pre_model_hook;+ post_model_hook -.-> tools;+ pre_model_hook --> agent;+ tools --> pre_model_hook;++ '''+# ---diff --git a/libs/langchain_v1/tests/unit_tests/agents/any_str.py b/libs/langchain_v1/tests/unit_tests/agents/any_str.pynew file mode 100644index 0000000000..790324322d--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/any_str.py@@ -0,0 +1,18 @@+import re+from typing import Union+++class AnyStr(str):+ def __init__(self, prefix: Union[str, re.Pattern] = "") -> None:+ super().__init__()+ self.prefix = prefix++ def __eq__(self, other: object) -> bool:+ return isinstance(other, str) and (+ other.startswith(self.prefix)+ if isinstance(self.prefix, str)+ else self.prefix.match(other)+ )++ def __hash__(self) -> int:+ return hash((str(self), self.prefix))diff --git a/libs/langchain_v1/tests/unit_tests/agents/compose-postgres.yml b/libs/langchain_v1/tests/unit_tests/agents/compose-postgres.ymlnew file mode 100644index 0000000000..221b35dafe--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/compose-postgres.yml@@ -0,0 +1,17 @@+name: langgraph-tests+services:+ postgres-test:+ image: postgres:16+ ports:+ - "5442:5432"+ environment:+ POSTGRES_DB: postgres+ POSTGRES_USER: postgres+ POSTGRES_PASSWORD: postgres+ healthcheck:+ test: pg_isready -U postgres+ start_period: 10s+ timeout: 1s+ retries: 5+ interval: 60s+ start_interval: 1sdiff --git a/libs/langchain_v1/tests/unit_tests/agents/compose-redis.yml b/libs/langchain_v1/tests/unit_tests/agents/compose-redis.ymlnew file mode 100644index 0000000000..18862fd28d--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/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 testingdiff --git a/libs/langchain_v1/tests/unit_tests/agents/conftest.py b/libs/langchain_v1/tests/unit_tests/agents/conftest.pynew file mode 100644index 0000000000..7e134f6827--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/conftest.py@@ -0,0 +1,194 @@+import os+from collections.abc import AsyncIterator, Iterator+from uuid import UUID++import pytest+from langgraph.checkpoint.base import BaseCheckpointSaver+from langgraph.store.base import BaseStore+from pytest_mock import MockerFixture++from .conftest_checkpointer import (+ _checkpointer_memory,+ _checkpointer_postgres,+ _checkpointer_postgres_aio,+ _checkpointer_postgres_aio_pipe,+ _checkpointer_postgres_aio_pool,+ _checkpointer_postgres_pipe,+ _checkpointer_postgres_pool,+ _checkpointer_sqlite,+ _checkpointer_sqlite_aio,+)+from .conftest_store import (+ _store_memory,+ _store_postgres,+ _store_postgres_aio,+ _store_postgres_aio_pipe,+ _store_postgres_aio_pool,+ _store_postgres_pipe,+ _store_postgres_pool,+)++# Global variables for checkpointer and store configurations+FAST_MODE = os.getenv("LANGGRAPH_TEST_FAST", "true").lower() in ("true", "1", "yes")++SYNC_CHECKPOINTER_PARAMS = (+ ["memory"]+ if FAST_MODE+ else [+ "memory",+ "sqlite",+ "postgres",+ "postgres_pipe",+ "postgres_pool",+ ]+)++ASYNC_CHECKPOINTER_PARAMS = (+ ["memory"]+ if FAST_MODE+ else [+ "memory",+ "sqlite_aio",+ "postgres_aio",+ "postgres_aio_pipe",+ "postgres_aio_pool",+ ]+)++SYNC_STORE_PARAMS = (+ ["in_memory"]+ if FAST_MODE+ else [+ "in_memory",+ "postgres",+ "postgres_pipe",+ "postgres_pool",+ ]+)++ASYNC_STORE_PARAMS = (+ ["in_memory"]+ if FAST_MODE+ else [+ "in_memory",+ "postgres_aio",+ "postgres_aio_pipe",+ "postgres_aio_pool",+ ]+)+++def anyio_backend() -> str:+ return "asyncio"+++def deterministic_uuids(mocker: MockerFixture) -> MockerFixture:+ side_effect = (UUID(f"00000000-0000-4000-8000-{i:012}", version=4) for i in range(10000))+ return mocker.patch("uuid.uuid4", side_effect=side_effect)+++# checkpointer fixtures+++ params=SYNC_STORE_PARAMS,+)+def sync_store(request: pytest.FixtureRequest) -> Iterator[BaseStore]:+ store_name = request.param+ if store_name is None:+ yield None+ elif store_name == "in_memory":+ with _store_memory() as store:+ yield store+ elif store_name == "postgres":+ with _store_postgres() as store:+ yield store+ elif store_name == "postgres_pipe":+ with _store_postgres_pipe() as store:+ yield store+ elif store_name == "postgres_pool":+ with _store_postgres_pool() as store:+ yield store+ else:+ msg = f"Unknown store {store_name}"+ raise NotImplementedError(msg)+++ params=ASYNC_STORE_PARAMS,+)+async def async_store(request: pytest.FixtureRequest) -> AsyncIterator[BaseStore]:+ store_name = request.param+ if store_name is None:+ yield None+ elif store_name == "in_memory":+ with _store_memory() as store:+ yield store+ elif store_name == "postgres_aio":+ async with _store_postgres_aio() as store:+ yield store+ elif store_name == "postgres_aio_pipe":+ async with _store_postgres_aio_pipe() as store:+ yield store+ elif store_name == "postgres_aio_pool":+ async with _store_postgres_aio_pool() as store:+ yield store+ else:+ msg = f"Unknown store {store_name}"+ raise NotImplementedError(msg)+++ params=SYNC_CHECKPOINTER_PARAMS,+)+def sync_checkpointer(+ request: pytest.FixtureRequest,+) -> Iterator[BaseCheckpointSaver]:+ checkpointer_name = request.param+ if checkpointer_name == "memory":+ with _checkpointer_memory() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "sqlite":+ with _checkpointer_sqlite() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "postgres":+ with _checkpointer_postgres() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "postgres_pipe":+ with _checkpointer_postgres_pipe() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "postgres_pool":+ with _checkpointer_postgres_pool() as checkpointer:+ yield checkpointer+ else:+ msg = f"Unknown checkpointer: {checkpointer_name}"+ raise NotImplementedError(msg)+++ params=ASYNC_CHECKPOINTER_PARAMS,+)+async def async_checkpointer(+ request: pytest.FixtureRequest,+) -> AsyncIterator[BaseCheckpointSaver]:+ checkpointer_name = request.param+ if checkpointer_name == "memory":+ with _checkpointer_memory() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "sqlite_aio":+ async with _checkpointer_sqlite_aio() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "postgres_aio":+ async with _checkpointer_postgres_aio() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "postgres_aio_pipe":+ async with _checkpointer_postgres_aio_pipe() as checkpointer:+ yield checkpointer+ elif checkpointer_name == "postgres_aio_pool":+ async with _checkpointer_postgres_aio_pool() as checkpointer:+ yield checkpointer+ else:+ msg = f"Unknown checkpointer: {checkpointer_name}"+ raise NotImplementedError(msg)diff --git a/libs/langchain_v1/tests/unit_tests/agents/conftest_checkpointer.py b/libs/langchain_v1/tests/unit_tests/agents/conftest_checkpointer.pynew file mode 100644index 0000000000..4505fb28ee--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/conftest_checkpointer.py@@ -0,0 +1,64 @@+from contextlib import asynccontextmanager, contextmanager++from .memory_assert import (+ MemorySaverAssertImmutable,+)+++@contextmanager+def _checkpointer_memory():+ yield MemorySaverAssertImmutable()+++@asynccontextmanager+async def _checkpointer_memory_aio():+ yield MemorySaverAssertImmutable()+++# Placeholder functions for other checkpointer types that aren't available+@contextmanager+def _checkpointer_sqlite():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()+++@contextmanager+def _checkpointer_postgres():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()+++@contextmanager+def _checkpointer_postgres_pipe():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()+++@contextmanager+def _checkpointer_postgres_pool():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()+++@asynccontextmanager+async def _checkpointer_sqlite_aio():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()+++@asynccontextmanager+async def _checkpointer_postgres_aio():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()+++@asynccontextmanager+async def _checkpointer_postgres_aio_pipe():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()+++@asynccontextmanager+async def _checkpointer_postgres_aio_pool():+ # Fallback to memory for now+ yield MemorySaverAssertImmutable()diff --git a/libs/langchain_v1/tests/unit_tests/agents/conftest_store.py b/libs/langchain_v1/tests/unit_tests/agents/conftest_store.pynew file mode 100644index 0000000000..fb0eb4e2fb--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/conftest_store.py@@ -0,0 +1,58 @@+from contextlib import asynccontextmanager, contextmanager++from langgraph.store.memory import InMemoryStore+++@contextmanager+def _store_memory():+ store = InMemoryStore()+ yield store+++@asynccontextmanager+async def _store_memory_aio():+ store = InMemoryStore()+ yield store+++# Placeholder functions for other store types that aren't available+@contextmanager+def _store_postgres():+ # Fallback to memory for now+ store = InMemoryStore()+ yield store+++@contextmanager+def _store_postgres_pipe():+ # Fallback to memory for now+ store = InMemoryStore()+ yield store+++@contextmanager+def _store_postgres_pool():+ # Fallback to memory for now+ store = InMemoryStore()+ yield store+++@asynccontextmanager+async def _store_postgres_aio():+ # Fallback to memory for now+ store = InMemoryStore()+ yield store+++@asynccontextmanager+async def _store_postgres_aio_pipe():+ # Fallback to memory for now+ store = InMemoryStore()+ yield store+++@asynccontextmanager+async def _store_postgres_aio_pool():+ # Fallback to memory for now+ store = InMemoryStore()+ yield storediff --git a/libs/langchain_v1/tests/unit_tests/agents/memory_assert.py b/libs/langchain_v1/tests/unit_tests/agents/memory_assert.pynew file mode 100644index 0000000000..99d66bbe02--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/memory_assert.py@@ -0,0 +1,56 @@+import os+import tempfile+from collections import defaultdict+from functools import partial++from langgraph.checkpoint.base import (+ ChannelVersions,+ Checkpoint,+ CheckpointMetadata,+ SerializerProtocol,+)+from langgraph.checkpoint.memory import InMemorySaver, PersistentDict+from langgraph.pregel._checkpoint import copy_checkpoint+++class MemorySaverAssertImmutable(InMemorySaver):+ storage_for_copies: defaultdict[str, dict[str, dict[str, Checkpoint]]]++ def __init__(+ self,+ *,+ serde: SerializerProtocol | None = None,+ put_sleep: float | None = None,+ ) -> None:+ _, filename = tempfile.mkstemp()+ super().__init__(serde=serde, factory=partial(PersistentDict, filename=filename))+ self.storage_for_copies = defaultdict(lambda: defaultdict(dict))+ self.put_sleep = put_sleep+ self.stack.callback(os.remove, filename)++ def put(+ self,+ config: dict,+ checkpoint: Checkpoint,+ metadata: CheckpointMetadata,+ new_versions: ChannelVersions,+ ) -> None:+ if self.put_sleep:+ import time++ time.sleep(self.put_sleep)+ # assert checkpoint hasn't been modified since last written+ thread_id = config["configurable"]["thread_id"]+ checkpoint_ns = config["configurable"]["checkpoint_ns"]+ if saved := super().get(config):+ assert (+ self.serde.loads_typed(+ self.storage_for_copies[thread_id][checkpoint_ns][saved["id"]]+ )+ == saved+ )+ self.storage_for_copies[thread_id][checkpoint_ns][checkpoint["id"]] = (+ self.serde.dumps_typed(copy_checkpoint(checkpoint))+ )+ # call super to write checkpoint+ return super().put(config, checkpoint, metadata, new_versions)diff --git a/libs/langchain_v1/tests/unit_tests/agents/messages.py b/libs/langchain_v1/tests/unit_tests/agents/messages.pynew file mode 100644index 0000000000..285c2941fe--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/messages.py@@ -0,0 +1,28 @@+"""Redefined messages as a work-around for pydantic issue with AnyStr.++The code below creates version of pydantic models+that will work in unit tests with AnyStr as id field+Please note that the `id` field is assigned AFTER the model is created+to workaround an issue with pydantic ignoring the __eq__ method on+subclassed strings.+"""++from typing import Any++from langchain_core.messages import HumanMessage, ToolMessage++from .any_str import AnyStr+++def _AnyIdHumanMessage(**kwargs: Any) -> HumanMessage:+ """Create a human message with an any id field."""+ message = HumanMessage(**kwargs)+ message.id = AnyStr()+ return message+++def _AnyIdToolMessage(**kwargs: Any) -> ToolMessage:+ """Create a tool message with an any id field."""+ message = ToolMessage(**kwargs)+ message.id = AnyStr()+ return messagediff --git a/libs/langchain_v1/tests/unit_tests/agents/model.py b/libs/langchain_v1/tests/unit_tests/agents/model.pynew file mode 100644index 0000000000..70cbbbafe0--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/model.py@@ -0,0 +1,111 @@+import json+from collections.abc import Callable, Sequence+from dataclasses import asdict, is_dataclass+from typing import (+ Any,+ Generic,+ Literal,+ TypeVar,+ Union,+)++from langchain_core.callbacks import CallbackManagerForLLMRun+from langchain_core.language_models import BaseChatModel, LanguageModelInput+from langchain_core.messages import (+ AIMessage,+ BaseMessage,+ ToolCall,+)+from langchain_core.outputs import ChatGeneration, ChatResult+from langchain_core.runnables import Runnable+from langchain_core.tools import BaseTool+from pydantic import BaseModel++StructuredResponseT = TypeVar("StructuredResponseT")+++class FakeToolCallingModel(BaseChatModel, Generic[StructuredResponseT]):+ tool_calls: Union[list[list[ToolCall]], list[list[dict]]] | None = None+ structured_response: StructuredResponseT | None = None+ index: int = 0+ tool_style: Literal["openai", "anthropic"] = "openai"++ def _generate(+ self,+ messages: list[BaseMessage],+ stop: list[str] | None = None,+ run_manager: CallbackManagerForLLMRun | None = None,+ **kwargs: Any,+ ) -> ChatResult:+ """Top Level call"""+ 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)])++ @property+ def _llm_type(self) -> str:+ return "fake-tool-call-model"++ def bind_tools(+ self,+ tools: Sequence[Union[dict[str, Any], type[BaseModel], Callable, BaseTool]],+ **kwargs: Any,+ ) -> Runnable[LanguageModelInput, BaseMessage]:+ if len(tools) == 0:+ msg = "Must provide at least one tool"+ raise ValueError(msg)++ tool_dicts = []+ for tool in tools:+ if isinstance(tool, dict):+ tool_dicts.append(tool)+ continue+ if not isinstance(tool, BaseTool):+ msg = "Only BaseTool and dict is supported by FakeToolCallingModel.bind_tools"+ raise TypeError(msg)++ # NOTE: this is a simplified tool spec for testing purposes only+ if self.tool_style == "openai":+ tool_dicts.append(+ {+ "type": "function",+ "function": {+ "name": tool.name,+ },+ }+ )+ elif self.tool_style == "anthropic":+ tool_dicts.append(+ {+ "name": tool.name,+ }+ )++ return self.bind(tools=tool_dicts)diff --git a/libs/langchain_v1/tests/unit_tests/agents/specifications/responses.json b/libs/langchain_v1/tests/unit_tests/agents/specifications/responses.jsonnew file mode 100644index 0000000000..2755ef9756--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/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+ }+ ]+ }+ ]\ No newline at end of filediff --git a/libs/langchain_v1/tests/unit_tests/agents/specifications/return_direct.json b/libs/langchain_v1/tests/unit_tests/agents/specifications/return_direct.jsonnew file mode 100644index 0000000000..e4cc5947ce--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/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+ }+]\ No newline at end of filediff --git a/libs/langchain_v1/tests/unit_tests/agents/test_react_agent.py b/libs/langchain_v1/tests/unit_tests/agents/test_react_agent.pynew file mode 100644index 0000000000..a42d019d27--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_react_agent.py@@ -0,0 +1,1647 @@+import dataclasses+import inspect+from typing import (+ Annotated,+ Union,+)++import pytest+from langchain_core.language_models import BaseChatModel+from langchain_core.messages import (+ AIMessage,+ HumanMessage,+ MessageLikeRepresentation,+ RemoveMessage,+ SystemMessage,+ ToolCall,+ ToolMessage,+)+from langchain_core.runnables import RunnableConfig, RunnableLambda+from langchain_core.tools import BaseTool, InjectedToolCallId, ToolException+from langchain_core.tools import tool as dec_tool+from langgraph.checkpoint.base import BaseCheckpointSaver+from langgraph.graph import START, MessagesState, StateGraph+from langgraph.graph.message import REMOVE_ALL_MESSAGES+from langgraph.runtime import Runtime+from langgraph.store.base import BaseStore+from langgraph.store.memory import InMemoryStore+from langgraph.types import Command, Interrupt, interrupt+from pydantic import BaseModel, Field+from typing_extensions import TypedDict++from langchain.agents import (+ AgentState,+ ToolNode,+ create_react_agent,+)+from langchain.agents.react_agent import _validate_chat_history+from langchain.agents.tool_node import (+ InjectedState,+ InjectedStore,+ _get_state_args,+ _infer_handled_types,+)++from .any_str import AnyStr+from .messages import _AnyIdHumanMessage, _AnyIdToolMessage+from .model import FakeToolCallingModel++pytestmark = pytest.mark.anyio+++def test_no_prompt(sync_checkpointer: BaseCheckpointSaver) -> None:+ model = FakeToolCallingModel()++ agent = create_react_agent(+ model,+ [],+ checkpointer=sync_checkpointer,+ )+ inputs = [HumanMessage("hi?")]+ thread = {"configurable": {"thread_id": "123"}}+ response = agent.invoke({"messages": inputs}, thread, debug=True)+ expected_response = {"messages": [*inputs, AIMessage(content="hi?", id="0")]}+ assert response == expected_response++ saved = sync_checkpointer.get_tuple(thread)+ assert saved is not None+ assert saved.checkpoint["channel_values"] == {+ "messages": [+ _AnyIdHumanMessage(content="hi?"),+ AIMessage(content="hi?", id="0"),+ ],+ }+ assert saved.metadata == {+ "parents": {},+ "source": "loop",+ "step": 1,+ }+ assert saved.pending_writes == []+++async def test_no_prompt_async(async_checkpointer: BaseCheckpointSaver) -> None:+ model = FakeToolCallingModel()++ agent = create_react_agent(model, [], checkpointer=async_checkpointer)+ inputs = [HumanMessage("hi?")]+ thread = {"configurable": {"thread_id": "123"}}+ response = await agent.ainvoke({"messages": inputs}, thread, debug=True)+ expected_response = {"messages": [*inputs, AIMessage(content="hi?", id="0")]}+ assert response == expected_response++ saved = await async_checkpointer.aget_tuple(thread)+ assert saved is not None+ assert saved.checkpoint["channel_values"] == {+ "messages": [+ _AnyIdHumanMessage(content="hi?"),+ AIMessage(content="hi?", id="0"),+ ],+ }+ assert saved.metadata == {+ "parents": {},+ "source": "loop",+ "step": 1,+ }+ assert saved.pending_writes == []+++def test_system_message_prompt() -> None:+ prompt = SystemMessage(content="Foo")+ agent = create_react_agent(FakeToolCallingModel(), [], prompt=prompt)+ inputs = [HumanMessage("hi?")]+ response = agent.invoke({"messages": inputs})+ expected_response = {"messages": [*inputs, AIMessage(content="Foo-hi?", id="0", tool_calls=[])]}+ assert response == expected_response+++def test_string_prompt() -> None:+ prompt = "Foo"+ agent = create_react_agent(FakeToolCallingModel(), [], prompt=prompt)+ inputs = [HumanMessage("hi?")]+ response = agent.invoke({"messages": inputs})+ expected_response = {"messages": [*inputs, AIMessage(content="Foo-hi?", id="0", tool_calls=[])]}+ assert response == expected_response+++def test_callable_prompt() -> None:+ def prompt(state):+ modified_message = f"Bar {state['messages'][-1].content}"+ return [HumanMessage(content=modified_message)]++ agent = create_react_agent(FakeToolCallingModel(), [], prompt=prompt)+ inputs = [HumanMessage("hi?")]+ response = agent.invoke({"messages": inputs})+ expected_response = {"messages": [*inputs, AIMessage(content="Bar hi?", id="0")]}+ assert response == expected_response+++async def test_callable_prompt_async() -> None:+ async def prompt(state):+ modified_message = f"Bar {state['messages'][-1].content}"+ return [HumanMessage(content=modified_message)]++ agent = create_react_agent(FakeToolCallingModel(), [], prompt=prompt)+ inputs = [HumanMessage("hi?")]+ response = await agent.ainvoke({"messages": inputs})+ expected_response = {"messages": [*inputs, AIMessage(content="Bar hi?", id="0")]}+ assert response == expected_response+++def test_runnable_prompt() -> None:+ prompt = RunnableLambda(+ lambda state: [HumanMessage(content=f"Baz {state['messages'][-1].content}")]+ )++ agent = create_react_agent(FakeToolCallingModel(), [], prompt=prompt)+ inputs = [HumanMessage("hi?")]+ response = agent.invoke({"messages": inputs})+ expected_response = {"messages": [*inputs, AIMessage(content="Baz hi?", id="0")]}+ assert response == expected_response+++def test_prompt_with_store() -> None:+ def add(a: int, b: int):+ """Adds a and b"""+ return a + b++ in_memory_store = InMemoryStore()+ in_memory_store.put(("memories", "1"), "user_name", {"data": "User name is Alice"})+ in_memory_store.put(("memories", "2"), "user_name", {"data": "User name is Bob"})++ def prompt(state, config, *, store):+ user_id = config["configurable"]["user_id"]+ system_str = store.get(("memories", user_id), "user_name").value["data"]+ return [SystemMessage(system_str)] + state["messages"]++ def prompt_no_store(state, config):+ return SystemMessage("foo") + state["messages"]++ model = FakeToolCallingModel()++ # test state modifier that uses store works+ agent = create_react_agent(+ model,+ [add],+ prompt=prompt,+ store=in_memory_store,+ )+ response = agent.invoke({"messages": [("user", "hi")]}, {"configurable": {"user_id": "1"}})+ assert response["messages"][-1].content == "User name is Alice-hi"++ # test state modifier that doesn't use store works+ agent = create_react_agent(+ model,+ [add],+ prompt=prompt_no_store,+ store=in_memory_store,+ )+ response = agent.invoke({"messages": [("user", "hi")]}, {"configurable": {"user_id": "2"}})+ assert response["messages"][-1].content == "foo-hi"+++async def test_prompt_with_store_async() -> None:+ async def add(a: int, b: int):+ """Adds a and b"""+ return a + b++ in_memory_store = InMemoryStore()+ await in_memory_store.aput(("memories", "1"), "user_name", {"data": "User name is Alice"})+ await in_memory_store.aput(("memories", "2"), "user_name", {"data": "User name is Bob"})++ async def prompt(state, config, *, store):+ user_id = config["configurable"]["user_id"]+ system_str = (await store.aget(("memories", user_id), "user_name")).value["data"]+ return [SystemMessage(system_str)] + state["messages"]++ async def prompt_no_store(state, config):+ return SystemMessage("foo") + state["messages"]++ model = FakeToolCallingModel()++ # test state modifier that uses store works+ agent = create_react_agent(model, [add], prompt=prompt, store=in_memory_store)+ response = await agent.ainvoke(+ {"messages": [("user", "hi")]}, {"configurable": {"user_id": "1"}}+ )+ assert response["messages"][-1].content == "User name is Alice-hi"++ # test state modifier that doesn't use store works+ agent = create_react_agent(model, [add], prompt=prompt_no_store, store=in_memory_store)+ response = await agent.ainvoke(+ {"messages": [("user", "hi")]}, {"configurable": {"user_id": "2"}}+ )+ assert response["messages"][-1].content == "foo-hi"++[email protected]("tool_style", ["openai", "anthropic"])[email protected]("include_builtin", [True, False])+def test_model_with_tools(tool_style: str, include_builtin: bool) -> None:+ model = FakeToolCallingModel(tool_style=tool_style)++ @dec_tool+ def tool1(some_val: int) -> str:+ """Tool 1 docstring."""+ return f"Tool 1: {some_val}"++ @dec_tool+ def tool2(some_val: int) -> str:+ """Tool 2 docstring."""+ return f"Tool 2: {some_val}"++ tools: list[BaseTool | dict] = [tool1, tool2]+ if include_builtin:+ tools.append(+ {+ "type": "mcp",+ "server_label": "atest_sever",+ "server_url": "https://some.mcp.somewhere.com/sse",+ "headers": {"foo": "bar"},+ "allowed_tools": [+ "mcp_tool_1",+ "set_active_account",+ "get_url_markdown",+ "get_url_screenshot",+ ],+ "require_approval": "never",+ }+ )+ # check valid agent constructor+ with pytest.raises(ValueError):+ create_react_agent(+ model.bind_tools(tools),+ tools,+ )+++def test__validate_messages() -> None:+ # empty input+ _validate_chat_history([])++ # single human message+ _validate_chat_history(+ [+ HumanMessage(content="What's the weather?"),+ ]+ )++ # human + AI+ _validate_chat_history(+ [+ HumanMessage(content="What's the weather?"),+ AIMessage(content="The weather is sunny and 75°F."),+ ]+ )++ # Answered tool calls+ _validate_chat_history(+ [+ HumanMessage(content="What's the weather?"),+ AIMessage(+ content="Let me check that for you.",+ tool_calls=[{"id": "call1", "name": "get_weather", "args": {}}],+ ),+ ToolMessage(content="Sunny, 75°F", tool_call_id="call1"),+ AIMessage(content="The weather is sunny and 75°F."),+ ]+ )++ # Unanswered tool calls+ with pytest.raises(ValueError):+ _validate_chat_history(+ [+ AIMessage(+ content="I'll check that for you.",+ tool_calls=[+ {"id": "call1", "name": "get_weather", "args": {}},+ {"id": "call2", "name": "get_time", "args": {}},+ ],+ )+ ]+ )++ with pytest.raises(ValueError):+ _validate_chat_history(+ [+ HumanMessage(content="What's the weather and time?"),+ AIMessage(+ content="I'll check that for you.",+ tool_calls=[+ {"id": "call1", "name": "get_weather", "args": {}},+ {"id": "call2", "name": "get_time", "args": {}},+ ],+ ),+ ToolMessage(content="Sunny, 75°F", tool_call_id="call1"),+ AIMessage(content="The weather is sunny and 75°F. Let me check the time."),+ ]+ )+++def test__infer_handled_types() -> None:+ def handle(e) -> str: # type: ignore+ return ""++ def handle2(e: Exception) -> str:+ return ""++ def handle3(e: Union[ValueError, ToolException]) -> str:+ return ""++ class Handler:+ def handle(self, e: ValueError) -> str:+ return ""++ handle4 = Handler().handle++ def handle5(e: Union[Union[TypeError, ValueError], ToolException]) -> str:+ return ""++ expected: tuple = (Exception,)+ actual = _infer_handled_types(handle)+ assert expected == actual++ expected = (Exception,)+ actual = _infer_handled_types(handle2)+ assert expected == actual++ expected = (ValueError, ToolException)+ actual = _infer_handled_types(handle3)+ assert expected == actual++ expected = (ValueError,)+ actual = _infer_handled_types(handle4)+ assert expected == actual++ expected = (TypeError, ValueError, ToolException)+ actual = _infer_handled_types(handle5)+ assert expected == actual++ with pytest.raises(ValueError):++ def handler(e: str) -> str:+ return ""++ _infer_handled_types(handler)++ with pytest.raises(ValueError):++ def handler(e: list[Exception]) -> str:+ return ""++ _infer_handled_types(handler)++ with pytest.raises(ValueError):++ def handler(e: Union[str, int]) -> str:+ return ""++ _infer_handled_types(handler)+++def test_react_agent_with_structured_response() -> None:+ class WeatherResponse(BaseModel):+ temperature: float = Field(description="The temperature in fahrenheit")++ tool_calls = [+ [{"args": {}, "id": "1", "name": "get_weather"}],+ [{"name": "WeatherResponse", "id": "2", "args": {"temperature": 75}}],+ ]++ def get_weather() -> str:+ """Get the weather"""+ return "The weather is sunny and 75°F."++ expected_structured_response = WeatherResponse(temperature=75)+ model = FakeToolCallingModel[WeatherResponse](+ tool_calls=tool_calls, structured_response=expected_structured_response+ )+ agent = create_react_agent(+ model,+ [get_weather],+ response_format=WeatherResponse,+ )+ 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):+ user_name: str+++def test_react_agent_update_state(+ sync_checkpointer: BaseCheckpointSaver,+) -> None:+ @dec_tool+ def get_user_name(tool_call_id: Annotated[str, InjectedToolCallId]):+ """Retrieve user name"""+ user_name = interrupt("Please provider user name:")+ return Command(+ update={+ "user_name": user_name,+ "messages": [+ ToolMessage("Successfully retrieved user name", tool_call_id=tool_call_id)+ ],+ }+ )++ def prompt(state: CustomState):+ user_name = state.get("user_name")+ if user_name is None:+ return state["messages"]++ system_msg = f"User name is {user_name}"+ return [{"role": "system", "content": system_msg}] + state["messages"]++ tool_calls = [[{"args": {}, "id": "1", "name": "get_user_name"}]]+ model = FakeToolCallingModel(tool_calls=tool_calls)+ agent = create_react_agent(+ model,+ [get_user_name],+ state_schema=CustomState,+ prompt=prompt,+ checkpointer=sync_checkpointer,+ )+ config = {"configurable": {"thread_id": "1"}}+ # Run until interrupted+ agent.invoke({"messages": [("user", "what's my name")]}, config)+ # supply the value for the interrupt+ response = agent.invoke(Command(resume="Archibald"), config)+ # confirm that the state was updated+ assert response["user_name"] == "Archibald"+ assert len(response["messages"]) == 4+ tool_message: ToolMessage = response["messages"][-2]+ assert tool_message.content == "Successfully retrieved user name"+ assert tool_message.tool_call_id == "1"+ assert tool_message.name == "get_user_name"+++def test_react_agent_parallel_tool_calls(+ sync_checkpointer: BaseCheckpointSaver,+) -> None:+ human_assistance_execution_count = 0++ @dec_tool+ def human_assistance(query: str) -> str:+ """Request assistance from a human."""+ nonlocal human_assistance_execution_count+ human_response = interrupt({"query": query})+ human_assistance_execution_count += 1+ return human_response["data"]++ get_weather_execution_count = 0++ @dec_tool+ def get_weather(location: str) -> str:+ """Use this tool to get the weather."""+ nonlocal get_weather_execution_count+ get_weather_execution_count += 1+ return "It's sunny!"++ tool_calls = [+ [+ {"args": {"location": "sf"}, "id": "1", "name": "get_weather"},+ {"args": {"query": "request help"}, "id": "2", "name": "human_assistance"},+ ],+ [],+ ]+ model = FakeToolCallingModel(tool_calls=tool_calls)+ agent = create_react_agent(+ model,+ [human_assistance, get_weather],+ checkpointer=sync_checkpointer,+ )+ config = {"configurable": {"thread_id": "1"}}+ query = "Get user assistance and also check the weather"+ message_types = []+ for event in agent.stream({"messages": [("user", query)]}, config, stream_mode="values"):+ if messages := event.get("messages"):+ message_types.append([m.type for m in messages])++ assert message_types == [+ ["human"],+ ["human", "ai"],+ ["human", "ai", "tool"],+ ]++ # Resume+ message_types = []+ for event in agent.stream(Command(resume={"data": "Hello"}), config, stream_mode="values"):+ if messages := event.get("messages"):+ message_types.append([m.type for m in messages])++ assert message_types == [+ ["human", "ai"],+ ["human", "ai", "tool", "tool"],+ ["human", "ai", "tool", "tool", "ai"],+ ]++ assert human_assistance_execution_count == 1+ assert get_weather_execution_count == 1+++class AgentStateExtraKey(AgentState):+ foo: int+++def test_create_react_agent_inject_vars() -> None:+ """Test that the agent can inject state and store into tool functions."""+ store = InMemoryStore()+ namespace = ("test",)+ store.put(namespace, "test_key", {"bar": 3})++ def tool1(+ some_val: int,+ state: Annotated[dict, InjectedState],+ store: Annotated[BaseStore, InjectedStore()],+ ) -> str:+ """Tool 1 docstring."""+ store_val = store.get(namespace, "test_key").value["bar"]+ return some_val + state["foo"] + store_val++ tool_call = {+ "name": "tool1",+ "args": {"some_val": 1},+ "id": "some 0",+ "type": "tool_call",+ }+ model = FakeToolCallingModel(tool_calls=[[tool_call], []])+ agent = create_react_agent(+ model,+ ToolNode([tool1], handle_tool_errors=False),+ state_schema=AgentStateExtraKey,+ store=store,+ )+ result = agent.invoke({"messages": [{"role": "user", "content": "hi"}], "foo": 2})+ assert result["messages"] == [+ _AnyIdHumanMessage(content="hi"),+ AIMessage(content="hi", tool_calls=[tool_call], id="0"),+ _AnyIdToolMessage(content="6", name="tool1", tool_call_id="some 0"),+ AIMessage("hi-hi-6", id="1"),+ ]+ assert result["foo"] == 2+++async def test_return_direct() -> None:+ @dec_tool(return_direct=True)+ def tool_return_direct(input: str) -> str:+ """A tool that returns directly."""+ return f"Direct result: {input}"++ @dec_tool+ def tool_normal(input: str) -> str:+ """A normal tool."""+ return f"Normal result: {input}"++ first_tool_call = [+ ToolCall(+ name="tool_return_direct",+ args={"input": "Test direct"},+ id="1",+ ),+ ]+ expected_ai = AIMessage(+ content="Test direct",+ id="0",+ tool_calls=first_tool_call,+ )+ model = FakeToolCallingModel(tool_calls=[first_tool_call, []])+ agent = create_react_agent(+ model,+ [tool_return_direct, tool_normal],+ )++ # Test direct return for tool_return_direct+ result = agent.invoke({"messages": [HumanMessage(content="Test direct", id="hum0")]})+ assert result["messages"] == [+ HumanMessage(content="Test direct", id="hum0"),+ expected_ai,+ ToolMessage(+ content="Direct result: Test direct",+ name="tool_return_direct",+ tool_call_id="1",+ id=result["messages"][2].id,+ ),+ ]+ second_tool_call = [+ ToolCall(+ name="tool_normal",+ args={"input": "Test normal"},+ id="2",+ ),+ ]+ model = FakeToolCallingModel(tool_calls=[second_tool_call, []])+ agent = create_react_agent(model, [tool_return_direct, tool_normal])+ result = agent.invoke({"messages": [HumanMessage(content="Test normal", id="hum1")]})+ assert result["messages"] == [+ HumanMessage(content="Test normal", id="hum1"),+ AIMessage(content="Test normal", id="0", tool_calls=second_tool_call),+ ToolMessage(+ content="Normal result: Test normal",+ name="tool_normal",+ tool_call_id="2",+ id=result["messages"][2].id,+ ),+ AIMessage(content="Test normal-Test normal-Normal result: Test normal", id="1"),+ ]++ both_tool_calls = [+ ToolCall(+ name="tool_return_direct",+ args={"input": "Test both direct"},+ id="3",+ ),+ ToolCall(+ name="tool_normal",+ args={"input": "Test both normal"},+ id="4",+ ),+ ]+ model = FakeToolCallingModel(tool_calls=[both_tool_calls, []])+ agent = create_react_agent(model, [tool_return_direct, tool_normal])+ result = agent.invoke({"messages": [HumanMessage(content="Test both", id="hum2")]})+ assert result["messages"] == [+ HumanMessage(content="Test both", id="hum2"),+ AIMessage(content="Test both", id="0", tool_calls=both_tool_calls),+ ToolMessage(+ content="Direct result: Test both direct",+ name="tool_return_direct",+ tool_call_id="3",+ id=result["messages"][2].id,+ ),+ ToolMessage(+ content="Normal result: Test both normal",+ name="tool_normal",+ tool_call_id="4",+ id=result["messages"][3].id,+ ),+ ]+++def test__get_state_args() -> None:+ class Schema1(BaseModel):+ a: Annotated[str, InjectedState]++ class Schema2(Schema1):+ b: Annotated[int, InjectedState("bar")]++ @dec_tool(args_schema=Schema2)+ def foo(a: str, b: int) -> float:+ """return"""+ return 0.0++ assert _get_state_args(foo) == {"a": None, "b": "bar"}+++def test_inspect_react() -> None:+ model = FakeToolCallingModel(tool_calls=[])+ agent = create_react_agent(model, [])+ inspect.getclosurevars(agent.nodes["agent"].bound.func)+++def test_react_with_subgraph_tools(+ sync_checkpointer: BaseCheckpointSaver,+) -> None:+ class State(TypedDict):+ a: int+ b: int++ class Output(TypedDict):+ result: int++ # Define the subgraphs+ def add(state):+ return {"result": state["a"] + state["b"]}++ add_subgraph = (+ StateGraph(State, output_schema=Output).add_node(add).add_edge(START, "add").compile()+ )++ def multiply(state):+ return {"result": state["a"] * state["b"]}++ multiply_subgraph = (+ StateGraph(State, output_schema=Output)+ .add_node(multiply)+ .add_edge(START, "multiply")+ .compile()+ )++ multiply_subgraph.invoke({"a": 2, "b": 3})++ # Add subgraphs as tools++ def addition(a: int, b: int):+ """Add two numbers"""+ return add_subgraph.invoke({"a": a, "b": b})["result"]++ def multiplication(a: int, b: int):+ """Multiply two numbers"""+ return multiply_subgraph.invoke({"a": a, "b": b})["result"]++ model = FakeToolCallingModel(+ tool_calls=[+ [+ {"args": {"a": 2, "b": 3}, "id": "1", "name": "addition"},+ {"args": {"a": 2, "b": 3}, "id": "2", "name": "multiplication"},+ ],+ [],+ ]+ )+ tool_node = ToolNode([addition, multiplication], handle_tool_errors=False)+ agent = create_react_agent(+ model,+ tool_node,+ checkpointer=sync_checkpointer,+ )+ result = agent.invoke(+ {"messages": [HumanMessage(content="What's 2 + 3 and 2 * 3?")]},+ config={"configurable": {"thread_id": "1"}},+ )+ assert result["messages"] == [+ _AnyIdHumanMessage(content="What's 2 + 3 and 2 * 3?"),+ AIMessage(+ content="What's 2 + 3 and 2 * 3?",+ id="0",+ tool_calls=[+ ToolCall(name="addition", args={"a": 2, "b": 3}, id="1"),+ ToolCall(name="multiplication", args={"a": 2, "b": 3}, id="2"),+ ],+ ),+ ToolMessage(content="5", name="addition", tool_call_id="1", id=result["messages"][2].id),+ ToolMessage(+ content="6",+ name="multiplication",+ tool_call_id="2",+ id=result["messages"][3].id,+ ),+ AIMessage(content="What's 2 + 3 and 2 * 3?-What's 2 + 3 and 2 * 3?-5-6", id="1"),+ ]+++def test_react_agent_subgraph_streaming_sync() -> None:+ """Test React agent streaming when used as a subgraph node sync version"""++ @dec_tool+ def get_weather(city: str) -> str:+ """Get the weather of a city."""+ return f"The weather of {city} is sunny."++ # Create a React agent+ model = FakeToolCallingModel(+ tool_calls=[+ [{"args": {"city": "Tokyo"}, "id": "1", "name": "get_weather"}],+ [],+ ]+ )++ agent = create_react_agent(+ model,+ tools=[get_weather],+ prompt="You are a helpful travel assistant.",+ )++ # Create a subgraph that uses the React agent as a node+ def react_agent_node(state: MessagesState, config: RunnableConfig) -> MessagesState:+ """Node that runs the React agent and collects streaming output."""+ collected_content = ""++ # Stream the agent output and collect content+ for msg_chunk, _msg_metadata in agent.stream(+ {"messages": [("user", state["messages"][-1].content)]},+ config,+ stream_mode="messages",+ ):+ if hasattr(msg_chunk, "content") and msg_chunk.content:+ collected_content += msg_chunk.content++ return {"messages": [("assistant", collected_content)]}++ # Create the main workflow with the React agent as a subgraph node+ workflow = StateGraph(MessagesState)+ workflow.add_node("react_agent", react_agent_node)+ workflow.add_edge(START, "react_agent")+ workflow.add_edge("react_agent", "__end__")+ compiled_workflow = workflow.compile()++ # Test the streaming functionality+ result = compiled_workflow.invoke({"messages": [("user", "What is the weather in Tokyo?")]})++ # Verify the result contains expected structure+ assert len(result["messages"]) == 2+ assert result["messages"][0].content == "What is the weather in Tokyo?"+ assert "assistant" in str(result["messages"][1])++ # Test streaming with subgraphs = True+ result = compiled_workflow.invoke(+ {"messages": [("user", "What is the weather in Tokyo?")]},+ subgraphs=True,+ )+ assert len(result["messages"]) == 2++ events = []+ for event in compiled_workflow.stream(+ {"messages": [("user", "What is the weather in Tokyo?")]},+ stream_mode="messages",+ subgraphs=False,+ ):+ events.append(event)++ assert len(events) == 0++ events = []+ for event in compiled_workflow.stream(+ {"messages": [("user", "What is the weather in Tokyo?")]},+ stream_mode="messages",+ subgraphs=True,+ ):+ events.append(event)++ assert len(events) == 3+ namespace, (msg, metadata) = events[0]+ # FakeToolCallingModel returns a single AIMessage with tool calls+ # The content of the AIMessage reflects the input message+ assert msg.content.startswith("You are a helpful travel assistant")+ namespace, (msg, metadata) = events[1] # ToolMessage+ assert msg.content.startswith("The weather of Tokyo is sunny.")+++async def test_react_agent_subgraph_streaming() -> None:+ """Test React agent streaming when used as a subgraph node."""++ @dec_tool+ def get_weather(city: str) -> str:+ """Get the weather of a city."""+ return f"The weather of {city} is sunny."++ # Create a React agent+ model = FakeToolCallingModel(+ tool_calls=[+ [{"args": {"city": "Tokyo"}, "id": "1", "name": "get_weather"}],+ [],+ ]+ )++ agent = create_react_agent(+ model,+ tools=[get_weather],+ prompt="You are a helpful travel assistant.",+ )++ # Create a subgraph that uses the React agent as a node+ async def react_agent_node(state: MessagesState, config: RunnableConfig) -> MessagesState:+ """Node that runs the React agent and collects streaming output."""+ collected_content = ""++ # Stream the agent output and collect content+ async for msg_chunk, _msg_metadata in agent.astream(+ {"messages": [("user", state["messages"][-1].content)]},+ config,+ stream_mode="messages",+ ):+ if hasattr(msg_chunk, "content") and msg_chunk.content:+ collected_content += msg_chunk.content++ return {"messages": [("assistant", collected_content)]}++ # Create the main workflow with the React agent as a subgraph node+ workflow = StateGraph(MessagesState)+ workflow.add_node("react_agent", react_agent_node)+ workflow.add_edge(START, "react_agent")+ workflow.add_edge("react_agent", "__end__")+ compiled_workflow = workflow.compile()++ # Test the streaming functionality+ result = await compiled_workflow.ainvoke(+ {"messages": [("user", "What is the weather in Tokyo?")]}+ )++ # Verify the result contains expected structure+ assert len(result["messages"]) == 2+ assert result["messages"][0].content == "What is the weather in Tokyo?"+ assert "assistant" in str(result["messages"][1])++ # Test streaming with subgraphs = True+ result = await compiled_workflow.ainvoke(+ {"messages": [("user", "What is the weather in Tokyo?")]},+ subgraphs=True,+ )+ assert len(result["messages"]) == 2++ events = []+ async for event in compiled_workflow.astream(+ {"messages": [("user", "What is the weather in Tokyo?")]},+ stream_mode="messages",+ subgraphs=False,+ ):+ events.append(event)++ assert len(events) == 0++ events = []+ async for event in compiled_workflow.astream(+ {"messages": [("user", "What is the weather in Tokyo?")]},+ stream_mode="messages",+ subgraphs=True,+ ):+ events.append(event)++ assert len(events) == 3+ namespace, (msg, metadata) = events[0]+ # FakeToolCallingModel returns a single AIMessage with tool calls+ # The content of the AIMessage reflects the input message+ assert msg.content.startswith("You are a helpful travel assistant")+ namespace, (msg, metadata) = events[1] # ToolMessage+ assert msg.content.startswith("The weather of Tokyo is sunny.")+++def test_tool_node_node_interrupt(+ sync_checkpointer: BaseCheckpointSaver,+) -> None:+ def tool_normal(some_val: int) -> str:+ """Tool docstring."""+ return "normal"++ def tool_interrupt(some_val: int) -> str:+ """Tool docstring."""+ return interrupt("provide value for foo")++ # test inside react agent+ model = FakeToolCallingModel(+ tool_calls=[+ [+ ToolCall(name="tool_interrupt", args={"some_val": 0}, id="1"),+ ToolCall(name="tool_normal", args={"some_val": 1}, id="2"),+ ],+ [],+ ]+ )+ config = {"configurable": {"thread_id": "1"}}+ agent = create_react_agent(+ model,+ [tool_interrupt, tool_normal],+ checkpointer=sync_checkpointer,+ )+ result = agent.invoke({"messages": [HumanMessage("hi?")]}, config)+ expected_messages = [+ _AnyIdHumanMessage(content="hi?"),+ AIMessage(+ content="hi?",+ id="0",+ tool_calls=[+ {+ "name": "tool_interrupt",+ "args": {"some_val": 0},+ "id": "1",+ "type": "tool_call",+ },+ {+ "name": "tool_normal",+ "args": {"some_val": 1},+ "id": "2",+ "type": "tool_call",+ },+ ],+ ),+ _AnyIdToolMessage(content="normal", name="tool_normal", tool_call_id="2"),+ ]+ assert result["messages"] == expected_messages++ state = agent.get_state(config)+ assert state.next == ("tools",)+ task = state.tasks[0]+ assert task.name == "tools"+ assert task.interrupts == (+ Interrupt(+ value="provide value for foo",+ id=AnyStr(),+ ),+ )+++def test_dynamic_model_basic() -> None:+ """Test basic dynamic model functionality."""++ def dynamic_model(state, runtime: Runtime):+ # Return different models based on state+ if "urgent" in state["messages"][-1].content:+ return FakeToolCallingModel(tool_calls=[])+ return FakeToolCallingModel(tool_calls=[])++ agent = create_react_agent(dynamic_model, [])++ result = agent.invoke({"messages": [HumanMessage("hello")]})+ assert len(result["messages"]) == 2+ assert result["messages"][-1].content == "hello"++ result = agent.invoke({"messages": [HumanMessage("urgent help")]})+ assert len(result["messages"]) == 2+ assert result["messages"][-1].content == "urgent help"+++def test_dynamic_model_with_tools() -> None:+ """Test dynamic model with tool calling."""++ @dec_tool+ def basic_tool(x: int) -> str:+ """Basic tool."""+ return f"basic: {x}"++ @dec_tool+ def advanced_tool(x: int) -> str:+ """Advanced tool."""+ return f"advanced: {x}"++ def dynamic_model(state: dict, runtime: Runtime) -> BaseChatModel:+ # Return model with different behaviors based on message content+ if "advanced" in state["messages"][-1].content:+ return FakeToolCallingModel(+ tool_calls=[+ [{"args": {"x": 1}, "id": "1", "name": "advanced_tool"}],+ [],+ ]+ )+ return FakeToolCallingModel(+ tool_calls=[[{"args": {"x": 1}, "id": "1", "name": "basic_tool"}], []]+ )++ agent = create_react_agent(dynamic_model, [basic_tool, advanced_tool])++ # Test basic tool usage+ result = agent.invoke({"messages": [HumanMessage("basic request")]})+ assert len(result["messages"]) == 3+ tool_message = result["messages"][-1]+ assert tool_message.content == "basic: 1"+ assert tool_message.name == "basic_tool"++ # Test advanced tool usage+ result = agent.invoke({"messages": [HumanMessage("advanced request")]})+ assert len(result["messages"]) == 3+ tool_message = result["messages"][-1]+ assert tool_message.content == "advanced: 1"+ assert tool_message.name == "advanced_tool"+++class Context:+ user_id: str+++def test_dynamic_model_with_context() -> None:+ """Test dynamic model using config parameters."""++ def dynamic_model(state, runtime: Runtime[Context]):+ # Use context to determine model behavior+ user_id = runtime.context.user_id+ if user_id == "user_premium":+ return FakeToolCallingModel(tool_calls=[])+ return FakeToolCallingModel(tool_calls=[])++ agent = create_react_agent(dynamic_model, [], context_schema=Context)++ # Test with basic user+ result = agent.invoke(+ {"messages": [HumanMessage("hello")]},+ context=Context(user_id="user_basic"),+ )+ assert len(result["messages"]) == 2++ # Test with premium user+ result = agent.invoke(+ {"messages": [HumanMessage("hello")]},+ context=Context(user_id="user_premium"),+ )+ assert len(result["messages"]) == 2+++def test_dynamic_model_with_state_schema() -> None:+ """Test dynamic model with custom state schema."""++ class CustomDynamicState(AgentState):+ model_preference: str = "default"++ def dynamic_model(state: CustomDynamicState, runtime: Runtime) -> BaseChatModel:+ # Use custom state field to determine model+ if state.get("model_preference") == "advanced":+ return FakeToolCallingModel(tool_calls=[])+ return FakeToolCallingModel(tool_calls=[])++ agent = create_react_agent(dynamic_model, [], state_schema=CustomDynamicState)++ result = agent.invoke({"messages": [HumanMessage("hello")], "model_preference": "advanced"})+ assert len(result["messages"]) == 2+ assert result["model_preference"] == "advanced"+++def test_dynamic_model_with_prompt() -> None:+ """Test dynamic model with different prompt types."""++ def dynamic_model(state: AgentState, runtime: Runtime) -> BaseChatModel:+ return FakeToolCallingModel(tool_calls=[])++ # Test with string prompt+ agent = create_react_agent(dynamic_model, [], prompt="system_msg")+ result = agent.invoke({"messages": [HumanMessage("human_msg")]})+ assert result["messages"][-1].content == "system_msg-human_msg"++ # Test with callable prompt+ def dynamic_prompt(state: AgentState) -> list[MessageLikeRepresentation]:+ """Generate a dynamic system message based on state."""+ return [{"role": "system", "content": "system_msg"}, *list(state["messages"])]++ agent = create_react_agent(dynamic_model, [], prompt=dynamic_prompt)+ result = agent.invoke({"messages": [HumanMessage("human_msg")]})+ assert result["messages"][-1].content == "system_msg-human_msg"+++async def test_dynamic_model_async() -> None:+ """Test dynamic model with async operations."""++ def dynamic_model(state: AgentState, runtime: Runtime) -> BaseChatModel:+ return FakeToolCallingModel(tool_calls=[])++ agent = create_react_agent(dynamic_model, [])++ result = await agent.ainvoke({"messages": [HumanMessage("hello async")]})+ assert len(result["messages"]) == 2+ assert result["messages"][-1].content == "hello async"+++def test_dynamic_model_with_structured_response() -> None:+ """Test dynamic model with structured response format."""++ class TestResponse(BaseModel):+ message: str+ confidence: float++ def dynamic_model(state, runtime: Runtime):+ return FakeToolCallingModel(+ tool_calls=[+ [+ ToolCall(+ name="TestResponse",+ args={"message": "dynamic response", "confidence": 0.9},+ id="1",+ type="tool_call",+ )+ ]+ ],+ )++ agent = create_react_agent(dynamic_model, [], response_format=TestResponse)++ result = agent.invoke({"messages": [HumanMessage("hello")]})+ assert "structured_response" in result+ assert result["structured_response"].message == "dynamic response"+ assert result["structured_response"].confidence == 0.9+++def test_dynamic_model_with_checkpointer(sync_checkpointer) -> None:+ """Test dynamic model with checkpointer."""+ call_count = 0++ def dynamic_model(state: AgentState, runtime: Runtime) -> BaseChatModel:+ nonlocal call_count+ call_count += 1+ return FakeToolCallingModel(+ tool_calls=[],+ # Incrementing the call count as it is used to assign an id+ # to the AIMessage.+ # The default reducer semantics are to overwrite an existing message+ # with the new one if the id matches.+ index=call_count,+ )++ agent = create_react_agent(dynamic_model, [], checkpointer=sync_checkpointer)+ config = {"configurable": {"thread_id": "test_dynamic"}}++ # First call+ result1 = agent.invoke({"messages": [HumanMessage("hello")]}, config)+ assert len(result1["messages"]) == 2 # Human + AI message++ # Second call - should load from checkpoint+ result2 = agent.invoke({"messages": [HumanMessage("world")]}, config)+ assert len(result2["messages"]) == 4++ # Dynamic model should be called each time+ assert call_count >= 2+++def test_dynamic_model_state_dependent_tools() -> None:+ """Test dynamic model that changes available tools based on state."""++ @dec_tool+ def tool_a(x: int) -> str:+ """Tool A."""+ return f"A: {x}"++ @dec_tool+ def tool_b(x: int) -> str:+ """Tool B."""+ return f"B: {x}"++ def dynamic_model(state, runtime: Runtime):+ # Switch tools based on message history+ if any("use_b" in msg.content for msg in state["messages"]):+ return FakeToolCallingModel(+ tool_calls=[[{"args": {"x": 2}, "id": "1", "name": "tool_b"}], []]+ )+ return FakeToolCallingModel(+ tool_calls=[[{"args": {"x": 1}, "id": "1", "name": "tool_a"}], []]+ )++ agent = create_react_agent(dynamic_model, [tool_a, tool_b])++ # Ask to use tool B+ result = agent.invoke({"messages": [HumanMessage("use_b please")]})+ last_message = result["messages"][-1]+ assert isinstance(last_message, ToolMessage)+ assert last_message.content == "B: 2"++ # Ask to use tool A+ result = agent.invoke({"messages": [HumanMessage("hello")]})+ last_message = result["messages"][-1]+ assert isinstance(last_message, ToolMessage)+ assert last_message.content == "A: 1"+++def test_dynamic_model_error_handling() -> None:+ """Test error handling in dynamic model."""++ def failing_dynamic_model(state, runtime: Runtime):+ if "fail" in state["messages"][-1].content:+ msg = "Dynamic model failed"+ raise ValueError(msg)+ return FakeToolCallingModel(tool_calls=[])++ agent = create_react_agent(failing_dynamic_model, [])++ # Normal operation should work+ result = agent.invoke({"messages": [HumanMessage("hello")]})+ assert len(result["messages"]) == 2++ # Should propagate the error+ with pytest.raises(ValueError, match="Dynamic model failed"):+ agent.invoke({"messages": [HumanMessage("fail now")]})+++def test_dynamic_model_vs_static_model_behavior() -> None:+ """Test that dynamic and static models produce equivalent results when configured the same."""+ # Static model+ static_model = FakeToolCallingModel(tool_calls=[])+ static_agent = create_react_agent(static_model, [])++ # Dynamic model returning the same model+ def dynamic_model(state, runtime: Runtime):+ return FakeToolCallingModel(tool_calls=[])++ dynamic_agent = create_react_agent(dynamic_model, [])++ input_msg = {"messages": [HumanMessage("test message")]}++ static_result = static_agent.invoke(input_msg)+ dynamic_result = dynamic_agent.invoke(input_msg)++ # Results should be equivalent (content-wise, IDs may differ)+ assert len(static_result["messages"]) == len(dynamic_result["messages"])+ assert static_result["messages"][0].content == dynamic_result["messages"][0].content+ assert static_result["messages"][1].content == dynamic_result["messages"][1].content+++def test_dynamic_model_receives_correct_state() -> None:+ """Test that the dynamic model function receives the correct state, not the model input."""+ received_states = []++ class CustomAgentState(AgentState):+ custom_field: str++ def dynamic_model(state, runtime: Runtime) -> BaseChatModel:+ # Capture the state that's passed to the dynamic model function+ received_states.append(state)+ return FakeToolCallingModel(tool_calls=[])++ agent = create_react_agent(dynamic_model, [], state_schema=CustomAgentState)++ # Test with initial state+ input_state = {"messages": [HumanMessage("hello")], "custom_field": "test_value"}+ agent.invoke(input_state)++ # The dynamic model function should receive the original state, not the processed model input+ assert len(received_states) == 1+ received_state = received_states[0]++ # Should have the custom field from original state+ assert "custom_field" in received_state+ assert received_state["custom_field"] == "test_value"++ # Should have the original messages+ assert len(received_state["messages"]) == 1+ assert received_state["messages"][0].content == "hello"+++async def test_dynamic_model_receives_correct_state_async() -> None:+ """Test that the async dynamic model function receives the correct state, not the model input."""+ received_states = []++ class CustomAgentStateAsync(AgentState):+ custom_field: str++ def dynamic_model(state, runtime: Runtime):+ # Capture the state that's passed to the dynamic model function+ received_states.append(state)+ return FakeToolCallingModel(tool_calls=[])++ agent = create_react_agent(dynamic_model, [], state_schema=CustomAgentStateAsync)++ # Test with initial state+ input_state = {+ "messages": [HumanMessage("hello async")],+ "custom_field": "test_value_async",+ }+ await agent.ainvoke(input_state)++ # The dynamic model function should receive the original state, not the processed model input+ assert len(received_states) == 1+ received_state = received_states[0]++ # Should have the custom field from original state+ assert "custom_field" in received_state+ assert received_state["custom_field"] == "test_value_async"++ # Should have the original messages+ assert len(received_state["messages"]) == 1+ assert received_state["messages"][0].content == "hello async"+++def test_pre_model_hook() -> None:+ model = FakeToolCallingModel(tool_calls=[])++ # Test `llm_input_messages`+ def pre_model_hook(state: AgentState):+ return {"llm_input_messages": [HumanMessage("Hello!")]}++ agent = create_react_agent(model, [], pre_model_hook=pre_model_hook)+ assert "pre_model_hook" in agent.nodes+ result = agent.invoke({"messages": [HumanMessage("hi?")]})+ assert result == {+ "messages": [+ _AnyIdHumanMessage(content="hi?"),+ AIMessage(content="Hello!", id="0"),+ ]+ }++ # Test `messages`+ def pre_model_hook(state: AgentState):+ return {"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), HumanMessage("Hello!")]}++ agent = create_react_agent(model, [], pre_model_hook=pre_model_hook)+ result = agent.invoke({"messages": [HumanMessage("hi?")]})+ assert result == {+ "messages": [+ _AnyIdHumanMessage(content="Hello!"),+ AIMessage(content="Hello!", id="1"),+ ]+ }+++def test_post_model_hook() -> None:+ class FlagState(AgentState):+ flag: bool++ model = FakeToolCallingModel(tool_calls=[])++ def post_model_hook(state: FlagState) -> dict[str, bool]:+ return {"flag": True}++ pmh_agent = create_react_agent(+ model, [], post_model_hook=post_model_hook, state_schema=FlagState+ )++ assert "post_model_hook" in pmh_agent.nodes++ result = pmh_agent.invoke({"messages": [HumanMessage("hi?")], "flag": False})+ assert result["flag"] is True++ events = list(pmh_agent.stream({"messages": [HumanMessage("hi?")], "flag": False}))+ assert events == [+ {+ "agent": {+ "messages": [+ AIMessage(+ content="hi?",+ additional_kwargs={},+ response_metadata={},+ id="1",+ )+ ]+ }+ },+ {"post_model_hook": {"flag": True}},+ ]+++def test_post_model_hook_with_structured_output() -> None:+ 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)++ class State(AgentState):+ flag: bool+ structured_response: WeatherResponse++ 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],+ response_format=WeatherResponse,+ post_model_hook=post_model_hook,+ state_schema=State,+ )++ assert "post_model_hook" in agent.nodes++ response = agent.invoke({"messages": [HumanMessage("What's the weather?")], "flag": False})+ 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 events == [+ {+ "agent": {+ "messages": [+ AIMessage(+ content="What's the weather?",+ additional_kwargs={},+ response_metadata={},+ id="0",+ tool_calls=[+ {+ "name": "get_weather",+ "args": {},+ "id": "1",+ "type": "tool_call",+ }+ ],+ )+ ]+ }+ },+ {"post_model_hook": {"flag": True}},+ {+ "tools": {+ "messages": [+ _AnyIdToolMessage(+ content="The weather is sunny and 75°F.",+ name="get_weather",+ tool_call_id="1",+ )+ ]+ }+ },+ {+ "agent": {+ "messages": [+ AIMessage(+ content="What's the weather?-What's the weather?-The weather is sunny and 75°F.",+ additional_kwargs={},+ response_metadata={},+ id="1",+ tool_calls=[+ {+ "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}},+ ]+++def test_create_react_agent_inject_vars_with_post_model_hook() -> None:+ store = InMemoryStore()+ namespace = ("test",)+ store.put(namespace, "test_key", {"bar": 3})++ def tool1(+ some_val: int,+ state: Annotated[dict, InjectedState],+ store: Annotated[BaseStore, InjectedStore()],+ ) -> str:+ """Tool 1 docstring."""+ store_val = store.get(namespace, "test_key").value["bar"]+ return some_val + state["foo"] + store_val++ tool_call = {+ "name": "tool1",+ "args": {"some_val": 1},+ "id": "some 0",+ "type": "tool_call",+ }++ def post_model_hook(state: dict) -> dict:+ """Post model hook is injecting a new foo key."""+ return {"foo": 2}++ model = FakeToolCallingModel(tool_calls=[[tool_call], []])+ agent = create_react_agent(+ model,+ ToolNode([tool1], handle_tool_errors=False),+ state_schema=AgentStateExtraKey,+ store=store,+ post_model_hook=post_model_hook,+ )+ input_message = HumanMessage("hi")+ result = agent.invoke({"messages": [input_message], "foo": 2})+ assert result["messages"] == [+ input_message,+ AIMessage(content="hi", tool_calls=[tool_call], id="0"),+ _AnyIdToolMessage(content="6", name="tool1", tool_call_id="some 0"),+ AIMessage("hi-hi-6", id="1"),+ ]+ assert result["foo"] == 2+++def test_response_format_using_tool_choice() -> 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,+ )+ response = agent.invoke(+ {+ "messages": [+ {+ "role": "user",+ "content": "What's the weather?",+ }+ ]+ }+ )+ assert response.get("structured_response") == expected_structured_responsediff --git a/libs/langchain_v1/tests/unit_tests/agents/test_react_agent_graph.py b/libs/langchain_v1/tests/unit_tests/agents/test_react_agent_graph.pynew file mode 100644index 0000000000..b978306c65--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_react_agent_graph.py@@ -0,0 +1,58 @@+from collections.abc import Callable+from typing import Union++import pytest+from pydantic import BaseModel+from syrupy.assertion import SnapshotAssertion++from langchain.agents import create_react_agent++from .model import FakeToolCallingModel++model = FakeToolCallingModel()+++def tool() -> None:+ """Testing tool."""+++def pre_model_hook() -> None:+ """Pre-model hook."""+++def post_model_hook() -> None:+ """Post-model hook."""+++class ResponseFormat(BaseModel):+ """Response format for the agent."""++ result: str++[email protected]("tools", [[], [tool]])[email protected]("pre_model_hook", [None, pre_model_hook])[email protected]("post_model_hook", [None, post_model_hook])+def test_react_agent_graph_structure(+ snapshot: SnapshotAssertion,+ tools: list[Callable],+ pre_model_hook: Union[Callable, None],+ post_model_hook: Union[Callable, None],+) -> None:+ agent = create_react_agent(+ model,+ tools=tools,+ pre_model_hook=pre_model_hook,+ post_model_hook=post_model_hook,+ )+ try:+ assert agent.get_graph().draw_mermaid(with_styles=False) == snapshot+ except Exception as e:+ msg = (+ "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}, "+ )+ raise ValueError(msg) from ediff --git a/libs/langchain_v1/tests/unit_tests/agents/test_response_format.py b/libs/langchain_v1/tests/unit_tests/agents/test_response_format.pynew file mode 100644index 0000000000..06cf8572b2--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_response_format.py@@ -0,0 +1,710 @@+"""Test suite for create_react_agent with structured output response_format permutations."""++import pytest++from dataclasses import dataclass+from typing import Union++from langchain_core.messages import HumanMessage+from langchain.agents import create_react_agent+from langchain.agents.structured_output import (+ MultipleStructuredOutputsError,+ ProviderStrategy,+ StructuredOutputValidationError,+ ToolStrategy,+)+from pydantic import BaseModel, Field+from typing_extensions import TypedDict++from tests.unit_tests.agents.model import FakeToolCallingModel+++# 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 TestResponseFormatAsToolStrategy:+ def test_pydantic_model(self) -> None:+ """Test response_format as ToolStrategy 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=ToolStrategy(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 ToolStrategy 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=ToolStrategy(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 ToolStrategy 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=ToolStrategy(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 ToolStrategy 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=ToolStrategy(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 ToolStrategy 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=ToolStrategy({"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=ToolStrategy({"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 ToolStrategy 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=ToolStrategy(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=ToolStrategy(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=ToolStrategy(+ 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=ToolStrategy(+ 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=ToolStrategy(+ WeatherBaseModel,+ handle_errors=False,+ ),+ )++ with pytest.raises(+ StructuredOutputValidationError,+ 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=ToolStrategy(+ WeatherBaseModel,+ handle_errors=(StructuredOutputValidationError,),+ ),+ )++ 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=ToolStrategy(+ 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=ToolStrategy(+ 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 TestResponseFormatAsProviderStrategy:+ def test_pydantic_model(self) -> None:+ """Test response_format as ProviderStrategy 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=ProviderStrategy(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 ProviderStrategy 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=ProviderStrategy(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 ProviderStrategy 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=ProviderStrategy(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 ProviderStrategy 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=ProviderStrategy(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 ProviderStrategy 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=ToolStrategy(Union[WeatherBaseModel, LocationResponse]),+ )+ response = agent.invoke({"messages": [HumanMessage("What's the weather?")]})++ assert response["structured_response"] == EXPECTED_WEATHER_PYDANTIC+ assert len(response["messages"]) == 5diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_responses.py b/libs/langchain_v1/tests/unit_tests/agents/test_responses.pynew file mode 100644index 0000000000..6f21e4b21c--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_responses.py@@ -0,0 +1,140 @@+"""Unit tests for langgraph.prebuilt.responses module."""++import pytest++# Skip this test since langgraph.prebuilt.responses is not available+pytest.skip("langgraph.prebuilt.responses not available", allow_module_level=True)+++class _TestModel(BaseModel):+ """A test model for structured output."""++ name: str+ age: int+ email: str = "[email protected]"+++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) -> None:+ """Test basic UsingToolStrategy creation."""+ strategy = ToolStrategy(schema=_TestModel)+ assert strategy.schema == _TestModel+ assert strategy.tool_message_content is None+ assert len(strategy.schema_specs) == 1++ def test_multiple_schemas(self) -> None:+ """Test UsingToolStrategy with multiple schemas."""+ strategy = ToolStrategy(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) -> None:+ """Test UsingToolStrategy with tool message content."""+ strategy = ToolStrategy(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) -> None:+ """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) -> None:+ """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) -> None:+ """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) -> None:+ """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) -> None:+ """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) -> None:+ """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 == "[email protected]" # default value++ def test_parse_payload_pydantic_validation_error(self) -> None:+ """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 = ToolStrategy(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 docstringdiff --git a/libs/langchain_v1/tests/unit_tests/agents/test_responses_spec.py b/libs/langchain_v1/tests/unit_tests/agents/test_responses_spec.pynew file mode 100644index 0000000000..ed1d67c3fc--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_responses_spec.py@@ -0,0 +1,147 @@+from __future__ import annotations++import pytest++# Skip this test since langgraph.prebuilt.responses is not available+pytest.skip("langgraph.prebuilt.responses not available", allow_module_level=True)++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}++[email protected](skip_openai_integration_tests, reason="OpenAI integration tests are disabled.")[email protected]("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 = ToolStrategy(response_format_spec[0])+ else:+ tool_output = ToolStrategy({"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_responsediff --git a/libs/langchain_v1/tests/unit_tests/agents/test_return_direct_spec.py b/libs/langchain_v1/tests/unit_tests/agents/test_return_direct_spec.pynew file mode 100644index 0000000000..d87c22bd28--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_return_direct_spec.py@@ -0,0 +1,107 @@+from __future__ import annotations++import pytest++# Skip this test since langgraph.prebuilt.responses is not available+pytest.skip("langgraph.prebuilt.responses not available", allow_module_level=True)++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}++[email protected](skip_openai_integration_tests, reason="OpenAI integration tests are disabled.")[email protected]("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=ToolStrategy(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 resultdiff --git a/libs/langchain_v1/tests/unit_tests/agents/test_tool_node.py b/libs/langchain_v1/tests/unit_tests/agents/test_tool_node.pynew file mode 100644index 0000000000..8581cf3c7c--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/test_tool_node.py@@ -0,0 +1,1482 @@+import contextlib+import dataclasses+import json+from functools import partial+from typing import (+ Annotated,+ Any,+ NoReturn,+ 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 langgraph.config import get_stream_writer+from langgraph.errors import GraphBubbleUp, GraphInterrupt+from langgraph.graph import START, MessagesState, StateGraph+from langgraph.graph.message import REMOVE_ALL_MESSAGES, add_messages+from langgraph.store.base import BaseStore+from langgraph.store.memory import InMemoryStore+from langgraph.types import Command, Send+from pydantic import BaseModel+from pydantic.v1 import BaseModel as BaseModelV1+from typing_extensions import TypedDict++from langchain.agents import (+ ToolNode,+)+from langchain.agents.tool_node import (+ TOOL_CALL_ERROR_TEMPLATE,+ InjectedState,+ InjectedStore,+ ToolInvocationError,+ tools_condition,+)++from .messages import _AnyIdHumanMessage, _AnyIdToolMessage+from .model import FakeToolCallingModel++pytestmark = pytest.mark.anyio+++def tool1(some_val: int, some_other_val: str) -> str:+ """Tool 1 docstring."""+ if some_val == 0:+ msg = "Test error"+ raise ValueError(msg)+ return f"{some_val} - {some_other_val}"+++async def tool2(some_val: int, some_other_val: str) -> str:+ """Tool 2 docstring."""+ if some_val == 0:+ msg = "Test error"+ raise ToolException(msg)+ return f"tool2: {some_val} - {some_other_val}"+++async def tool3(some_val: int, some_other_val: str) -> str:+ """Tool 3 docstring."""+ return [+ {"key_1": some_val, "key_2": "foo"},+ {"key_1": some_other_val, "key_2": "baz"},+ ]+++async def tool4(some_val: int, some_other_val: str) -> str:+ """Tool 4 docstring."""+ return [+ {"type": "image_url", "image_url": {"url": "abdc"}},+ ]+++@dec_tool+def tool5(some_val: int) -> NoReturn:+ """Tool 5 docstring."""+ msg = "Test error"+ raise ToolException(msg)+++tool5.handle_tool_error = "foo"+++async def test_tool_node() -> None:+ """Test tool node."""+ result = ToolNode([tool1]).invoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool1",+ "args": {"some_val": 1, "some_other_val": "foo"},+ "id": "some 0",+ }+ ],+ )+ ]+ }+ )++ tool_message: ToolMessage = result["messages"][-1]+ assert tool_message.type == "tool"+ assert tool_message.content == "1 - foo"+ assert tool_message.tool_call_id == "some 0"++ result2 = await ToolNode([tool2]).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool2",+ "args": {"some_val": 2, "some_other_val": "bar"},+ "id": "some 1",+ }+ ],+ )+ ]+ }+ )++ tool_message: ToolMessage = result2["messages"][-1]+ assert tool_message.type == "tool"+ assert tool_message.content == "tool2: 2 - bar"++ # list of dicts tool content+ result3 = await ToolNode([tool3]).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool3",+ "args": {"some_val": 2, "some_other_val": "bar"},+ "id": "some 2",+ }+ ],+ )+ ]+ }+ )+ tool_message: ToolMessage = result3["messages"][-1]+ assert tool_message.type == "tool"+ assert (+ tool_message.content == '[{"key_1": 2, "key_2": "foo"}, {"key_1": "bar", "key_2": "baz"}]'+ )+ assert tool_message.tool_call_id == "some 2"++ # list of content blocks tool content+ result4 = await ToolNode([tool4]).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool4",+ "args": {"some_val": 2, "some_other_val": "bar"},+ "id": "some 3",+ }+ ],+ )+ ]+ }+ )+ tool_message: ToolMessage = result4["messages"][-1]+ assert tool_message.type == "tool"+ assert tool_message.content == [{"type": "image_url", "image_url": {"url": "abdc"}}]+ assert tool_message.tool_call_id == "some 3"+++async def test_tool_node_tool_call_input() -> None:+ # Single tool call+ tool_call_1 = {+ "name": "tool1",+ "args": {"some_val": 1, "some_other_val": "foo"},+ "id": "some 0",+ "type": "tool_call",+ }+ result = ToolNode([tool1]).invoke([tool_call_1])+ assert result["messages"] == [+ ToolMessage(content="1 - foo", tool_call_id="some 0", name="tool1"),+ ]++ # Multiple tool calls+ tool_call_2 = {+ "name": "tool1",+ "args": {"some_val": 2, "some_other_val": "bar"},+ "id": "some 1",+ "type": "tool_call",+ }+ result = ToolNode([tool1]).invoke([tool_call_1, tool_call_2])+ assert result["messages"] == [+ ToolMessage(content="1 - foo", tool_call_id="some 0", name="tool1"),+ ToolMessage(content="2 - bar", tool_call_id="some 1", name="tool1"),+ ]++ # Test with unknown tool+ tool_call_3 = tool_call_1.copy()+ tool_call_3["name"] = "tool2"+ result = ToolNode([tool1]).invoke([tool_call_1, tool_call_3])+ assert result["messages"] == [+ ToolMessage(content="1 - foo", tool_call_id="some 0", name="tool1"),+ ToolMessage(+ content="Error: tool2 is not a valid tool, try one of [tool1].",+ name="tool2",+ tool_call_id="some 0",+ status="error",+ ),+ ]+++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 tuple of all exceptions+ # - passing a callable with all exceptions in the signature+ for handle_tool_errors in (+ True,+ (ValueError, ToolException, ToolInvocationError),+ handle_all,+ ):+ result_error = await ToolNode(+ [tool1, tool2, tool3], handle_tool_errors=handle_tool_errors+ ).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool1",+ "args": {"some_val": 0, "some_other_val": "foo"},+ "id": "some id",+ },+ {+ "name": "tool2",+ "args": {"some_val": 0, "some_other_val": "bar"},+ "id": "some other id",+ },+ {+ "name": "tool3",+ "args": {"some_val": 0},+ "id": "another id",+ },+ ],+ )+ ]+ }+ )++ assert all(m.type == "tool" for m in result_error["messages"])+ assert all(m.status == "error" for m in result_error["messages"])+ assert (+ result_error["messages"][0].content+ == f"Error: {ValueError('Test error')!r}\n Please fix your mistakes."+ )+ assert (+ result_error["messages"][1].content+ == f"Error: {ToolException('Test error')!r}\n Please fix your mistakes."+ )+ assert (+ "ValidationError" in result_error["messages"][2].content+ or "validation error" in result_error["messages"][2].content+ )++ assert result_error["messages"][0].tool_call_id == "some id"+ assert result_error["messages"][1].tool_call_id == "some other id"+ assert result_error["messages"][2].tool_call_id == "another id"+++async def test_tool_node_error_handling_callable() -> None:+ def handle_value_error(e: ValueError) -> str:+ return "Value error"++ def handle_tool_exception(e: ToolException) -> str:+ return "Tool exception"++ for handle_tool_errors in ("Value error", handle_value_error):+ result_error = await ToolNode([tool1], handle_tool_errors=handle_tool_errors).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool1",+ "args": {"some_val": 0, "some_other_val": "foo"},+ "id": "some id",+ },+ ],+ )+ ]+ }+ )+ tool_message: ToolMessage = result_error["messages"][-1]+ assert tool_message.type == "tool"+ assert tool_message.status == "error"+ assert tool_message.content == "Value error"++ # test raising for an unhandled exception, via:+ # - passing a tuple of all exceptions+ # - passing a callable with all exceptions in the signature+ for handle_tool_errors in ((ValueError,), handle_value_error):+ with pytest.raises(ToolException) as exc_info:+ await ToolNode([tool1, tool2], handle_tool_errors=handle_tool_errors).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool1",+ "args": {"some_val": 0, "some_other_val": "foo"},+ "id": "some id",+ },+ {+ "name": "tool2",+ "args": {"some_val": 0, "some_other_val": "bar"},+ "id": "some other id",+ },+ ],+ )+ ]+ }+ )+ assert str(exc_info.value) == "Test error"++ for handle_tool_errors in ((ToolException,), handle_tool_exception):+ with pytest.raises(ValueError) as exc_info:+ await ToolNode([tool1, tool2], handle_tool_errors=handle_tool_errors).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool1",+ "args": {"some_val": 0, "some_other_val": "foo"},+ "id": "some id",+ },+ {+ "name": "tool2",+ "args": {"some_val": 0, "some_other_val": "bar"},+ "id": "some other id",+ },+ ],+ )+ ]+ }+ )+ assert str(exc_info.value) == "Test error"+++async def test_tool_node_handle_tool_errors_false() -> None:+ with pytest.raises(ValueError) as exc_info:+ ToolNode([tool1], handle_tool_errors=False).invoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool1",+ "args": {"some_val": 0, "some_other_val": "foo"},+ "id": "some id",+ }+ ],+ )+ ]+ }+ )++ assert str(exc_info.value) == "Test error"++ with pytest.raises(ToolException):+ await ToolNode([tool2], handle_tool_errors=False).ainvoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool2",+ "args": {"some_val": 0, "some_other_val": "bar"},+ "id": "some id",+ }+ ],+ )+ ]+ }+ )++ assert str(exc_info.value) == "Test error"++ # test validation errors get raised if handle_tool_errors is False+ with pytest.raises(ToolInvocationError):+ ToolNode([tool1], handle_tool_errors=False).invoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool1",+ "args": {"some_val": 0},+ "id": "some id",+ }+ ],+ )+ ]+ }+ )+++def test_tool_node_individual_tool_error_handling() -> None:+ # test error handling on individual tools (and that it overrides overall error handling!)+ result_individual_tool_error_handler = ToolNode([tool5], handle_tool_errors="bar").invoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool5",+ "args": {"some_val": 0},+ "id": "some 0",+ }+ ],+ )+ ]+ }+ )++ tool_message: ToolMessage = result_individual_tool_error_handler["messages"][-1]+ assert tool_message.type == "tool"+ assert tool_message.status == "error"+ assert tool_message.content == "foo"+ assert tool_message.tool_call_id == "some 0"+++def test_tool_node_incorrect_tool_name() -> None:+ result_incorrect_name = ToolNode([tool1, tool2]).invoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool3",+ "args": {"some_val": 1, "some_other_val": "foo"},+ "id": "some 0",+ }+ ],+ )+ ]+ }+ )++ tool_message: ToolMessage = result_incorrect_name["messages"][-1]+ assert tool_message.type == "tool"+ assert tool_message.status == "error"+ assert tool_message.content == "Error: tool3 is not a valid tool, try one of [tool1, tool2]."+ assert tool_message.tool_call_id == "some 0"+++def test_tool_node_node_interrupt() -> None:+ def tool_interrupt(some_val: int) -> None:+ """Tool docstring."""+ msg = "foo"+ raise GraphBubbleUp(msg)++ def handle(e: GraphInterrupt) -> str:+ return "handled"++ for handle_tool_errors in (True, (GraphBubbleUp,), "handled", handle, False):+ node = ToolNode([tool_interrupt], handle_tool_errors=handle_tool_errors)+ with pytest.raises(GraphBubbleUp) as exc_info:+ node.invoke(+ {+ "messages": [+ AIMessage(+ "hi?",+ tool_calls=[+ {+ "name": "tool_interrupt",+ "args": {"some_val": 0},+ "id": "some 0",+ }+ ],+ )+ ]+ }+ )+ assert exc_info.value == "foo"++[email protected]("input_type", ["dict", "tool_calls"])+async def test_tool_node_command(input_type: str) -> None:+ from langchain_core.tools.base import InjectedToolCallId++ @dec_tool+ def transfer_to_bob(tool_call_id: Annotated[str, InjectedToolCallId]):+ """Transfer to Bob"""+ return Command(+ update={+ "messages": [ToolMessage(content="Transferred to Bob", tool_call_id=tool_call_id)]+ },+ goto="bob",+ graph=Command.PARENT,+ )++ @dec_tool+ async def async_transfer_to_bob(tool_call_id: Annotated[str, InjectedToolCallId]):+ """Transfer to Bob"""+ return Command(+ update={+ "messages": [ToolMessage(content="Transferred to Bob", tool_call_id=tool_call_id)]+ },+ goto="bob",+ graph=Command.PARENT,+ )++ class CustomToolSchema(BaseModel):+ tool_call_id: Annotated[str, InjectedToolCallId]++ class MyCustomTool(BaseTool):+ def _run(*args: Any, **kwargs: Any):+ return Command(+ update={+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id=kwargs["tool_call_id"],+ )+ ]+ },+ goto="bob",+ graph=Command.PARENT,+ )++ async def _arun(*args: Any, **kwargs: Any):+ return Command(+ update={+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id=kwargs["tool_call_id"],+ )+ ]+ },+ goto="bob",+ graph=Command.PARENT,+ )++ custom_tool = MyCustomTool(+ name="custom_transfer_to_bob",+ description="Transfer to bob",+ args_schema=CustomToolSchema,+ )+ async_custom_tool = MyCustomTool(+ name="async_custom_transfer_to_bob",+ description="Transfer to bob",+ args_schema=CustomToolSchema,+ )++ # test mixing regular tools and tools returning commands+ def add(a: int, b: int) -> int:+ """Add two numbers"""+ return a + b++ tool_calls = [+ {"args": {"a": 1, "b": 2}, "id": "1", "name": "add", "type": "tool_call"},+ {"args": {}, "id": "2", "name": "transfer_to_bob", "type": "tool_call"},+ ]+ if input_type == "dict":+ input_ = {"messages": [AIMessage("", tool_calls=tool_calls)]}+ elif input_type == "tool_calls":+ input_ = tool_calls+ result = ToolNode([add, transfer_to_bob]).invoke(input_)++ assert result == [+ {+ "messages": [+ ToolMessage(+ content="3",+ tool_call_id="1",+ name="add",+ )+ ]+ },+ Command(+ update={+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="2",+ name="transfer_to_bob",+ )+ ]+ },+ goto="bob",+ graph=Command.PARENT,+ ),+ ]++ # test tools returning commands++ # test sync tools+ for tool in [transfer_to_bob, custom_tool]:+ result = ToolNode([tool]).invoke(+ {"messages": [AIMessage("", tool_calls=[{"args": {}, "id": "1", "name": tool.name}])]}+ )+ assert result == [+ Command(+ update={+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="1",+ name=tool.name,+ )+ ]+ },+ goto="bob",+ graph=Command.PARENT,+ )+ ]++ # test async tools+ for tool in [async_transfer_to_bob, async_custom_tool]:+ result = await ToolNode([tool]).ainvoke(+ {"messages": [AIMessage("", tool_calls=[{"args": {}, "id": "1", "name": tool.name}])]}+ )+ assert result == [+ Command(+ update={+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="1",+ name=tool.name,+ )+ ]+ },+ goto="bob",+ graph=Command.PARENT,+ )+ ]++ # test multiple commands+ result = ToolNode([transfer_to_bob, custom_tool]).invoke(+ {+ "messages": [+ AIMessage(+ "",+ tool_calls=[+ {"args": {}, "id": "1", "name": "transfer_to_bob"},+ {"args": {}, "id": "2", "name": "custom_transfer_to_bob"},+ ],+ )+ ]+ }+ )+ assert result == [+ Command(+ update={+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="1",+ name="transfer_to_bob",+ )+ ]+ },+ goto="bob",+ graph=Command.PARENT,+ ),+ Command(+ update={+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="2",+ name="custom_transfer_to_bob",+ )+ ]+ },+ goto="bob",+ graph=Command.PARENT,+ ),+ ]++ # test validation (mismatch between input type and command.update type)+ with pytest.raises(ValueError):++ @dec_tool+ def list_update_tool(tool_call_id: Annotated[str, InjectedToolCallId]):+ """My tool"""+ return Command(update=[ToolMessage(content="foo", tool_call_id=tool_call_id)])++ ToolNode([list_update_tool]).invoke(+ {+ "messages": [+ AIMessage(+ "",+ tool_calls=[{"args": {}, "id": "1", "name": "list_update_tool"}],+ )+ ]+ }+ )++ # test validation (missing tool message in the update for current graph)+ with pytest.raises(ValueError):++ @dec_tool+ def no_update_tool():+ """My tool"""+ return Command(update={"messages": []})++ ToolNode([no_update_tool]).invoke(+ {+ "messages": [+ AIMessage(+ "",+ tool_calls=[{"args": {}, "id": "1", "name": "no_update_tool"}],+ )+ ]+ }+ )++ # test validation (tool message with a wrong tool call ID)+ with pytest.raises(ValueError):++ @dec_tool+ def mismatching_tool_call_id_tool():+ """My tool"""+ return Command(update={"messages": [ToolMessage(content="foo", tool_call_id="2")]})++ ToolNode([mismatching_tool_call_id_tool]).invoke(+ {+ "messages": [+ AIMessage(+ "",+ tool_calls=[+ {+ "args": {},+ "id": "1",+ "name": "mismatching_tool_call_id_tool",+ }+ ],+ )+ ]+ }+ )++ # test validation (missing tool message in the update for parent graph is OK)+ @dec_tool+ def node_update_parent_tool():+ """No update"""+ return Command(update={"messages": []}, graph=Command.PARENT)++ assert ToolNode([node_update_parent_tool]).invoke(+ {+ "messages": [+ AIMessage(+ "",+ tool_calls=[{"args": {}, "id": "1", "name": "node_update_parent_tool"}],+ )+ ]+ }+ ) == [Command(update={"messages": []}, graph=Command.PARENT)]+++async def test_tool_node_command_list_input() -> None:+ from langchain_core.tools.base import InjectedToolCallId++ @dec_tool+ def transfer_to_bob(tool_call_id: Annotated[str, InjectedToolCallId]):+ """Transfer to Bob"""+ return Command(+ update=[ToolMessage(content="Transferred to Bob", tool_call_id=tool_call_id)],+ goto="bob",+ graph=Command.PARENT,+ )++ @dec_tool+ async def async_transfer_to_bob(tool_call_id: Annotated[str, InjectedToolCallId]):+ """Transfer to Bob"""+ return Command(+ update=[ToolMessage(content="Transferred to Bob", tool_call_id=tool_call_id)],+ goto="bob",+ graph=Command.PARENT,+ )++ class CustomToolSchema(BaseModel):+ tool_call_id: Annotated[str, InjectedToolCallId]++ class MyCustomTool(BaseTool):+ def _run(*args: Any, **kwargs: Any):+ return Command(+ update=[+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id=kwargs["tool_call_id"],+ )+ ],+ goto="bob",+ graph=Command.PARENT,+ )++ async def _arun(*args: Any, **kwargs: Any):+ return Command(+ update=[+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id=kwargs["tool_call_id"],+ )+ ],+ goto="bob",+ graph=Command.PARENT,+ )++ custom_tool = MyCustomTool(+ name="custom_transfer_to_bob",+ description="Transfer to bob",+ args_schema=CustomToolSchema,+ )+ async_custom_tool = MyCustomTool(+ name="async_custom_transfer_to_bob",+ description="Transfer to bob",+ args_schema=CustomToolSchema,+ )++ # test mixing regular tools and tools returning commands+ def add(a: int, b: int) -> int:+ """Add two numbers"""+ return a + b++ result = ToolNode([add, transfer_to_bob]).invoke(+ [+ AIMessage(+ "",+ tool_calls=[+ {"args": {"a": 1, "b": 2}, "id": "1", "name": "add"},+ {"args": {}, "id": "2", "name": "transfer_to_bob"},+ ],+ )+ ]+ )++ assert result == [+ [+ ToolMessage(+ content="3",+ tool_call_id="1",+ name="add",+ )+ ],+ Command(+ update=[+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="2",+ name="transfer_to_bob",+ )+ ],+ goto="bob",+ graph=Command.PARENT,+ ),+ ]++ # test tools returning commands++ # test sync tools+ for tool in [transfer_to_bob, custom_tool]:+ result = ToolNode([tool]).invoke(+ [AIMessage("", tool_calls=[{"args": {}, "id": "1", "name": tool.name}])]+ )+ assert result == [+ Command(+ update=[+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="1",+ name=tool.name,+ )+ ],+ goto="bob",+ graph=Command.PARENT,+ )+ ]++ # test async tools+ for tool in [async_transfer_to_bob, async_custom_tool]:+ result = await ToolNode([tool]).ainvoke(+ [AIMessage("", tool_calls=[{"args": {}, "id": "1", "name": tool.name}])]+ )+ assert result == [+ Command(+ update=[+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="1",+ name=tool.name,+ )+ ],+ goto="bob",+ graph=Command.PARENT,+ )+ ]++ # test multiple commands+ result = ToolNode([transfer_to_bob, custom_tool]).invoke(+ [+ AIMessage(+ "",+ tool_calls=[+ {"args": {}, "id": "1", "name": "transfer_to_bob"},+ {"args": {}, "id": "2", "name": "custom_transfer_to_bob"},+ ],+ )+ ]+ )+ assert result == [+ Command(+ update=[+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="1",+ name="transfer_to_bob",+ )+ ],+ goto="bob",+ graph=Command.PARENT,+ ),+ Command(+ update=[+ ToolMessage(+ content="Transferred to Bob",+ tool_call_id="2",+ name="custom_transfer_to_bob",+ )+ ],+ goto="bob",+ graph=Command.PARENT,+ ),+ ]++ # test validation (mismatch between input type and command.update type)+ with pytest.raises(ValueError):++ @dec_tool+ def list_update_tool(tool_call_id: Annotated[str, InjectedToolCallId]):+ """My tool"""+ return Command(+ update={"messages": [ToolMessage(content="foo", tool_call_id=tool_call_id)]}+ )++ ToolNode([list_update_tool]).invoke(+ [+ AIMessage(+ "",+ tool_calls=[{"args": {}, "id": "1", "name": "list_update_tool"}],+ )+ ]+ )++ # test validation (missing tool message in the update for current graph)+ with pytest.raises(ValueError):++ @dec_tool+ def no_update_tool():+ """My tool"""+ return Command(update=[])++ ToolNode([no_update_tool]).invoke(+ [+ AIMessage(+ "",+ tool_calls=[{"args": {}, "id": "1", "name": "no_update_tool"}],+ )+ ]+ )++ # test validation (tool message with a wrong tool call ID)+ with pytest.raises(ValueError):++ @dec_tool+ def mismatching_tool_call_id_tool():+ """My tool"""+ return Command(update=[ToolMessage(content="foo", tool_call_id="2")])++ ToolNode([mismatching_tool_call_id_tool]).invoke(+ [+ AIMessage(+ "",+ tool_calls=[{"args": {}, "id": "1", "name": "mismatching_tool_call_id_tool"}],+ )+ ]+ )++ # test validation (missing tool message in the update for parent graph is OK)+ @dec_tool+ def node_update_parent_tool():+ """No update"""+ return Command(update=[], graph=Command.PARENT)++ assert ToolNode([node_update_parent_tool]).invoke(+ [+ AIMessage(+ "",+ tool_calls=[{"args": {}, "id": "1", "name": "node_update_parent_tool"}],+ )+ ]+ ) == [Command(update=[], graph=Command.PARENT)]+++def test_tool_node_parent_command_with_send() -> None:+ from langchain_core.tools.base import InjectedToolCallId++ @dec_tool+ def transfer_to_alice(tool_call_id: Annotated[str, InjectedToolCallId]):+ """Transfer to Alice"""+ return Command(+ goto=[+ Send(+ "alice",+ {+ "messages": [+ ToolMessage(+ content="Transferred to Alice",+ name="transfer_to_alice",+ tool_call_id=tool_call_id,+ )+ ]+ },+ )+ ],+ graph=Command.PARENT,+ )++ @dec_tool+ def transfer_to_bob(tool_call_id: Annotated[str, InjectedToolCallId]):+ """Transfer to Bob"""+ return Command(+ goto=[+ Send(+ "bob",+ {+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ name="transfer_to_bob",+ tool_call_id=tool_call_id,+ )+ ]+ },+ )+ ],+ graph=Command.PARENT,+ )++ tool_calls = [+ {"args": {}, "id": "1", "name": "transfer_to_alice", "type": "tool_call"},+ {"args": {}, "id": "2", "name": "transfer_to_bob", "type": "tool_call"},+ ]++ result = ToolNode([transfer_to_alice, transfer_to_bob]).invoke(+ [AIMessage("", tool_calls=tool_calls)]+ )++ assert result == [+ Command(+ goto=[+ Send(+ "alice",+ {+ "messages": [+ ToolMessage(+ content="Transferred to Alice",+ name="transfer_to_alice",+ tool_call_id="1",+ )+ ]+ },+ ),+ Send(+ "bob",+ {+ "messages": [+ ToolMessage(+ content="Transferred to Bob",+ name="transfer_to_bob",+ tool_call_id="2",+ )+ ]+ },+ ),+ ],+ graph=Command.PARENT,+ )+ ]+++async def test_tool_node_command_remove_all_messages() -> None:+ from langchain_core.tools.base import InjectedToolCallId++ @dec_tool+ def remove_all_messages_tool(tool_call_id: Annotated[str, InjectedToolCallId]):+ """A tool that removes all messages."""+ return Command(update={"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES)]})++ tool_node = ToolNode([remove_all_messages_tool])+ tool_call = {+ "name": "remove_all_messages_tool",+ "args": {},+ "id": "tool_call_123",+ }+ result = await tool_node.ainvoke({"messages": [AIMessage(content="", tool_calls=[tool_call])]})++ assert isinstance(result, list)+ assert len(result) == 1+ 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+++class _InjectedStateDataclassSchema:+ messages: list+ foo: str+++T = TypeVar("T")+++ "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"]+ return state.foo++ def tool2(some_val: int, state: Annotated[T, InjectedState()]) -> str:+ """Tool 2 docstring."""+ if isinstance(state, dict):+ return state["foo"]+ return 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+ with contextlib.suppress(Exception):+ failure_input = schema_(messages=[msg], notfoo="bar")+ 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) -> 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) -> dict[str, Any]:+ 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",+ ),+ ],+ },+ },+ ),+ ]diff --git a/libs/langchain_v1/tests/unit_tests/agents/utils.py b/libs/langchain_v1/tests/unit_tests/agents/utils.pynew file mode 100644index 0000000000..21a9d438af--- /dev/null+++ b/libs/langchain_v1/tests/unit_tests/agents/utils.py@@ -0,0 +1,21 @@+import json+from pathlib import Path++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]diff --git a/libs/langchain_v1/tests/unit_tests/conftest.py b/libs/langchain_v1/tests/unit_tests/conftest.pyindex 6656529a4d..46db164778 100644--- a/libs/langchain_v1/tests/unit_tests/conftest.py+++ b/libs/langchain_v1/tests/unit_tests/conftest.py@@ -1,42 +1,9 @@"""Configuration for unit tests."""-from collections.abc import Iterator, Sequence+from collections.abc import Sequencefrom importlib import utilimport pytest-from blockbuster import blockbuster_ctx--[email protected](autouse=True)-def blockbuster() -> Iterator[None]:- with blockbuster_ctx("langchain") as bb:- bb.functions["io.TextIOWrapper.read"].can_block_in(- "langchain/__init__.py",- "<module>",- )-- for func in ["os.stat", "os.path.abspath"]:- (- bb.functions[func]- .can_block_in("langchain_core/runnables/base.py", "__repr__")- .can_block_in(- "langchain_core/beta/runnables/context.py",- "aconfig_with_context",- )- )-- for func in ["os.stat", "io.TextIOWrapper.read"]:- bb.functions[func].can_block_in(- "langsmith/client.py",- "_default_retry_config",- )-- for bb_function in bb.functions.values():- bb_function.can_block_in(- "freezegun/api.py",- "_get_cached_module_attributes",- )- yielddef pytest_addoption(parser: pytest.Parser) -> None:diff --git a/libs/langchain_v1/uv.lock b/libs/langchain_v1/uv.lockindex fbb87832ba..2daff5ca14 100644--- a/libs/langchain_v1/uv.lock+++ b/libs/langchain_v1/uv.lock@@ -264,18 +264,6 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/a0/59/76ab57e3fe74484f48a53f8e337171b4a2349e506eabe136d7e01d059086/backports_asyncio_runner-1.2.0-py3-none-any.whl", hash = "sha256:0da0a936a8aeb554eccb426dc55af3ba63bcdc69fa1a600b5bb305413a4477b5", size = 12313, upload-time = "2025-07-02T02:27:14.263Z" },]-[[package]]-name = "blockbuster"-version = "1.5.25"-source = { registry = "https://pypi.org/simple" }-dependencies = [- { name = "forbiddenfruit", marker = "implementation_name == 'cpython'" },-]-sdist = { url = "https://files.pythonhosted.org/packages/7f/bc/57c49465decaeeedd58ce2d970b4cdfd93a74ba9993abff2dc498a31c283/blockbuster-1.5.25.tar.gz", hash = "sha256:b72f1d2aefdeecd2a820ddf1e1c8593bf00b96e9fdc4cd2199ebafd06f7cb8f0", size = 36058, upload-time = "2025-07-14T16:00:20.766Z" }-wheels = [- { url = "https://files.pythonhosted.org/packages/0b/01/dccc277c014f171f61a6047bb22c684e16c7f2db6bb5c8cce1feaf41ec55/blockbuster-1.5.25-py3-none-any.whl", hash = "sha256:cb06229762273e0f5f3accdaed3d2c5a3b61b055e38843de202311ede21bb0f5", size = 13196, upload-time = "2025-07-14T16:00:19.396Z" },-]-[[package]]name = "boto3"version = "1.40.18"@@ -724,7 +712,7 @@ name = "exceptiongroup"version = "1.3.0"source = { registry = "https://pypi.org/simple" }dependencies = [- { name = "typing-extensions", marker = "python_full_version < '3.12'" },+ { name = "typing-extensions", marker = "python_full_version < '3.11'" },]sdist = { url = "https://files.pythonhosted.org/packages/0b/9f/a65090624ecf468cdca03533906e7c69ed7588582240cfe7cc9e770b50eb/exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88", size = 29749, upload-time = "2025-05-10T17:42:51.123Z" }wheels = [@@ -774,12 +762,6 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/5f/e7/319a4ce37bed682741bc8ebbb84b7983da3d8cd7ac069d86b52a37d79f2e/fireworks_ai-0.15.15-py3-none-any.whl", hash = "sha256:1047b8e575a536898a827b089b0022c1fab207940f9773b90fa357ebf942f5c9", size = 112831, upload-time = "2025-06-20T21:11:26.701Z" },]-[[package]]-name = "forbiddenfruit"-version = "0.1.4"-source = { registry = "https://pypi.org/simple" }-sdist = { url = "https://files.pythonhosted.org/packages/e6/79/d4f20e91327c98096d605646bdc6a5ffedae820f38d378d3515c42ec5e60/forbiddenfruit-0.1.4.tar.gz", hash = "sha256:e3f7e66561a29ae129aac139a85d610dbf3dd896128187ed5454b6421f624253", size = 43756, upload-time = "2021-01-16T21:03:35.401Z" }-[[package]]name = "frozenlist"version = "1.7.0"@@ -1514,13 +1496,13 @@ lint = [{ name = "ruff" },]test = [- { name = "blockbuster" },{ name = "langchain-openai" },{ name = "langchain-tests" },{ name = "langchain-text-splitters" },{ name = "pytest" },{ name = "pytest-asyncio" },{ name = "pytest-cov" },+ { name = "pytest-mock" },{ name = "pytest-socket" },{ name = "pytest-watcher" },{ name = "pytest-xdist" },@@ -1571,13 +1553,13 @@ lint = [{ name = "ruff", specifier = ">=0.12.2" },]test = [- { name = "blockbuster", specifier = ">=1.5.18" },{ name = "langchain-openai", editable = "../partners/openai" },{ name = "langchain-tests", editable = "../standard-tests" },{ name = "langchain-text-splitters", editable = "../text-splitters" },{ name = "pytest", specifier = ">=8,<9" },{ name = "pytest-asyncio", specifier = ">=0.23.2" },{ name = "pytest-cov", specifier = ">=4.0.0" },+ { name = "pytest-mock" },{ name = "pytest-socket", specifier = ">=0.6.0" },{ name = "pytest-watcher", specifier = ">=0.2.6" },{ name = "pytest-xdist", specifier = ">=3.6.1" },@@ -3169,6 +3151,18 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/bc/16/4ea354101abb1287856baa4af2732be351c7bee728065aed451b678153fd/pytest_cov-6.2.1-py3-none-any.whl", hash = "sha256:f5bc4c23f42f1cdd23c70b1dab1bbaef4fc505ba950d53e0081d0730dd7e86d5", size = 24644, upload-time = "2025-06-12T10:47:45.932Z" },]+[[package]]+name = "pytest-mock"+version = "3.14.1"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "pytest" },+]+sdist = { url = "https://files.pythonhosted.org/packages/71/28/67172c96ba684058a4d24ffe144d64783d2a270d0af0d9e792737bddc75c/pytest_mock-3.14.1.tar.gz", hash = "sha256:159e9edac4c451ce77a5cdb9fc5d1100708d2dd4ba3c3df572f14097351af80e", size = 33241, upload-time = "2025-05-26T13:58:45.167Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/b2/05/77b60e520511c53d1c1ca75f1930c7dd8e971d0c4379b7f4b3f9644685ba/pytest_mock-3.14.1-py3-none-any.whl", hash = "sha256:178aefcd11307d874b4cd3100344e7e2d888d9791a6a1d9bfe90fbc1b74fd1d0", size = 9923, upload-time = "2025-05-26T13:58:43.487Z" },+]+[[package]]name = "pytest-recording"version = "0.13.4"