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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.4.0
+Version: 0.4.2
 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.2}/langchain_agentx/loop/hook/engine.py

@@ -185,6 +185,16 @@ class HookEngine:
         if one.state_patch:
             agg.state_patch.update(one.state_patch)
 
+        # 聚合 Hook 输出结果（stdout/stderr/exit_code）
+        if one.stdout is not None:
+            agg.stdouts.append(one.stdout)
+            agg.combined_stdout += one.stdout
+        if one.stderr is not None:
+            agg.stderrs.append(one.stderr)
+            agg.combined_stderr += one.stderr
+        if one.exit_code is not None:
+            agg.exit_codes.append(one.exit_code)
+
         agg.permission_behavior = merge_permission_behavior(
             agg.permission_behavior,
             one.permission_behavior,

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.2}/langchain_agentx/loop/hook/executors/command.py

@@ -136,7 +136,12 @@ class CommandExecutor:
         stderr = stderr_raw.decode("utf-8", errors="replace")
         returncode = int(proc.returncode or 0)
 
-        result = HookResult(outcome="success")
+        result = HookResult(
+            outcome="success",
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=returncode,
+        )
         parsed_json = self._parse_json(stdout)
         if isinstance(parsed_json, dict):
             self._apply_json_result(result, parsed_json)

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.2}/langchain_agentx/loop/hook/graph_wiring.py

@@ -23,6 +23,7 @@ from .types import AggregatedHookResult, HookContext, HookEvent
 
 
 def _to_hook_result_dict(result: AggregatedHookResult) -> dict[str, Any]:
+    """将 AggregatedHookResult 转换为字典，包含 Hook 输出结果（stdout/stderr/exit_code）。"""
     return {
         "prevent_continuation": result.prevent_continuation,
         "blocking_errors": list(result.blocking_errors) or None,
@@ -31,6 +32,12 @@ def _to_hook_result_dict(result: AggregatedHookResult) -> dict[str, Any]:
         "additional_contexts": list(result.additional_contexts),
         "updated_input": result.updated_input,
         "state_patch": dict(result.state_patch),
+        # Hook 输出结果（对齐 CC hook_response）
+        "stdouts": list(result.stdouts) or None,
+        "stderrs": list(result.stderrs) or None,
+        "exit_codes": list(result.exit_codes) or None,
+        "combined_stdout": result.combined_stdout or None,
+        "combined_stderr": result.combined_stderr or None,
     }
 
 

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.2}/langchain_agentx/loop/hook/types.py

@@ -121,6 +121,10 @@ class HookResult:
     additional_context: str | None = None
     updated_input: dict[str, Any] | None = None
     state_patch: dict[str, Any] = field(default_factory=dict)
+    # 新增：Hook 输出结果（对齐 CC hook_response）
+    stdout: str | None = None
+    stderr: str | None = None
+    exit_code: int | None = None
 
 
 @dataclass
@@ -134,6 +138,13 @@ class AggregatedHookResult:
     additional_contexts: list[str] = field(default_factory=list)
     updated_input: dict[str, Any] | None = None
     state_patch: dict[str, Any] = field(default_factory=dict)
+    # 新增：聚合所有 Hook 的输出结果（对齐 CC hook_response）
+    stdouts: list[str] = field(default_factory=list)
+    stderrs: list[str] = field(default_factory=list)
+    exit_codes: list[int] = field(default_factory=list)
+    # 合并后的完整输出（用于事件展示）
+    combined_stdout: str = ""
+    combined_stderr: str = ""
 
 
 __all__ = [

{langchain-agentx-python-0.4.0 → langchain-agentx-python-0.4.2}/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.2}/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.2}/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 冒泡到父级，
         父级调用此方法将事件转换为标准格式。
@@ -661,14 +674,24 @@ class LangGraphToLangchainAgentEventAdapter:
         if self.enable_hook_events and self._is_hook_node(name):
             output = data.get("output") if isinstance(data, dict) else None
             outcome = "success"
+            hook_result_data: dict[str, Any] = {}
             if isinstance(output, dict):
                 outcome = str(output.get("outcome") or outcome)
+                # 提取 Hook 输出结果（对齐 CC hook_response）
+                hook_result_data = {
+                    "stdouts": output.get("stdouts"),
+                    "stderrs": output.get("stderrs"),
+                    "exit_codes": output.get("exit_codes"),
+                    "combined_stdout": output.get("combined_stdout"),
+                    "combined_stderr": output.get("combined_stderr"),
+                }
             yield self._event(
                 event_type=LangchainAgentEventType.HOOK_FINISHED,
                 data={
                     "hook_event": self._hook_event_from_name(name),
                     "hook_name": name,
                     "outcome": outcome,
+                    **hook_result_data,  # 包含 stdout/stderr/exit_code
                 },
                 step_index=self.state.step_index or None,
             )
@@ -1045,6 +1068,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",