langchain-agentx-python 2.1.4__py3-none-any.whl → 2.1.6__py3-none-any.whl

langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "2.1.4"
+__version__ = "2.1.6"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

langchain_agentx/loop/__init__.py

@@ -35,13 +35,14 @@ for chunk in agent.stream({"messages": [{"role": "user", "content": "Hello"}]}):
 from .graph.factory import (
     create_loop_agent,
 )
-from .loop_abort import LoopAbortSignal
+from .loop_abort import LoopAbortSignal, raise_if_cancel_requested
 from .config import build_agent_config
 
 __all__ = [
     # 主要接口
     "create_loop_agent",
     "LoopAbortSignal",
+    "raise_if_cancel_requested",
     # 配置助手
     "build_agent_config",
 ]

langchain_agentx/loop/graph/builtin_loop_control.py

@@ -1,12 +1,14 @@
 """
 内置 loop 控制：捕获 ``LoopAbortSignal``，写入 ``abort_terminal_reason``（及工具侧合成 ToolMessage）。
 
-始终由 ``create_loop_agent`` 注入到 ``wrap_model_call`` / ``wrap_tool_call`` 链的最外层，
-用户 middleware 在内层抛出 ``LoopAbortSignal`` 即可，无需手写 Command。
+由 ModelNode / RuntimeToolsNode 在 invoke 路径最外层调用；handler 前读
+``raise_if_cancel_requested``（Doc-35 P1 / D-ABORT-1）。用户侧抛出 ``LoopAbortSignal``
+即可，无需手写 Command。
 """
 
 from __future__ import annotations
 
+import asyncio
 import copy
 import logging
 from typing import Any
@@ -21,7 +23,7 @@ from ..exit.reason_codes import (
     TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
     TERMINAL_REASON_HOOK_STOPPED,
 )
-from ..loop_abort import LoopAbortSignal
+from ..loop_abort import LoopAbortSignal, raise_if_cancel_requested
 from ..model.orphan_tool_results import synthetic_tool_messages_for_orphan_tool_calls
 from ...tool_runtime.classifier_denial_limit import ClassifierDenialLimitAbort
 from ...tool_runtime.permission_context import clear_auto_approved_window
@@ -50,46 +52,51 @@ def _session_store_from_request(request: Any) -> Any | None:
     return None
 
 
+def _model_abort_response(sig: LoopAbortSignal) -> ExtendedModelResponse:
+    ai = AIMessage(
+        content=_abort_model_content(sig.terminal_reason, sig.detail),
+        response_metadata={"finish_reason": "stop"},
+    )
+    return ExtendedModelResponse(
+        model_response=ModelResponse(result=[ai], structured_response=None),
+        command=Command(update={"abort_terminal_reason": sig.terminal_reason}),
+    )
+
+
 class _LoopBuiltinModelControl:
-    """内部单例：捕获模型侧的 ``LoopAbortSignal``。"""
+    """内部单例：协作读停令 + 捕获模型侧的 ``LoopAbortSignal``。"""
 
     def wrap_model_call(self, request: Any, handler: Any) -> Any:
         clear_auto_approved_window(_session_store_from_request(request))
         try:
+            raise_if_cancel_requested(phase="model")
             return handler(request)
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="model")
+            raise
         except LoopAbortSignal as sig:
             if sig.terminal_reason not in (
                 TERMINAL_REASON_ABORTED_STREAMING,
                 TERMINAL_REASON_HOOK_STOPPED,
             ):
                 raise
-            ai = AIMessage(
-                content=_abort_model_content(sig.terminal_reason, sig.detail),
-                response_metadata={"finish_reason": "stop"},
-            )
-            return ExtendedModelResponse(
-                model_response=ModelResponse(result=[ai], structured_response=None),
-                command=Command(update={"abort_terminal_reason": sig.terminal_reason}),
-            )
+            return _model_abort_response(sig)
 
     async def awrap_model_call(self, request: Any, handler: Any) -> Any:
         clear_auto_approved_window(_session_store_from_request(request))
         try:
