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

langchain_agentx/loop/runtime/subagent_execution_paths.py

@@ -0,0 +1,68 @@
+"""
+loop/runtime/subagent_execution_paths.py — 子 Agent 工作目录与 worktree 单点准备
+
+职责：
+    计算子会话的 ``effective_cwd``（供 ``run_with_cwd_override`` / ``AgentLoopConfig.cwd`` /
+    ``SubagentContext.cwd`` 同源），并在 ``isolation=worktree`` 时创建唯一临时目录。
+链路位置：
+    ``SubagentOrchestrator._derive_runtime_context`` → ``prepare`` → ``RuntimeContextFactory.derive``；
+    ``create_subagent_context(..., path_prep=...)`` 消费本结构，避免重复 ``mkdir``。
+当前裁剪范围：
+    仅 ``none`` / ``worktree``；不处理 CC ``remote`` isolation。路径展开 / 权限校验留在 Phase 2。
+CC 对照：
+    ``AgentTool.tsx`` 中 ``cwdOverridePath = cwd ?? worktreeInfo?.worktreePath``。
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_agentx.loop.runtime.context import SubagentContextOverrides
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+
+@dataclass(frozen=True)
+class PreparedSubagentPaths:
+    """``SubagentExecutionPaths.prepare`` 的输出：最终 cwd 与可选 worktree 目录。"""
+
+    effective_cwd: str
+    worktree_dir: str | None = None
+
+
+class SubagentExecutionPaths:
+    """子 Agent 路径准备（OOP 单点，禁止在 orchestrator 内堆叠 mkdir 逻辑）。"""
+
+    @staticmethod
+    def prepare(
+        *,
+        parent_ctx: Any,
+        overrides: "SubagentContextOverrides",
+    ) -> PreparedSubagentPaths:
+        """解析 ``effective_cwd``，并在 worktree 模式下创建临时目录。
+
+        顺序对齐 CC：**显式 ``overrides.cwd`` 优先于 worktree 目录**（``cwd ?? worktreePath``）。
+        """
+        parent_cwd = getattr(parent_ctx, "cwd", None)
+        parent_workspace_root = getattr(parent_ctx, "workspace_root", None) or os.getcwd()
+        parent_agent_home = getattr(parent_ctx, "agent_home", ".langchain_agentx")
+        raw = overrides.cwd
+        override_cwd = raw.strip() if isinstance(raw, str) and raw.strip() else None
+
+        if overrides.isolation == "worktree":
+            workspace_cfg = resolve_agent_workspace_config(
+                workspace_root=parent_workspace_root,
+                agent_home=parent_agent_home,
+            )
+            workspace_cfg.worktrees_dir.mkdir(parents=True, exist_ok=True)
+            worktree_dir = str(
+                workspace_cfg.worktrees_dir / f"agentx-worktree-{uuid.uuid4().hex[:12]}"
+            )
+            os.makedirs(worktree_dir, exist_ok=False)
+            effective = override_cwd or worktree_dir
+            return PreparedSubagentPaths(effective_cwd=effective, worktree_dir=worktree_dir)
+
+        base = override_cwd or parent_cwd or os.getcwd()
+        return PreparedSubagentPaths(effective_cwd=base, worktree_dir=None)

langchain_agentx/loop/subagent/__init__.py

@@ -0,0 +1,53 @@
+"""Loop Subagent 框架
+
+职责：子 Agent 执行框架的公共接口导出
+在整体链路中的位置：被 tools/agent/tool.py 调用
+CC 对照：src/agent/subagent/ 目录
+当前裁剪范围：v1 同步执行路径，stub runner
+"""
+
+from langchain_agentx.loop.subagent.context import (
+    SubagentContext,
+    SubagentResult,
+    cleanup_subagent_context,
+    create_subagent_context,
+)
+from langchain_agentx.loop.subagent.async_runner import (
+    BackgroundAgentHandle,
+    get_background_agent_handle,
+    register_background_agent,
+    run_async_agent_lifecycle,
+)
+from langchain_agentx.loop.subagent.progress import SubagentProgressEvent
+from langchain_agentx.loop.subagent.runner import (
+    BackgroundLaunchedResult,
+    _run_coroutine_sync,
+    run_subagent,
+    run_subagent_with_background_signal,
+)
+from langchain_agentx.loop.subagent.transcript import (
+    JsonlTranscriptStore,
+    SubagentTranscriptManager,
+    SubagentTranscriptStore,
+)
+from langchain_agentx.loop.subagent.graph import create_subagent_graph
+
+__all__ = [
+    "SubagentContext",
+    "SubagentResult",
+    "create_subagent_context",
+    "cleanup_subagent_context",
+    "SubagentProgressEvent",
+    "run_subagent",
+    "run_subagent_with_background_signal",
+    "BackgroundLaunchedResult",
+    "_run_coroutine_sync",
+    "register_background_agent",
+    "get_background_agent_handle",
+    "BackgroundAgentHandle",
+    "run_async_agent_lifecycle",
+    "JsonlTranscriptStore",
+    "SubagentTranscriptManager",
+    "SubagentTranscriptStore",
+    "create_subagent_graph",
+]

langchain_agentx/loop/subagent/async_runner.py

@@ -0,0 +1,215 @@
+"""
+loop/subagent/async_runner.py — 子 Agent 异步生命周期管理
+
+职责：
+  - register_background_agent()：threading 后台启动子 Agent（旧接口，供 v1 兼容）
+  - run_async_agent_lifecycle()：coordinate 模式纯 async 生命周期（计划接口，供 AgentRuntimeTool 调用）
+在整体链路中的位置：AgentRuntimeTool.invoke(is_async=True) → run_async_agent_lifecycle()
+CC 对照：agentToolUtils.ts runAsyncAgentLifecycle()；LocalAgentTask enqueueAgentNotification()
+当前裁剪范围：v1 基础版；完整 worktree 清理 / output_file 管理为 v2
+
+执行流程（run_async_agent_lifecycle）：
+  1. 构造 output_file 路径，确保父目录存在
+  2. task_runtime.update(task_id, {status: running})
+  3. 临时置 ctx.is_async=False，调用 run_subagent() 执行子图
+  4. 写 output_file（result.content）
+  5. task_runtime.mark_terminal(completed/failed)
+  异常分支：
+    CancelledError → 写 "cancelled"，mark_terminal(failed, terminal_reason="cancelled")，re-raise
+    其他 Exception → 写错误信息，mark_terminal(failed)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import threading
+import uuid
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from langchain_agentx.task_runtime.core.types import TaskScope, TaskSpec, TaskStatus, TaskType
+
+from .context import SubagentContext
+from .runner import run_subagent
+
+
+@dataclass
+class BackgroundAgentHandle:
+    task_id: str
+    agent_id: str
+    output_file: str
+    thread: threading.Thread
+
+
+_BACKGROUND_HANDLES: dict[str, BackgroundAgentHandle] = {}
+
+
+def _ensure_parent(path: str) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+
+
+def _resolve_task_runtime(ctx: Any) -> Any | None:
+    runtime = getattr(ctx, "task_runtime", None)
+    if runtime is not None:
+        return runtime
+    state = getattr(ctx, "state", {})
+    if isinstance(state, dict):
+        return state.get("task_runtime")
+    return None
+
+
+def _spawn_task_record(task_runtime: Any, ctx: SubagentContext, description: str) -> str:
+    if task_runtime is None:
+        return str(uuid.uuid4())
+    spec = TaskSpec(
+        task_type=TaskType.LOCAL_AGENT,
+        description=description,
+        input={"prompt": description, "agent_label": ctx.subagent_type},
+        scope=TaskScope(agent_id=ctx.parent_agent_id),
+    )
+    return task_runtime.spawn(spec)
+
+
+def register_background_agent(
+    *,
+    ctx: SubagentContext,
+    loader: Any,
+    model: Any | None,
+    output_dir: str,
+    description: str,
+    on_progress: Callable[[Any], None] | None = None,
+    parent_ctx: Any | None = None,
+) -> BackgroundAgentHandle:
+    """注册并启动后台子 Agent。"""
+    task_runtime = _resolve_task_runtime(parent_ctx)
+    task_id = _spawn_task_record(task_runtime, ctx, description)
+    output_file = os.path.join(output_dir, task_id, "output.txt")
+    _ensure_parent(output_file)
+
+    def _run() -> None:
+        async def _lifecycle() -> None:
+            try:
+                result = await run_subagent(
+                    ctx=ctx,
+                    loader=loader,
+                    model=model,
+                    on_progress=on_progress,
+                )
+                with open(output_file, "w", encoding="utf-8") as fp:
+                    fp.write(result.content)
+                if task_runtime is not None:
+                    status = TaskStatus.COMPLETED if result.status == "completed" else TaskStatus.FAILED
+                    task_runtime.mark_terminal(
+                        task_id,
+                        status,
+                        result.content[:500] if result.content else (result.error_message or "subagent completed"),
+                        output_file=output_file,
+                        terminal_reason=result.terminal_reason or None,
+                    )
+            except Exception as exc:
+                with open(output_file, "w", encoding="utf-8") as fp:
+                    fp.write(str(exc))
+                if task_runtime is not None:
+                    task_runtime.mark_terminal(
+                        task_id,
+                        TaskStatus.FAILED,
+                        f"Subagent background lifecycle failed: {exc}",
+                        output_file=output_file,
+                        terminal_reason="error",
+                    )
+
+        asyncio.run(_lifecycle())
+
+    thread = threading.Thread(target=_run, daemon=True, name=f"agentx-subagent-{task_id}")
+    thread.start()
+    handle = BackgroundAgentHandle(
+        task_id=task_id,
+        agent_id=ctx.agent_id,
+        output_file=output_file,
+        thread=thread,
+    )
+    _BACKGROUND_HANDLES[task_id] = handle
+    return handle
+
+
+def get_background_agent_handle(task_id: str) -> BackgroundAgentHandle | None:
+    return _BACKGROUND_HANDLES.get(task_id)
+
+
+async def run_async_agent_lifecycle(
+    task_id: str,
+    ctx: SubagentContext,
+    loader: Any,
+    task_runtime: Any,
+    output_dir: str,
+) -> None:
+    """coordinate 模式异步生命周期：后台执行子 Agent，完成后通过 task_runtime 写通知。
+
+    Args:
+        task_id: 已由调用方在 task_runtime 中注册的任务 ID
+        ctx: 子 Agent 执行上下文（is_async 应为 True）
+        tools: 工具列表
+        task_runtime: TaskRuntime 实例，用于写终态通知
+        output_dir: 输出文件根目录
+
+    执行流程：
+        1. mark_terminal(running)
+        2. run_subagent()
+        3. 写 output_file
+        4. mark_terminal(completed/failed)
+
+    CancelledError 单独捕获，写 cancelled 状态后 re-raise。
+    """
+    output_file = os.path.join(output_dir, task_id, "output.txt")
+    _ensure_parent(output_file)
+
+    if task_runtime is not None:
+        try:
+            task_runtime.update(task_id, {"status": TaskStatus.RUNNING.value})
+        except Exception:
+            pass
+
+    try:
+        # 子会话 is_async=True 时 run_subagent 会抛 RuntimeError，
+        # 此处临时置 False 走真实执行路径（lifecycle 本身已是异步上下文）
+        ctx.is_async = False
+        result = await run_subagent(ctx=ctx, loader=loader, model=None)
+
+        with open(output_file, "w", encoding="utf-8") as fp:
+            fp.write(result.content)
+
+        if task_runtime is not None:
+            status = TaskStatus.COMPLETED if result.status == "completed" else TaskStatus.FAILED
+            task_runtime.mark_terminal(
+                task_id,
+                status,
+                result.content[:500] if result.content else (result.error_message or "done"),
+                output_file=output_file,
+                terminal_reason=result.terminal_reason or None,
+            )
+
+    except asyncio.CancelledError:
+        with open(output_file, "w", encoding="utf-8") as fp:
+            fp.write("cancelled")
+        if task_runtime is not None:
+            try:
+                task_runtime.mark_terminal(
+                    task_id, TaskStatus.FAILED, "subagent cancelled",
+                    output_file=output_file, terminal_reason="cancelled",
+                )
+            except Exception:
+                pass
+        raise
+
+    except Exception as exc:
+        with open(output_file, "w", encoding="utf-8") as fp:
+            fp.write(str(exc))
+        if task_runtime is not None:
+            task_runtime.mark_terminal(
+                task_id,
+                TaskStatus.FAILED,
+                f"subagent failed: {exc}",
+                output_file=output_file,
+                terminal_reason="error",
+            )

