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

langchain_agentx/tools/agent/models.py

@@ -0,0 +1,85 @@
+"""
+tools/agent/models.py — AgentRuntimeTool 输入输出模型
+
+职责：定义 Agent 工具对模型暴露的输入/输出 schema，不承载执行逻辑。
+在整体链路中的位置：ToolExecutorPipeline 的 schema 校验层；invoke() 与 present() 的数据契约。
+CC 对照：src/tools/AgentTool/AgentTool.tsx 的 inputSchema / outputSchema（Zod）。
+当前裁剪范围：v1 实现同步输出与异步输出模型；异步执行链路留给 v2。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class AgentToolInput(BaseModel):
+    """Agent 工具输入参数。"""
+
+    prompt: str = Field(..., description="The task for the agent to perform")
+    description: str = Field(
+        ...,
+        description="A short (3-5 word) description of the task",
+    )
+    subagent_type: str | None = Field(
+        default=None,
+        description=(
+            "The type of specialized agent to use for this task. "
+            "If omitted, defaults to 'general-purpose'."
+        ),
+    )
+    model: Any | None = Field(
+        default=None,
+        description="Optional model override for the subagent.",
+    )
+    run_in_background: bool = Field(
+        default=False,
+        description="If true, run subagent in background mode.",
+    )
+    isolation: Literal["none", "worktree"] = Field(
+        default="none",
+        description=(
+            'Execution isolation mode for subagent. When "worktree", a temporary '
+            "directory is created; if `cwd` is also set, the effective process cwd "
+            "uses `cwd` first (CC: cwd ?? worktreePath)."
+        ),
+    )
+    cwd: str | None = Field(
+        default=None,
+        description=(
+            "Optional working directory override for subagent. "
+            "Relative paths are resolved against workspace_root; "
+            "validate_input normalizes to an absolute path when workspace_root is set."
+        ),
+    )
+    fork_from_parent: bool = Field(
+        default=False,
+        description="If true, inherit parent message history when creating subagent context.",
+    )
+
+
+class AgentToolOutput(BaseModel):
+    """同步执行输出。"""
+
+    status: Literal["completed", "error", "interrupted", "async_launched"]
+    content: str = ""
+    agent_id: str = ""
+    total_steps: int = 0
+    terminal_reason: str | None = None
+    error_message: str | None = None
+    task_id: str | None = None
+    output_file: str | None = None
+    child_run_id: str | None = None  # 子会话 trace session_id
+
+
+class AgentToolAsyncOutput(BaseModel):
+    """异步执行输出（v2 预留）。"""
+
+    status: Literal["async_launched"]
+    agent_id: str
+    task_id: str
+    output_file: str
+    description: str
+    prompt: str
+    can_read_output_file: bool = True

langchain_agentx/tools/agent/prompt.py

@@ -0,0 +1,120 @@
+"""
+tools/agent/prompt.py — Agent 工具描述生成
+
+职责：按当前可用 subagent 类型动态生成给模型看的工具描述。
+在整体链路中的位置：AgentRuntimeTool.description 属性调用 get_prompt()。
+CC 对照：src/tools/AgentTool/prompt.ts 的 getPrompt()/formatAgentLine()。
+当前裁剪范围：v3 对齐 CC 主提示词核心段落，并按本工程能力做最小差异收敛。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .registry.config import SubagentConfig
+
+TOOL_NAME = "Agent"
+LEGACY_TOOL_NAME = "agent"
+
+
+def format_agent_line(config: "SubagentConfig") -> str:
+    """格式化单个 subagent 条目。CC 对照：formatAgentLine()，含 whenToUse 字段。"""
+    when_to_use = config.when_to_use or config.description
+    return f"- {config.name}: {when_to_use} (Tools: {config.tools_description})"
+
+
+def get_prompt(available_agents: list["SubagentConfig"]) -> str:
+    """生成 Agent 工具完整描述。"""
+    agent_lines = "\n".join(format_agent_line(cfg) for cfg in available_agents) or "- None"
+    return (
+        "Launch a new agent to handle complex, multi-step tasks autonomously.\n\n"
+        "The Agent tool launches specialized agents that can handle focused work.\n"
+        "Each subagent type has different strengths and tool access.\n\n"
+        "Available agent types and their tools:\n"
+        f"{agent_lines}\n\n"
+        "When using Agent, pass subagent_type to select a specialist.\n"
+        "If subagent_type is omitted, general-purpose is used.\n\n"
+        "When NOT to use Agent:\n"
+        "- If you need to read one known file, call Read directly.\n"
+        "- If you only need 1-2 quick searches in nearby files, use Glob/Grep directly.\n"
+        "- If the task is a single-step edit you can do immediately, do it directly.\n\n"
+        "Usage notes:\n"
+        "- Always include a short description (3-5 words).\n"
+        "- The subagent result is not automatically shown to the user; summarize it yourself.\n"
+        "- If user asks for parallel subagents, emit multiple Agent tool calls in one message.\n"
+        "- Use run_in_background=true only for genuinely independent work.\n"
+        "- For foreground runs, wait for the subagent result before continuing.\n"
+        "- You can set isolation='worktree' to run in a temporary git worktree.\n"
+        "- You can set fork_from_parent=true to inherit parent context (fork style).\n"
+        "- If cwd is provided, it must point to a safe workspace path.\n"
+        "- Do not invent background subagent results before completion notifications arrive.\n\n"
+        "Prompt writing guidance:\n"
+        "- Brief the subagent like a new teammate: goal, context, constraints, and done criteria.\n"
+        "- For research tasks, provide the question and scope, not rigid step scripts.\n"
+        "- For implementation tasks, include concrete files/symbols and expected changes.\n"
+    )
+
+
+DESCRIPTION = get_prompt([])
+
+# CC 对照：EXPLORE_AGENT_MIN_QUERIES（exploreAgent.ts）
+_EXPLORE_MIN_QUERIES = 3
+_DEFAULT_SEARCH_TOOLS = "Glob, Grep, and Bash"
+
+
+def build_agent_guidance_section(
+    available_tools: list,
+    search_tools: str = _DEFAULT_SEARCH_TOOLS,
+) -> str | None:
+    """生成主 system prompt 中的 Agent 使用引导段落。
+
+    CC 对照：prompts.ts 第 374-380 行的条件性注入。
+    完全 registry 驱动：只有已注册的 agent 才会出现在引导中。
+    - 若 Explore 已注册，追加 Explore 专项引导（CC 原文）。
+    - 若其他 agent 有 when_to_use，追加通用 agent 选择引导。
+    返回 None 表示 Agent 工具不存在或无任何 when_to_use 可注入。
+    """
+    agent_tool = next(
+        (t for t in available_tools if getattr(t, "name", "") in (TOOL_NAME, LEGACY_TOOL_NAME)),
+        None,
+    )
+    if agent_tool is None:
+        return None
+    registry = getattr(agent_tool, "_registry", None)
+    if registry is None:
+        return None
+
+    registered = registry.list_all()
+    registered_names = {cfg.name for cfg in registered}
+    agents_with_guidance = [cfg for cfg in registered if cfg.when_to_use]
+
+    if not agents_with_guidance:
+        return None
+
+    parts: list[str] = []
+
+    # Explore 专项引导（CC 原文对照）
+    if "Explore" in registered_names:
+        parts.append(
+            f"For simple, directed codebase searches (e.g. for a specific file/class/function) "
+            f"use {search_tools} directly.\n"
+            f"For broader codebase exploration and deep research, use the {TOOL_NAME} tool with "
+            f"subagent_type=Explore. This is slower than using {search_tools} directly, so use "
+            f"this only when a simple, directed search proves to be insufficient or when your task "
+            f"will clearly require more than {_EXPLORE_MIN_QUERIES} queries."
+        )
+
+    # 其余有 when_to_use 的 agent（排除 Explore，已单独处理）
+    others = [cfg for cfg in agents_with_guidance if cfg.name != "Explore"]
+    if others:
+        lines = "\n".join(f"- {cfg.name}: {cfg.when_to_use}" for cfg in others)
+        parts.append(
+            f"When delegating to a specialized agent, choose based on the task:\n{lines}"
+        )
+
+    return "\n\n".join(parts) if parts else None
+
+
+# 向后兼容别名
+build_explore_plan_guidance = build_agent_guidance_section