+            raise_if_cancel_requested(phase="model")
             return await handler(request)
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="model")
+            raise
         except LoopAbortSignal as sig:
             if sig.terminal_reason not in (
                 TERMINAL_REASON_ABORTED_STREAMING,
                 TERMINAL_REASON_HOOK_STOPPED,
             ):
                 raise
-            ai = AIMessage(
-                content=_abort_model_content(sig.terminal_reason, sig.detail),
-                response_metadata={"finish_reason": "stop"},
-            )
-            return ExtendedModelResponse(
-                model_response=ModelResponse(result=[ai], structured_response=None),
-                command=Command(update={"abort_terminal_reason": sig.terminal_reason}),
-            )
+            return _model_abort_response(sig)
 
 
 _LOOP_BUILTIN_MODEL_SINGLETON = _LoopBuiltinModelControl()
@@ -173,8 +180,12 @@ def _tool_abort_command(
 
 def builtin_sync_tool_wrapper(request: Any, handler: Any) -> Any:
     try:
+        raise_if_cancel_requested(phase="tools")
         result = handler(_with_injected_agent_tool_model(request))
         return apply_tool_message_status_to_result(result)
+    except asyncio.CancelledError:
+        raise_if_cancel_requested(phase="tools")
+        raise
     except ClassifierDenialLimitAbort as exc:
         return _tool_abort_command(
             request,
@@ -192,8 +203,12 @@ def builtin_sync_tool_wrapper(request: Any, handler: Any) -> Any:
 
 async def builtin_async_tool_wrapper(request: Any, handler: Any) -> Any:
     try:
+        raise_if_cancel_requested(phase="tools")
         result = await handler(_with_injected_agent_tool_model(request))
         return apply_tool_message_status_to_result(result)
+    except asyncio.CancelledError:
+        raise_if_cancel_requested(phase="tools")
+        raise
     except ClassifierDenialLimitAbort as exc:
         return _tool_abort_command(
             request,
@@ -209,8 +224,33 @@ async def builtin_async_tool_wrapper(request: Any, handler: Any) -> Any:
         )
 
 
+def tools_batch_abort_command(
+    tool_calls: list[dict[str, Any]],
+    *,
+    terminal_reason: str = TERMINAL_REASON_ABORTED_TOOLS,
+    content_template: str | None = None,
+) -> Command:
+    """tools 节点批次入口 abort：合成 orphan ToolMessage + abort_terminal_reason。"""
+    synth = (
+        synthetic_tool_messages_for_orphan_tool_calls(
+            pending_tool_calls=list(tool_calls),
+            reason="user_interrupted",
+            content_template=content_template,
+        )
+        if tool_calls
+        else []
+    )
+    return Command(
+        update={
+            "abort_terminal_reason": terminal_reason,
+            "messages": synth,
+        }
+    )
+
+
 __all__ = [
     "builtin_async_tool_wrapper",
     "builtin_sync_tool_wrapper",
     "get_loop_builtin_model_middleware",
+    "tools_batch_abort_command",
 ]

langchain_agentx/loop/graph/runtime_tools_node.py

@@ -9,17 +9,21 @@ loop/graph/runtime_tools_node.py — 新 tools 执行 graph bridge
 
 当前裁剪范围：
     Phase 4 readonly_parallel 由 engine 对 safe_group 受控并发；exclusive 仍串行。
+    P1：批次入口读 cancel_requested → LoopAbortSignal 单轨（D-ABORT-1）。
 """
 
 from __future__ import annotations
 
+import asyncio
 from typing import Any, MutableMapping
 
 from langchain_core.messages import AIMessage, ToolMessage
 from langchain_core.runnables import Runnable, RunnableConfig
 from langchain_core.tools import BaseTool
+from langgraph.types import Command
 
 from ...tool_runtime.adapter import LangChainAdapter
+from ...tool_runtime.classifier_denial_limit import ClassifierDenialLimitAbort
 from ...tool_runtime.execution import (
     EngineConfig,
     EnginePolicy,
@@ -29,6 +33,12 @@ from ...tool_runtime.execution import (
 )
 from ...tool_runtime.pipeline import ToolExecutorPipeline
 from ...tool_runtime.registry import RuntimeToolRegistry
+from ..exit.reason_codes import (
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
+)
+from ..loop_abort import LoopAbortSignal, raise_if_cancel_requested
+from .builtin_loop_control import tools_batch_abort_command
 
 
 class RuntimeToolsNode(Runnable):
@@ -87,35 +97,71 @@ class RuntimeToolsNode(Runnable):
         self,
         state: MutableMapping[str, Any],
         config: RunnableConfig | None,
-    ) -> dict[str, Any]:
+    ) -> dict[str, Any] | Command:
         _ai_message, tool_calls = _extract_tool_calls(state)
         if not tool_calls:
             return {}
-        batches = self._planner.plan(tool_calls)
-        records = self._engine.execute_turn(
-            batches=batches,
-            state=state,
-            config=config,
-        )
-        tool_messages = self._message_adapter.records_to_graph_messages(records)
-        return {"messages": tool_messages}
+        try:
+            raise_if_cancel_requested(phase="tools")
+            batches = self._planner.plan(tool_calls)
+            records = self._engine.execute_turn(
+                batches=batches,
+                state=state,
+                config=config,
+            )
+            tool_messages = self._message_adapter.records_to_graph_messages(records)
+            return {"messages": tool_messages}
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="tools")
+            raise
+        except ClassifierDenialLimitAbort as exc:
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
+                content_template=exc.message,
+            )
+        except LoopAbortSignal as sig:
+            if sig.terminal_reason != TERMINAL_REASON_ABORTED_TOOLS:
+                raise
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_ABORTED_TOOLS,
+            )
 
     async def _arun(
         self,
         state: MutableMapping[str, Any],
         config: RunnableConfig | None,
-    ) -> dict[str, Any]:
+    ) -> dict[str, Any] | Command:
         _ai_message, tool_calls = _extract_tool_calls(state)
         if not tool_calls:
             return {}
-        batches = self._planner.plan(tool_calls)
-        records = await self._engine.aexecute_turn(
-            batches=batches,
-            state=state,
-            config=config,
-        )
-        tool_messages = self._message_adapter.records_to_graph_messages(records)
-        return {"messages": tool_messages}
+        try:
+            raise_if_cancel_requested(phase="tools")
+            batches = self._planner.plan(tool_calls)
+            records = await self._engine.aexecute_turn(
+                batches=batches,
+                state=state,
+                config=config,
+            )
+            tool_messages = self._message_adapter.records_to_graph_messages(records)
+            return {"messages": tool_messages}
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="tools")
+            raise
+        except ClassifierDenialLimitAbort as exc:
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
+                content_template=exc.message,
+            )
+        except LoopAbortSignal as sig:
+            if sig.terminal_reason != TERMINAL_REASON_ABORTED_TOOLS:
+                raise
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_ABORTED_TOOLS,
+            )
 
 
 def _extract_tool_calls(

langchain_agentx/loop/loop_abort.py

@@ -1,19 +1,27 @@
-"""流式 / 工具 / hook 中断信号：由业务 middleware 或工具抛出，由内置 wrapper 转为 state 契约。"""
+"""流式 / 工具 / hook 中断信号：由业务 middleware 或工具抛出，由内置 wrapper 转为 state 契约。
+
+P1（Doc-35 D-ABORT-1）：``raise_if_cancel_requested`` 读 ``RunContext.cancel_requested``，
+真则抛既有 ``LoopAbortSignal``（单轨）；禁止平行 Abort 异常族。
+"""
 
 from __future__ import annotations
 
+from typing import Literal
+
 from .exit.reason_codes import (
     TERMINAL_REASON_ABORTED_STREAMING,
     TERMINAL_REASON_ABORTED_TOOLS,
     TERMINAL_REASON_HOOK_STOPPED,
 )
 
+CancelAbortPhase = Literal["model", "tools"]
+
 
 class LoopAbortSignal(Exception):
     """请求以 CC 式 abort 终局结束（写入 ``abort_terminal_reason``）。
 
     - ``aborted_streaming`` / ``hook_stopped``：在 ``wrap_model_call`` / ``awrap_model_call`` 中抛出，
-      由 ``_LoopBuiltinModelControlMiddleware`` 捕获并合成 AIMessage + Command。
+      由 ``_LoopBuiltinModelControl`` 捕获并合成 AIMessage + Command。
     - ``aborted_tools``：在工具执行或 ``wrap_tool_call`` 中抛出，由内置 tool wrapper 捕获并
       注入合成 ``ToolMessage`` + ``abort_terminal_reason``。
     """
@@ -33,4 +41,27 @@ class LoopAbortSignal(Exception):
         super().__init__(detail or terminal_reason)
 
 
-__all__ = ["LoopAbortSignal"]
+def raise_if_cancel_requested(*, phase: CancelAbortPhase) -> None:
+    """若当前 ``RunContext.cancel_requested`` 为真，抛既有 ``LoopAbortSignal``。
+
+    对齐 CC ``query.ts`` 读 ``signal.aborted``；SDK 原语为 bool（D-SEM-1），
+    退出语义仅走 ``LoopAbortSignal`` → ``builtin_loop_control``（D-ABORT-1）。
+    无 RunContext 时 no-op。
+    """
+    from .run_context import get_run_context
+
+    ctx = get_run_context()
+    if ctx is None or not ctx.cancel_requested:
+        return
+    if phase == "tools":
+        raise LoopAbortSignal(
+            TERMINAL_REASON_ABORTED_TOOLS,
+            detail="cancel_requested",
+        )
+    raise LoopAbortSignal(
+        TERMINAL_REASON_ABORTED_STREAMING,
+        detail="cancel_requested",
+    )
+
+
+__all__ = ["CancelAbortPhase", "LoopAbortSignal", "raise_if_cancel_requested"]

langchain_agentx/loop/model/model_node.py

@@ -338,55 +338,103 @@ class ModelNode(Runnable):
 
     def _run(self, state: dict, config: RunnableConfig) -> dict:
         """核心同步执行逻辑。"""
-        runtime = config.get("configurable", {}).get("__pregel_runtime")
-        request = self._build_request(state, runtime, config=config)
+        from langchain.agents.middleware.types import ExtendedModelResponse
+        from langgraph.types import Command
 
-        synth = _model_response_if_context_token_blocked(
-            state_messages=state.get("messages", []),
-            name=self._name,
-            initial_response_format=self._initial_response_format,
-            structured_output_tools=self._structured_output_tools,
-            compaction_settings=self._compaction_settings,
-            query_source=state.get("query_source")
-            if isinstance(state.get("query_source"), str)
-            else None,
+        from langchain_agentx.loop.graph.builtin_loop_control import (
+            get_loop_builtin_model_middleware,
         )
-        if synth is not None:
-            model_response = synth
+
+        runtime = config.get("configurable", {}).get("__pregel_runtime")
+        request = self._build_request(state, runtime, config=config)
+        mw = get_loop_builtin_model_middleware()
+
+        def _handler(req: Any) -> Any:
+            synth = _model_response_if_context_token_blocked(
+                state_messages=state.get("messages", []),
+                name=self._name,
+                initial_response_format=self._initial_response_format,
+                structured_output_tools=self._structured_output_tools,
+                compaction_settings=self._compaction_settings,
+                query_source=state.get("query_source")
+                if isinstance(state.get("query_source"), str)
+                else None,
+            )
+            if synth is not None:
+                return synth
+            model_response, _ = self._run_sync(req, state, config=config)
+            return model_response
+
+        wrapped = mw.wrap_model_call(request, _handler)
+        abort_reason: str | None = None
+        if isinstance(wrapped, ExtendedModelResponse):
+            model_response = wrapped.model_response
+            cmd = wrapped.command
+            if isinstance(cmd, Command) and isinstance(cmd.update, dict):
+                reason = cmd.update.get("abort_terminal_reason")
+                if isinstance(reason, str):
+                    abort_reason = reason
         else:
-            model_response, _ = self._run_sync(request, state, config=config)
+            model_response = wrapped
 
-        return self._build_state_update(
+        updates = self._build_state_update(
             state=state,
             model_response=model_response,
             mode="sync",
         )
+        if abort_reason:
+            return list(updates) + [Command(update={"abort_terminal_reason": abort_reason})]
+        return updates
 
     async def _arun(self, state: dict, config: RunnableConfig) -> dict:
         """核心异步执行逻辑。"""
-        runtime = config.get("configurable", {}).get("__pregel_runtime")
-        request = self._build_request(state, runtime, config=config)
+        from langchain.agents.middleware.types import ExtendedModelResponse
+        from langgraph.types import Command
 
-        synth = _model_response_if_context_token_blocked(
-            state_messages=state.get("messages", []),
-            name=self._name,
-            initial_response_format=self._initial_response_format,
-            structured_output_tools=self._structured_output_tools,
-            compaction_settings=self._compaction_settings,
-            query_source=state.get("query_source")
-            if isinstance(state.get("query_source"), str)
-            else None,
+        from langchain_agentx.loop.graph.builtin_loop_control import (
+            get_loop_builtin_model_middleware,
         )
-        if synth is not None:
-            model_response = synth
+
+        runtime = config.get("configurable", {}).get("__pregel_runtime")
+        request = self._build_request(state, runtime, config=config)
+        mw = get_loop_builtin_model_middleware()
+
+        async def _handler(req: Any) -> Any:
+            synth = _model_response_if_context_token_blocked(
+                state_messages=state.get("messages", []),
+                name=self._name,
+                initial_response_format=self._initial_response_format,
+                structured_output_tools=self._structured_output_tools,
+                compaction_settings=self._compaction_settings,
+                query_source=state.get("query_source")
+                if isinstance(state.get("query_source"), str)
+                else None,
+            )
+            if synth is not None:
+                return synth
+            model_response, _ = await self._arun_async(req, state, config=config)
+            return model_response
+
+        wrapped = await mw.awrap_model_call(request, _handler)
+        abort_reason: str | None = None
+        if isinstance(wrapped, ExtendedModelResponse):
+            model_response = wrapped.model_response
+            cmd = wrapped.command
+            if isinstance(cmd, Command) and isinstance(cmd.update, dict):
+                reason = cmd.update.get("abort_terminal_reason")
+                if isinstance(reason, str):
+                    abort_reason = reason
         else:
-            model_response, _ = await self._arun_async(request, state, config=config)
+            model_response = wrapped
 
-        return self._build_state_update(
+        updates = self._build_state_update(
             state=state,
             model_response=model_response,
             mode="async",
         )
+        if abort_reason:
+            return list(updates) + [Command(update={"abort_terminal_reason": abort_reason})]
+        return updates
 
     # ===== 请求构建 =====
 

langchain_agentx/loop/subagent/__init__.py

@@ -28,7 +28,10 @@ from langchain_agentx.loop.subagent.forked_runner import (
 )
 from langchain_agentx.loop.subagent.async_runner import (
     BackgroundAgentHandle,
+    BackgroundAgentLoopRequiredError,
     get_background_agent_handle,
+    kill_all_background_agents,
+    kill_background_agent,
     register_background_agent,
     run_async_agent_lifecycle,
 )
@@ -67,7 +70,10 @@ __all__ = [
     "_run_coroutine_sync",
     "register_background_agent",
     "get_background_agent_handle",
+    "kill_background_agent",
+    "kill_all_background_agents",
     "BackgroundAgentHandle",
+    "BackgroundAgentLoopRequiredError",
     "run_async_agent_lifecycle",
     "JsonlTranscriptStore",
     "SubagentTranscriptManager",