langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/model/model_nodes.py

@@ -0,0 +1,661 @@
+"""
+LangChain AgentX agent 的 model 节点实现（向后兼容层）。
+
+本模块当前职责：
+  - `make_model_nodes()` — 兼容接口，内部构造 ModelNode(Runnable) 并返回 (invoke, ainvoke)
+  - `_ModelNodeBuilder` — 旧构建器（已私有化），新增功能请直接在 ModelNode 上扩展
+  - 辅助函数：`_inject_model_into_agent_tool_calls`、`_messages_for_model_invoke`、
+    `_model_response_if_context_token_blocked`（与 model_node.py 共享）
+
+核心实现在 model_node.py → ModelNode(Runnable)，本模块仅为向后兼容的薄封装。
+"""
+
+from __future__ import annotations
+
+import copy
+import logging
+from typing import Any, Callable, Dict, List, Tuple
+
+from langchain.agents.middleware.types import AgentState, ContextT
+from langchain.agents.structured_output import ResponseFormat
+from langchain_core.messages import AIMessage
+from langchain_core.runnables.config import RunnableConfig
+from langgraph.types import Command
+from langgraph.runtime import Runtime
+
+from .model_node import ModelNode
+from ..context.settings import CompactionSettings, get_active_compaction_settings
+from ..exit.exit_logic import (
+    MAX_OUTPUT_TOKENS_RECOVERY_LIMIT,
+    RECOVERABLE_TERMINAL_REASONS,
+    determine_should_end,
+    extract_finish_reason,
+)
+from ..exit.reason_codes import (
+    TERMINAL_REASON_BLOCKING_LIMIT,
+    TERMINAL_REASON_MAX_TOKENS,
+    TRANSITION_WITHHOLD_RECOVERY_EXHAUSTED,
+    TRANSITION_WITHHOLD_RECOVERY_RETRY,
+)
+from .retry_bridge import build_retry_event_commands
+from .retrier import ModelCallRetrier, RetryContext
+from .tool_and_model_binding import get_bound_model, handle_model_output
+from .tool_transcript_guard import repair_messages_for_llm_invoke
+
+
+def _synthetic_api_error_model_response(exc: Exception, name: str | None) -> Any:
+    """invoke/ainvoke 最终失败时合成 AIMessage，供 loop_controller CC §5.7 优先级 4 识别。"""
+    from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+    meta = {
+        "finish_reason": "error",
+        "langchain_agentx_api_error": True,
+        "error": {
+            "type": type(exc).__name__,
+            "message": str(exc),
+        },
+    }
+    ai = AIMessage(content=f"[LLM request failed] {exc}", response_metadata=meta)
+    if name:
+        ai.name = name
+    return _ModelResponse(result=[ai], structured_response=None)
+
+
+logger = logging.getLogger(__name__)
+
+
+def _inject_model_into_agent_tool_calls(messages: list[Any], model: Any) -> None:
+    """在模型输出阶段为 Agent 工具调用补齐 model/tool_call_id 入参。"""
+    if not isinstance(model, str):
+        return
+    for msg in messages:
+        tool_calls = getattr(msg, "tool_calls", None)
+        if not isinstance(tool_calls, list):
+            continue
+        for tc in tool_calls:
+            if not isinstance(tc, dict) or tc.get("name") != "Agent":
+                continue
+            args = tc.get("args")
+            if not isinstance(args, dict):
+                continue
+            if not args.get("model"):
+                args["model"] = model
+            # 透传 LLM 原生 tool_call.id，供 Runtime 层建立 parent_tool_call_id 关联。
+            call_id = tc.get("id")
+            if isinstance(call_id, str) and call_id and not args.get("tool_call_id"):
+                args["tool_call_id"] = call_id
+
+
+def _messages_for_model_invoke(req: Any) -> list[Any]:
+    """组装本次 LLM 调用使用的消息列表；可选在 invoke 前做 tool 管线修复（见 `tool_transcript_guard`）。"""
+    messages = list(req.messages or [])
+    s = get_active_compaction_settings()
+    if getattr(s, "enable_tool_transcript_repair_before_llm", True):
+        messages, stats = repair_messages_for_llm_invoke(messages)
+        if stats.get("repaired"):
+            logger.debug("tool_transcript_guard applied | %s", stats)
+    if req.system_message:
+        return [req.system_message, *messages]
+    return messages
+
+
+def _model_response_if_context_token_blocked(
+    *,
+    state_messages: List[Any],
+    name: str | None,
+    initial_response_format: ResponseFormat[Any] | None,
+    structured_output_tools: Dict[str, Any],
+    compaction_settings: CompactionSettings | None,
+) -> Any | None:
+    """若主上下文启发式已超过 `CompactionSettings` 顶线，返回合成 `ModelResponse`，否则 None。"""
+    from langchain_agentx.loop.context.blocking_guard import CompactionBlockingGuard
+    from langchain_agentx.loop.context.types import ContextCompactionContext
+    from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+    s = compaction_settings or get_active_compaction_settings()
+    if not s.enable_main_model_context_token_block:
+        return None
+    guard = CompactionBlockingGuard(settings=s)
+    est = guard.estimate_messages_tokens(state_messages)
+    if not guard.should_block(ContextCompactionContext(), estimated_tokens=est):
+        return None
+    tw = guard.calculate_token_warning_state(state_messages)
+    blocked_ai = AIMessage(
+        content=(
+            "[Stopped before LLM call: estimated conversation tokens "
+            f"({tw.estimated_tokens}) reached or exceeded the configured "
+            f"context ceiling ({tw.block_main_model_threshold_tokens}).]"
+        ),
+        response_metadata={
+            "finish_reason": "stop",
+            "langchain_agentx_terminal_reason": TERMINAL_REASON_BLOCKING_LIMIT,
+        },
+    )
+    if name:
+        blocked_ai.name = name
+    handled = handle_model_output(
+        blocked_ai,
+        initial_response_format,
+        structured_output_tools,
+    )
+    return _ModelResponse(
+        result=handled["messages"],
+        structured_response=handled.get("structured_response"),
+    )
+
+
+class _ModelNodeBuilder:
+    """同步/异步 model 节点构建器。"""
+
+    def __init__(
+        self,
+        *,
+        model: Any,
+        default_tools: List[Any],
+        system_message: Any,
+        initial_response_format: ResponseFormat[Any] | None,
+        max_steps: int | None,
+        max_turns: int | None,
+        max_withhold_retries: int,
+        name: str | None,
+        structured_output_tools: Dict[str, Any],
+        tool_strategy_for_setup: Any,
+        retrier: ModelCallRetrier | None,
+        tool_node: Any,
+        dynamic_tool_error_template: str,
+        fallback_model: Any | None,
+        llm_callback_handler: Any | None,
+        compaction_settings: CompactionSettings | None,
+        max_output_tokens_cap: int | None,
+    ) -> None:
+        self._model = model
+        self._default_tools = default_tools
+        self._system_message = system_message
+        self._initial_response_format = initial_response_format
+        self._max_steps = max_steps
+        self._max_turns = max_turns
+        self._max_withhold_retries = max_withhold_retries
+        self._name = name
+        self._structured_output_tools = structured_output_tools
+        self._tool_strategy_for_setup = tool_strategy_for_setup
+        self._retrier = retrier
+        self._tool_node = tool_node
+        self._dynamic_tool_error_template = dynamic_tool_error_template
+        self._fallback_model = fallback_model
+        self._llm_callback_handler = llm_callback_handler
+        self._dynamic_sections: list[Any] = []
+        self._base_prompt: str | None = None
+        self._override_prompt: str | None = None
+        self._append_prompt: str | None = None
+        self._has_volatile_sections: bool = False
+        self._compaction_settings = compaction_settings
+        self._max_output_tokens_cap = max_output_tokens_cap
+
+    def build_sync(
+        self,
+    ) -> Callable[[AgentState[Any], Runtime[ContextT]], List[Command[Any]]]:
+        def model_node(
+            state: AgentState[Any],
+            runtime: Runtime[ContextT],
+            config: RunnableConfig | None = None,
+        ) -> List[Command[Any]]:
+            request = self._build_request(state, runtime)
+            model_response, retry_event_commands = self._run_sync_with_retries(
+                request,
+                state,
+                config=config,
+            )
+            return self._build_commands_from_response(
+                state=state,
+                model_response=model_response,
+                retry_event_commands=retry_event_commands,
+                mode="sync",
+            )
+
+        return model_node
+
+    def build_async(
+        self,
+    ) -> Callable[[AgentState[Any], Runtime[ContextT]], Any]:
+        async def amodel_node(
+            state: AgentState[Any],
+            runtime: Runtime[ContextT],
+            config: RunnableConfig | None = None,
+        ) -> List[Command[Any]]:
+            request = self._build_request(state, runtime)
+            model_response, retry_event_commands = await self._run_async_with_retries(
+                request,
+                state,
+                config=config,
+            )
+            return self._build_commands_from_response(
+                state=state,
+                model_response=model_response,
+                retry_event_commands=retry_event_commands,
+                mode="async",
+            )
+
+        return amodel_node
+
+    def _build_request(self, state: AgentState[Any], runtime: Runtime[ContextT]) -> Any:
+        from langchain.agents.middleware.types import ModelRequest as _ModelRequest
+
+        model_settings: Dict[str, Any] = {}
+        if state.get("max_output_tokens_override") is not None:
+            requested_override = int(state["max_output_tokens_override"])
+            cap = self._max_output_tokens_cap
+            if cap is not None:
+                requested_override = min(requested_override, int(cap))
+            model_settings["max_tokens"] = requested_override
+
+        system_message = self._system_message
+        if self._has_volatile_sections:
+            from ..prompt.builder import build_effective_system_prompt
+            from langchain_core.messages import SystemMessage as _SystemMessage
+            section_cache: dict[str, Any] = state.get("section_cache") or {}
+            effective = build_effective_system_prompt(
+                system_prompt=self._base_prompt,
+                override_system_prompt=self._override_prompt,
+                append_system_prompt=self._append_prompt,
+                dynamic_sections=self._dynamic_sections,
+                section_cache=section_cache,
+            )
+            system_message = _SystemMessage(content=effective) if effective is not None else None
+
+        return _ModelRequest(
+            model=self._model,
+            tools=self._default_tools,
+            system_message=system_message,
+            response_format=self._initial_response_format,
+            messages=state["messages"],
+            tool_choice=None,
+            state=state,
+            runtime=runtime,
+            model_settings=model_settings,
+        )
+
+    def _invoke_bound_sync(self, req: Any, *, config: RunnableConfig | None = None) -> Any:
+        from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+        model_, effective_response_format = get_bound_model(
+            request=req,
+            structured_output_tools=self._structured_output_tools,
+            initial_response_format=self._initial_response_format,
+            tool_strategy_for_setup=self._tool_strategy_for_setup,
+            tool_node=self._tool_node,
+            wrap_tool_call_wrapper=None,
+            awrap_tool_call_wrapper=None,
+            dynamic_tool_error_template=self._dynamic_tool_error_template,
+        )
+        model_ = self._bind_llm_callback_handler(model_, config)
+        messages = _messages_for_model_invoke(req)
+        output = model_.invoke(messages, config=config)
+        if self._name:
+            output.name = self._name
+        handled_output = handle_model_output(
+            output=output,
+            effective_response_format=effective_response_format,
+            structured_output_tools=self._structured_output_tools,
+        )
+        messages_list = handled_output["messages"]
+        _inject_model_into_agent_tool_calls(messages_list, req.model)
+        return _ModelResponse(
+            result=messages_list,
+            structured_response=handled_output.get("structured_response"),
+        )
+
+    async def _invoke_bound_async(
+        self,
+        req: Any,
+        *,
+        config: RunnableConfig | None = None,
+    ) -> Any:
+        from langchain.agents.middleware.types import ModelResponse as _ModelResponse
+
+        model_, effective_response_format = get_bound_model(
+            request=req,
+            structured_output_tools=self._structured_output_tools,
+            initial_response_format=self._initial_response_format,
+            tool_strategy_for_setup=self._tool_strategy_for_setup,
+            tool_node=self._tool_node,
+            wrap_tool_call_wrapper=None,
+            awrap_tool_call_wrapper=None,
+            dynamic_tool_error_template=self._dynamic_tool_error_template,
+        )
+        model_ = self._bind_llm_callback_handler(model_, config)
+        messages = _messages_for_model_invoke(req)
+        output = await model_.ainvoke(messages, config=config)
+        if self._name:
+            output.name = self._name
+        handled_output = handle_model_output(
+            output=output,
+            effective_response_format=effective_response_format,
+            structured_output_tools=self._structured_output_tools,
+        )
+        messages_list = handled_output["messages"]
+        _inject_model_into_agent_tool_calls(messages_list, req.model)
+        return _ModelResponse(
+            result=messages_list,
+            structured_response=handled_output.get("structured_response"),
+        )
+
+    def _bind_llm_callback_handler(self, model: Any, config: RunnableConfig | None) -> Any:
+        if self._llm_callback_handler is None:
+            return model
+        callbacks: list[Any] = []
+        if isinstance(config, dict):
+            configured_callbacks = config.get("callbacks")
+            if isinstance(configured_callbacks, list):
+                callbacks.extend(configured_callbacks)
+            elif configured_callbacks is not None:
+                manager_handlers = getattr(configured_callbacks, "handlers", None)
+                if isinstance(manager_handlers, list):
+                    callbacks.extend(manager_handlers)
+        if self._llm_callback_handler not in callbacks:
+            callbacks.append(self._llm_callback_handler)
+        return model.with_config({"callbacks": callbacks})
+
+    def _run_sync_with_retries(
+        self,
+        request: Any,
+        state: AgentState[Any],
+        *,
+        config: RunnableConfig | None = None,
+    ) -> tuple[Any, list[Command[Any]]]:
+        synth = _model_response_if_context_token_blocked(
+            state_messages=state["messages"],
+            name=self._name,
+            initial_response_format=self._initial_response_format,
+            structured_output_tools=self._structured_output_tools,
+            compaction_settings=self._compaction_settings,
+        )
+        if synth is not None:
+            return synth, []
+        retry_event_commands: list[Command[Any]] = []
+        try:
+            if self._retrier is None:
+                return self._invoke_bound_sync(request, config=config), retry_event_commands
+            retry_ctx = RetryContext(
+                scope="background" if state.get("retry_scope") == "background" else "foreground"
+            )
+            retry_result = self._retrier.invoke(
+                lambda: self._invoke_bound_sync(request, config=config),
+                context=retry_ctx,
+            )
+            retry_event_commands = build_retry_event_commands(retry_result.events)
+            return retry_result.value, retry_event_commands
+        except Exception as primary_exc:
+            if self._fallback_model is None:
+                return _synthetic_api_error_model_response(primary_exc, self._name), retry_event_commands
+            logger.warning(
+                "Primary model invoke failed; retrying once with fallback_model",
+                exc_info=True,
+            )
+            req_fb = copy.copy(request)
+            req_fb.model = self._fallback_model
+            try:
+                if self._retrier is None:
+                    return self._invoke_bound_sync(req_fb, config=config), retry_event_commands
+                fb_result = self._retrier.invoke(
+                    lambda: self._invoke_bound_sync(req_fb, config=config),
+                    context=retry_ctx,
+                )
+                retry_event_commands.extend(build_retry_event_commands(fb_result.events))
+                return fb_result.value, retry_event_commands
+            except Exception as fb_exc:
+                return _synthetic_api_error_model_response(fb_exc, self._name), retry_event_commands
+
+    async def _run_async_with_retries(
+        self,
+        request: Any,
+        state: AgentState[Any],
+        *,
+        config: RunnableConfig | None = None,
+    ) -> tuple[Any, list[Command[Any]]]:
+        synth = _model_response_if_context_token_blocked(
+            state_messages=state["messages"],
+            name=self._name,
+            initial_response_format=self._initial_response_format,
+            structured_output_tools=self._structured_output_tools,
+            compaction_settings=self._compaction_settings,
+        )
+        if synth is not None:
+            return synth, []
+        retry_event_commands: list[Command[Any]] = []
+        try:
+            if self._retrier is None:
+                return await self._invoke_bound_async(request, config=config), retry_event_commands
+            retry_ctx = RetryContext(
+                scope="background" if state.get("retry_scope") == "background" else "foreground"
+            )
+            retry_result = await self._retrier.ainvoke(
+                lambda: self._invoke_bound_async(request, config=config),
+                context=retry_ctx,
+            )
+            retry_event_commands = build_retry_event_commands(retry_result.events)
+            return retry_result.value, retry_event_commands
+        except Exception as primary_exc:
+            if self._fallback_model is None:
+                return _synthetic_api_error_model_response(primary_exc, self._name), retry_event_commands
+            logger.warning(
+                "Primary model ainvoke failed; retrying once with fallback_model",
+                exc_info=True,
+            )
+            req_fb = copy.copy(request)
+            req_fb.model = self._fallback_model
+            try:
+                if self._retrier is None:
+                    return await self._invoke_bound_async(req_fb, config=config), retry_event_commands
+                fb_result = await self._retrier.ainvoke(
+                    lambda: self._invoke_bound_async(req_fb, config=config),
+                    context=retry_ctx,
+                )
+                retry_event_commands.extend(build_retry_event_commands(fb_result.events))
+                return fb_result.value, retry_event_commands
+            except Exception as fb_exc:
+                return _synthetic_api_error_model_response(fb_exc, self._name), retry_event_commands
+
+    def _build_commands_from_response(
+        self,
+        *,
+        state: AgentState[Any],
+        model_response: Any,
+        retry_event_commands: list[Command[Any]],
+        mode: str,
+    ) -> List[Command[Any]]:
+        last_ai_message = self._find_last_ai_message(model_response.result)
+        should_end, terminal_reason = determine_should_end(
+            state, last_ai_message, self._max_steps, self._max_turns
+        )
+        finish_reason = extract_finish_reason(last_ai_message)
+        self._log_stop_if_needed(
+            should_end=should_end,
+            terminal_reason=terminal_reason,
+            mode=mode,
+            step=state.get("step", 0) + 1,
+            finish_reason=finish_reason,
+        )
+        finish_reasons = self._append_finish_reason(state, finish_reason)
+        recovery_update = self._resolve_withhold_recovery_update(
+            state=state,
+            should_end=should_end,
+            terminal_reason=terminal_reason,
+            finish_reason=finish_reason,
+        )
+        state_update: Dict[str, Any] = {
+            "step": state.get("step", 0) + 1,
+            "should_end": recovery_update["should_end"],
+            "finish_reason": finish_reason,
+            "terminal_reason": recovery_update["terminal_reason"],
+            "withheld_error": recovery_update["withheld_error"],
+            "withhold_retry_count": recovery_update["withhold_retry_count"],
+            "max_output_tokens_override": recovery_update["max_output_tokens_override"],
+            "max_output_tokens_recovery_count": recovery_update["max_output_tokens_recovery_count"],
+            "transition": recovery_update["transition"],
+            "finish_reasons": finish_reasons,
+        }
+        base_state: Dict[str, Any] = {"messages": model_response.result}
+        if model_response.structured_response is not None:
+            base_state["structured_response"] = model_response.structured_response
+            state_update["structured_response"] = model_response.structured_response
+        return [*retry_event_commands, Command(update=base_state), Command(update=state_update)]
+
+    def _find_last_ai_message(self, messages: list[Any]) -> AIMessage | None:
+        for msg in reversed(messages):
+            if isinstance(msg, AIMessage):
+                return msg
+        return None
+
+    def _log_stop_if_needed(
+        self,
+        *,
+        should_end: bool,
+        terminal_reason: str | None,
+        mode: str,
+        step: int,
+        finish_reason: str | None,
+    ) -> None:
+        if not should_end:
+            return
+        logger.info(
+            "LangChain-AgentX agent stopping (%s) | terminal_reason=%s, step=%s, finish_reason=%s",
+            mode,
+            terminal_reason,
+            step,
+            finish_reason,
+        )
+
+    def _append_finish_reason(
+        self,
+        state: AgentState[Any],
+        finish_reason: str | None,
+    ) -> list[str]:
+        finish_reasons = list(state.get("finish_reasons", []))
+        if finish_reason:
+            finish_reasons.append(finish_reason)
+        return finish_reasons
+
+    def _resolve_withhold_recovery_update(
+        self,
+        *,
+        state: AgentState[Any],
+        should_end: bool,
+        terminal_reason: str | None,
+        finish_reason: str | None,
+    ) -> Dict[str, Any]:
+        withheld_error = state.get("withheld_error")
+        withhold_retry_count = int(state.get("withhold_retry_count", 0) or 0)
+        max_output_tokens_override = state.get("max_output_tokens_override")
+        max_output_tokens_recovery_count = int(state.get("max_output_tokens_recovery_count", 0) or 0)
+        can_default_withhold_retry = withhold_retry_count < self._max_withhold_retries
+        can_max_tokens_recovery_retry = (
+            terminal_reason == TERMINAL_REASON_MAX_TOKENS
+            and max_output_tokens_override is not None
+            and max_output_tokens_recovery_count < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT
+        )
+        if should_end and terminal_reason in RECOVERABLE_TERMINAL_REASONS and (
+            can_default_withhold_retry or can_max_tokens_recovery_retry
+        ):
+            withheld_error = {"reason": terminal_reason, "finish_reason": finish_reason}
+            if can_default_withhold_retry:
+                withhold_retry_count += 1
+            return {
+                "should_end": False,
+                "terminal_reason": None,
+                "withheld_error": withheld_error,
+                "withhold_retry_count": withhold_retry_count,
+                "max_output_tokens_override": max_output_tokens_override,
+                "max_output_tokens_recovery_count": max_output_tokens_recovery_count,
+                "transition": {
+                    "reason": TRANSITION_WITHHOLD_RECOVERY_RETRY,
+                    "error_reason": withheld_error["reason"],
+                    "attempt": withhold_retry_count,
+                },
+            }
+        if should_end and terminal_reason in RECOVERABLE_TERMINAL_REASONS:
+            return {
+                "should_end": should_end,
+                "terminal_reason": terminal_reason,
+                "withheld_error": None,
+                "withhold_retry_count": withhold_retry_count,
+                "max_output_tokens_override": max_output_tokens_override,
+                "max_output_tokens_recovery_count": max_output_tokens_recovery_count,
+                "transition": {
+                    "reason": TRANSITION_WITHHOLD_RECOVERY_EXHAUSTED,
+                    "error_reason": terminal_reason,
+                    "attempt": withhold_retry_count,
+                },
+            }
+        if terminal_reason != TERMINAL_REASON_MAX_TOKENS:
+            max_output_tokens_override = None
+            max_output_tokens_recovery_count = 0
+        if not should_end:
+            withhold_retry_count = 0
+        return {
+            "should_end": should_end,
+            "terminal_reason": terminal_reason,
+            "withheld_error": None,
+            "withhold_retry_count": withhold_retry_count,
+            "max_output_tokens_override": max_output_tokens_override,
+            "max_output_tokens_recovery_count": max_output_tokens_recovery_count,
+            "transition": None,
+        }
+
+
+def make_model_nodes(
+    *,
+    model: Any,
+    default_tools: List[Any],
+    system_message: Any,
+    initial_response_format: ResponseFormat[Any] | None,
+    max_steps: int | None,
+    max_turns: int | None,
+    max_withhold_retries: int = 1,
+    name: str | None,
+    structured_output_tools: Dict[str, Any],
+    tool_strategy_for_setup: Any,
+    retrier: ModelCallRetrier | None,
+    tool_node: Any,
+    dynamic_tool_error_template: str,
+    fallback_model: Any | None = None,
+    llm_callback_handler: Any | None = None,
+    dynamic_sections: List[Any] | None = None,
+    base_prompt: str | None = None,
+    override_prompt: str | None = None,
+    append_prompt: str | None = None,
+    compaction_settings: CompactionSettings | None = None,
+    max_output_tokens_cap: int | None = None,
+) -> Tuple[Callable[..., Any], Callable[..., Any]]:
+    """根据传入配置构造 sync/async model 节点函数。
+
+    当前使用 ModelNode(Runnable) 内部实现，保证 on_chat_model_stream 事件可透传。
+    _ModelNodeBuilder 保留做兼容，新增功能请直接在 ModelNode 上扩展。
+    """
+    node = ModelNode(
+        model=model,
+        default_tools=default_tools,
+        system_message=system_message,
+        initial_response_format=initial_response_format,
+        max_steps=max_steps,
+        max_turns=max_turns,
+        max_withhold_retries=max_withhold_retries,
+        name=name,
+        structured_output_tools=structured_output_tools,
+        tool_strategy_for_setup=tool_strategy_for_setup,
+        retrier=retrier,
+        tool_node=tool_node,
+        dynamic_tool_error_template=dynamic_tool_error_template,
+        fallback_model=fallback_model,
+        llm_callback_handler=llm_callback_handler,
+        compaction_settings=compaction_settings,
+        max_output_tokens_cap=max_output_tokens_cap,
+        dynamic_sections=dynamic_sections,
+        base_prompt=base_prompt,
+        override_prompt=override_prompt,
+        append_prompt=append_prompt,
+    )
+    return node.invoke, node.ainvoke
+
+
+__all__ = ["make_model_nodes"]
+

