langchain-agentx-python 0.4.0__tar.gz → 0.4.1__tar.gz

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.4.0
+Version: 0.4.1
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/langchain_agentx/loop/subagent/orchestrator.py

@@ -11,6 +11,8 @@ CC 对照：src/tools/AgentTool/AgentTool.tsx call() 中 runAgent / registerAsyn
 
 from __future__ import annotations
 
+import asyncio
+import inspect
 import logging
 import os
 import time
@@ -51,50 +53,36 @@ def _make_progress_handler(
     parent_tool_use_id: str | None = None,
     tool_progress_callback: Any = None,
 ):
-    """构造 on_progress 回调（2s hint 阈值 + stderr 单行覆写 + 事件冒泡）。
+    """构造 on_progress 回调（事件冒泡 + 可选的 CLI 提示）。
 
     Args:
         subagent_type: 子 agent 类型
         started_at: 开始时间戳
         parent_tool_use_id: 父级 tool_use_id，用于事件冒泡（CC 对齐）
-        tool_progress_callback: 父级的工具进度回调，用于转发子 agent 事件
-    """
-    import sys
-    hint_shown = False
+        tool_progress_callback: 父级的工具进度回调（异步路径用于 adispatch_custom_event）
 
+    事件流向：
+        同步路径: 子 agent 事件 → tool_progress_callback（Channel B）→ CLI 处理
+        异步路径: 子 agent 事件 → tool_progress_callback → adispatch_custom_event（Channel A）
+    """
     def _on_progress(event: Any) -> None:
-        nonlocal hint_shown
 
         # 设置 parent_tool_use_id（如果事件支持）
         if hasattr(event, "parent_tool_use_id") and event.parent_tool_use_id is None:
             object.__setattr__(event, "parent_tool_use_id", parent_tool_use_id)
 
-        # 事件冒泡：转发到父级的 tool_progress_callback
-        # 子 agent 的事件通过此回调冒泡到父级，实现对齐 CC 的目录式展示
+        # 事件冒泡：转发到 tool_progress_callback
+        # - 同步路径：转发到 CLI 的 tool_progress_callback（Channel B）
+        # - 异步路径：转发到 _bubble_progress → adispatch_custom_event（Channel A）
         if tool_progress_callback is not None and callable(tool_progress_callback):
             try:
-                tool_progress_callback(event)
+                result = tool_progress_callback(event)
+                # 支持异步回调
+                if inspect.iscoroutine(result):
+                    asyncio.create_task(result)
             except Exception:
                 logger.debug("tool_progress_callback failed", exc_info=True)
 
-        # CLI 输出
-        if not hint_shown and time.monotonic() - started_at > 2.0:
-            hint_shown = True
-            print(
-                f"\r[Agent:{subagent_type}] task is running... (Ctrl+C to interrupt)",
-                file=sys.stderr,
-                flush=True,
-            )
-        if getattr(event, "summary", ""):
-            print(
-                f"\r[{subagent_type}] {event.summary:<80}",
-                file=sys.stderr,
-                end="",
-                flush=True,
-            )
-        if getattr(event, "type", "") == "completed":
-            print("", file=sys.stderr)
-
     return _on_progress
 
 
@@ -265,6 +253,130 @@ class SubagentOrchestrator:
             execution_trace=getattr(result, "execution_trace", None),
         )
 
