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

langchain_agentx/loop/model/tool_and_model_binding.py

@@ -0,0 +1,227 @@
+"""
+LangChain AgentX agent 的模型绑定与执行工具。
+
+本模块从 `factory.py` 中拆分出"模型调用路径"的通用逻辑：
+- 根据 response_format / 模型能力 / tools 决定如何 bind 模型（含 ProviderStrategy / ToolStrategy）
+- 统一处理模型输出（messages + optional structured_response）
+- 提供同步 / 异步模型执行的辅助函数，供 model 节点使用
+
+注意：这里不包含图路由（edges）或 OpenCode 状态字段更新，只关注"模型 I/O 层"。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple, List
+
+from langchain.agents.structured_output import (
+    AutoStrategy,
+    ProviderStrategy,
+    ProviderStrategyBinding,
+    ResponseFormat,
+    StructuredOutputError,
+    StructuredOutputValidationError,
+    ToolStrategy,
+    OutputToolBinding,
+    MultipleStructuredOutputsError,
+)
+from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.tools import BaseTool
+
+from .schema_and_format import _supports_provider_strategy, _handle_structured_output_error
+
+
+def handle_model_output(
+    output: AIMessage,
+    effective_response_format: ResponseFormat[Any] | None,
+    structured_output_tools: Dict[str, OutputToolBinding[Any]],
+) -> Dict[str, Any]:
+    """处理模型输出（含结构化输出），返回 {'messages': [...], 'structured_response': ...}."""
+    if isinstance(effective_response_format, ProviderStrategy):
+        if not output.tool_calls:
+            provider_strategy_binding = ProviderStrategyBinding.from_schema_spec(
+                effective_response_format.schema_spec
+            )
+            try:
+                structured_response = provider_strategy_binding.parse(output)
+            except Exception as exc:
+                schema_name = getattr(
+                    effective_response_format.schema_spec.schema, "__name__", "response_format"
+                )
+                validation_error = StructuredOutputValidationError(schema_name, exc, output)
+                raise validation_error from exc
+            else:
+                return {"messages": [output], "structured_response": structured_response}
+        return {"messages": [output]}
+
+    if (
+        isinstance(effective_response_format, ToolStrategy)
+        and isinstance(output, AIMessage)
+        and output.tool_calls
+    ):
+        structured_tool_calls = [
+            tc for tc in output.tool_calls if tc["name"] in structured_output_tools
+        ]
+
+        if structured_tool_calls:
+            exception: StructuredOutputError | None = None
+            if len(structured_tool_calls) > 1:
+                tool_names = [tc["name"] for tc in structured_tool_calls]
+                exception = MultipleStructuredOutputsError(tool_names, output)
+                should_retry, error_message = _handle_structured_output_error(
+                    exception, effective_response_format
+                )
+                if not should_retry:
+                    raise exception
+
+                tool_messages = [
+                    ToolMessage(
+                        content=error_message,
+                        tool_call_id=tc["id"],
+                        name=tc["name"],
+                    )
+                    for tc in structured_tool_calls
+                ]
+                return {"messages": [output, *tool_messages]}
+
+            tool_call = structured_tool_calls[0]
+            try:
+                structured_tool_binding = structured_output_tools[tool_call["name"]]
+                structured_response = structured_tool_binding.parse(tool_call["args"])
+
+                tool_message_content = (
+                    effective_response_format.tool_message_content
+                    or f"Returning structured response: {structured_response}"
+                )
+
+                return {
+                    "messages": [
+                        output,
+                        ToolMessage(
+                            content=tool_message_content,
+                            tool_call_id=tool_call["id"],
+                            name=tool_call["name"],
+                        ),
+                    ],
+                    "structured_response": structured_response,
+                }
+            except Exception as exc:
+                exception = StructuredOutputValidationError(tool_call["name"], exc, output)
+                should_retry, error_message = _handle_structured_output_error(
+                    exception, effective_response_format
+                )
+                if not should_retry:
+                    raise exception from exc
+
+                return {
+                    "messages": [
+                        output,
+                        ToolMessage(
+                            content=error_message,
+                            tool_call_id=tool_call["id"],
+                            name=tool_call["name"],
+                        ),
+                    ],
+                }
+
+    return {"messages": [output]}
+
+
+def get_bound_model(
+    *,
+    request,
+    structured_output_tools: Dict[str, OutputToolBinding[Any]],
+    initial_response_format: ResponseFormat[Any] | None,
+    tool_strategy_for_setup,
+    tool_node,
+    wrap_tool_call_wrapper,
+    awrap_tool_call_wrapper,
+    dynamic_tool_error_template: str,
+) -> Tuple[Any, ResponseFormat[Any] | None]:
+    """根据 request / response_format / tools 返回 (bound_model, effective_response_format)."""
+    has_wrap_tool_call = wrap_tool_call_wrapper or awrap_tool_call_wrapper
+
+    available_tools_by_name: Dict[str, Any] = {}
+    if tool_node:
+        available_tools_by_name = tool_node.tools_by_name.copy()
+
+    if not has_wrap_tool_call:
+        unknown_tool_names: List[str] = []
+        for t in request.tools:
+            if isinstance(t, dict):
+                continue
+            if isinstance(t, BaseTool) and t.name not in available_tools_by_name:
+                unknown_tool_names.append(t.name)
+
+        if unknown_tool_names:
+            available_tool_names = sorted(available_tools_by_name.keys())
+            msg = dynamic_tool_error_template.format(
+                unknown_tool_names=unknown_tool_names,
+                available_tool_names=available_tool_names,
+            )
+            raise ValueError(msg)
+
+    response_format: ResponseFormat[Any] | Any | None = request.response_format
+    if response_format is not None and not isinstance(
+        response_format, (AutoStrategy, ToolStrategy, ProviderStrategy)
+    ):
+        response_format = AutoStrategy(schema=response_format)
+
+    if isinstance(response_format, AutoStrategy):
+        if _supports_provider_strategy(request.model, tools=request.tools):
+            effective_response_format: ResponseFormat[Any] | None = ProviderStrategy(
+                schema=response_format.schema
+            )
+        elif response_format is initial_response_format and tool_strategy_for_setup is not None:
+            effective_response_format = tool_strategy_for_setup
+        else:
+            effective_response_format = ToolStrategy(schema=response_format.schema)
+    else:
+        effective_response_format = response_format
+
+    final_tools: List[Any] = list(request.tools)
+    if isinstance(effective_response_format, ToolStrategy):
+        structured_tools = [info.tool for info in structured_output_tools.values()]
+        final_tools.extend(structured_tools)
+
+    if isinstance(effective_response_format, ProviderStrategy):
+        kwargs = effective_response_format.to_model_kwargs()
+        return (
+            request.model.bind_tools(
+                final_tools, strict=True, **kwargs, **request.model_settings
+            ),
+            effective_response_format,
+        )
+
+    if isinstance(effective_response_format, ToolStrategy):
+        for tc in effective_response_format.schema_specs:
+            if tc.name not in structured_output_tools:
+                msg = (
+                    f"ToolStrategy specifies tool '{tc.name}' "
+                    "which wasn't declared in the original "
+                    "response format when creating the agent."
+                )
+                raise ValueError(msg)
+
+        tool_choice = "any" if structured_output_tools else request.tool_choice
+        return (
+            request.model.bind_tools(
+                final_tools, tool_choice=tool_choice, **request.model_settings
+            ),
+            effective_response_format,
+        )
+
+    if final_tools:
+        return (
+            request.model.bind_tools(
+                final_tools, tool_choice=request.tool_choice, **request.model_settings
+            ),
+            None,
+        )
+    return request.model.bind(**request.model_settings), None
+
+
+__all__ = [
+    "handle_model_output",
+    "get_bound_model",
+]
+

langchain_agentx/loop/model/tool_call_degradation_corrector.py

@@ -0,0 +1,443 @@
+"""
+工具调用退化纠偏器（Tool Call Degradation Corrector）
+====================================================
+
+目的：
+- 解决模型/网关在特定条件下，把结构化 tool_calls 退化为 `<tool_call>...</tool_call>` 文本的问题。
+- 将退化文本解析为 LangChain 可执行的结构化 `tool_calls`，从而让 Agent 继续运行而不中断。
+
+设计约束：
+- 仅作为内部能力在 LangChain-AgentX Agent 中使用，对外不导出公共接口。
+- 必须做工具白名单校验：只允许调用已注册/已注入的工具。
+
+说明：
+- 该纠偏器以"包装器"的方式工作：对外暴露 invoke/ainvoke，并把其他属性/方法透传给底层 llm。
+- stream/astream 不经过纠偏（流式分块无法整体解析），如需纠偏请使用 invoke/ainvoke。
+- DeepAgent/中间件一般以 Runnable 方式使用 model，因此 duck typing 足够。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import uuid
+from typing import Any, Dict, List, Optional, Sequence, Set
+
+from langchain.agents.structured_output import OutputToolBinding
+from langgraph.prebuilt.tool_node import ToolNode
+from langchain_core.messages import AIMessage
+
+logger = logging.getLogger(__name__)
+
+
+# <tool_call>...</tool_call> 标签格式
+_TOOL_CALL_TAG_RE = re.compile(r"<tool_call>(.*?)</tool_call>", re.DOTALL)
+
+# 行内 CALL_TOOL / TOOL_CALL 前缀格式（仅用于定位起始位置，JSON 提取由 raw_decode 完成）
+_CALL_TOOL_PREFIX_RE = re.compile(
+    r"(?:CALL_TOOL|TOOL_CALL)\s*:\s*",
+    re.DOTALL,
+)
+
+# 用于清理 content 中残留的 CALL_TOOL: {...} 文本
+# 注意：清理时使用贪婪匹配到行尾，实际 JSON 边界已由 raw_decode 确定
+_CALL_TOOL_CLEANUP_RE = re.compile(
+    r"(?:CALL_TOOL|TOOL_CALL)\s*:\s*\{[^}]*(?:\{[^}]*\}[^}]*)?\}",
+    re.DOTALL,
+)
+
+# XML 自闭合格式：<tool_name param1="val1" param2="val2" />
+# 捕获组 1 = 工具名，捕获组 2 = 属性字符串
+_XML_SELF_CLOSING_RE = re.compile(
+    r"<([A-Za-z_][A-Za-z0-9_]*)(\s[^>]*)?\s*/>",
+    re.DOTALL,
+)
+
+# XML 子元素格式：<tool_name><param>val</param>...</tool_name>
+# 捕获组 1 = 工具名，捕获组 2 = 内部内容
+_XML_ELEMENT_RE = re.compile(
+    r"<([A-Za-z_][A-Za-z0-9_]*)>(.*?)</\1>",
+    re.DOTALL,
+)
+
+# XML 属性解析：key="value" 或 key='value'
+_XML_ATTR_RE = re.compile(r"""([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')""")
+
+# XML 子元素解析：<key>value</key>
+_XML_CHILD_RE = re.compile(r"<([A-Za-z_][A-Za-z0-9_]*)>(.*?)</\1>", re.DOTALL)
+
+# <tool_code>...</tool_code> Python 代码块格式
+_TOOL_CODE_RE = re.compile(r"<tool_code>(.*?)</tool_code>", re.DOTALL)
+
+# Python 函数名（后跟 '('），用于定位调用起始位置；参数由平衡括号扫描提取
+_PY_FUNC_NAME_RE = re.compile(r"([A-Za-z_][A-Za-z0-9_]*)\s*\(")
+
+
+def _extract_json_objects_from_text(text: str) -> list[str]:
+    """
+    从任意文本中提取所有顶层 JSON 对象字符串。
+
+    使用 json.JSONDecoder.raw_decode 逐字符扫描，正确处理嵌套大括号，
+    避免正则截断嵌套 JSON 的问题（Bug 1 修复）。
+    """
+    decoder = json.JSONDecoder()
+    results: list[str] = []
+    i = 0
+    while i < len(text):
+        if text[i] != "{":
+            i += 1
+            continue
+        try:
+            obj, end = decoder.raw_decode(text, i)
+            if isinstance(obj, dict):
+                results.append(text[i:end])
+            i = end
+        except json.JSONDecodeError:
+            i += 1
+    return results
+
+
+class ToolCallDegradationCorrector:
+    """
+    包装一个 ChatModel，当检测到 `<tool_call>...</tool_call>` 退化输出时，进行纠偏。
+
+    纠偏触发条件（严格）：
+    - response.content 包含 `<tool_call>` 标签 或 `CALL_TOOL:` / `TOOL_CALL:` 前缀
+    - 且 response.tool_calls 为空 / 不存在
+
+    不支持流式纠偏（stream/astream 直接透传）。
+    """
+
+    def __init__(
+        self,
+        llm: Any,
+        allowed_tool_names: Set[str],
+    ) -> None:
+        self._llm = llm
+        self._allowed_tool_names = allowed_tool_names
+
+    # ----------------------------
+    # 属性透传（例如 llm.streaming）
+    # ----------------------------
+    @property
+    def streaming(self) -> Any:
+        return getattr(self._llm, "streaming", None)
+
+    @streaming.setter
+    def streaming(self, value: Any) -> None:
+        setattr(self._llm, "streaming", value)
+
+    def __getattr__(self, name: str) -> Any:
+        # 兜底透传：DeepAgent/中间件可能访问底层 llm 的其他方法/属性（如 bind_tools 等）
+        return getattr(self._llm, name)
+
+    def bind_tools(
+        self,
+        tools: Sequence[Any],
+        *,
+        tool_choice: str | None = None,
+        **kwargs: Any,
+    ) -> "ToolCallDegradationCorrector":
+        """
+        DeepAgent/LangChain 会在运行时调用 model.bind_tools(...) 生成"绑定工具后的模型"。
+
+        如果这里直接透传到底层 llm，会导致 wrapper 丢失（返回的是底层 llm），从而纠偏逻辑失效。
+        因此必须：
+        - 先对底层 llm 执行 bind_tools
+        - 再把返回的 bound model 重新包装为 ToolCallDegradationCorrector
+        - 同步更新 allowed_tool_names，避免新绑定工具被白名单拦截（Bug 5 修复）
+        """
+        bound = self._llm.bind_tools(tools, tool_choice=tool_choice, **kwargs)
+
+        # 从新绑定的 tools 中提取工具名，合并到现有白名单（Bug 5 修复）
+        new_names: Set[str] = set()
+        for t in tools:
+            if hasattr(t, "name") and isinstance(t.name, str):
+                new_names.add(t.name)
+            elif isinstance(t, dict) and isinstance(t.get("name"), str):
+                new_names.add(t["name"])
+
+        return ToolCallDegradationCorrector(
+            llm=bound,
+            allowed_tool_names=self._allowed_tool_names | new_names,
+        )
+
+    # ----------------------------
+    # Runnable 接口：invoke / ainvoke
+    # ----------------------------
+    def invoke(self, input: Any, **kwargs: Any) -> Any:
+        resp = self._llm.invoke(input, **kwargs)
+        return self._correct_if_needed(resp)
+
+    async def ainvoke(self, input: Any, **kwargs: Any) -> Any:
+        resp = await self._llm.ainvoke(input, **kwargs)
+        return self._correct_if_needed(resp)
+
+    # stream / astream 不经过纠偏（流式分块无法整体解析），直接透传给底层 llm。
+    # 如需纠偏，请改用 invoke / ainvoke。
+
+    # ----------------------------
+    # 核心纠偏逻辑
+    # ----------------------------
+    def _correct_if_needed(self, resp: Any) -> Any:
+        if not isinstance(resp, AIMessage):
+            return resp
+
+        tool_calls: Optional[Any] = getattr(resp, "tool_calls", None)
+        if tool_calls:
+            # 正常结构化 tool_calls，不需要纠偏
+            return resp
+
+        content = resp.content
+        if not isinstance(content, str):
+            return resp
+
+        # 支持多种退化格式，从文本中尽力解析 tool_calls
+        parsed_tool_calls = self._parse_text_tool_calls(content)
+        if not parsed_tool_calls:
+            return resp
+
+        # 清理所有退化格式残留文本
+        cleaned_content = _TOOL_CALL_TAG_RE.sub("", content)
+        cleaned_content = _CALL_TOOL_CLEANUP_RE.sub("", cleaned_content)
+        cleaned_content = _TOOL_CODE_RE.sub("", cleaned_content)
+        # XML 自闭合：只清理命中白名单的标签
+        def _remove_xml_self_closing(m: re.Match) -> str:
+            return "" if m.group(1) in self._allowed_tool_names else m.group(0)
+        cleaned_content = _XML_SELF_CLOSING_RE.sub(_remove_xml_self_closing, cleaned_content)
+        # XML 子元素：只清理命中白名单的标签
+        def _remove_xml_element(m: re.Match) -> str:
+            return "" if m.group(1) in self._allowed_tool_names else m.group(0)
+        cleaned_content = _XML_ELEMENT_RE.sub(_remove_xml_element, cleaned_content)
+        cleaned_content = cleaned_content.strip()
+
+        logger.warning(
+            "检测到工具调用退化，已纠偏为结构化 tool_calls | tools=%s",
+            [tc.get("name") for tc in parsed_tool_calls],
+        )
+
+        return self._clone_ai_message_with_tool_calls(
+            original=resp,
+            content=cleaned_content,
+            tool_calls=parsed_tool_calls,
+        )
+
+    def _parse_text_tool_calls(self, content: str) -> List[Dict[str, Any]]:
+        """
+        从 content 中解析一个或多个退化格式的工具调用。
+
+        支持格式：
+        - <tool_call>{"name": "...", "args": {...}}</tool_call>
+        - CALL_TOOL: {"name": "...", "args": {...}}  /  TOOL_CALL: {...}
+        - <tool_name param="val" />                  — XML 自闭合
+        - <tool_name><param>val</param></tool_name>  — XML 子元素
+        - <tool_code>print(tool_name(...))</tool_code> — Python 代码块
+
+        支持三类 JSON 结构：
+        - {"name": "...", "args": {...}}          — LangChain 标准结构
+        - {"name": "...", "arguments": {...}}     — OpenAI 原生格式（arguments 为 dict 或 JSON 字符串）
+        - {"name": "...", "param1": "..."}        — 扁平化参数
+        """
+        # 收集 (tool_name, tool_args) 对，最后统一去重
+        candidates: List[tuple[str, Dict[str, Any]]] = []
+
+        # 1) <tool_call>...</tool_call> 包裹的 JSON
+        for tag_content in _TOOL_CALL_TAG_RE.findall(content):
+            for raw in _extract_json_objects_from_text(tag_content.strip()):
+                parsed = self._parse_json_payload(raw)
+                if parsed:
+                    candidates.append(parsed)
+
+        # 2) CALL_TOOL: / TOOL_CALL: 前缀后的 JSON（Bug 1 修复：用 raw_decode 提取）
+        for m in _CALL_TOOL_PREFIX_RE.finditer(content):
+            after_prefix = content[m.end():]
+            objs = _extract_json_objects_from_text(after_prefix)
+            if objs:
+                parsed = self._parse_json_payload(objs[0])
+                if parsed:
+                    candidates.append(parsed)
+
+        # 3) XML 自闭合格式：<tool_name attr="val" />
+        for m in _XML_SELF_CLOSING_RE.finditer(content):
+            tool_name = m.group(1)
+            if tool_name not in self._allowed_tool_names:
+                continue
+            attrs_str = m.group(2) or ""
+            tool_args = {
+                k: v1 if v1 is not None else v2
+                for k, v1, v2 in _XML_ATTR_RE.findall(attrs_str)
+            }
+            candidates.append((tool_name, tool_args))
+
+        # 4) XML 子元素格式：<tool_name><param>val</param></tool_name>
+        #    跳过已被 <tool_call> 处理的标签，以及 tool_call / tool_code 本身
+        _skip_tags = {"tool_call", "tool_code"}
+        for m in _XML_ELEMENT_RE.finditer(content):
+            tool_name = m.group(1)
+            if tool_name in _skip_tags:
+                continue
+            if tool_name not in self._allowed_tool_names:
+                continue
+            inner = m.group(2)
+            tool_args = {k: v.strip() for k, v in _XML_CHILD_RE.findall(inner)}
+            candidates.append((tool_name, tool_args))
+
+        # 5) <tool_code>...</tool_code> Python 代码块
+        for code_block in _TOOL_CODE_RE.findall(content):
+            for m in _PY_FUNC_NAME_RE.finditer(code_block):
+                tool_name = m.group(1)
+                if tool_name not in self._allowed_tool_names:
+                    continue
+                # 平衡括号扫描，提取完整参数字符串（支持嵌套调用）
+                start = m.end()  # 指向 '(' 之后
+                depth = 1
+                i = start
+                while i < len(code_block) and depth > 0:
+                    if code_block[i] == "(":
+                        depth += 1
+                    elif code_block[i] == ")":
+                        depth -= 1
+                    i += 1
+                args_str = code_block[start:i - 1].strip()
+                tool_args = self._parse_python_kwargs(args_str)
+                candidates.append((tool_name, tool_args))
+
+        if not candidates:
+            return []
+
+        # Bug 6 修复：去重（以 tool_name + sorted args 为 key）
+        seen: Set[str] = set()
+        tool_calls: List[Dict[str, Any]] = []
+        for tool_name, tool_args in candidates:
+            if tool_name not in self._allowed_tool_names:
+                logger.warning(
+                    "退化工具调用包含未注册工具，已忽略 | tool=%s | allowed=%s",
+                    tool_name,
+                    sorted(self._allowed_tool_names),
+                )
+                continue
+            dedup_key = f"{tool_name}:{json.dumps(tool_args, sort_keys=True)}"
+            if dedup_key in seen:
+                continue
+            seen.add(dedup_key)
+            tool_calls.append(
+                {
+                    "name": tool_name,
+                    "args": tool_args,
+                    "id": f"degraded-corrected-{uuid.uuid4().hex[:12]}",
+                    "type": "tool_call",
+                }
+            )
+
+        return tool_calls
+
+    def _parse_json_payload(self, raw: str) -> tuple[str, Dict[str, Any]] | None:
+        """解析单个 JSON 字符串为 (tool_name, tool_args)，失败返回 None。"""
+        raw = raw.strip()
+        if not raw:
+            return None
+        try:
+            payload = json.loads(raw)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("解析退化工具调用 JSON 失败：%s | raw=%r", e, raw[:300])
+            return None
+        if not isinstance(payload, dict):
+            return None
+        tool_name = payload.get("name")
+        if not tool_name or not isinstance(tool_name, str):
+            return None
+        if "args" in payload and isinstance(payload.get("args"), dict):
+            tool_args = payload["args"]
+        elif "arguments" in payload:
+            raw_args = payload["arguments"]
+            if isinstance(raw_args, str):
+                try:
+                    tool_args = json.loads(raw_args)
+                except json.JSONDecodeError:
+                    logger.warning("arguments 字段不是合法 JSON：%r", raw_args[:200])
+                    return None
+            elif isinstance(raw_args, dict):
+                tool_args = raw_args
+            else:
+                tool_args = {}
+        else:
+            tool_args = {k: v for k, v in payload.items() if k != "name"}
+        return tool_name, tool_args
+
+    @staticmethod
+    def _parse_python_kwargs(args_str: str) -> Dict[str, Any]:
+        """从 Python 函数调用参数字符串中提取 keyword arguments。"""
+        result: Dict[str, Any] = {}
+        # 匹配 key="val" 或 key='val' 或 key=bare_word
+        for m in re.finditer(
+            r"""([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+))""",
+            args_str,
+        ):
+            key = m.group(1)
+            val = m.group(2) if m.group(2) is not None else (
+                m.group(3) if m.group(3) is not None else m.group(4)
+            )
+            result[key] = val
+        return result
+
+    def _clone_ai_message_with_tool_calls(
+        self,
+        *,
+        original: AIMessage,
+        content: str,
+        tool_calls: List[Dict[str, Any]],
+    ) -> AIMessage:
+        """
+        生成一个新的 AIMessage，保留原消息的元信息，替换 content/tool_calls。
+        """
+        # AIMessage 字段随 langchain_core 版本可能变化，这里尽量"保守拷贝"
+        # 只拷贝常见字段，避免传入未知字段导致构造失败。
+        kwargs: Dict[str, Any] = {}
+
+        for key in ("additional_kwargs", "response_metadata", "usage_metadata", "id", "name"):
+            if hasattr(original, key):
+                kwargs[key] = getattr(original, key)
+
+        # 如果发生退化并且我们已经成功恢复了结构化 tool_calls，
+        # 需要同步修正 finish_reason，否则上层 LangChain-AgentX Agent 会因为
+        # finish_reason="stop" 误判为结束而不去执行工具。
+        #
+        # Bug 3 修复：浅拷贝 response_metadata，避免原地修改污染 original 的元数据。
+        rm = dict(kwargs.get("response_metadata") or {})
+        rm["finish_reason"] = "tool-calls"
+        kwargs["response_metadata"] = rm
+
+        # invalid_tool_calls 也一起保留（如果存在）
+        if hasattr(original, "invalid_tool_calls"):
+            kwargs["invalid_tool_calls"] = getattr(original, "invalid_tool_calls")
+
+        return AIMessage(
+            content=content,
+            tool_calls=tool_calls,
+            **kwargs,
+        )
+
+
+def _build_allowed_tool_names_for_degradation_correction(
+    tool_node: ToolNode | None,
+    built_in_tools: list[dict[str, Any] | Any],
+    structured_output_tools: dict[str, OutputToolBinding[Any]],
+) -> Set[str]:
+    """Build tool name whitelist for ToolCallDegradationCorrector."""
+    allowed_tool_names: Set[str] = set()
+
+    # 1) Tools executed via ToolNode (client-side BaseTool / callables)
+    if tool_node:
+        allowed_tool_names.update(tool_node.tools_by_name.keys())
+
+    # 2) Provider-side tools (dict format) passed through to the LLM
+    for t in built_in_tools:
+        name_attr = t.get("name") if isinstance(t, dict) else None
+        if isinstance(name_attr, str):
+            allowed_tool_names.add(name_attr)
+
+    # 3) Structured output tools derived from response_format / AutoStrategy
+    allowed_tool_names.update(structured_output_tools.keys())
+
+    return allowed_tool_names