langchain_agentx/loop/subagent/context.py

@@ -0,0 +1,209 @@
+"""Subagent Context 与 Result 数据结构
+
+职责：封装子会话的独立状态与继承自父会话的共享引用
+在整体链路中的位置：create_subagent_context() 构造 → run_subagent() 消费
+CC 对照：src/agent/subagent/context.ts SubagentContext 接口
+当前裁剪范围：v1 全量；system_prompt / is_async 字段驱动执行路径选择；
+      ``path_prep`` 与遗留 ``cwd``/worktree 自建二选一（编排层须传 ``path_prep``）；
+      fork + worktree 时可选注入 CC 等价 ``buildWorktreeNotice`` user 消息（见 ``fork_worktree_notice``）。
+"""
+
+import os
+import shutil
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from langchain_agentx.loop.runtime.subagent_execution_paths import PreparedSubagentPaths
+from langchain_agentx.loop.subagent.fork_worktree_notice import build_worktree_notice
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+
+@dataclass
+class SubagentContext:
+    """子 Agent 执行上下文
+
+    独立字段：agent_id / initial_messages / max_steps / subagent_type / agent_depth
+             system_prompt / is_async / fork_from_parent
+    共享字段：session_store / tool_registry（从父会话继承）
+    执行路径：fork_from_parent 决定消息构造；is_async 决定同步/异步路径路由
+    """
+    # 独立字段
+    agent_id: str
+    initial_messages: list[dict[str, Any]]
+    max_steps: int | None
+    subagent_type: str
+    model: Any | None = None
+    agent_depth: int = 0
+
+    # 执行路径字段（由外部注入，驱动 runner 路由决策）
+    system_prompt: str = ""       # 由 SubagentConfig.system_prompt_factory() 注入
+    fork_from_parent: bool = False  # True = fork 模式，initial_messages 含父会话历史
+    is_async: bool = False         # True = 走异步路径（coordinate/fork-async）
+
+    # 共享字段（从父会话继承）
+    session_store: Any = None  # SessionStore
+    tool_registry: Any = None  # ToolRegistry
+    tool_loader: Any = None  # ToolRuntimeLoader
+
+    # 可选字段
+    parent_agent_id: str | None = None
+    parent_run_id: str | None = None      # 父 Agent 的 trace run_id，供 TraceLifecycleCollector/Collector 建立父子链接
+    parent_tool_call_id: str | None = None  # 触发本子 Agent 的 tool_call_id
+    parent_conversation_session_id: str | None = None
+    enable_trace: bool = True
+    isolation: str = "none"
+    worktree_dir: str | None = None
+    workspace_root: str = ""
+    agent_home: str = ".langchain_agentx"
+    cwd: str | None = None
+    _file_read_state: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SubagentResult:
+    """子 Agent 执行结果"""
+    agent_id: str
+    content: str
+    status: str  # "completed" | "error" | "interrupted"
+    terminal_reason: str = ""
+    total_steps: int = 0
+    error_message: str = ""
+    output_file: str | None = None
+    child_run_id: str | None = None  # 子会话的 trace session_id，供父 run 追溯
+
+
+def create_subagent_context(
+    parent_ctx: Any,
+    task: str,
+    subagent_type: str,
+    system_prompt: str = "",
+    max_steps: int | None = None,
+    model: Any | None = None,
+    agent_depth: int = 0,
+    isolation: str = "none",
+    cwd: str | None = None,
+    fork_from_parent: bool = False,
+    is_async: bool = False,
+    *,
+    path_prep: PreparedSubagentPaths | None = None,
+    inject_fork_worktree_notice: bool = False,
+    fork_worktree_parent_cwd: str | None = None,
+    fork_worktree_path: str | None = None,
+) -> SubagentContext:
+    """工厂函数：从父上下文创建子 Agent 上下文
+
+    Args:
+        parent_ctx: 父会话上下文（需有 session_store / tool_registry）
+        task: 子任务描述
+        subagent_type: 子 Agent 类型（"general-purpose" / "explore" / "plan"）
+        system_prompt: 系统提示词（由 SubagentConfig.system_prompt_factory() 提供）
+        max_steps: 最大步数
+        model: 子 Agent 使用模型（None 时由调用方在 runner 阶段继续继承）
+        agent_depth: Agent 嵌套深度
+        isolation: 隔离模式（"none" / "worktree"）
+        cwd: 工作目录覆盖（与 ``path_prep`` 二选一；``path_prep`` 非空时忽略本参数的路径语义）
+        fork_from_parent: True = fork 模式，initial_messages 继承父会话历史
+        is_async: True = 走异步执行路径（coordinate/fork-async）
+        path_prep: 由 ``SubagentExecutionPaths.prepare`` 提供时，使用其 ``effective_cwd`` /
+            ``worktree_dir``，且不再在本函数内创建 worktree 目录。
+        inject_fork_worktree_notice: 为 True 且 ``fork_from_parent`` 且 ``fork_worktree_path`` 非空时，
+            在最终任务 user 消息前插入 CC 等价 worktree 提示（父 cwd 由 ``fork_worktree_parent_cwd`` 提供）。
+        fork_worktree_parent_cwd: 父 Agent 工作目录（须在 ``run_with_cwd_override`` 子 cwd 生效前由编排层捕获）。
+        fork_worktree_path: 子 Agent 的 worktree 根路径（通常即 ``path_prep.worktree_dir``）。
+
+    Returns:
+        SubagentContext 实例
+    """
+    agent_id = str(uuid.uuid4())
+    parent_run_id_raw = getattr(parent_ctx, "run_id", None)
+    if not isinstance(parent_run_id_raw, str) or not parent_run_id_raw:
+        parent_run_id_raw = getattr(parent_ctx, "session_id", None)
+        if not isinstance(parent_run_id_raw, str) or not parent_run_id_raw:
+            parent_run_id_raw = None
+    parent_conversation_id = getattr(parent_ctx, "conversation_session_id", None)
+    if not isinstance(parent_conversation_id, str) or not parent_conversation_id:
+        parent_conversation_id = parent_run_id_raw
+    parent_tool_call_id = getattr(parent_ctx, "tool_call_id", None)
+    if not isinstance(parent_tool_call_id, str) or not parent_tool_call_id:
+        anchor = parent_run_id_raw or "unknown-run"
+        parent_tool_call_id = f"synthetic-agent-call:{anchor}:{agent_id[:8]}"
+
+    parent_cwd = getattr(parent_ctx, "cwd", None)
+
+    initial_messages = [{"role": "user", "content": task}]
+    if fork_from_parent:
+        parent_messages = getattr(parent_ctx, "state", {}).get("messages", [])
+        if isinstance(parent_messages, list):
+            initial_messages = []
+            for msg in parent_messages:
+                if isinstance(msg, dict):
+                    initial_messages.append(dict(msg))
+            notice_parent = fork_worktree_parent_cwd or parent_cwd or os.getcwd()
+            if (
+                inject_fork_worktree_notice
+                and fork_worktree_path
+                and isinstance(notice_parent, str)
+                and notice_parent.strip()
+            ):
+                initial_messages.append(
+                    {
+                        "role": "user",
+                        "content": build_worktree_notice(
+                            notice_parent.strip(),
+                            fork_worktree_path,
+                        ),
+                    }
+                )
+            initial_messages.append({"role": "user", "content": task})
+
+    parent_workspace_root = getattr(parent_ctx, "workspace_root", None) or os.getcwd()
+    parent_agent_home = getattr(parent_ctx, "agent_home", ".langchain_agentx")
+    worktree_dir: str | None = None
+    if path_prep is not None:
+        effective_cwd = path_prep.effective_cwd
+        worktree_dir = path_prep.worktree_dir
+    else:
+        effective_cwd = cwd or parent_cwd or os.getcwd()
+        if isolation == "worktree":
+            workspace_cfg = resolve_agent_workspace_config(
+                workspace_root=parent_workspace_root,
+                agent_home=parent_agent_home,
+            )
+            workspace_cfg.worktrees_dir.mkdir(parents=True, exist_ok=True)
+            worktree_dir = str(
+                workspace_cfg.worktrees_dir / f"agentx-worktree-{uuid.uuid4().hex[:12]}"
+            )
+            os.makedirs(worktree_dir, exist_ok=False)
+            effective_cwd = (cwd.strip() if isinstance(cwd, str) and cwd.strip() else None) or worktree_dir
+
+    return SubagentContext(
+        agent_id=agent_id,
+        initial_messages=initial_messages,
+        max_steps=max_steps,
+        model=model,
+        subagent_type=subagent_type,
+        agent_depth=agent_depth,
+        system_prompt=system_prompt,
+        fork_from_parent=fork_from_parent,
+        is_async=is_async,
+        session_store=getattr(parent_ctx, "session_store", None),
+        tool_registry=getattr(parent_ctx, "tool_registry", None),
+        tool_loader=getattr(parent_ctx, "tool_loader", None),
+        parent_agent_id=getattr(parent_ctx, "agent_id", None),
+        parent_run_id=parent_run_id_raw,
+        parent_tool_call_id=parent_tool_call_id,
+        parent_conversation_session_id=parent_conversation_id,
+        enable_trace=bool(getattr(parent_ctx, "trace_enabled", True)),
+        isolation=isolation,
+        worktree_dir=worktree_dir,
+        workspace_root=str(parent_workspace_root),
+        agent_home=str(parent_agent_home),
+        cwd=effective_cwd,
+    )
+
+
+def cleanup_subagent_context(ctx: SubagentContext) -> None:
+    """清理 subagent 临时资源（如 worktree 目录）。"""
+    if ctx.isolation == "worktree" and ctx.worktree_dir:
+        shutil.rmtree(ctx.worktree_dir, ignore_errors=True)