langchain_agentx/tools/agent/registry/__init__.py

@@ -0,0 +1,18 @@
+"""
+tools/agent/registry — 能力原语注册表
+
+职责：导出 SubagentConfig / SubagentRegistry，供工具层使用。
+在整体链路中的位置：built_in/*.py 构造配置 → registry 管理 → tool.py 消费。
+CC 对照：src/tools/AgentTool/builtInAgents.ts 的内置类型集合（扩展为可变注册表）。
+当前裁剪范围：v1 仅导出能力原语相关类型；SubagentComposition/presets 属于编排层，不在此导出。
+"""
+
+from .config import SubagentConfig
+from .registry import SubagentRegistry, get_global_registry
+
+__all__ = [
+    "SubagentConfig",
+    "SubagentRegistry",
+    "get_global_registry",
+]
+

langchain_agentx/tools/agent/registry/config.py

@@ -0,0 +1,29 @@
+"""
+tools/agent/registry/config.py — SubagentConfig 数据结构
+
+职责：描述单个 subagent 类型的稳定配置，不承载注册与组合逻辑。
+在整体链路中的位置：built_in/*.py 构造配置 → registry/composition/tool 消费。
+CC 对照：src/tools/AgentTool/loadAgentsDir.ts 的 AgentDefinition（简化版）。
+当前裁剪范围：v1 仅支持内置类型配置与工具过滤策略注入。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class SubagentConfig:
+    """单个 subagent 类型完整描述。"""
+
+    name: str
+    description: str
+    system_prompt_factory: Callable[[], str]
+    tool_filter: Callable[[list], list] | None = None
+    tools_description: str = "All tools"
+    default_max_steps: int | None = None
+    default_model: str | None = None
+    allow_async: bool = True
+    tags: set[str] = field(default_factory=set)
+    when_to_use: str | None = None  # CC 对照：BuiltInAgentDefinition.whenToUse

langchain_agentx/tools/agent/registry/registry.py

@@ -0,0 +1,47 @@
+"""
+tools/agent/registry/registry.py — SubagentRegistry 全局注册表
+
+职责：管理 subagent 类型注册与查询，不承载场景组合决策。
+在整体链路中的位置：built_in 模块注册；composition/tool 查询可用类型。
+CC 对照：src/tools/AgentTool/builtInAgents.ts 的内置类型集合（扩展为可变注册表）。
+当前裁剪范围：v1 提供 register/get/list/filter 基础能力。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .config import SubagentConfig
+
+
+@dataclass
+class SubagentRegistry:
+    """subagent 类型注册表。"""
+
+    _registry: dict[str, SubagentConfig] = field(default_factory=dict)
+
+    def register(self, config: SubagentConfig) -> None:
+        """注册或覆盖同名 subagent 类型。"""
+        self._registry[config.name] = config
+
+    def get(self, name: str) -> SubagentConfig:
+        """按名称获取类型配置，不存在时抛 KeyError。"""
+        return self._registry[name]
+
+    def list_all(self) -> list[SubagentConfig]:
+        """返回所有已注册类型。"""
+        return list(self._registry.values())
+
+    def filter_by_tags(self, tags: set[str]) -> list[SubagentConfig]:
+        """按标签过滤类型。"""
+        if not tags:
+            return self.list_all()
+        return [cfg for cfg in self._registry.values() if cfg.tags & tags]
+
+
+_global_registry = SubagentRegistry()
+
+
+def get_global_registry() -> SubagentRegistry:
+    """获取进程级全局注册表。"""
+    return _global_registry