+    async def ainvoke_subagent(
+        self,
+        inp: "AgentToolInput",
+        ctx: "ToolExecutionContext",
+        subagent_config: "SubagentConfig",
+        on_progress: Any | None = None,
+    ) -> "AgentToolOutput":
+        """异步执行子代理（支持实时事件冒泡）。
+
+        与 invoke_subagent 的区别：
+        - on_progress 回调支持异步（用于 adispatch_custom_event）
+        - 不通过 _run_coroutine_sync，直接在异步上下文执行
+        - 保留同步 invoke 路径用于兼容（非 ToolNode 场景）
+
+        CC 对照：AgentTool.tsx call() 中 onProgress 回调
+        """
+        from langchain_agentx.tools.agent.models import AgentToolOutput
+        from langchain_agentx.loop.subagent.async_runner import run_async_agent_lifecycle
+
+        log = self._build_logger(ctx)
+        child_agent_id = str(uuid.uuid4())
+        overrides, runtime_ctx, prepared = self._derive_runtime_context(
+            inp=inp,
+            ctx=ctx,
+            subagent_config=subagent_config,
+            child_agent_id=child_agent_id,
+        )
+        is_async = self._decide_async(inp=inp, ctx=ctx)
+
+        log.info(
+            "agent ainvoke mode=%s subagent_type=%s async=%s",
+            self._mode, inp.subagent_type or "general-purpose", is_async,
+        )
+
+        parent_registry = getattr(ctx, "tool_registry", None)
+        if parent_registry is None or not hasattr(parent_registry, "list"):
+            raise RuntimeError(
+                "tool_registry missing in ToolExecutionContext; "
+                "please construct the parent agent with ToolRuntimeLoader(loader=...)."
+            )
+        parent_loader = getattr(ctx, "tool_loader", None)
+        if parent_loader is None or not hasattr(parent_loader, "fork_with_tools"):
+            raise RuntimeError(
+                "tool_loader missing in ToolExecutionContext; "
+                "please construct the parent agent with ToolRuntimeLoader(loader=...)."
+            )
+
+        runtime_tools = list(parent_registry.list())
+        runtime_tools = assemble_tool_pool(runtime_tools, subagent_config, is_async=is_async)
+        allowed_tool_names: set[str] = {getattr(t, "name", "") for t in runtime_tools if getattr(t, "name", "")}
+        child_loader = parent_loader.fork_with_tools(runtime_tools)
+
+        system_prompt = enhance_system_prompt_with_env(
+            subagent_config.system_prompt_factory(),
+            runtime_ctx.cwd,
+        )
+
+        effective_cwd = runtime_ctx.cwd or get_cwd()
+        parent_notice_cwd = getattr(ctx, "cwd", None) or get_cwd()
+        inject_fork_wt = self._mode == "fork" and prepared.worktree_dir is not None
+        with run_with_cwd_override(effective_cwd):
+            output_dir = self._resolve_background_output_dir(runtime_ctx)
+            subagent_ctx = create_subagent_context(
+                parent_ctx=ctx,
+                task=inp.prompt,
+                subagent_type=inp.subagent_type or "general-purpose",
+                system_prompt=system_prompt,
+                max_steps=runtime_ctx.max_steps,
+                agent_depth=runtime_ctx.agent_depth,
+                isolation=overrides.isolation,
+                fork_from_parent=(self._mode == "fork"),
+                is_async=is_async,
+                model=runtime_ctx.model,
+                path_prep=prepared,
+                inject_fork_worktree_notice=inject_fork_wt,
+                fork_worktree_parent_cwd=parent_notice_cwd,
+                fork_worktree_path=prepared.worktree_dir,
+            )
+            subagent_ctx.agent_id = child_agent_id
+
+            parent_tool_use_id = getattr(ctx, "tool_call_id", None)
+
+            # 构造异步进度回调
+            _on_progress = _make_progress_handler(
+                inp.subagent_type or "general-purpose",
+                time.monotonic(),
+                parent_tool_use_id=parent_tool_use_id,
+                tool_progress_callback=on_progress,  # 使用传入的异步回调
+            )
+            os.makedirs(output_dir, exist_ok=True)
+
+            if is_async:
+                return await self._launch_async_subagent_with_progress(
+                    agent_output_cls=AgentToolOutput,
+                    subagent_ctx=subagent_ctx,
+                    loader=child_loader,
+                    model=runtime_ctx.model,
+                    description=inp.description,
+                    on_progress=_on_progress,
+                    parent_ctx=ctx,
+                    output_dir=output_dir,
+                )
+
+            # 前台执行：直接调用 run_subagent（异步版本）
+            result = await run_subagent(
+                ctx=subagent_ctx,
+                loader=child_loader,
+                model=runtime_ctx.model,
+                on_progress=_on_progress,
+                allowed_tool_names=allowed_tool_names,
+            )
+
+        return AgentToolOutput(
+            status=result.status,
+            content=result.content,
+            agent_id=result.agent_id,
+            total_steps=result.total_steps,
+            terminal_reason=result.terminal_reason or None,
+            error_message=result.error_message or None,
+            output_file=getattr(result, "output_file", None),
+            child_run_id=getattr(result, "child_run_id", None),
+            execution_trace=getattr(result, "execution_trace", None),
+        )
+
     def _build_logger(self, ctx: "ToolExecutionContext") -> ObservabilityLoggerAdapter:
         return ObservabilityLoggerAdapter(
             logger,
@@ -359,6 +471,44 @@ class SubagentOrchestrator:
             output_file=handle.output_file,
         )
 