langchain_agentx/loop/subagent/fork_worktree_notice.py

@@ -0,0 +1,25 @@
+"""
+loop/subagent/fork_worktree_notice.py — Fork 子 Agent 的 worktree 路径提示文案
+
+职责：
+    生成与 Claude Code ``buildWorktreeNotice`` 等价的 user 消息正文，提示子 Agent
+    将继承消息中的路径从父工作目录映射到隔离 worktree。
+链路位置：
+    ``create_subagent_context`` 在 ``fork_from_parent`` 且存在 worktree 目录时追加一条 user 消息。
+当前裁剪范围：
+    仅英文固定模板（与 CC 原文一致）；不承载 i18n。
+CC 对照：
+    ``src/tools/AgentTool/forkSubagent.ts`` ``buildWorktreeNotice(parentCwd, worktreeCwd)``。
+"""
+
+
+def build_worktree_notice(parent_cwd: str, worktree_path: str) -> str:
+    """与 CC ``buildWorktreeNotice`` 原文一致（参数为父 cwd 与 worktree 根路径）。"""
+    return (
+        f"You've inherited the conversation context above from a parent agent working in {parent_cwd}. "
+        f"You are operating in an isolated git worktree at {worktree_path} — same repository, "
+        "same relative file structure, separate working copy. Paths in the inherited context refer "
+        "to the parent's working directory; translate them to your worktree root. Re-read files before "
+        "editing if the parent may have modified them since they appear in the context. Your changes stay "
+        "in this worktree and will not affect the parent's files."
+    )

