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

langchain_agentx/tools/agent/tool.py

@@ -0,0 +1,256 @@
+"""
+tools/agent/tool.py — AgentRuntimeTool 生命周期编排
+
+职责：AgentRuntimeTool normalize/validate/check_permissions/invoke/present 五钩子实现，
+      不承载底层执行逻辑（执行委托给 SubagentOrchestrator）。
+在整体链路中的位置：主 Loop ToolNode → LangChainAdapter → ToolExecutorPipeline → AgentRuntimeTool
+                    → SubagentOrchestrator.invoke_subagent()
+CC 对照：src/tools/AgentTool/AgentTool.tsx call() 方法
+当前裁剪范围：v1 三种 mode 同步/异步路径；on_progress 由 orchestrator 内部处理；
+      ``cwd`` 展开与 workspace 校验见 ``cwd_resolution.apply_agent_cwd_to_data``。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Literal
+
+from langchain_agentx.loop.subagent.orchestrator import SubagentOrchestrator
+from langchain_agentx.tool_runtime.base import RuntimeTool
+from langchain_agentx.tool_runtime.models import (
+    AuthorizationDecision,
+    ToolExecutionContext,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+
+from .builtin_subagent_loader import DefaultSubagentRegistryProvider
+from .cwd_resolution import apply_agent_cwd_to_data
+from .limits import MAX_AGENT_DEPTH, MAX_OUTPUT_CHARS
+from .models import AgentToolInput, AgentToolOutput
+from .prompt import TOOL_NAME, get_prompt
+from .registry.registry import SubagentRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class AgentRuntimeTool(RuntimeTool):
+    """子 Agent 委派工具。
+
+    mode 参数（构造时由编排层传入）：
+        "plain"      — 默认同步；run_in_background=True 时异步
+        "fork"       — 继承父会话历史；is_fork_enabled=True 时 forceAsync
+        "coordinate" — worker 由 is_coordinator=True 强制异步
+
+    registry 参数：
+        SubagentRegistry 实例，由编排层填充可用能力原语。
+        None 时使用 DefaultSubagentRegistryProvider：按 LANGCHAIN_AGENTX_BUILTIN_* 装入内置类型。
+
+    CC 对照：AgentTool.tsx 类定义与 buildTool() 注册项
+    """
+
+    name: str = TOOL_NAME
+    input_model = AgentToolInput
+    output_model = AgentToolOutput
+    is_destructive: bool = False
+    is_concurrency_safe: bool = True
+    max_result_size_chars: int = MAX_OUTPUT_CHARS
+
+    def __init__(
+        self,
+        mode: Literal["plain", "fork", "coordinate"] = "plain",
+        registry: SubagentRegistry | None = None,
+        *,
+        policy: Any | None = None,
+        state_bridge: Any | None = None,
+    ) -> None:
+        super().__init__(policy=policy, state_bridge=state_bridge)
+        self._mode = mode
+        self._registry = registry if registry is not None else DefaultSubagentRegistryProvider.get()
+        self._orchestrator = SubagentOrchestrator(mode=mode)
+
+    @property
+    def description(self) -> str:
+        """动态生成工具描述（包含当前注册表中所有能力原语）。"""
+        return get_prompt(self._registry.list_all())
+
+    # ── 生命周期钩子 ──────────────────────────────────────────────────────
+
+    def normalize_input(
+        self,
+        raw: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> dict[str, Any]:
+        """输入归一化：subagent_type 默认 general-purpose，去首尾空白。
+        CC 对照：AgentTool.tsx call() 参数解构时的默认值赋值。
+        """
+        data = dict(raw)
+        data["subagent_type"] = (data.get("subagent_type") or "general-purpose").strip()
+        if isinstance(data.get("prompt"), str):
+            data["prompt"] = data["prompt"].strip()
+        if isinstance(data.get("description"), str):
+            data["description"] = data["description"].strip()
+        if isinstance(data.get("cwd"), str):
+            data["cwd"] = data["cwd"].strip() or None
+        return data
+
+    def validate_input(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> ValidationResult:
+        """语义校验（模型可修复错误，不涉及权限）。
+        CC 对照：AgentTool.tsx call() 开头的参数合法性检查。
+        """
+        from pydantic import ValidationError
+        try:
+            inp = AgentToolInput.model_validate(data)
+        except ValidationError as exc:
+            return ValidationResult(ok=False, message=str(exc))
+
+        if not inp.prompt.strip():
+            return ValidationResult(ok=False, message="prompt 不能为空。")
+        if not inp.description.strip():
+            return ValidationResult(ok=False, message="description 不能为空。")
+        if inp.isolation not in {"none", "worktree"}:
+            return ValidationResult(ok=False, message="isolation 仅支持 none/worktree。")
+
+        cwd_vr = apply_agent_cwd_to_data(data, ctx)
+        if cwd_vr is not None:
+            return cwd_vr
+
+        # subagent_type 不在 registry → 语义错误（不是权限拒绝）
+        subagent_type = inp.subagent_type or "general-purpose"
+        try:
+            self._registry.get(subagent_type)
+        except KeyError:
+            available = sorted(c.name for c in self._registry.list_all())
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"subagent_type '{subagent_type}' 不可用。"
+                    f"当前已注册类型：{available}。"
+                ),
+            )
+        return ValidationResult(ok=True)
+
+    def check_permissions(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> AuthorizationDecision:
+        """权限检查：嵌套深度 + PolicyEngine 兜底。
+        CC 对照：AgentTool.tsx getDenyRuleForAgent() / filterDeniedAgents()。
+        """
+        current_depth = ctx.agent_depth
+        if current_depth >= MAX_AGENT_DEPTH:
+            return AuthorizationDecision(
+                behavior="deny",
+                message=(
+                    f"Agent nesting depth exceeded: {current_depth} >= {MAX_AGENT_DEPTH}."
+                ),
+            )
+        return super().check_permissions(data, ctx)
+
+    def _resolve_subagent_model(
+        self,
+        *,
+        inp: AgentToolInput,
+        subagent_config: Any,
+        ctx: ToolExecutionContext,
+    ) -> Any | None:
+        """解析子 Agent 模型：显式入参 > 配置默认 > 父 ctx.model（SSOT）。
+        已由 RuntimeContextFactory.derive() 取代，保留作兼容适配层。
+        """
+        if inp.model:
+            return inp.model
+        default_model = getattr(subagent_config, "default_model", None)
+        if default_model:
+            return default_model
+        return ctx.model
+
+    def invoke(self, data: dict[str, Any], ctx: ToolExecutionContext) -> AgentToolOutput:
+        """执行子 Agent：委托给 SubagentOrchestrator.invoke_subagent()。
+        CC 对照：AgentTool.tsx call() 中 runAgent() / registerAsyncAgent() 分支。
+        """
+        cwd_vr = apply_agent_cwd_to_data(data, ctx)
+        if cwd_vr is not None:
+            return AgentToolOutput(
+                status="error",
+                content="",
+                agent_id="",
+                total_steps=0,
+                error_message=cwd_vr.message or "cwd 校验失败",
+            )
+        inp = AgentToolInput.model_validate(data)
+        subagent_type = inp.subagent_type or "general-purpose"
+        subagent_config = self._registry.get(subagent_type)
+        return self._orchestrator.invoke_subagent(inp=inp, ctx=ctx, subagent_config=subagent_config)
+
+    def present(
+        self,
+        data: dict[str, Any],
+        result: Any,
+        ctx: ToolExecutionContext,
+    ) -> ToolResultEnvelope:
+        """结果封装为 ToolResultEnvelope。
+        CC 对照：AgentTool.tsx syncOutputSchema 的结果格式化。
+        """
+        inp = AgentToolInput.model_validate(data)
+        out = result if isinstance(result, AgentToolOutput) else AgentToolOutput.model_validate(result)
+
+        if out.status == "async_launched":
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=self.name,
+                summary=f"Agent({inp.subagent_type}) launched in background",
+                payload=(
+                    f"task_id={out.task_id}\n"
+                    f"output_file={out.output_file}\n"
+                    "Use task notifications or Read tool on output_file for details."
+                ),
+                meta={
+                    "agent_id": out.agent_id,
+                    "task_id": out.task_id,
+                    "output_file": out.output_file,
+                    "subagent_type": inp.subagent_type,
+                    "mode": self._mode,
+                },
+            )
+        if out.status == "completed":
+            # 空内容兜底：父模型收到空 ToolMessage 容易直接模板收场。
+            # CC 对照：mapToolResultToToolResultBlockParam 中 contentOrMarker 逻辑。
+            content = out.content or "(Subagent completed but returned no output.)"
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=self.name,
+                summary=f"Agent({inp.subagent_type}): {inp.description}",
+                payload=content,
+                meta={
+                    "agent_id": out.agent_id,
+                    "total_steps": out.total_steps,
+                    "terminal_reason": out.terminal_reason,
+                    "subagent_type": inp.subagent_type,
+                    "mode": self._mode,
+                    "child_run_id": out.child_run_id,
+                },
+            )
+        if out.status == "error":
+            return ToolResultEnvelope(
+                status="error",
+                tool_name=self.name,
+                summary=f"Agent({inp.subagent_type}) failed",
+                payload=out.error_message or "Subagent execution failed",
+                meta={"agent_id": out.agent_id, "mode": self._mode},
+            )
+        return ToolResultEnvelope(
+            status="error",
+            tool_name=self.name,
+            summary=f"Agent({inp.subagent_type}) interrupted",
+            payload=out.content or "Subagent execution interrupted",
+            meta={
+                "agent_id": out.agent_id,
+                "terminal_reason": out.terminal_reason,
+                "mode": self._mode,
+            },
+        )

langchain_agentx/tools/bash/__init__.py

@@ -0,0 +1,9 @@
+"""
+tools/bash — BashRuntimeTool 包
+
+BashRuntimeTool 是工具体系 P4 工具，支持 Shell 命令执行、后台任务、cwd 持久化。
+"""
+
+from .tool import BashRuntimeTool
+
+__all__ = ["BashRuntimeTool"]