Avoid complex 'lambda' functions; prefer named functions for clarity and debugging
"process_inputs": lambda inputs: process_inputs(_scrub_inputs(inputs)),
1"""Agent factory for creating agents with middleware support."""23from __future__ import annotations45import functools6import importlib7import itertools8import re9from dataclasses import dataclass, field, fields10from typing import (11 TYPE_CHECKING,12 Annotated,13 Any,14 Generic,15 NotRequired,16 Required,17 cast,18 get_args,19 get_origin,20 get_type_hints,21 overload,22)2324from langchain_core.language_models.chat_models import BaseChatModel25from langchain_core.messages import (26 AIMessage,27 AnyMessage,28 RemoveMessage,29 SystemMessage,30 ToolMessage,31)32from langchain_core.tools import BaseTool33from langgraph._internal._runnable import RunnableCallable34from langgraph.constants import END, START35from langgraph.graph.message import REMOVE_ALL_MESSAGES36from langgraph.graph.state import StateGraph37from langgraph.prebuilt import ToolCallTransformer38from langgraph.prebuilt.tool_node import ToolNode39from langgraph.types import Command, Send40from langsmith import traceable41from typing_extensions import TypedDict4243from langchain.agents._subagent_transformer import SubagentTransformer44from langchain.agents.middleware._trace_policy import (45 _node_trace_policy,46 _resolved_transform,47)48from langchain.agents.middleware.types import (49 AgentMiddleware,50 AgentState,51 ContextT,52 ExtendedModelResponse,53 InputAgentState,54 JumpTo,55 ModelRequest,56 ModelResponse,57 OmitFromSchema,58 OutputAgentState,59 ResponseT,60 StateT_co,61 ToolCallRequest,62)63from langchain.agents.structured_output import (64 AutoStrategy,65 MultipleStructuredOutputsError,66 OutputToolBinding,67 ProviderStrategy,68 ProviderStrategyBinding,69 ResponseFormat,70 StructuredOutputError,71 StructuredOutputValidationError,72 ToolStrategy,73)74from langchain.chat_models import init_chat_model757677@dataclass78class _ComposedExtendedModelResponse(Generic[ResponseT]):79 """Internal result from composed `wrap_model_call` middleware.8081 Unlike `ExtendedModelResponse` (user-facing, single command), this holds the82 full list of commands accumulated across all middleware layers during83 composition.84 """8586 model_response: ModelResponse[ResponseT]87 """The underlying model response."""8889 commands: list[Command[Any]] = field(default_factory=list)90 """Commands accumulated from all middleware layers (inner-first, then outer)."""919293if TYPE_CHECKING:94 from collections.abc import Awaitable, Callable, Iterable, Sequence9596 from langchain_core.messages import InvalidToolCall97 from langchain_core.runnables import Runnable, RunnableConfig98 from langgraph.cache.base import BaseCache99 from langgraph.graph.state import CompiledStateGraph100 from langgraph.runtime import Runtime101 from langgraph.store.base import BaseStore102 from langgraph.stream._mux import TransformerFactory103 from langgraph.types import Checkpointer104105 from langchain.agents.middleware.types import ToolCallWrapper106107 _ModelCallHandler = Callable[108 [ModelRequest[ContextT], Callable[[ModelRequest[ContextT]], ModelResponse]],109 ModelResponse | AIMessage | ExtendedModelResponse,110 ]111112 _ComposedModelCallHandler = Callable[113 [ModelRequest[ContextT], Callable[[ModelRequest[ContextT]], ModelResponse]],114 _ComposedExtendedModelResponse,115 ]116117 _AsyncModelCallHandler = Callable[118 [ModelRequest[ContextT], Callable[[ModelRequest[ContextT]], Awaitable[ModelResponse]]],119 Awaitable[ModelResponse | AIMessage | ExtendedModelResponse],120 ]121122 _ComposedAsyncModelCallHandler = Callable[123 [ModelRequest[ContextT], Callable[[ModelRequest[ContextT]], Awaitable[ModelResponse]]],124 Awaitable[_ComposedExtendedModelResponse],125 ]126127128STRUCTURED_OUTPUT_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."129130DYNAMIC_TOOL_ERROR_TEMPLATE = """131Middleware added tools that the agent doesn't know how to execute.132133Unknown tools: {unknown_tool_names}134Registered tools: {available_tool_names}135136This happens when middleware modifies `request.tools` in `wrap_model_call` to include137tools that weren't passed to `create_agent()`.138139How to fix this:140141Option 1: Register tools at agent creation (recommended for most cases)142 Pass the tools to `create_agent(tools=[...])` or set them on `middleware.tools`.143 This makes tools available for every agent invocation.144145Option 2: Handle dynamic tools in middleware (for tools created at runtime)146 Implement `wrap_tool_call` to execute tools that are added dynamically:147148 class MyMiddleware(AgentMiddleware):149 def wrap_tool_call(self, request, handler):150 if request.tool_call["name"] == "dynamic_tool":151 # Execute the dynamic tool yourself or override with tool instance152 return handler(request.override(tool=my_dynamic_tool))153 return handler(request)154""".strip()155156157def _scrub_inputs(inputs: dict[str, Any]) -> dict[str, Any]:158 """Remove `runtime` and `handler` from trace inputs before sending to LangSmith."""159 filtered = inputs.copy()160 filtered.pop("handler", None)161 req = filtered.get("request")162 if isinstance(req, (ModelRequest, ToolCallRequest)):163 filtered["request"] = {164 f.name: getattr(req, f.name) for f in fields(req) if f.name != "runtime"165 }166 return filtered167168169def _wrap_trace_kwargs(middleware: AgentMiddleware[Any, Any]) -> dict[str, Any]:170 """`traceable` kwargs for a middleware's `wrap_*` hook spans.171172 The `_scrub_inputs` baseline (strip the unserializable `handler`/`runtime`) always173 runs first; the effective `TracePolicy` (the middleware's own, else the process-wide174 default) composes on top. The effective policy is resolved at call time, so a175 `configure_trace_policy` call after `create_agent` still applies.176 """177 process_inputs = _resolved_transform(middleware.trace_policy, "process_inputs")178 process_outputs = _resolved_transform(middleware.trace_policy, "process_outputs")179 return {180 "process_inputs": lambda inputs: process_inputs(_scrub_inputs(inputs)),181 "process_outputs": process_outputs,182 }183184185FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT = [186 # If model profile data are not available, model names matching these patterns187 # are assumed to support provider-native structured output. These are regexes188 # so matches stay bounded to model-name segments instead of arbitrary substrings.189 r"(^|[/:.])gpt-4\.1($|[-/:])",190 r"(^|[/:.])gpt-4o($|[-/:])",191 r"(^|[/:.])gpt-5($|[-/:])",192 r"(^|[/:.])gpt-5\.1($|[-/:])",193 r"(^|[/:.])gpt-5\.2(-\d{4}-\d{2}-\d{2})?($|[/:])",194 r"(^|[/:.])gpt-5\.2-(chat|codex)($|[-/:])",195 r"(^|[/:.])gpt-5\.3($|[-/:])",196 r"(^|[/:.])gpt-5\.4(-\d{4}-\d{2}-\d{2})?($|[/:])",197 r"(^|[/:.])gpt-5\.4-(mini|nano)($|[-/:])",198 r"(^|[/:.])gpt-5\.5($|[-/:])",199 r"(^|[/:.])gpt-6-(astra|luna|sol)($|[-/:])",200 r"(^|[/:.])claude-(fable|mythos)-5(?:-\d{8})?(?:-v\d(?::\d)?)?($|[/:])",201 r"(^|[/:.])claude-haiku-4-5(?:-\d{8})?(?:-v\d(?::\d)?)?($|[/:])",202 r"(^|[/:.])claude-opus-4-(5|6|7|8)(?:-\d{8})?(?:-v\d(?::\d)?)?($|[/:])",203 r"(^|[/:.])claude-sonnet-4-(5|6)(?:-\d{8})?(?:-v\d(?::\d)?)?($|[/:])",204 r"(^|[/:.])grok-4($|[-.:/])",205 r"(^|[/:.])grok-build($|[-/:])",206]207208209def _normalize_to_model_response(210 result: ModelResponse | AIMessage | ExtendedModelResponse,211) -> ModelResponse:212 """Normalize middleware return value to ModelResponse.213214 At inner composition boundaries, `ExtendedModelResponse` is unwrapped to its215 underlying `ModelResponse` so that inner middleware always sees `ModelResponse`216 from the handler.217 """218 if isinstance(result, AIMessage):219 return ModelResponse(result=[result], structured_response=None)220 if isinstance(result, ExtendedModelResponse):221 return result.model_response222 return result223224225def _build_commands(226 model_response: ModelResponse,227 middleware_commands: list[Command[Any]] | None = None,228 *,229 has_structured_output: bool = False,230 repaired_messages: list[AnyMessage] | None = None,231) -> list[Command[Any]]:232 """Build a list of Commands from a model response and middleware commands.233234 The first Command contains the model response state (messages and optional235 structured_response). Middleware commands are appended as-is.236237 Args:238 model_response: The model response containing messages and optional239 structured output.240 middleware_commands: Commands accumulated from middleware layers during241 composition (inner-first ordering).242 has_structured_output: Whether the agent was configured with a243 `response_format`. When `True` and no structured response was244 produced, `structured_response` is explicitly cleared to avoid a245 stale value from a previous checkpointed turn.246 repaired_messages: Complete message history after repairing invalid tool calls.247248 Returns:249 List of `Command` objects ready to be returned from a model node.250 """251 messages = model_response.result252 if repaired_messages is not None:253 messages = [254 RemoveMessage(id=REMOVE_ALL_MESSAGES),255 *repaired_messages,256 *model_response.result,257 ]258 state: dict[str, Any] = {"messages": messages}259260 if model_response.structured_response is not None:261 state["structured_response"] = model_response.structured_response262 elif has_structured_output:263 state["structured_response"] = None264265 for cmd in middleware_commands or []:266 if cmd.goto:267 msg = (268 "Command goto is not yet supported in wrap_model_call middleware. "269 "Use the jump_to state field with before_model/after_model hooks instead."270 )271 raise NotImplementedError(msg)272 if cmd.resume:273 msg = "Command resume is not yet supported in wrap_model_call middleware."274 raise NotImplementedError(msg)275 if cmd.graph:276 msg = "Command graph is not yet supported in wrap_model_call middleware."277 raise NotImplementedError(msg)278279 commands: list[Command[Any]] = [Command(update=state)]280 commands.extend(middleware_commands or [])281 return commands282283284def _chain_model_call_handlers(285 handlers: Sequence[_ModelCallHandler[ContextT]],286) -> _ComposedModelCallHandler[ContextT] | None:287 """Compose multiple `wrap_model_call` handlers into single middleware stack.288289 Composes handlers so first in list becomes outermost layer. Each handler receives a290 handler callback to execute inner layers. Commands from each layer are accumulated291 into a list (inner-first, then outer) without merging.292293 Args:294 handlers: List of handlers.295296 First handler wraps all others.297298 Returns:299 Composed handler returning `_ComposedExtendedModelResponse`,300 or `None` if handlers empty.301 """302 if not handlers:303 return None304305 def _to_composed_result(306 result: ModelResponse | AIMessage | ExtendedModelResponse | _ComposedExtendedModelResponse,307 extra_commands: list[Command[Any]] | None = None,308 ) -> _ComposedExtendedModelResponse:309 """Normalize any handler result to _ComposedExtendedModelResponse."""310 commands: list[Command[Any]] = list(extra_commands or [])311 if isinstance(result, _ComposedExtendedModelResponse):312 commands.extend(result.commands)313 model_response = result.model_response314 elif isinstance(result, ExtendedModelResponse):315 model_response = result.model_response316 if result.command is not None:317 commands.append(result.command)318 else:319 model_response = _normalize_to_model_response(result)320321 return _ComposedExtendedModelResponse(model_response=model_response, commands=commands)322323 if len(handlers) == 1:324 single_handler = handlers[0]325326 def normalized_single(327 request: ModelRequest[ContextT],328 handler: Callable[[ModelRequest[ContextT]], ModelResponse],329 ) -> _ComposedExtendedModelResponse:330 return _to_composed_result(single_handler(request, handler))331332 return normalized_single333334 def compose_two(335 outer: _ModelCallHandler[ContextT] | _ComposedModelCallHandler[ContextT],336 inner: _ModelCallHandler[ContextT] | _ComposedModelCallHandler[ContextT],337 ) -> _ComposedModelCallHandler[ContextT]:338 """Compose two handlers where outer wraps inner."""339340 def composed(341 request: ModelRequest[ContextT],342 handler: Callable[[ModelRequest[ContextT]], ModelResponse],343 ) -> _ComposedExtendedModelResponse:344 # Closure variable to capture inner's commands before normalizing345 accumulated_commands: list[Command[Any]] = []346347 def inner_handler(req: ModelRequest[ContextT]) -> ModelResponse:348 # Clear on each call for retry safety349 accumulated_commands.clear()350 inner_result = inner(req, handler)351 if isinstance(inner_result, _ComposedExtendedModelResponse):352 accumulated_commands.extend(inner_result.commands)353 return inner_result.model_response354 if isinstance(inner_result, ExtendedModelResponse):355 if inner_result.command is not None:356 accumulated_commands.append(inner_result.command)357 return inner_result.model_response358 return _normalize_to_model_response(inner_result)359360 outer_result = outer(request, inner_handler)361 return _to_composed_result(362 outer_result,363 extra_commands=accumulated_commands or None,364 )365366 return composed367368 # Compose right-to-left: outer(inner(innermost(handler)))369 composed_handler = compose_two(handlers[-2], handlers[-1])370 for h in reversed(handlers[:-2]):371 composed_handler = compose_two(h, composed_handler)372373 return composed_handler374375376def _chain_async_model_call_handlers(377 handlers: Sequence[_AsyncModelCallHandler[ContextT]],378) -> _ComposedAsyncModelCallHandler[ContextT] | None:379 """Compose multiple async `wrap_model_call` handlers into single middleware stack.380381 Commands from each layer are accumulated into a list (inner-first, then outer)382 without merging.383384 Args:385 handlers: List of async handlers.386387 First handler wraps all others.388389 Returns:390 Composed async handler returning `_ComposedExtendedModelResponse`,391 or `None` if handlers empty.392 """393 if not handlers:394 return None395396 def _to_composed_result(397 result: ModelResponse | AIMessage | ExtendedModelResponse | _ComposedExtendedModelResponse,398 extra_commands: list[Command[Any]] | None = None,399 ) -> _ComposedExtendedModelResponse:400 """Normalize any handler result to _ComposedExtendedModelResponse."""401 commands: list[Command[Any]] = list(extra_commands or [])402 if isinstance(result, _ComposedExtendedModelResponse):403 commands.extend(result.commands)404 model_response = result.model_response405 elif isinstance(result, ExtendedModelResponse):406 model_response = result.model_response407 if result.command is not None:408 commands.append(result.command)409 else:410 model_response = _normalize_to_model_response(result)411412 return _ComposedExtendedModelResponse(model_response=model_response, commands=commands)413414 if len(handlers) == 1:415 single_handler = handlers[0]416417 async def normalized_single(418 request: ModelRequest[ContextT],419 handler: Callable[[ModelRequest[ContextT]], Awaitable[ModelResponse]],420 ) -> _ComposedExtendedModelResponse:421 return _to_composed_result(await single_handler(request, handler))422423 return normalized_single424425 def compose_two(426 outer: _AsyncModelCallHandler[ContextT] | _ComposedAsyncModelCallHandler[ContextT],427 inner: _AsyncModelCallHandler[ContextT] | _ComposedAsyncModelCallHandler[ContextT],428 ) -> _ComposedAsyncModelCallHandler[ContextT]:429 """Compose two async handlers where outer wraps inner."""430431 async def composed(432 request: ModelRequest[ContextT],433 handler: Callable[[ModelRequest[ContextT]], Awaitable[ModelResponse]],434 ) -> _ComposedExtendedModelResponse:435 # Closure variable to capture inner's commands before normalizing436 accumulated_commands: list[Command[Any]] = []437438 async def inner_handler(req: ModelRequest[ContextT]) -> ModelResponse:439 # Clear on each call for retry safety440 accumulated_commands.clear()441 inner_result = await inner(req, handler)442 if isinstance(inner_result, _ComposedExtendedModelResponse):443 accumulated_commands.extend(inner_result.commands)444 return inner_result.model_response445 if isinstance(inner_result, ExtendedModelResponse):446 if inner_result.command is not None:447 accumulated_commands.append(inner_result.command)448 return inner_result.model_response449 return _normalize_to_model_response(inner_result)450451 outer_result = await outer(request, inner_handler)452 return _to_composed_result(453 outer_result,454 extra_commands=accumulated_commands or None,455 )456457 return composed458459 # Compose right-to-left: outer(inner(innermost(handler)))460 composed_handler = compose_two(handlers[-2], handlers[-1])461 for h in reversed(handlers[:-2]):462 composed_handler = compose_two(h, composed_handler)463464 return composed_handler465466467@functools.lru_cache(maxsize=100)468def _get_schema_type_hints(schema: type) -> dict[str, Any]:469 """Return cached type hints for a schema."""470 return get_type_hints(schema, include_extras=True)471472473def _resolve_schemas(schemas: list[type]) -> tuple[type, type, type]:474 """Resolve state, input, and output schemas for the given schemas.475476 Schemas are merged in list order; later entries override earlier ones when the477 same field is declared by multiple schemas. Duplicates are harmless — a type478 that appears more than once is processed at its last position.479 """480 schema_hints: dict[type, dict[str, Any]] = {}481 for schema in schemas:482 # Reinsert duplicates so dict iteration reflects their final position.483 schema_hints.pop(schema, None)484 schema_hints[schema] = _get_schema_type_hints(schema)485 return (486 _resolve_schema(schema_hints, "StateSchema", None),487 _resolve_schema(schema_hints, "InputSchema", "input"),488 _resolve_schema(schema_hints, "OutputSchema", "output"),489 )490491492def _resolve_schema(493 schema_hints: dict[type, dict[str, Any]],494 schema_name: str,495 omit_flag: str | None = None,496) -> type:497 """Resolve schema by merging schemas and optionally respecting `OmitFromSchema` annotations.498499 Args:500 schema_hints: Resolved schema annotations to merge501 schema_name: Name for the generated `TypedDict`502 omit_flag: If specified, omit fields with this flag set (`'input'` or503 `'output'`)504505 Returns:506 Merged schema as `TypedDict`507 """508 all_annotations = {}509510 for hints in schema_hints.values():511 for field_name, field_type in hints.items():512 should_omit = False513514 if omit_flag:515 metadata = _extract_metadata(field_type)516 for meta in metadata:517 if isinstance(meta, OmitFromSchema) and getattr(meta, omit_flag) is True:518 should_omit = True519 break520521 if not should_omit:522 all_annotations[field_name] = field_type523524 # `TypedDict` dynamically creates a class, but type checkers don't infer that525 # the runtime result satisfies this function's `type` return contract.526 return cast("type", TypedDict(schema_name, all_annotations)) # type: ignore[operator]527528529def _extract_metadata(type_: type) -> list[Any]:530 """Extract metadata from a field type, handling `Required`/`NotRequired` and `Annotated` wrappers.""" # noqa: E501531 # Handle Required[Annotated[...]] or NotRequired[Annotated[...]]532 if get_origin(type_) in {Required, NotRequired}:533 inner_type = get_args(type_)[0]534 if get_origin(inner_type) is Annotated:535 return list(get_args(inner_type)[1:])536537 # Handle direct Annotated[...]538 elif get_origin(type_) is Annotated:539 return list(get_args(type_)[1:])540541 return []542543544def _get_can_jump_to(middleware: AgentMiddleware[Any, Any], hook_name: str) -> list[JumpTo]:545 """Get the `can_jump_to` list from either sync or async hook methods.546547 Args:548 middleware: The middleware instance to inspect.549 hook_name: The name of the hook (`'before_model'` or `'after_model'`).550551 Returns:552 List of jump destinations, or empty list if not configured.553 """554 # Get the base class method for comparison555 base_sync_method = getattr(AgentMiddleware, hook_name, None)556 base_async_method = getattr(AgentMiddleware, f"a{hook_name}", None)557558 # Try sync method first - only if it's overridden from base class559 sync_method = getattr(middleware.__class__, hook_name, None)560 if (561 sync_method562 and sync_method is not base_sync_method563 and hasattr(sync_method, "__can_jump_to__")564 ):565 # `hasattr` proves the metadata exists at runtime, but not its value type.566 return cast("list[JumpTo]", sync_method.__can_jump_to__)567568 # Try async method - only if it's overridden from base class569 async_method = getattr(middleware.__class__, f"a{hook_name}", None)570 if (571 async_method572 and async_method is not base_async_method573 and hasattr(async_method, "__can_jump_to__")574 ):575 # `hasattr` proves the metadata exists at runtime, but not its value type.576 return cast("list[JumpTo]", async_method.__can_jump_to__)577578 return []579580581def _supports_provider_strategy(582 model: str | BaseChatModel, tools: list[BaseTool | dict[str, Any]] | None = None583) -> bool:584 """Check if a model supports provider-specific structured output.585586 Args:587 model: Model name string or `BaseChatModel` instance.588 tools: Optional list of tools provided to the agent.589590 Needed because some models don't support structured output together with tool calling.591592 Returns:593 `True` if the model supports provider-specific structured output, `False` otherwise.594 """595 model_name: str | None = None596 if isinstance(model, str):597 model_name = model598 elif isinstance(model, BaseChatModel):599 model_name = (600 getattr(model, "model_name", None)601 or getattr(model, "model", None)602 or getattr(model, "model_id", "")603 )604 model_profile = model.profile605 if (606 model_profile is not None607 and model_profile.get("structured_output")608 # We make an exception for Gemini < 3-series models, which currently do not support609 # simultaneous tool use with structured output; 3-series can.610 and not (611 tools612 and isinstance(model_name, str)613 and "gemini" in model_name.lower()614 and "gemini-3" not in model_name.lower()615 )616 ):617 return True618619 return (620 any(621 re.search(pattern, model_name.lower())622 for pattern in FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT623 )624 if model_name625 else False626 )627628629def _is_openai_compatible_model(model: BaseChatModel) -> bool:630 """Check if a model inherits from `BaseChatOpenAI`.631632 Used to redundantly set `strict=True` on tools when `response_format` is633 provided, as older versions of `langchain-openai` do not auto-set it.634 Covers `ChatOpenAI`, `ChatDeepSeek`, `ChatXAI`, etc.635636 Args:637 model: The chat model to check.638639 Returns:640 `True` if the model inherits from `BaseChatOpenAI`, `False` otherwise.641 """642 try:643 base_chat_openai = importlib.import_module("langchain_openai.chat_models.base")644 except ImportError:645 return False646 return isinstance(model, base_chat_openai.BaseChatOpenAI)647648649def _handle_structured_output_error(650 exception: Exception,651 response_format: ResponseFormat[Any],652) -> tuple[bool, str]:653 """Handle structured output error.654655 Returns `(should_retry, retry_tool_message)`.656 """657 if not isinstance(response_format, ToolStrategy):658 return False, ""659660 handle_errors = response_format.handle_errors661662 if handle_errors is False:663 return False, ""664 if handle_errors is True:665 return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))666 if isinstance(handle_errors, str):667 return True, handle_errors668 if isinstance(handle_errors, type):669 if issubclass(handle_errors, Exception) and isinstance(exception, handle_errors):670 return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))671 return False, ""672 if isinstance(handle_errors, tuple):673 if any(isinstance(exception, exc_type) for exc_type in handle_errors):674 return True, STRUCTURED_OUTPUT_ERROR_TEMPLATE.format(error=str(exception))675 return False, ""676 return True, handle_errors(exception)677678679def _invalid_tool_call_message(tool_call: InvalidToolCall) -> ToolMessage | None:680 tool_call_id = tool_call.get("id")681 if tool_call_id is None:682 return None683 name = tool_call.get("name") or "unknown"684 return ToolMessage(685 content=(686 f"Tool call {name} with id {tool_call_id} could not be executed - "687 "arguments were malformed or truncated."688 ),689 name=name,690 tool_call_id=tool_call_id,691 status="error",692 )693694695def _patch_invalid_tool_calls(messages: Sequence[AnyMessage]) -> list[AnyMessage]:696 answered_ids = {697 message.tool_call_id for message in messages if isinstance(message, ToolMessage)698 }699 patched_messages: list[AnyMessage] = []700 for message in messages:701 patched_messages.append(message)702 if not isinstance(message, AIMessage):703 continue704 for tool_call in message.invalid_tool_calls:705 if tool_call.get("id") in answered_ids:706 continue707 if tool_message := _invalid_tool_call_message(tool_call):708 patched_messages.append(tool_message)709 answered_ids.add(tool_message.tool_call_id)710 return patched_messages711712713def _chain_tool_call_wrappers(714 wrappers: Sequence[ToolCallWrapper],715) -> ToolCallWrapper | None:716 """Compose wrappers into middleware stack (first = outermost).717718 Args:719 wrappers: Wrappers in middleware order.720721 Returns:722 Composed wrapper, or `None` if empty.723724 Example:725 ```python726 wrapper = _chain_tool_call_wrappers([auth, cache, retry])727 # Request flows: auth -> cache -> retry -> tool728 # Response flows: tool -> retry -> cache -> auth729 ```730 """731 if not wrappers:732 return None733734 if len(wrappers) == 1:735 return wrappers[0]736737 def compose_two(outer: ToolCallWrapper, inner: ToolCallWrapper) -> ToolCallWrapper:738 """Compose two wrappers where outer wraps inner."""739740 def composed(741 request: ToolCallRequest,742 execute: Callable[[ToolCallRequest], ToolMessage | Command[Any]],743 ) -> ToolMessage | Command[Any]:744 # Create a callable that invokes inner with the original execute745 def call_inner(req: ToolCallRequest) -> ToolMessage | Command[Any]:746 return inner(req, execute)747748 # Outer can call call_inner multiple times749 return outer(request, call_inner)750751 return composed752753 # Chain all wrappers: first -> second -> ... -> last754 result = wrappers[-1]755 for wrapper in reversed(wrappers[:-1]):756 result = compose_two(wrapper, result)757758 return result759760761def _chain_async_tool_call_wrappers(762 wrappers: Sequence[763 Callable[764 [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]]],765 Awaitable[ToolMessage | Command[Any]],766 ]767 ],768) -> (769 Callable[770 [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]]],771 Awaitable[ToolMessage | Command[Any]],772 ]773 | None774):775 """Compose async wrappers into middleware stack (first = outermost).776777 Args:778 wrappers: Async wrappers in middleware order.779780 Returns:781 Composed async wrapper, or `None` if empty.782 """783 if not wrappers:784 return None785786 if len(wrappers) == 1:787 return wrappers[0]788789 def compose_two(790 outer: Callable[791 [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]]],792 Awaitable[ToolMessage | Command[Any]],793 ],794 inner: Callable[795 [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]]],796 Awaitable[ToolMessage | Command[Any]],797 ],798 ) -> Callable[799 [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]]],800 Awaitable[ToolMessage | Command[Any]],801 ]:802 """Compose two async wrappers where outer wraps inner."""803804 async def composed(805 request: ToolCallRequest,806 execute: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],807 ) -> ToolMessage | Command[Any]:808 # Create an async callable that invokes inner with the original execute809 async def call_inner(req: ToolCallRequest) -> ToolMessage | Command[Any]:810 return await inner(req, execute)811812 # Outer can call call_inner multiple times813 return await outer(request, call_inner)814815 return composed816817 # Chain all wrappers: first -> second -> ... -> last818 result = wrappers[-1]819 for wrapper in reversed(wrappers[:-1]):820 result = compose_two(wrapper, result)821822 return result823824825# No `response_format`: there is no structured output, so `ResponseT` resolves to `Any`.826@overload827def create_agent(828 model: str | BaseChatModel,829 tools: Sequence[BaseTool | Callable[..., Any] | dict[str, Any]] | None = None,830 *,831 system_prompt: str | SystemMessage | None = None,832 middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),833 response_format: None = None,834 state_schema: None = None,835 context_schema: type[ContextT] | None = None,836 checkpointer: Checkpointer | None = None,837 store: BaseStore | None = None,838 interrupt_before: list[str] | None = None,839 interrupt_after: list[str] | None = None,840 debug: bool = False,841 name: str | None = None,842 cache: BaseCache[Any] | None = None,843 transformers: Sequence[TransformerFactory] | None = None,844) -> CompiledStateGraph[AgentState[Any], ContextT, InputAgentState, OutputAgentState[Any]]: ...845846847# Raw-dict `response_format`: structured output is an untyped `dict[str, Any]`.848@overload849def create_agent(850 model: str | BaseChatModel,851 tools: Sequence[BaseTool | Callable[..., Any] | dict[str, Any]] | None = None,852 *,853 system_prompt: str | SystemMessage | None = None,854 middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),855 response_format: dict[str, Any],856 state_schema: type[AgentState[dict[str, Any]]] | None = None,857 context_schema: type[ContextT] | None = None,858 checkpointer: Checkpointer | None = None,859 store: BaseStore | None = None,860 interrupt_before: list[str] | None = None,861 interrupt_after: list[str] | None = None,862 debug: bool = False,863 name: str | None = None,864 cache: BaseCache[Any] | None = None,865 transformers: Sequence[TransformerFactory] | None = None,866) -> CompiledStateGraph[867 AgentState[dict[str, Any]], ContextT, InputAgentState, OutputAgentState[dict[str, Any]]868]: ...869870871# Schema-typed `response_format`: `ResponseT` is inferred from the schema/type.872@overload873def create_agent(874 model: str | BaseChatModel,875 tools: Sequence[BaseTool | Callable[..., Any] | dict[str, Any]] | None = None,876 *,877 system_prompt: str | SystemMessage | None = None,878 middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),879 response_format: ResponseFormat[ResponseT] | type[ResponseT] | None = None,880 state_schema: type[AgentState[ResponseT]] | None = None,881 context_schema: type[ContextT] | None = None,882 checkpointer: Checkpointer | None = None,883 store: BaseStore | None = None,884 interrupt_before: list[str] | None = None,885 interrupt_after: list[str] | None = None,886 debug: bool = False,887 name: str | None = None,888 cache: BaseCache[Any] | None = None,889 transformers: Sequence[TransformerFactory] | None = None,890) -> CompiledStateGraph[891 AgentState[ResponseT], ContextT, InputAgentState, OutputAgentState[ResponseT]892]: ...893894895def create_agent(896 model: str | BaseChatModel,897 tools: Sequence[BaseTool | Callable[..., Any] | dict[str, Any]] | None = None,898 *,899 system_prompt: str | SystemMessage | None = None,900 middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),901 response_format: ResponseFormat[ResponseT] | type[ResponseT] | dict[str, Any] | None = None,902 state_schema: type[AgentState[ResponseT]] | None = None,903 context_schema: type[ContextT] | None = None,904 checkpointer: Checkpointer | None = None,905 store: BaseStore | None = None,906 interrupt_before: list[str] | None = None,907 interrupt_after: list[str] | None = None,908 debug: bool = False,909 name: str | None = None,910 cache: BaseCache[Any] | None = None,911 transformers: Sequence[TransformerFactory] | None = None,912) -> CompiledStateGraph[913 AgentState[ResponseT], ContextT, InputAgentState, OutputAgentState[ResponseT]914]:915 """Creates an agent graph that calls tools in a loop until a stopping condition is met.916917 For more details on using `create_agent`,918 visit the [Agents](https://docs.langchain.com/oss/python/langchain/agents) docs.919920 Args:921 model: The language model for the agent.922923 Can be a string identifier (e.g., `"openai:gpt-5.5"`) or a direct chat model924 instance (e.g., [`ChatOpenAI`][langchain_openai.ChatOpenAI] or other another925 [LangChain chat model](https://docs.langchain.com/oss/python/integrations/chat)).926927 For a full list of supported model strings, see928 [`init_chat_model`][langchain.chat_models.init_chat_model(model_provider)].929930 !!! tip ""931932 See the [Models](https://docs.langchain.com/oss/python/langchain/models)933 docs for more information.934 tools: A list of tools, `dict`, or `Callable`.935936 If `None` or an empty list, the agent will consist of a model node without a937 tool calling loop.938939940 !!! tip ""941942 See the [Tools](https://docs.langchain.com/oss/python/langchain/tools)943 docs for more information.944 system_prompt: An optional system prompt for the LLM.945946 Can be a `str` (which will be converted to a `SystemMessage`) or a947 `SystemMessage` instance directly. The system message is added to the948 beginning of the message list when calling the model.949 middleware: A sequence of middleware instances to apply to the agent.950951 Middleware can intercept and modify agent behavior at various stages.952953 !!! tip ""954955 See the [Middleware](https://docs.langchain.com/oss/python/langchain/middleware)956 docs for more information.957 response_format: An optional configuration for structured responses.958959 Can be a `ToolStrategy`, `ProviderStrategy`, or a Pydantic model class.960961 If provided, the agent will handle structured output during the962 conversation flow.963964 Raw schemas will be wrapped in an appropriate strategy based on model965 capabilities.966967 !!! tip ""968969 See the [Structured output](https://docs.langchain.com/oss/python/langchain/structured-output)970 docs for more information.971 state_schema: An optional `TypedDict` schema that extends `AgentState`.972973 When provided, this schema is used instead of `AgentState` as the base974 schema for merging with middleware state schemas. This allows users to975 add custom state fields without needing to create custom middleware.976977 Generally, it's recommended to use `state_schema` extensions via middleware978 to keep relevant extensions scoped to corresponding hooks / tools.979 context_schema: An optional schema for runtime context.980 checkpointer: An optional checkpoint saver object.981982 Used for persisting the state of the graph (e.g., as chat memory) for a983 single thread (e.g., a single conversation).984 store: An optional store object.985986 Used for persisting data across multiple threads (e.g., multiple987 conversations / users).988 interrupt_before: An optional list of node names to interrupt before.989990 Useful if you want to add a user confirmation or other interrupt991 before taking an action.992 interrupt_after: An optional list of node names to interrupt after.993994 Useful if you want to return directly or run additional processing995 on an output.996 debug: Whether to enable verbose logging for graph execution.997998 When enabled, prints detailed information about each node execution, state999 updates, and transitions during agent runtime. Useful for debugging1000 middleware behavior and understanding agent execution flow.1001 name: An optional name for the `CompiledStateGraph`.10021003 This name will be automatically used when adding the agent graph to1004 another graph as a subgraph node - particularly useful for building1005 multi-agent systems.1006 cache: An optional `BaseCache` instance to enable caching of graph execution.1007 transformers: Optional sequence of scope-aware `StreamTransformer`1008 factories to register on the compiled graph in addition to1009 the agent defaults. Each factory is invoked as `factory(scope)`1010 so every invocation receives a fresh instance. The final order1011 on the compiled graph is: `ToolCallTransformer`, then any1012 factories declared by middleware via1013 `AgentMiddleware.transformers`, then any factories supplied here.10141015 Returns:1016 A compiled `StateGraph` that can be used for chat interactions.10171018 Raises:1019 AssertionError: If duplicate middleware instances are provided.10201021 The agent node calls the language model with the messages list (after applying1022 the system prompt). If the resulting [`AIMessage`][langchain.messages.AIMessage]1023 contains `tool_calls`, the graph will then call the tools. The tools node executes1024 the tools and adds the responses to the messages list as1025 [`ToolMessage`][langchain.messages.ToolMessage] objects. The agent node then calls1026 the language model again. The process repeats until no more `tool_calls` are present1027 in the response. The agent then returns the full list of messages.10281029 Example:1030 ```python1031 from langchain.agents import create_agent103210331034 def check_weather(location: str) -> str:1035 '''Return the weather forecast for the specified location.'''1036 return f"It's always sunny in {location}"103710381039 graph = create_agent(1040 model="anthropic:claude-sonnet-4-5-20250929",1041 tools=[check_weather],1042 system_prompt="You are a helpful assistant",1043 )1044 inputs = {"messages": [{"role": "user", "content": "what is the weather in sf"}]}1045 for chunk in graph.stream(inputs, stream_mode="updates"):1046 print(chunk)1047 ```1048 """1049 # init chat model1050 if isinstance(model, str):1051 model = init_chat_model(model)10521053 # Convert system_prompt to SystemMessage if needed1054 system_message: SystemMessage | None = None1055 if system_prompt is not None:1056 if isinstance(system_prompt, SystemMessage):1057 system_message = system_prompt1058 else:1059 system_message = SystemMessage(content=system_prompt)10601061 # Handle tools being None or empty1062 if tools is None:1063 tools = []10641065 # Convert response format and setup structured output tools1066 # Raw schemas are wrapped in AutoStrategy to preserve auto-detection intent.1067 # AutoStrategy is converted to ToolStrategy upfront to calculate tools during agent creation,1068 # but may be replaced with ProviderStrategy later based on model capabilities.1069 initial_response_format: ToolStrategy[Any] | ProviderStrategy[Any] | AutoStrategy[Any] | None1070 if response_format is None:1071 initial_response_format = None1072 elif isinstance(response_format, (ToolStrategy, ProviderStrategy, AutoStrategy)):1073 # Explicit Tool/Provider strategy, or AutoStrategy for later capability detection1074 initial_response_format = response_format1075 else:1076 # Raw schema - wrap in AutoStrategy to enable auto-detection1077 initial_response_format = AutoStrategy(schema=response_format)10781079 # For AutoStrategy, convert to ToolStrategy to setup tools upfront1080 # (may be replaced with ProviderStrategy later based on model)1081 tool_strategy_for_setup: ToolStrategy[Any] | None = None1082 if isinstance(initial_response_format, AutoStrategy):1083 tool_strategy_for_setup = ToolStrategy(schema=initial_response_format.schema)1084 elif isinstance(initial_response_format, ToolStrategy):1085 tool_strategy_for_setup = initial_response_format10861087 structured_output_tools: dict[str, OutputToolBinding[Any]] = {}1088 if tool_strategy_for_setup:1089 for response_schema in tool_strategy_for_setup.schema_specs:1090 structured_tool_info = OutputToolBinding.from_schema_spec(response_schema)1091 structured_output_tools[structured_tool_info.tool.name] = structured_tool_info1092 middleware_tools = [t for m in middleware for t in getattr(m, "tools", [])]10931094 # Collect middleware with wrap_tool_call or awrap_tool_call hooks1095 # Include middleware with either implementation to ensure NotImplementedError is raised1096 # when middleware doesn't support the execution path1097 middleware_w_wrap_tool_call = [1098 m1099 for m in middleware1100 if m.__class__.wrap_tool_call is not AgentMiddleware.wrap_tool_call1101 or m.__class__.awrap_tool_call is not AgentMiddleware.awrap_tool_call1102 ]11031104 # Chain all wrap_tool_call handlers into a single composed handler1105 wrap_tool_call_wrapper = None1106 if middleware_w_wrap_tool_call:1107 wrappers = [1108 traceable(name=f"{m.name}.wrap_tool_call", **_wrap_trace_kwargs(m))(m.wrap_tool_call)1109 for m in middleware_w_wrap_tool_call1110 ]1111 wrap_tool_call_wrapper = _chain_tool_call_wrappers(wrappers)11121113 # Collect middleware with awrap_tool_call or wrap_tool_call hooks1114 # Include middleware with either implementation to ensure NotImplementedError is raised1115 # when middleware doesn't support the execution path1116 middleware_w_awrap_tool_call = [1117 m1118 for m in middleware1119 if m.__class__.awrap_tool_call is not AgentMiddleware.awrap_tool_call1120 or m.__class__.wrap_tool_call is not AgentMiddleware.wrap_tool_call1121 ]11221123 # Chain all awrap_tool_call handlers into a single composed async handler1124 awrap_tool_call_wrapper = None1125 if middleware_w_awrap_tool_call:1126 async_wrappers = [1127 traceable(name=f"{m.name}.awrap_tool_call", **_wrap_trace_kwargs(m))(m.awrap_tool_call)1128 for m in middleware_w_awrap_tool_call1129 ]1130 awrap_tool_call_wrapper = _chain_async_tool_call_wrappers(async_wrappers)11311132 # Setup tools1133 tool_node: ToolNode | None = None1134 # Extract built-in provider tools (dict format) and regular tools (BaseTool/callables)1135 built_in_tools = [t for t in tools if isinstance(t, dict)]1136 regular_tools = [t for t in tools if not isinstance(t, dict)]11371138 # Tools that require client-side execution (must be in ToolNode)1139 available_tools = middleware_tools + regular_tools11401141 # Create ToolNode if we have client-side tools OR if middleware defines wrap_tool_call1142 # (which may handle dynamically registered tools)1143 tool_node = (1144 ToolNode(1145 tools=available_tools,1146 wrap_tool_call=wrap_tool_call_wrapper,1147 awrap_tool_call=awrap_tool_call_wrapper,1148 )1149 if available_tools or wrap_tool_call_wrapper or awrap_tool_call_wrapper1150 else None1151 )11521153 # Default tools for ModelRequest initialization1154 # Use converted BaseTool instances from ToolNode (not raw callables)1155 # Include built-ins and converted tools (can be changed dynamically by middleware)1156 # Structured tools are NOT included - they're added dynamically based on response_format1157 if tool_node:1158 default_tools = list(tool_node.tools_by_name.values()) + built_in_tools1159 else:1160 default_tools = list(built_in_tools)11611162 # validate middleware1163 if len({m.name for m in middleware}) != len(middleware):1164 msg = "Please remove duplicate middleware instances."1165 raise AssertionError(msg)1166 middleware_w_before_agent = [1167 m1168 for m in middleware1169 if m.__class__.before_agent is not AgentMiddleware.before_agent1170 or m.__class__.abefore_agent is not AgentMiddleware.abefore_agent1171 ]1172 middleware_w_before_model = [1173 m1174 for m in middleware1175 if m.__class__.before_model is not AgentMiddleware.before_model1176 or m.__class__.abefore_model is not AgentMiddleware.abefore_model1177 ]1178 middleware_w_after_model = [1179 m1180 for m in middleware1181 if m.__class__.after_model is not AgentMiddleware.after_model1182 or m.__class__.aafter_model is not AgentMiddleware.aafter_model1183 ]1184 middleware_w_after_agent = [1185 m1186 for m in middleware1187 if m.__class__.after_agent is not AgentMiddleware.after_agent1188 or m.__class__.aafter_agent is not AgentMiddleware.aafter_agent1189 ]1190 # Collect middleware with wrap_model_call or awrap_model_call hooks1191 # Include middleware with either implementation to ensure NotImplementedError is raised1192 # when middleware doesn't support the execution path1193 middleware_w_wrap_model_call = [1194 m1195 for m in middleware1196 if m.__class__.wrap_model_call is not AgentMiddleware.wrap_model_call1197 or m.__class__.awrap_model_call is not AgentMiddleware.awrap_model_call1198 ]1199 # Collect middleware with awrap_model_call or wrap_model_call hooks1200 # Include middleware with either implementation to ensure NotImplementedError is raised1201 # when middleware doesn't support the execution path1202 middleware_w_awrap_model_call = [1203 m1204 for m in middleware1205 if m.__class__.awrap_model_call is not AgentMiddleware.awrap_model_call1206 or m.__class__.wrap_model_call is not AgentMiddleware.wrap_model_call1207 ]12081209 # Compose wrap_model_call handlers into a single middleware stack (sync)1210 wrap_model_call_handler = None1211 if middleware_w_wrap_model_call:1212 sync_handlers = [1213 traceable(name=f"{m.name}.wrap_model_call", **_wrap_trace_kwargs(m))(m.wrap_model_call)1214 for m in middleware_w_wrap_model_call1215 ]1216 wrap_model_call_handler = _chain_model_call_handlers(sync_handlers)12171218 # Compose awrap_model_call handlers into a single middleware stack (async)1219 awrap_model_call_handler = None1220 if middleware_w_awrap_model_call:1221 async_handlers = [1222 traceable(name=f"{m.name}.awrap_model_call", **_wrap_trace_kwargs(m))(1223 m.awrap_model_call1224 )1225 for m in middleware_w_awrap_model_call1226 ]1227 awrap_model_call_handler = _chain_async_model_call_handlers(async_handlers)12281229 base_state = state_schema if state_schema is not None else AgentState1230 # Build an ordered list: middleware schemas first (in registration order),1231 # base_state last so it wins any field conflict. This lets the caller's1232 # explicit state_schema override middleware annotations — e.g. passing1233 # a DeltaChannel-annotated schema wins over BinaryOperatorAggregate from1234 # AgentState without requiring a post-compilation patch.1235 state_schemas: list[type] = [*(m.state_schema for m in middleware), base_state]12361237 resolved_state_schema, input_schema, output_schema = _resolve_schemas(state_schemas)12381239 # create graph, add nodes1240 graph: StateGraph[1241 AgentState[ResponseT], ContextT, InputAgentState, OutputAgentState[ResponseT]1242 ] = StateGraph(1243 state_schema=resolved_state_schema,1244 input_schema=input_schema,1245 output_schema=output_schema,1246 context_schema=context_schema,1247 )12481249 def _handle_model_output(1250 output: AIMessage, effective_response_format: ResponseFormat[Any] | None1251 ) -> dict[str, Any]:1252 """Handle model output including structured responses.12531254 Args:1255 output: The AI message output from the model.1256 effective_response_format: The actual strategy used (may differ from initial1257 if auto-detected).1258 """1259 # Handle structured output with provider strategy1260 if isinstance(effective_response_format, ProviderStrategy):1261 if not output.tool_calls:1262 provider_strategy_binding = ProviderStrategyBinding.from_schema_spec(1263 effective_response_format.schema_spec1264 )1265 try:1266 structured_response = provider_strategy_binding.parse(output)1267 except Exception as exc:1268 schema_name = getattr(1269 effective_response_format.schema_spec.schema, "__name__", "response_format"1270 )1271 validation_error = StructuredOutputValidationError(schema_name, exc, output)1272 raise validation_error from exc1273 else:1274 return {"messages": [output], "structured_response": structured_response}1275 return {"messages": [output]}12761277 # Handle structured output with tool strategy1278 if (1279 isinstance(effective_response_format, ToolStrategy)1280 and isinstance(output, AIMessage)1281 and output.tool_calls1282 ):1283 structured_tool_calls = [1284 tc for tc in output.tool_calls if tc["name"] in structured_output_tools1285 ]12861287 if structured_tool_calls:1288 exception: StructuredOutputError | None = None1289 if len(structured_tool_calls) > 1:1290 # Handle multiple structured outputs error1291 tool_names = [tc["name"] for tc in structured_tool_calls]1292 exception = MultipleStructuredOutputsError(tool_names, output)1293 should_retry, error_message = _handle_structured_output_error(1294 exception, effective_response_format1295 )1296 if not should_retry:1297 raise exception12981299 # Add error messages and retry1300 tool_messages = [1301 ToolMessage(1302 content=error_message,1303 tool_call_id=tc["id"],1304 name=tc["name"],1305 )1306 for tc in structured_tool_calls1307 ]1308 return {"messages": [output, *tool_messages]}13091310 # Handle single structured output1311 tool_call = structured_tool_calls[0]1312 try:1313 structured_tool_binding = structured_output_tools[tool_call["name"]]1314 structured_response = structured_tool_binding.parse(tool_call["args"])13151316 tool_message_content = (1317 effective_response_format.tool_message_content1318 or f"Returning structured response: {structured_response}"1319 )13201321 return {1322 "messages": [1323 output,1324 ToolMessage(1325 content=tool_message_content,1326 tool_call_id=tool_call["id"],1327 name=tool_call["name"],1328 ),1329 ],1330 "structured_response": structured_response,1331 }1332 except Exception as exc:1333 exception = StructuredOutputValidationError(tool_call["name"], exc, output)1334 should_retry, error_message = _handle_structured_output_error(1335 exception, effective_response_format1336 )1337 if not should_retry:1338 raise exception from exc13391340 return {1341 "messages": [1342 output,1343 ToolMessage(1344 content=error_message,1345 tool_call_id=tool_call["id"],1346 name=tool_call["name"],1347 ),1348 ],1349 }13501351 return {"messages": [output]}13521353 def _get_bound_model(1354 request: ModelRequest[ContextT],1355 ) -> tuple[Runnable[Any, Any], ResponseFormat[Any] | None]:1356 """Get the model with appropriate tool bindings.13571358 Performs auto-detection of strategy if needed based on model capabilities.13591360 Args:1361 request: The model request containing model, tools, and response format.13621363 Returns:1364 Tuple of `(bound_model, effective_response_format)` where1365 `effective_response_format` is the actual strategy used (may differ from1366 initial if auto-detected).13671368 Raises:1369 ValueError: If middleware returned unknown client-side tool names.1370 ValueError: If `ToolStrategy` specifies tools not declared upfront.1371 """1372 # Validate ONLY client-side tools that need to exist in tool_node1373 # Skip validation when wrap_tool_call is defined, as middleware may handle1374 # dynamic tools that are added at runtime via wrap_model_call1375 has_wrap_tool_call = wrap_tool_call_wrapper or awrap_tool_call_wrapper13761377 # Build map of available client-side tools from the ToolNode1378 # (which has already converted callables)1379 available_tools_by_name = {}1380 if tool_node:1381 available_tools_by_name = tool_node.tools_by_name.copy()13821383 # Check if any requested tools are unknown CLIENT-SIDE tools1384 # Only validate if wrap_tool_call is NOT defined (no dynamic tool handling)1385 if not has_wrap_tool_call:1386 unknown_tool_names = []1387 for t in request.tools:1388 # Only validate BaseTool instances (skip built-in dict tools)1389 if isinstance(t, dict):1390 continue1391 if isinstance(t, BaseTool) and t.name not in available_tools_by_name:1392 unknown_tool_names.append(t.name)13931394 if unknown_tool_names:1395 available_tool_names = sorted(available_tools_by_name.keys())1396 msg = DYNAMIC_TOOL_ERROR_TEMPLATE.format(1397 unknown_tool_names=unknown_tool_names,1398 available_tool_names=available_tool_names,1399 )1400 raise ValueError(msg)14011402 # Normalize raw schemas to AutoStrategy1403 # (handles middleware override with raw Pydantic classes)1404 response_format: ResponseFormat[Any] | Any | None = request.response_format1405 if response_format is not None and not isinstance(1406 response_format, (AutoStrategy, ToolStrategy, ProviderStrategy)1407 ):1408 response_format = AutoStrategy(schema=response_format)14091410 # Determine effective response format (auto-detect if needed)1411 effective_response_format: ResponseFormat[Any] | None1412 if isinstance(response_format, AutoStrategy):1413 # User provided raw schema via AutoStrategy - auto-detect best strategy based on model1414 if _supports_provider_strategy(request.model, tools=request.tools):1415 # Model supports provider strategy - use it1416 effective_response_format = ProviderStrategy(schema=response_format.schema)1417 elif response_format is initial_response_format and tool_strategy_for_setup is not None:1418 # Model doesn't support provider strategy - use ToolStrategy1419 # Reuse the strategy from setup if possible to preserve tool names1420 effective_response_format = tool_strategy_for_setup1421 else:1422 effective_response_format = ToolStrategy(schema=response_format.schema)1423 else:1424 # User explicitly specified a strategy - preserve it1425 effective_response_format = response_format14261427 # Build final tools list including structured output tools1428 # request.tools now only contains BaseTool instances (converted from callables)1429 # and dicts (built-ins)1430 final_tools = list(request.tools)1431 if isinstance(effective_response_format, ToolStrategy):1432 # Add structured output tools to final tools list, narrowed to only the1433 # schemas present in the (possibly middleware-narrowed) response format.1434 # This ensures middleware that narrows a union `ToolStrategy` to a subset1435 # via `request.override()` actually restricts which structured output1436 # tools the model can choose from.1437 narrowed_tool_names = {spec.name for spec in effective_response_format.schema_specs}1438 structured_tools = [1439 info.tool1440 for name, info in structured_output_tools.items()1441 if name in narrowed_tool_names1442 ]1443 final_tools.extend(structured_tools)14441445 # Bind model based on effective response format1446 if isinstance(effective_response_format, ProviderStrategy):1447 # (Backward compatibility) Use OpenAI format structured output1448 # Redundantly set strict=True on tools for OpenAI-compatible models, as older1449 # versions of langchain-openai do not auto-set it in bind_tools.1450 kwargs = effective_response_format.to_model_kwargs()1451 bind_kwargs: dict[str, Any] = {**kwargs, **request.model_settings}1452 if _is_openai_compatible_model(request.model) and not getattr(1453 request.model, "use_responses_api", False1454 ):1455 bind_kwargs["strict"] = True1456 return (1457 request.model.bind_tools(final_tools, **bind_kwargs),1458 effective_response_format,1459 )14601461 if isinstance(effective_response_format, ToolStrategy):1462 # Current implementation requires that tools used for structured output1463 # have to be declared upfront when creating the agent as part of the1464 # response format. Middleware is allowed to change the response format1465 # to a subset of the original structured tools when using ToolStrategy,1466 # but not to add new structured tools that weren't declared upfront.1467 # Compute output binding1468 for tc in effective_response_format.schema_specs:1469 if tc.name not in structured_output_tools:1470 msg = (1471 f"ToolStrategy specifies tool '{tc.name}' "1472 "which wasn't declared in the original "1473 "response format when creating the agent."1474 )1475 raise ValueError(msg)14761477 # Force tool use if we have structured output tools1478 tool_choice = "any" if structured_output_tools else request.tool_choice1479 return (1480 request.model.bind_tools(1481 final_tools, tool_choice=tool_choice, **request.model_settings1482 ),1483 effective_response_format,1484 )14851486 # No structured output - standard model binding1487 if final_tools:1488 return (1489 request.model.bind_tools(1490 final_tools, tool_choice=request.tool_choice, **request.model_settings1491 ),1492 None,1493 )1494 return request.model.bind(**request.model_settings), None14951496 def _execute_model_sync(request: ModelRequest[ContextT]) -> ModelResponse:1497 """Execute model and return response.14981499 This is the core model execution logic wrapped by `wrap_model_call` handlers.15001501 Raises any exceptions that occur during model invocation.1502 """1503 # Get the bound model (with auto-detection if needed)1504 model_, effective_response_format = _get_bound_model(request)1505 messages = request.messages1506 if request.system_message:1507 messages = [request.system_message, *messages]15081509 output = model_.invoke(messages)1510 if name:1511 output.name = name15121513 # Handle model output to get messages and structured_response1514 handled_output = _handle_model_output(output, effective_response_format)1515 messages_list = handled_output["messages"]1516 structured_response = handled_output.get("structured_response")15171518 return ModelResponse(1519 result=messages_list,1520 structured_response=structured_response,1521 )15221523 def model_node(state: AgentState[Any], runtime: Runtime[ContextT]) -> list[Command[Any]]:1524 """Sync model request handler with sequential middleware processing."""1525 messages = _patch_invalid_tool_calls(state["messages"])1526 request = ModelRequest(1527 model=model,1528 tools=default_tools,1529 system_message=system_message,1530 response_format=initial_response_format,1531 messages=messages,1532 tool_choice=None,1533 state=state,1534 runtime=runtime,1535 )15361537 has_structured_output = initial_response_format is not None1538 if wrap_model_call_handler is None:1539 model_response = _execute_model_sync(request)1540 return _build_commands(1541 model_response,1542 has_structured_output=has_structured_output,1543 repaired_messages=messages if messages != state["messages"] else None,1544 )15451546 result = wrap_model_call_handler(request, _execute_model_sync)1547 return _build_commands(1548 result.model_response,1549 result.commands,1550 has_structured_output=has_structured_output,1551 repaired_messages=messages if messages != state["messages"] else None,1552 )15531554 async def _execute_model_async(request: ModelRequest[ContextT]) -> ModelResponse:1555 """Execute model asynchronously and return response.15561557 This is the core async model execution logic wrapped by `wrap_model_call`1558 handlers.15591560 Raises any exceptions that occur during model invocation.1561 """1562 # Get the bound model (with auto-detection if needed)1563 model_, effective_response_format = _get_bound_model(request)1564 messages = request.messages1565 if request.system_message:1566 messages = [request.system_message, *messages]15671568 output = await model_.ainvoke(messages)1569 if name:1570 output.name = name15711572 # Handle model output to get messages and structured_response1573 handled_output = _handle_model_output(output, effective_response_format)1574 messages_list = handled_output["messages"]1575 structured_response = handled_output.get("structured_response")15761577 return ModelResponse(1578 result=messages_list,1579 structured_response=structured_response,1580 )15811582 async def amodel_node(state: AgentState[Any], runtime: Runtime[ContextT]) -> list[Command[Any]]:1583 """Async model request handler with sequential middleware processing."""1584 messages = _patch_invalid_tool_calls(state["messages"])1585 request = ModelRequest(1586 model=model,1587 tools=default_tools,1588 system_message=system_message,1589 response_format=initial_response_format,1590 messages=messages,1591 tool_choice=None,1592 state=state,1593 runtime=runtime,1594 )15951596 has_structured_output = initial_response_format is not None1597 if awrap_model_call_handler is None:1598 model_response = await _execute_model_async(request)1599 return _build_commands(1600 model_response,1601 has_structured_output=has_structured_output,1602 repaired_messages=messages if messages != state["messages"] else None,1603 )16041605 result = await awrap_model_call_handler(request, _execute_model_async)1606 return _build_commands(1607 result.model_response,1608 result.commands,1609 has_structured_output=has_structured_output,1610 repaired_messages=messages if messages != state["messages"] else None,1611 )16121613 # Use sync or async based on model capabilities1614 graph.add_node("model", RunnableCallable(model_node, amodel_node, trace=False))16151616 # Only add tools node if we have tools1617 if tool_node is not None:1618 graph.add_node("tools", tool_node)16191620 # Add middleware nodes1621 for m in middleware:1622 if (1623 m.__class__.before_agent is not AgentMiddleware.before_agent1624 or m.__class__.abefore_agent is not AgentMiddleware.abefore_agent1625 ):1626 # Use RunnableCallable to support both sync and async1627 # Pass None for sync if not overridden to avoid signature conflicts1628 sync_before_agent = (1629 m.before_agent1630 if m.__class__.before_agent is not AgentMiddleware.before_agent1631 else None1632 )1633 async_before_agent = (1634 m.abefore_agent1635 if m.__class__.abefore_agent is not AgentMiddleware.abefore_agent1636 else None1637 )1638 before_agent_node = RunnableCallable(sync_before_agent, async_before_agent, trace=False)1639 graph.add_node(1640 f"{m.name}.before_agent",1641 before_agent_node,1642 input_schema=resolved_state_schema,1643 trace_policy=_node_trace_policy(m.trace_policy),1644 )16451646 if (1647 m.__class__.before_model is not AgentMiddleware.before_model1648 or m.__class__.abefore_model is not AgentMiddleware.abefore_model1649 ):1650 # Use RunnableCallable to support both sync and async1651 # Pass None for sync if not overridden to avoid signature conflicts1652 sync_before = (1653 m.before_model1654 if m.__class__.before_model is not AgentMiddleware.before_model1655 else None1656 )1657 async_before = (1658 m.abefore_model1659 if m.__class__.abefore_model is not AgentMiddleware.abefore_model1660 else None1661 )1662 before_node = RunnableCallable(sync_before, async_before, trace=False)1663 graph.add_node(1664 f"{m.name}.before_model",1665 before_node,1666 input_schema=resolved_state_schema,1667 trace_policy=_node_trace_policy(m.trace_policy),1668 )16691670 if (1671 m.__class__.after_model is not AgentMiddleware.after_model1672 or m.__class__.aafter_model is not AgentMiddleware.aafter_model1673 ):1674 # Use RunnableCallable to support both sync and async1675 # Pass None for sync if not overridden to avoid signature conflicts1676 sync_after = (1677 m.after_model1678 if m.__class__.after_model is not AgentMiddleware.after_model1679 else None1680 )1681 async_after = (1682 m.aafter_model1683 if m.__class__.aafter_model is not AgentMiddleware.aafter_model1684 else None1685 )1686 after_node = RunnableCallable(sync_after, async_after, trace=False)1687 graph.add_node(1688 f"{m.name}.after_model",1689 after_node,1690 input_schema=resolved_state_schema,1691 trace_policy=_node_trace_policy(m.trace_policy),1692 )16931694 if (1695 m.__class__.after_agent is not AgentMiddleware.after_agent1696 or m.__class__.aafter_agent is not AgentMiddleware.aafter_agent1697 ):1698 # Use RunnableCallable to support both sync and async1699 # Pass None for sync if not overridden to avoid signature conflicts1700 sync_after_agent = (1701 m.after_agent1702 if m.__class__.after_agent is not AgentMiddleware.after_agent1703 else None1704 )1705 async_after_agent = (1706 m.aafter_agent1707 if m.__class__.aafter_agent is not AgentMiddleware.aafter_agent1708 else None1709 )1710 after_agent_node = RunnableCallable(sync_after_agent, async_after_agent, trace=False)1711 graph.add_node(1712 f"{m.name}.after_agent",1713 after_agent_node,1714 input_schema=resolved_state_schema,1715 trace_policy=_node_trace_policy(m.trace_policy),1716 )17171718 # Determine the entry node (runs once at start): before_agent -> before_model -> model1719 if middleware_w_before_agent:1720 entry_node = f"{middleware_w_before_agent[0].name}.before_agent"1721 elif middleware_w_before_model:1722 entry_node = f"{middleware_w_before_model[0].name}.before_model"1723 else:1724 entry_node = "model"17251726 # Determine the loop entry node (beginning of agent loop, excludes before_agent)1727 # This is where tools will loop back to for the next iteration1728 if middleware_w_before_model:1729 loop_entry_node = f"{middleware_w_before_model[0].name}.before_model"1730 else:1731 loop_entry_node = "model"17321733 # Determine the loop exit node (end of each iteration, can run multiple times)1734 # This is after_model or model, but NOT after_agent1735 if middleware_w_after_model:1736 loop_exit_node = f"{middleware_w_after_model[0].name}.after_model"1737 else:1738 loop_exit_node = "model"17391740 # Determine the exit node (runs once at end): after_agent or END1741 if middleware_w_after_agent:1742 exit_node = f"{middleware_w_after_agent[-1].name}.after_agent"1743 else:1744 exit_node = END17451746 graph.add_edge(START, entry_node)1747 # add conditional edges only if tools exist1748 if tool_node is not None:1749 # Only include exit_node in destinations if any tool has return_direct=True1750 # or if there are structured output tools1751 tools_to_model_destinations = [loop_entry_node]1752 if (1753 any(tool.return_direct for tool in tool_node.tools_by_name.values())1754 or structured_output_tools1755 ):1756 tools_to_model_destinations.append(exit_node)17571758 graph.add_conditional_edges(1759 "tools",1760 RunnableCallable(1761 _make_tools_to_model_edge(1762 tool_node=tool_node,1763 model_destination=loop_entry_node,1764 structured_output_tools=structured_output_tools,1765 end_destination=exit_node,1766 ),1767 trace=False,1768 ),1769 tools_to_model_destinations,1770 )17711772 # Include loop_entry_node when middleware can inject synthetic tool1773 # messages, or when structured output or after-model hooks can reroute there.1774 model_to_tools_destinations = ["tools", exit_node]1775 if response_format or loop_exit_node != "model" or middleware_w_wrap_model_call:1776 model_to_tools_destinations.append(loop_entry_node)17771778 graph.add_conditional_edges(1779 loop_exit_node,1780 RunnableCallable(1781 _make_model_to_tools_edge(1782 model_destination=loop_entry_node,1783 structured_output_tools=structured_output_tools,1784 end_destination=exit_node,1785 ),1786 trace=False,1787 ),1788 model_to_tools_destinations,1789 )1790 elif len(structured_output_tools) > 0:1791 graph.add_conditional_edges(1792 loop_exit_node,1793 RunnableCallable(1794 _make_model_to_model_edge(1795 model_destination=loop_entry_node,1796 end_destination=exit_node,1797 ),1798 trace=False,1799 ),1800 [loop_entry_node, exit_node],1801 )1802 elif loop_exit_node == "model":1803 # If no tools and no after_model, go directly to exit_node1804 graph.add_edge(loop_exit_node, exit_node)1805 # No tools but we have after_model - connect after_model to exit_node1806 else:1807 _add_middleware_edge(1808 graph,1809 name=f"{middleware_w_after_model[0].name}.after_model",1810 default_destination=exit_node,1811 model_destination=loop_entry_node,1812 end_destination=exit_node,1813 can_jump_to=_get_can_jump_to(middleware_w_after_model[0], "after_model"),1814 )18151816 # Add before_agent middleware edges1817 if middleware_w_before_agent:1818 for m1, m2 in itertools.pairwise(middleware_w_before_agent):1819 _add_middleware_edge(1820 graph,1821 name=f"{m1.name}.before_agent",1822 default_destination=f"{m2.name}.before_agent",1823 model_destination=loop_entry_node,1824 end_destination=exit_node,1825 can_jump_to=_get_can_jump_to(m1, "before_agent"),1826 )1827 # Connect last before_agent to loop_entry_node (before_model or model)1828 _add_middleware_edge(1829 graph,1830 name=f"{middleware_w_before_agent[-1].name}.before_agent",1831 default_destination=loop_entry_node,1832 model_destination=loop_entry_node,1833 end_destination=exit_node,1834 can_jump_to=_get_can_jump_to(middleware_w_before_agent[-1], "before_agent"),1835 )18361837 # Add before_model middleware edges1838 if middleware_w_before_model:1839 for m1, m2 in itertools.pairwise(middleware_w_before_model):1840 _add_middleware_edge(1841 graph,1842 name=f"{m1.name}.before_model",1843 default_destination=f"{m2.name}.before_model",1844 model_destination=loop_entry_node,1845 end_destination=exit_node,1846 can_jump_to=_get_can_jump_to(m1, "before_model"),1847 )1848 # Go directly to model after the last before_model1849 _add_middleware_edge(1850 graph,1851 name=f"{middleware_w_before_model[-1].name}.before_model",1852 default_destination="model",1853 model_destination=loop_entry_node,1854 end_destination=exit_node,1855 can_jump_to=_get_can_jump_to(middleware_w_before_model[-1], "before_model"),1856 )18571858 # Add after_model middleware edges1859 if middleware_w_after_model:1860 graph.add_edge("model", f"{middleware_w_after_model[-1].name}.after_model")1861 for idx in range(len(middleware_w_after_model) - 1, 0, -1):1862 m1 = middleware_w_after_model[idx]1863 m2 = middleware_w_after_model[idx - 1]1864 _add_middleware_edge(1865 graph,1866 name=f"{m1.name}.after_model",1867 default_destination=f"{m2.name}.after_model",1868 model_destination=loop_entry_node,1869 end_destination=exit_node,1870 can_jump_to=_get_can_jump_to(m1, "after_model"),1871 )1872 # Note: Connection from after_model to after_agent/END is handled above1873 # in the conditional edges section18741875 # Add after_agent middleware edges1876 if middleware_w_after_agent:1877 # Chain after_agent middleware (runs once at the very end, before END)1878 for idx in range(len(middleware_w_after_agent) - 1, 0, -1):1879 m1 = middleware_w_after_agent[idx]1880 m2 = middleware_w_after_agent[idx - 1]1881 _add_middleware_edge(1882 graph,1883 name=f"{m1.name}.after_agent",1884 default_destination=f"{m2.name}.after_agent",1885 model_destination=loop_entry_node,1886 end_destination=exit_node,1887 can_jump_to=_get_can_jump_to(m1, "after_agent"),1888 )18891890 # Connect the last after_agent to END1891 _add_middleware_edge(1892 graph,1893 name=f"{middleware_w_after_agent[0].name}.after_agent",1894 default_destination=END,1895 model_destination=loop_entry_node,1896 end_destination=exit_node,1897 can_jump_to=_get_can_jump_to(middleware_w_after_agent[0], "after_agent"),1898 )18991900 # Set recursion limit to 9_9991901 # https://github.com/langchain-ai/langgraph/issues/73131902 config: RunnableConfig = {"recursion_limit": 9_999}1903 config["metadata"] = {"ls_integration": "langchain_create_agent"}1904 if name:1905 config["metadata"]["lc_agent_name"] = name19061907 middleware_transformers = [t for m in middleware for t in getattr(m, "transformers", ())]19081909 return graph.compile(1910 checkpointer=checkpointer,1911 store=store,1912 interrupt_before=interrupt_before,1913 interrupt_after=interrupt_after,1914 debug=debug,1915 name=name,1916 cache=cache,1917 transformers=_dedupe_transformers(1918 [1919 ToolCallTransformer,1920 SubagentTransformer,1921 *middleware_transformers,1922 *(transformers or ()),1923 ]1924 ),1925 ).with_config(config)192619271928def _dedupe_transformers(1929 factories: Iterable[TransformerFactory],1930) -> list[TransformerFactory]:1931 """Order-preserving de-dup of transformer factories, by identity.19321933 `AgentMiddleware.transformers` accepts any scope-aware callable, and1934 callables aren't required to be hashable (e.g. a dataclass-based factory1935 with `__hash__ = None`), so this can't use a `set`/`dict` keyed on the1936 factories themselves. Combining several middleware that each declare the1937 same shared transformer class (e.g. `InternalCallTransformer`) would1938 otherwise register it once per middleware.19391940 Args:1941 factories: Transformer factories to de-dup, in registration order.19421943 Returns:1944 The same factories with exact repeats (by `is`) removed, order kept.1945 """1946 seen_ids: set[int] = set()1947 deduped: list[TransformerFactory] = []1948 for factory in factories:1949 if id(factory) not in seen_ids:1950 seen_ids.add(id(factory))1951 deduped.append(factory)1952 return deduped195319541955def _resolve_jump(1956 jump_to: JumpTo | None,1957 *,1958 model_destination: str,1959 end_destination: str,1960) -> str | None:1961 if jump_to == "model":1962 return model_destination1963 if jump_to == "end":1964 return end_destination1965 if jump_to == "tools":1966 return "tools"1967 return None196819691970def _fetch_last_ai_and_tool_messages(1971 messages: list[AnyMessage],1972) -> tuple[AIMessage | None, list[ToolMessage]]:1973 """Return the last AI message and any subsequent tool messages.19741975 Args:1976 messages: List of messages to search through.19771978 Returns:1979 A tuple of (last_ai_message, tool_messages). If no AIMessage is found,1980 returns (None, []). Callers must handle the None case appropriately.1981 """1982 for i in range(len(messages) - 1, -1, -1):1983 if isinstance(messages[i], AIMessage):1984 last_ai_message = cast("AIMessage", messages[i])1985 tool_messages = [m for m in messages[i + 1 :] if isinstance(m, ToolMessage)]1986 return last_ai_message, tool_messages19871988 return None, []198919901991def _make_model_to_tools_edge(1992 *,1993 model_destination: str,1994 structured_output_tools: dict[str, OutputToolBinding[Any]],1995 end_destination: str,1996) -> Callable[[dict[str, Any]], str | list[Send] | None]:1997 def model_to_tools(1998 state: dict[str, Any],1999 ) -> str | list[Send] | None:2000 # 1. If there's an explicit jump_to in the state, use it
Same data, no extra tab — call code_get_file + code_get_findings over MCP from Claude/Cursor/Copilot.
Generated by searchcode.com · powered by code_get_file + code_get_findings