langchain_agentx/loop/subagent/graph.py

@@ -0,0 +1,72 @@
+"""
+loop/subagent/graph.py — 子 Agent 图创建
+
+职责：create_subagent_graph()，基于 SubagentContext 创建独立子 Loop 图
+在整体链路中的位置：run_subagent() → create_subagent_graph() → subagent_graph.astream_events()
+CC 对照：runAgent.ts 中 queryLoop() 调用（子会话复用主引擎）
+当前裁剪范围：v1 复用 create_loop_agent；通过 tools 参数注入子代理工具，并传入
+  parent_run_id/parent_tool_call_id 与父 run 关联。
+
+执行流程（create_subagent_graph）：
+  1. 从 ctx 读取 system_prompt / session_store / max_steps
+  2. 调用 create_loop_agent(is_subagent=True, loader=..., parent_run_id=..., parent_tool_call_id=...)
+     创建子图
+  3. 返回编译后的 CompiledStateGraph，由 run_subagent() 调用 astream_events()
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from langchain_core.language_models.chat_models import BaseChatModel
+    from langchain_core.tools import BaseTool
+    from langgraph.graph.state import CompiledStateGraph
+
+    from .context import SubagentContext
+
+
+def create_subagent_graph(
+    ctx: SubagentContext,
+    loader: Any,
+    model: str | BaseChatModel | None = None,
+) -> CompiledStateGraph:
+    """创建子 Agent 的 LangGraph 图。
+
+    复用 create_loop_agent(..., is_subagent=True)。
+
+    Args:
+        ctx: 子 Agent 执行上下文（SubagentContext）
+        loader: 子会话 ToolRuntimeLoader（已完成工具过滤与运行时装配）
+        model: 语言模型（str 或 BaseChatModel），None 时由调用方保证已在 ctx 外部传入
+
+    Returns:
+        编译后的 CompiledStateGraph，可直接调用 astream_events()
+    """
+    from langchain_agentx.loop.graph.factory import create_loop_agent
+
+    if model is None:
+        raise ValueError("model is required for create_subagent_graph")
+
+    # 显式 session_id：避免子图构图时生成 ephemeral id 刷屏日志，并与 ctx.agent_id 对齐便于追溯
+    session_id = f"subagent:{ctx.subagent_type}:{ctx.agent_id}"
+
+    return create_loop_agent(
+        model=model,
+        loader=loader,
+        system_prompt=ctx.system_prompt or None,
+        session_id=session_id,
+        session_store=ctx.session_store,
+        max_steps=ctx.max_steps,
+        is_subagent=True,
+        name=f"subagent:{ctx.subagent_type}:{ctx.agent_id[:8]}",
+        parent_run_id=ctx.parent_run_id,
+        parent_tool_call_id=ctx.parent_tool_call_id,
+        parent_conversation_session_id=ctx.parent_conversation_session_id,
+        enable_trace=ctx.enable_trace,
+        # 背景子代理默认隐藏；前台子代理沿用默认可见性。
+        trace_visibility="hidden" if ctx.is_async else "default",
+        workspace_root=ctx.workspace_root or None,
+        agent_home=ctx.agent_home,
+        subagent_type=ctx.subagent_type,
+    )