langchain_agentx/loop/model/orphan_tool_results.py

@@ -0,0 +1,38 @@
+"""
+流式中断 / 工具中断时 orphan tool_use 的 synthetic tool_result 占位（CC §5.3 / §5.6）。
+
+与 `ToolNode` 执行路径解耦：完整注入应在 **tools 节点后**或 **model 节点**检测 abort 后调用。
+当前仅提供契约与扩展点，避免与现有 LangGraph `Send` 并行语义冲突。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import ToolMessage
+
+
+def synthetic_tool_messages_for_orphan_tool_calls(
+    *,
+    pending_tool_calls: list[dict[str, Any]],
+    content_template: str = "[Tool call aborted or stream interrupted; synthetic result.]",
+) -> list[ToolMessage]:
+    """为仍挂在最后一条 AIMessage 上、但未收到 ToolMessage 的 tool_call 生成占位结果。
+
+    供流式中断、abort、synthetic 兜底路径组装 `messages` 时使用；**不**代替 ToolNode 的真实执行。
+    """
+    out: list[ToolMessage] = []
+    for tc in pending_tool_calls:
+        tid = tc.get("id") or ""
+        name = str(tc.get("name") or "unknown_tool")
+        out.append(
+            ToolMessage(
+                content=content_template,
+                tool_call_id=tid,
+                name=name,
+            )
+        )
+    return out
+
+
+__all__ = ["synthetic_tool_messages_for_orphan_tool_calls"]