+    async def _launch_async_subagent_with_progress(
+        self,
+        *,
+        agent_output_cls: type[Any],
+        subagent_ctx: Any,
+        loader: Any,
+        model: Any,
+        description: str | None,
+        on_progress: Any,
+        parent_ctx: "ToolExecutionContext",
+        output_dir: str,
+    ) -> Any:
+        """异步启动子 agent（支持实时进度回调）。
+
+        与 _launch_async_subagent 的区别：
+        - 使用 register_background_agent 但不等待完成
+        - 返回 async_launched 状态
+        - 进度通过 on_progress 回调实时上报
+        """
+        handle = self._register_background_agent(
+            subagent_ctx=subagent_ctx,
+            loader=loader,
+            model=model,
+            output_dir=output_dir,
+            description=description,
+            on_progress=on_progress,
+            parent_ctx=parent_ctx,
+        )
+        return agent_output_cls(
+            status="async_launched",
+            content="",
+            agent_id=handle.agent_id,
+            total_steps=0,
+            terminal_reason="background",
+            task_id=handle.task_id,
+            output_file=handle.output_file,
+        )
+
     def _run_with_background_signal(
         self,
         *,

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/langchain_agentx/loop/subagent/runner.py

@@ -24,6 +24,7 @@ CC 对照：runAgent.ts runAgent()；onProgress 回调逻辑
 from __future__ import annotations
 
 import asyncio
+import inspect
 import logging
 import threading
 from concurrent.futures import Future
@@ -190,19 +191,27 @@ def _build_graph_input_messages(initial_messages: list[Any]) -> list[Any]:
     ]
 
 