langchain_agentx/tools/agent/scope.py

@@ -0,0 +1,137 @@
+"""
+tools/agent/scope.py — Tool Scope 统一裁决入口
+
+职责：统一计算 candidate/agent-filter/skill-allow/deny 之后的有效工具范围与自动批准集合。
+在整体链路中的位置：由 skill 执行路径调用，用于生成可观测的 scope 决策结果。
+CC 对照：forkedAgent.ts 中 alwaysAllowRules union + alwaysDenyRules 优先级语义。
+当前裁剪范围：v1 仅提供纯函数裁决与 explain，不直接改写 runtime 状态。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .backend import _ALWAYS_DISALLOWED_FOR_SUBAGENT
+
+if TYPE_CHECKING:
+    from .registry.config import SubagentConfig
+
+
+@dataclass(frozen=True)
+class EffectiveToolScope:
+    """工具范围裁决结果。"""
+
+    candidate_tools: frozenset[str]
+    agent_filter_result: frozenset[str]
+    skill_auto_approved: frozenset[str]
+    policy_denied: frozenset[str]
+    final_allowed: frozenset[str]
+    auto_approved: frozenset[str]
+    explain: list[str]
+
+
+def _normalize_tool_names(
+    names: list[str] | None,
+    known: frozenset[str],
+) -> tuple[frozenset[str], frozenset[str]]:
+    """将输入工具名对齐到 known 的 canonical 名称，返回 (matched, unknown)。"""
+    if not names:
+        return frozenset(), frozenset()
+
+    known_lower = {name.lower(): name for name in known}
+    matched: set[str] = set()
+    unknown: set[str] = set()
+    for name in names:
+        if not isinstance(name, str):
+            unknown.add(str(name))
+            continue
+        canonical = known_lower.get(name.strip().lower())
+        if canonical:
+            matched.add(canonical)
+        else:
+            unknown.add(name)
+    return frozenset(matched), frozenset(unknown)
+
+
+def resolve_effective_tools(
+    *,
+    candidate_tools: list,
+    agent_config: "SubagentConfig | None",
+    skill_allowed_tools: list[str] | None,
+    parent_auto_approved: set[str] | frozenset[str] | None,
+    global_deny: set[str] | frozenset[str] | None,
+) -> EffectiveToolScope:
+    """
+    统一工具范围裁决入口。
+
+    规则：
+    1) Agent filter 收窄（若 agent_config=None 则视为 identity）
+    2) Skill allowed-tools 以 union 方式追加到 auto_approved
+    3) deny 永远优先，final_allowed/auto_approved 都要剔除 deny
+    """
+    explain: list[str] = []
+    candidate = frozenset(
+        name for t in candidate_tools if (name := getattr(t, "name", ""))
+    )
+
+    # Step 1: agent filter + always disallowed
+    if agent_config is not None and agent_config.tool_filter is not None:
+        filtered_tools = agent_config.tool_filter(candidate_tools)
+    else:
+        filtered_tools = list(candidate_tools)
+    filtered_names_raw = frozenset(
+        name for t in filtered_tools if (name := getattr(t, "name", ""))
+    )
+    filtered_names = filtered_names_raw - frozenset(_ALWAYS_DISALLOWED_FOR_SUBAGENT)
+    explain.append(f"agent_filter: {len(candidate)} -> {len(filtered_names)} tools")
+    removed_by_always_disallowed = filtered_names_raw - filtered_names
+    if removed_by_always_disallowed:
+        explain.append(
+            "agent_filter: removed "
+            f"{removed_by_always_disallowed} (always_disallowed_for_subagent)"
+        )
+
+    # Step 2: skill union on auto-approved only
+    normalized_skill_allowed, unknown_skill_allowed = _normalize_tool_names(
+        skill_allowed_tools,
+        filtered_names,
+    )
+    base_approved, _ = _normalize_tool_names(
+        list(parent_auto_approved or set()),
+        filtered_names,
+    )
+    raw_parent_approved = frozenset(str(x) for x in (parent_auto_approved or set()))
+    dropped_parent_approved = raw_parent_approved - base_approved
+    if dropped_parent_approved:
+        explain.append(
+            "parent_auto_approved: dropped out-of-scope tools "
+            f"{dropped_parent_approved}"
+        )
+    auto_approved = base_approved | normalized_skill_allowed
+    if normalized_skill_allowed:
+        explain.append(
+            f"skill_auto_approved: added {normalized_skill_allowed} (from skill frontmatter)"
+        )
+    if unknown_skill_allowed:
+        explain.append(
+            f"skill_auto_approved: unknown tools ignored: {unknown_skill_allowed}"
+        )
+
+    # Step 3: deny highest priority
+    denied_normalized, _ = _normalize_tool_names(list(global_deny or set()), filtered_names)
+    final_allowed = filtered_names - denied_normalized
+    final_auto_approved = auto_approved - denied_normalized
+    if denied_normalized:
+        explain.append(f"policy_denied: removed {denied_normalized} (global deny rule)")
+
+    return EffectiveToolScope(
+        candidate_tools=candidate,
+        agent_filter_result=filtered_names,
+        skill_auto_approved=normalized_skill_allowed,
+        policy_denied=denied_normalized,
+        final_allowed=final_allowed,
+        auto_approved=final_auto_approved,
+        explain=explain,
+    )
+