-def _emit_progress(
-    on_progress: Callable[[SubagentProgressEvent], None] | None,
+async def _emit_progress(
+    on_progress: Any,
     event: SubagentProgressEvent,
 ) -> None:
+    """发射进度事件（支持异步回调）。
+
+    如果 on_progress 是异步函数，则使用 await 调用；
+    否则使用同步调用。这允许子 Agent 进度事件通过
+    adispatch_custom_event 实时冒泡到主 graph。
+    """
     if on_progress:
-        on_progress(event)
+        result = on_progress(event)
+        if inspect.iscoroutine(result):
+            await result
 
 
-def _handle_tool_start_event(
+async def _handle_tool_start_event(
     *,
     ctx: SubagentContext,
     event: dict[str, Any],
-    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    on_progress: Any,
     current_step: int,
     trace: SubagentExecutionTrace | None = None,
 ) -> tuple[int, str]:
@@ -225,7 +234,7 @@ def _handle_tool_start_event(
     if trace:
         trace.add_tool_call(tool_call)
 
-    _emit_progress(
+    await _emit_progress(
         on_progress,
         SubagentProgressEvent(
             type="tool_use",
@@ -272,13 +281,13 @@ def _is_tool_error(output: Any) -> bool:
     return False
 
 
-def _handle_tool_end_event(
+async def _handle_tool_end_event(
     *,
     ctx: SubagentContext,
     event: dict[str, Any],
     data: dict[str, Any],
     transcript: SubagentTranscriptManager,
-    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    on_progress: Any,
     step: int,
     trace: SubagentExecutionTrace | None = None,
 ) -> None:
@@ -306,7 +315,7 @@ def _handle_tool_end_event(
 
     msg_dict = {"role": "tool", "tool_name": tool_name, "content": transcript_text}
     transcript.append(msg_dict)
-    _emit_progress(
+    await _emit_progress(
         on_progress,
         SubagentProgressEvent(
             type="tool_result",
@@ -319,11 +328,11 @@ def _handle_tool_end_event(
     )
 
 
-def _handle_chat_model_end_event(
+async def _handle_chat_model_end_event(
     *,
     ctx: SubagentContext,
     data: dict[str, Any],
-    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    on_progress: Any,
     collected_assistant_messages: list[Any],
     total_steps: int,
 ) -> int:
@@ -333,7 +342,7 @@ def _handle_chat_model_end_event(
     has_tool_calls = bool(output is not None and getattr(output, "tool_calls", None))
     if not has_tool_calls:
         total_steps += 1
-        _emit_progress(
+        await _emit_progress(
             on_progress,
             SubagentProgressEvent(
                 type="model_step",
@@ -370,7 +379,7 @@ async def _collect_subagent_events(
     graph_input: dict[str, Any],
     run_tags: list[str],
     transcript: SubagentTranscriptManager,
-    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    on_progress: Any,
     trace: SubagentExecutionTrace,
 ) -> _EventCollectionResult:
     collected_assistant_messages: list[Any] = []
@@ -389,7 +398,7 @@ async def _collect_subagent_events(
             event_name = event.get("event", "")
             data = event.get("data") or {}
             if event_name == "on_tool_start":
-                tool_step, last_tool_name = _handle_tool_start_event(
+                tool_step, last_tool_name = await _handle_tool_start_event(
                     ctx=ctx,
                     event=event,
                     on_progress=on_progress,
@@ -397,7 +406,7 @@ async def _collect_subagent_events(
                     trace=trace,
                 )
             elif event_name == "on_tool_end":
-                _handle_tool_end_event(
+                await _handle_tool_end_event(
                     ctx=ctx,
                     event=event,
                     data=data,
@@ -407,7 +416,7 @@ async def _collect_subagent_events(
                     trace=trace,
                 )
             elif event_name == "on_chat_model_end":
-                total_steps = _handle_chat_model_end_event(
+                total_steps = await _handle_chat_model_end_event(
                     ctx=ctx,
                     data=data,
                     on_progress=on_progress,
@@ -440,13 +449,13 @@ async def _collect_subagent_events(
     )
 
 
-def _build_subagent_result(
+async def _build_subagent_result(
     *,
     ctx: SubagentContext,
     collected: _EventCollectionResult,
     transcript: SubagentTranscriptManager,
     allowed_tool_names: set[str] | None,
-    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    on_progress: Any,
     trace: SubagentExecutionTrace,
 ) -> SubagentResult:
     content = _extract_final_content(collected.collected_assistant_messages, allowed_tool_names)
@@ -463,7 +472,7 @@ def _build_subagent_result(
         )
     # 更新 trace 的 terminal_reason
     trace.terminal_reason = collected.terminal_reason
-    _emit_progress(
+    await _emit_progress(
         on_progress,
         SubagentProgressEvent(
             type="completed",
@@ -490,7 +499,7 @@ async def run_subagent(
     ctx: SubagentContext,
     loader: Any,
     model: Any | None = None,
-    on_progress: Callable[[SubagentProgressEvent], None] | None = None,
+    on_progress: Any = None,
     allowed_tool_names: set[str] | None = None,
 ) -> SubagentResult:
     """运行子 Agent（plain/fork 同步路径）。
@@ -499,7 +508,7 @@ async def run_subagent(
         ctx: 子 Agent 执行上下文
         loader: 子会话 ToolRuntimeLoader
         model: 语言模型（str 或 BaseChatModel），None 时继承 ctx.model
-        on_progress: 进度回调（Channel B），每个工具调用步骤触发
+        on_progress: 进度回调（Channel B），每个工具调用步骤触发（支持异步）
         allowed_tool_names: 工具白名单，用于识别 XML 退化格式（如 <Read>...</Read>）
 
     Returns:
@@ -536,7 +545,7 @@ async def run_subagent(
             on_progress=on_progress,
             trace=trace,
         )
-        return _build_subagent_result(
+        return await _build_subagent_result(
             ctx=ctx,
             collected=collected,
             transcript=transcript,
@@ -554,7 +563,7 @@ async def run_subagent_with_background_signal(
     ctx: SubagentContext,
     loader: Any,
     model: Any | None = None,
-    on_progress: Callable[[SubagentProgressEvent], None] | None = None,
+    on_progress: Any = None,
     background_signal: asyncio.Event | None = None,
     on_background_request: Callable[[SubagentContext], str] | None = None,
     allowed_tool_names: set[str] | None = None,

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/langchain_agentx/observability/events/langchain_agentx_event_adapter.py

@@ -84,6 +84,10 @@ class LangchainAgentEventType(Enum):
     # 子 Agent
     SUBAGENT_START = "subagent-start"
     SUBAGENT_END = "subagent-end"
+    # 子 Agent 内部工具调用事件（通过 adispatch_custom_event 冒泡）
+    SUBAGENT_TOOL_CALL = "subagent-tool-call"
+    SUBAGENT_TOOL_RESULT = "subagent-tool-result"
+    SUBAGENT_MODEL_STEP = "subagent-model-step"
 
     # 错误
     ERROR = "error"
@@ -229,6 +233,11 @@ class LangGraphToLangchainAgentEventAdapter:
                 async for oc_event in self._handle_error(name, data):
                     yield oc_event
 
+            elif event_type == "on_custom_event":
+                async for oc_event in self._handle_custom_event(event):
+                    if oc_event is not None:
+                        yield oc_event
+
     def _event(
         self,
         *,
@@ -253,6 +262,10 @@ class LangGraphToLangchainAgentEventAdapter:
     def emit_subagent_event(self, progress_event: Any) -> LangchainAgentEvent | None:
         """将子 agent 的进度事件转换为 LangchainAgentEvent（事件冒泡）。
 
+        .. deprecated::
+            推荐使用 adispatch_custom_event + _handle_custom_event 路径（Channel A）。
+            此方法保留用于兼容旧代码和测试。
+
         用于实现 CC 风格的子 agent 内部工具调用事件转发。
         当子 agent 调用工具时，其事件通过 tool_progress_callback 冒泡到父级，
         父级调用此方法将事件转换为标准格式。
@@ -1045,6 +1058,81 @@ class LangGraphToLangchainAgentEventAdapter:
             step_index=self.state.step_index,
         )
 
+    async def _handle_custom_event(
+        self, event: Dict[str, Any]
+    ) -> AsyncGenerator[LangchainAgentEvent, None]:
+        """处理 on_custom_event（子 Agent 事件冒泡）。
+
+        当子 Agent 通过 adispatch_custom_event 发射进度事件时，
+        这些事件会通过主 graph 的 astream_events 流冒泡上来。
+
+        事件格式：
+        {
+            "event": "on_custom_event",
+            "name": "subagent_progress",
+            "data": {
+                "type": "tool_use" | "tool_result" | "model_step" | "completed",
+                "subagent_type": str,
+                "agent_id": str,
+                "tool_name": str,
+                "summary": str,
+                "step": int,
+                "parent_tool_use_id": str,
+            }
+        }
+        """
+        if not self.enable_subagent_events:
+            return
+
+        event_name = event.get("name", "")
+        if event_name != "subagent_progress":
+            return
+
+        data = event.get("data", {})
+        if not isinstance(data, dict):
+            return
+
+        event_type = data.get("type", "")
+        parent_tool_use_id = data.get("parent_tool_use_id")
+
+        # 映射到 SDK 事件类型
+        type_mapping = {
+            "tool_use": LangchainAgentEventType.SUBAGENT_TOOL_CALL,
+            "tool_result": LangchainAgentEventType.SUBAGENT_TOOL_RESULT,
+            "model_step": LangchainAgentEventType.SUBAGENT_MODEL_STEP,
+            "completed": None,  # 不发事件，由 SUBAGENT_END 表示
+        }
+
+        target_type = type_mapping.get(event_type)
+        if target_type is None:
+            return
+
+        event_data: Dict[str, Any] = {
+            "subagent_type": data.get("subagent_type", ""),
+            "agent_id": data.get("agent_id", ""),
+            "summary": data.get("summary", "")[:200],
+        }
+
+        if parent_tool_use_id:
+            event_data["parent_tool_use_id"] = parent_tool_use_id
+
+        if event_type == "tool_use":
+            event_data["tool_name"] = data.get("tool_name", "")
+            event_data["status"] = "running"
+            event_data["step"] = data.get("step", 0)
+        elif event_type == "tool_result":
+            event_data["tool_name"] = data.get("tool_name", "")
+            event_data["summary"] = data.get("summary", "")[:200]
+        elif event_type == "model_step":
+            event_data["text"] = data.get("summary", "")
+
+        yield self._event(
+            event_type=target_type,
+            data=event_data,
+            step_index=self.state.step_index,
+            tool_name=data.get("tool_name"),
+        )
+
 
 __all__ = [
     "LangchainAgentEventType",

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/langchain_agentx/tool_runtime/adapter.py

@@ -206,6 +206,12 @@ class LangChainAdapter:
         if tool_progress_callback is None and loop_config is not None:
             tool_progress_callback = getattr(loop_config, "tool_progress_callback", None)
 
+        # 保留原始 RunnableConfig 用于 adispatch_custom_event（子 Agent 事件冒泡）
+        # 只在 config 非空时传递，避免工具层直接访问 LangGraph 内部字段
+        runnable_config_to_pass: Any | None = None
+        if config is not None and not isinstance(config, str):
+            runnable_config_to_pass = config
+
         return ToolExecutionContext(
             tool_name=tool_name,
             # 回退顺序：显式 tool_call_id -> config.tool_call_id -> input.tool_call_id -> input.id -> run_id
@@ -240,6 +246,7 @@ class LangChainAdapter:
             capabilities=capabilities,
             network_access_allowed=network_access_allowed,
             tool_progress_callback=tool_progress_callback,
+            runnable_config=runnable_config_to_pass,
         )
 
     def build_structured_tool(

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/langchain_agentx/tool_runtime/models.py

@@ -120,8 +120,16 @@ class ToolExecutionContext:
     tool_progress_callback: Any | None = None
     """
     可选；``RunnableConfig.configurable["tool_progress_callback"]`` 或 AgentLoopConfig 注入。
-    签名为 ``(event: ProgressEvent) -> None``（具体类型由工具包定义，避免 runtime 循环依赖）。
+    签名为 ``(event: ProgressEvent) -> None | Coroutine``（具体类型由工具包定义，避免 runtime 循环依赖）。
+
+    用于：
+      - 同步路径：子 agent 事件通过此回调转发到 CLI（Channel B）
+      - 异步路径：子 agent 事件通过此回调 → adispatch_custom_event（Channel A）
+    """
+    runnable_config: Any | None = None
     """
+    可选；LangGraph RunnableConfig 原始对象，保留用于 adispatch_custom_event 等需要
+    parent_run_id 上下文的场景（子 Agent 事件冒泡）。工具层不应直接访问其内部字段。"""
 
 
 # ---------------------------------------------------------------------------

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/langchain_agentx/tools/agent/tool.py

@@ -12,9 +12,12 @@ CC 对照：src/tools/AgentTool/AgentTool.tsx call() 方法
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import Any, Literal
 
+from langchain_core.callbacks import adispatch_custom_event
+
 from langchain_agentx.loop.subagent.orchestrator import SubagentOrchestrator
 from langchain_agentx.tool_runtime.base import RuntimeTool
 from langchain_agentx.tool_runtime.models import (
@@ -187,6 +190,61 @@ class AgentRuntimeTool(RuntimeTool):
         subagent_config = self._registry.get(subagent_type)
         return self._orchestrator.invoke_subagent(inp=inp, ctx=ctx, subagent_config=subagent_config)
 
+    async def ainvoke(self, data: dict[str, Any], ctx: ToolExecutionContext) -> AgentToolOutput:
+        """异步执行子 Agent（支持实时事件冒泡）。
+
+        与 invoke 的区别：
+        - 通过 adispatch_custom_event 将子 Agent 进度事件实时冒泡到主 graph
+        - on_progress 回调改为异步，支持实时事件发射
+        - 保留同步 invoke 路径用于兼容（ToolNode 默认使用 arun）
+
+        CC 对照：AgentTool.tsx call() 中 onProgress → createProgressMessage → stream.enqueue
+        """
+        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)
+
+        # 获取 parent_config 用于 adispatch_custom_event（需要 parent_run_id）
+        parent_config = getattr(ctx, "runnable_config", None)
+        parent_tool_use_id = getattr(ctx, "tool_call_id", None)
+
+        # 构造异步进度回调：实时冒泡子 Agent 事件到主 graph
+        async def _bubble_progress(event: Any) -> None:
+            """实时冒泡子 Agent 进度事件到主 graph 的 astream_events 流。"""
+            if parent_config is not None:
+                try:
+                    await adispatch_custom_event(
+                        name="subagent_progress",
+                        data={
+                            "type": getattr(event, "type", ""),
+                            "subagent_type": getattr(event, "subagent_type", ""),
+                            "agent_id": getattr(event, "agent_id", ""),
+                            "tool_name": getattr(event, "tool_name", ""),
+                            "summary": getattr(event, "summary", "")[:200],
+                            "step": getattr(event, "step", 0),
+                            "parent_tool_use_id": parent_tool_use_id,
+                        },
+                        config=parent_config,
+                    )
+                except Exception:
+                    logger.debug("adispatch_custom_event failed", exc_info=True)
+
+        return await self._orchestrator.ainvoke_subagent(
+            inp=inp,
+            ctx=ctx,
+            subagent_config=subagent_config,
+            on_progress=_bubble_progress,
+        )
+
     def present(
         self,
         data: dict[str, Any],

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.1}/langchain_agentx_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.4.0
+Version: 0.4.1
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License