agentengine-sdk-python 0.6.9__py3-none-any.whl → 0.8.0__py3-none-any.whl

ksadk/runners/langgraph_runner.py

@@ -4,24 +4,26 @@ LangGraphRunner - LangGraph 框架运行时
 直接透传 LangGraph 原生能力，最小化封装
 """
 
+import base64
+import inspect
 import os
-import uuid
 import re
+import uuid
 from typing import Any, AsyncIterator, Dict, Mapping
-import base64
-from pathlib import Path
 
-from ksadk.runners.base_runner import BaseRunner
-from ksadk.sessions.continuity import LangGraphSessionAdapter
-from ksadk.runners.utils import get_langfuse_callbacks, get_langfuse_metadata, load_agent_module
 from langgraph.types import Command
+
 from ksadk.conversations.attachments import classify_attachment_kind, read_attachment_uri_bytes
 from ksadk.conversations.reasoning_markup import ReasoningMarkupParser, strip_reasoning_markup
+from ksadk.runners.base_runner import BaseRunner
+from ksadk.runners.usage_accumulator import accumulate_usage
+from ksadk.runners.utils import get_langfuse_callbacks, get_langfuse_metadata, load_agent_module
+from ksadk.sessions.continuity import LangGraphSessionAdapter
 
 
 class LangGraphRunner(BaseRunner):
     """LangGraph 框架运行时
-    
+
     透传原生 LangGraph 功能，支持任意 State 格式
     """
 
@@ -39,7 +41,7 @@ class LangGraphRunner(BaseRunner):
         self._loaded_model_name = self.normalize_requested_model(
             os.getenv("OPENAI_MODEL_NAME") or os.getenv("MODEL_NAME")
         )
-        
+
         if not hasattr(self._agent, "invoke"):
             raise TypeError("加载的对象不是有效的 LangGraph CompiledGraph")
 
@@ -56,10 +58,10 @@ class LangGraphRunner(BaseRunner):
 
     def describe_checkpoint_capability(self) -> dict[str, Any]:
         agent = getattr(self, "_agent", None)
-        has_checkpointer = bool(
-            getattr(agent, "checkpointer", None) or getattr(agent, "_checkpointer", None)
-        )
-        if not has_checkpointer:
+        checkpointer = getattr(agent, "checkpointer", None)
+        if checkpointer is None:
+            checkpointer = getattr(agent, "_checkpointer", None)
+        if checkpointer is None:
             return {
                 "Supported": False,
                 "Backend": "none",
@@ -69,7 +71,16 @@ class LangGraphRunner(BaseRunner):
                 "Reason": "LangGraph graph has no configured checkpointer",
             }
 
-        backend = str(os.getenv("KSADK_CHECKPOINT_BACKEND") or "").strip().lower()
+        checkpointer_type = type(checkpointer)
+        type_name = f"{checkpointer_type.__module__}.{checkpointer_type.__name__}".lower()
+        if "memory" in type_name or "inmemory" in type_name:
+            backend = "memory"
+        elif "sqlite" in type_name:
+            backend = "sqlite"
+        elif "postgres" in type_name:
+            backend = "postgres"
+        else:
+            backend = str(os.getenv("KSADK_CHECKPOINT_BACKEND") or "").strip().lower()
         if backend == "local":
             backend = "sqlite"
         if not backend:
@@ -86,7 +97,9 @@ class LangGraphRunner(BaseRunner):
             scope = "pod_local"
             durable = True
             shared = False
-            reason = "SQLite checkpoint is durable for local web debugging but is not shared across pods"
+            reason = (
+                "SQLite checkpoint is durable for local web debugging but is not shared across pods"
+            )
         elif backend in {"memory", "inmemory"}:
             backend = "memory"
             scope = "process_local"
@@ -108,25 +121,23 @@ class LangGraphRunner(BaseRunner):
         capabilities = super().get_runtime_capabilities()
         capabilities["SessionContinuity"] = {
             "Supported": True,
-            "Type": "checkpoint"
-            if capabilities["Checkpoint"].get("Supported")
-            else "semantic_replay",
-            "Level": "runtime"
-            if capabilities["Checkpoint"].get("Supported")
-            else "semantic",
+            "Type": (
+                "checkpoint" if capabilities["Checkpoint"].get("Supported") else "semantic_replay"
+            ),
+            "Level": "runtime" if capabilities["Checkpoint"].get("Supported") else "semantic",
             "Reason": "",
         }
         return capabilities
 
     def _get_config(self, session_id: str) -> dict:
         """获取运行配置"""
-        config = {"configurable": {"thread_id": session_id}}
-        
+        config: dict[str, Any] = {"configurable": {"thread_id": session_id}}
+
         langfuse_callbacks = get_langfuse_callbacks()
         if langfuse_callbacks:
             config["callbacks"] = langfuse_callbacks
             config["metadata"] = get_langfuse_metadata(session_id)
-        
+
         return config
 
     @staticmethod
@@ -153,7 +164,9 @@ class LangGraphRunner(BaseRunner):
 
         thread_id = str(checkpoint_ref.get("thread_id") or session_id or "").strip()
         if not thread_id:
-            raise ValueError("checkpoint_resume requires session_id or framework_ref.langgraph.thread_id")
+            raise ValueError(
+                "checkpoint_resume requires session_id or framework_ref.langgraph.thread_id"
+            )
 
         next_config = dict(config)
         configurable = dict(next_config.get("configurable") or {})
@@ -163,6 +176,18 @@ class LangGraphRunner(BaseRunner):
         next_config["configurable"] = configurable
         return next_config
 
+    @staticmethod
+    def _checkpoint_resume_input(
+        value: Any,
+        *,
+        payload_provided: bool,
+        interrupt_id: str,
+    ) -> Command | None:
+        if not payload_provided:
+            return None
+        resume_value = {interrupt_id: value} if interrupt_id else value
+        return Command(resume=resume_value)
+
     @staticmethod
     def _checkpoint_ref_from_state(state: Any) -> dict[str, Any]:
         state_config = None
@@ -179,17 +204,15 @@ class LangGraphRunner(BaseRunner):
         checkpoint_id = str(configurable.get("checkpoint_id") or "").strip()
         if not thread_id or not checkpoint_id:
             return {}
-        next_nodes_raw = state.get("next") if isinstance(state, dict) else getattr(state, "next", None)
+        next_nodes_raw = (
+            state.get("next") if isinstance(state, dict) else getattr(state, "next", None)
+        )
         next_nodes: list[str] = []
         if isinstance(next_nodes_raw, str):
             if next_nodes_raw.strip():
                 next_nodes = [next_nodes_raw.strip()]
         elif isinstance(next_nodes_raw, (list, tuple, set)):
-            next_nodes = [
-                str(item).strip()
-                for item in next_nodes_raw
-                if str(item or "").strip()
-            ]
+            next_nodes = [str(item).strip() for item in next_nodes_raw if str(item or "").strip()]
         return {
             "langgraph": {
                 "thread_id": thread_id,
@@ -259,11 +282,24 @@ class LangGraphRunner(BaseRunner):
             return self._extract_usage(values)
         return {}
 
+    @staticmethod
+    def _latest_checkpoint_config(config: dict[str, Any]) -> dict[str, Any]:
+        """Select the newest state in a resumed thread, not the source checkpoint."""
+        latest_config = dict(config)
+        configurable = dict(latest_config.get("configurable") or {})
+        configurable.pop("checkpoint_id", None)
+        latest_config["configurable"] = configurable
+        return latest_config
+
     @staticmethod
     def _ambient_context_text(payload: Dict[str, Any]) -> str:
         sections: list[str] = []
         kb_context = payload.get("kb_context") or {}
-        kb_text = str(kb_context.get("formatted_text") or "").strip() if isinstance(kb_context, dict) else ""
+        kb_text = (
+            str(kb_context.get("formatted_text") or "").strip()
+            if isinstance(kb_context, dict)
+            else ""
+        )
         if kb_text:
             sections.append(f"Knowledge base context:\n{kb_text}")
 
@@ -315,6 +351,14 @@ class LangGraphRunner(BaseRunner):
         prepared = prepare_state(dict(normalized_payload), session_context)
         if not isinstance(prepared, dict):
             raise TypeError("ksadk_prepare_state(payload, session_context) must return a dict")
+        # A custom state hook owns application state, but must not accidentally
+        # erase protocol namespaces that framework middleware consumes. In
+        # particular CopilotKit reads ``ag-ui`` to decide whether to inject the
+        # official A2UI tool, and reads ``copilotkit.actions`` for frontend
+        # actions. Keep these namespaces narrow and transport-owned.
+        for namespace in ("ag-ui", "copilotkit"):
+            if namespace in normalized_payload:
+                prepared.setdefault(namespace, normalized_payload[namespace])
         return prepared
 
     def _to_state(self, payload: Dict[str, Any], history: list) -> Dict[str, Any]:
@@ -328,7 +372,7 @@ class LangGraphRunner(BaseRunner):
         if "input" in normalized_payload and "messages" not in normalized_payload:
             from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
 
-            messages = []
+            messages: list[Any] = []
             if system_text:
                 messages.append(SystemMessage(content=system_text))
             for msg in history:
@@ -432,11 +476,11 @@ class LangGraphRunner(BaseRunner):
                 )
                 continue
 
-            file_uri = attachment.get("file_uri")
-            if not file_uri:
+            attachment_uri = attachment.get("file_uri")
+            if not attachment_uri:
                 continue
 
-            raw = read_attachment_uri_bytes(file_uri)
+            raw = read_attachment_uri_bytes(str(attachment_uri))
             if not raw:
                 continue
 
@@ -479,22 +523,72 @@ class LangGraphRunner(BaseRunner):
         )
         return self._agent.invoke(payload, **kwargs)
 
+    async def _invoke_from_stream_events(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        chunks: list[dict[str, Any]] = []
+        accumulated_text = ""
+        final_chunk: dict[str, Any] | None = None
+        metadata: dict[str, Any] = {}
+
+        async for chunk in self.stream(input_data):
+            chunks.append(dict(chunk))
+            chunk_type = chunk.get("type")
+            if chunk_type == "text":
+                accumulated_text += str(chunk.get("delta") or "")
+            elif chunk_type == "final":
+                final_chunk = dict(chunk)
+            elif chunk_type == "checkpoint":
+                chunk_metadata = chunk.get("metadata")
+                if isinstance(chunk_metadata, Mapping):
+                    metadata.update(dict(chunk_metadata))
+            elif chunk_type == "interrupt":
+                return {
+                    "type": "interrupt",
+                    "interrupt_info": chunk.get("interrupt_info"),
+                    "session_id": chunk.get("session_id") or input_data.get("session_id"),
+                    "output": (
+                        chunk.get("interrupt_info", {}).get("message", "需要用户确认")
+                        if isinstance(chunk.get("interrupt_info"), Mapping)
+                        else "需要用户确认"
+                    ),
+                    "raw": {"chunks": chunks},
+                }
+
+        if final_chunk:
+            output_text = str(final_chunk.get("output") or accumulated_text)
+            final_metadata = final_chunk.get("metadata")
+            if isinstance(final_metadata, Mapping):
+                metadata = {**dict(final_metadata), **metadata}
+            result: dict[str, Any] = {"output": output_text, "raw": {"chunks": chunks}}
+            usage = final_chunk.get("usage")
+            if isinstance(usage, Mapping) and usage:
+                result["usage"] = dict(usage)
+            if metadata:
+                result["metadata"] = metadata
+            return result
+
+        return {"output": accumulated_text, "raw": {"chunks": chunks}}
+
     async def invoke(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
         """调用 LangGraph 图
-        
+
         支持两种输入格式：
         1. 简化格式: {"input": "hello"} - 自动转换为 messages
         2. 原生格式: {"messages": [...]} 或自定义 State - 直接透传
         """
         payload = dict(input_data)
+        force_graph_invoke = bool(payload.pop("_ksadk_force_graph_invoke", False))
+        if not force_graph_invoke and hasattr(self._agent, "astream_events"):
+            return await self._invoke_from_stream_events(payload)
+
         session_id = payload.pop("session_id", None) or str(uuid.uuid4())[:8]
         is_resume = payload.pop("resume", False)
         is_checkpoint_resume = bool(payload.pop("checkpoint_resume", False))
+        resume_payload_provided = bool(payload.pop("resume_payload_provided", False))
+        resume_interrupt_id = str(payload.pop("resume_interrupt_id", "") or "")
+        resume_value = payload.get("input")
         checkpoint_ref = self._extract_langgraph_checkpoint_ref(payload)
         history = payload.pop("history", [])
         native_context = self.build_native_context(payload.get("platform_context"))
-        normalized_payload = self._strip_platform_context_fields(payload)
-        
         config = self._get_config(session_id)
         if is_checkpoint_resume:
             config = self._apply_checkpoint_resume_config(
@@ -502,24 +596,29 @@ class LangGraphRunner(BaseRunner):
                 session_id=session_id,
                 checkpoint_ref=checkpoint_ref,
             )
-        
+
         # 判断输入格式 / resume
         if is_checkpoint_resume:
-            state = None
-        elif self._has_prepare_state_hook():
-            state = self._prepare_state_with_hook(payload, session_id, history, is_resume=is_resume)
+            state = resume_value
         elif is_resume:
-            if "input" in normalized_payload and len(normalized_payload) == 1:
-                state = normalized_payload["input"]
-            else:
-                state = normalized_payload
+            # ``Command(resume=...)`` is delivered to the graph's suspended
+            # interrupt. A custom prepare-state hook is for new user input;
+            # applying it here can rewrite an approval decision into ordinary
+            # graph state and turn an approved HITL action into a rejection.
+            state = resume_value
+        elif self._has_prepare_state_hook():
+            state = self._prepare_state_with_hook(payload, session_id, history)
         else:
             state = self._to_state(payload, history)
 
         try:
             if is_checkpoint_resume:
                 result = await self._invoke_graph(
-                    None,
+                    self._checkpoint_resume_input(
+                        state,
+                        payload_provided=resume_payload_provided,
+                        interrupt_id=resume_interrupt_id,
+                    ),
                     config=config,
                     context=native_context,
                 )
@@ -547,7 +646,7 @@ class LangGraphRunner(BaseRunner):
             if metadata:
                 output["metadata"] = {**(output.get("metadata") or {}), **metadata}
             return output
-            
+
         except Exception as e:
             if "Interrupt" in type(e).__name__:
                 interrupt_info = self._get_interrupt_info(self._agent.get_state(config))
@@ -555,7 +654,11 @@ class LangGraphRunner(BaseRunner):
                     "type": "interrupt",
                     "interrupt_info": interrupt_info,
                     "session_id": session_id,
-                    "output": interrupt_info.get("message", "需要用户确认") if isinstance(interrupt_info, dict) else "需要用户确认",
+                    "output": (
+                        interrupt_info.get("message", "需要用户确认")
+                        if isinstance(interrupt_info, dict)
+                        else "需要用户确认"
+                    ),
                 }
             raise
 
@@ -564,16 +667,21 @@ class LangGraphRunner(BaseRunner):
         if isinstance(result, dict):
             # 自定义 output 字段是业务显式出参，优先于内部 messages state。
             if "output" in result:
-                return result["output"]
+                return str(result["output"])
             # LangGraph 示例常用 answer 作为最终业务回答字段。
             if "answer" in result:
-                return result["answer"]
+                return str(result["answer"])
             # 标准 messages 格式
             if "messages" in result:
                 messages = result["messages"]
                 if messages:
                     last = messages[-1]
-                    return last.get("content", str(last)) if isinstance(last, dict) else getattr(last, "content", str(last))
+                    content = (
+                        last.get("content", str(last))
+                        if isinstance(last, dict)
+                        else getattr(last, "content", str(last))
+                    )
+                    return str(content)
         return str(result) if result else ""
 
     def _get_interrupt_info(self, state) -> dict:
@@ -583,12 +691,18 @@ class LangGraphRunner(BaseRunner):
                 if hasattr(task, "interrupts") and task.interrupts:
                     for intr in task.interrupts:
                         if hasattr(intr, "value"):
-                            return intr.value
+                            value = intr.value
+                            info = dict(value) if isinstance(value, Mapping) else {"value": value}
+                            interrupt_id = str(getattr(intr, "id", "") or "")
+                            if interrupt_id:
+                                info.setdefault("approval_request_id", interrupt_id)
+                            return info
         return {}
 
     async def _stream_checkpoint_resume_updates(
         self,
         *,
+        stream_input: Any,
         config: dict[str, Any],
         context: dict[str, Any] | None,
     ) -> AsyncIterator[Dict[str, Any]]:
@@ -605,11 +719,17 @@ class LangGraphRunner(BaseRunner):
 
         latest_output: Any = None
         emitted_update = False
-        async for update in self._agent.astream(None, **kwargs):
+        tool_names: dict[str, str] = {}
+        async for update in self._agent.astream(stream_input, **kwargs):
             emitted_update = True
             latest_output = update
             if isinstance(update, Mapping):
                 for node_name, node_output in update.items():
+                    for tool_event in self._tool_events_from_graph_update(
+                        node_output,
+                        tool_names=tool_names,
+                    ):
+                        yield tool_event
                     yield {
                         "type": "graph_update",
                         "node": str(node_name),
@@ -618,14 +738,15 @@ class LangGraphRunner(BaseRunner):
             else:
                 yield {"type": "graph_update", "output": update}
 
-        state_usage = await self._latest_state_usage(config)
+        latest_config = self._latest_checkpoint_config(config)
+        state_usage = await self._latest_state_usage(latest_config)
         state_output = ""
         try:
             state = None
             if callable(getattr(self._agent, "aget_state", None)):
-                state = await self._agent.aget_state(config)
+                state = await self._agent.aget_state(latest_config)
             elif callable(getattr(self._agent, "get_state", None)):
-                state = self._agent.get_state(config)
+                state = self._agent.get_state(latest_config)
             values = getattr(state, "values", None)
             if values is not None:
                 state_output = self._extract_output(values)
@@ -639,21 +760,93 @@ class LangGraphRunner(BaseRunner):
             **({"resume_noop": True} if not emitted_update else {}),
         }
 
-        metadata = await self._latest_checkpoint_metadata(config)
+        metadata = await self._latest_checkpoint_metadata(latest_config)
         if metadata:
             yield {"type": "checkpoint", "metadata": metadata}
 
+    @staticmethod
+    def _tool_events_from_graph_update(
+        node_output: Any,
+        *,
+        tool_names: dict[str, str],
+    ) -> list[dict[str, Any]]:
+        """Preserve LangGraph update-mode tool messages as structured runner events."""
+
+        if isinstance(node_output, Mapping):
+            messages = node_output.get("messages")
+        else:
+            messages = getattr(node_output, "messages", None)
+        if not isinstance(messages, (list, tuple)):
+            return []
+
+        events: list[dict[str, Any]] = []
+        for message in messages:
+            if isinstance(message, Mapping):
+                tool_calls = message.get("tool_calls")
+                tool_call_id = message.get("tool_call_id")
+                message_name = message.get("name")
+                message_content = message.get("content")
+                message_status = message.get("status")
+            else:
+                tool_calls = getattr(message, "tool_calls", None)
+                tool_call_id = getattr(message, "tool_call_id", None)
+                message_name = getattr(message, "name", None)
+                message_content = getattr(message, "content", None)
+                message_status = getattr(message, "status", None)
+
+            if isinstance(tool_calls, (list, tuple)):
+                for tool_call in tool_calls:
+                    if isinstance(tool_call, Mapping):
+                        call_id = str(tool_call.get("id") or tool_call.get("tool_call_id") or "")
+                        name = str(tool_call.get("name") or "tool")
+                        args = tool_call.get("args")
+                    else:
+                        call_id = str(
+                            getattr(tool_call, "id", None)
+                            or getattr(tool_call, "tool_call_id", None)
+                            or ""
+                        )
+                        name = str(getattr(tool_call, "name", None) or "tool")
+                        args = getattr(tool_call, "args", None)
+                    if call_id:
+                        tool_names[call_id] = name
+                    events.append(
+                        {
+                            "type": "tool_call",
+                            "tool_call_id": call_id or name,
+                            "tool_name": name,
+                            "tool_args": args,
+                        }
+                    )
+
+            if tool_call_id:
+                call_id = str(tool_call_id)
+                name = str(message_name or tool_names.get(call_id) or "tool")
+                status = str(message_status or "").lower()
+                events.append(
+                    {
+                        "type": "tool_result",
+                        "tool_call_id": call_id,
+                        "tool_name": name,
+                        "tool_output": message_content,
+                        "error": message_content if status in {"error", "failed"} else None,
+                    }
+                )
+        return events
+
     async def stream(self, input_data: Dict[str, Any]) -> AsyncIterator[Dict[str, Any]]:
         """流式调用 LangGraph 图"""
         payload = dict(input_data)
+        payload.pop("_ksadk_force_graph_invoke", None)
         session_id = payload.pop("session_id", None) or str(uuid.uuid4())[:8]
         history = payload.pop("history", [])
         is_resume = payload.pop("resume", False)
         is_checkpoint_resume = bool(payload.pop("checkpoint_resume", False))
+        resume_payload_provided = bool(payload.pop("resume_payload_provided", False))
+        resume_interrupt_id = str(payload.pop("resume_interrupt_id", "") or "")
+        resume_value = payload.get("input")
         checkpoint_ref = self._extract_langgraph_checkpoint_ref(payload)
         native_context = self.build_native_context(payload.get("platform_context"))
-        normalized_payload = self._strip_platform_context_fields(payload)
-
         invoke_payload = dict(payload)
         invoke_payload["session_id"] = session_id
         if history:
@@ -662,7 +855,9 @@ class LangGraphRunner(BaseRunner):
             invoke_payload["resume"] = True
         if is_checkpoint_resume:
             invoke_payload["checkpoint_resume"] = True
-        
+            invoke_payload["resume_payload_provided"] = resume_payload_provided
+            invoke_payload["resume_interrupt_id"] = resume_interrupt_id
+
         config = self._get_config(session_id)
         if is_checkpoint_resume:
             config = self._apply_checkpoint_resume_config(
@@ -672,14 +867,13 @@ class LangGraphRunner(BaseRunner):
             )
 
         if is_checkpoint_resume:
-            state = None
-        elif self._has_prepare_state_hook():
-            state = self._prepare_state_with_hook(payload, session_id, history, is_resume=is_resume)
+            state = resume_value
         elif is_resume:
-            if "input" in normalized_payload and len(normalized_payload) == 1:
-                state = normalized_payload["input"]
-            else:
-                state = normalized_payload
+            # Keep the interrupt value intact for ``Command(resume=...)``;
+            # prepare-state hooks only shape fresh user turns.
+            state = resume_value
+        elif self._has_prepare_state_hook():
+            state = self._prepare_state_with_hook(payload, session_id, history)
         else:
             state = self._to_state(payload, history)
 
@@ -689,10 +883,60 @@ class LangGraphRunner(BaseRunner):
         emitted_non_text_event = False
         final_output_text = ""
         final_output_usage: dict[str, Any] = {}
+        final_output_last_usage: dict[str, Any] = {}
+        model_run_usages: dict[str, dict[str, Any]] = {}
+        model_run_order: list[str] = []
+        stream_usage_run_keys: set[str] = set()
+        latest_stream_usage: dict[str, Any] = {}
+
+        def model_run_key(
+            event: Mapping[str, Any],
+            *,
+            fallback_key: str | None = None,
+        ) -> str:
+            raw_run_id = event.get("run_id")
+            return (
+                str(raw_run_id)
+                if raw_run_id
+                else fallback_key or f"model-event-{len(model_run_order)}"
+            )
+
+        def record_model_usage(
+            event: Mapping[str, Any],
+            usage: dict[str, Any],
+            *,
+            fallback_key: str | None = None,
+        ) -> None:
+            if not usage:
+                return
+            run_key = model_run_key(event, fallback_key=fallback_key)
+            if run_key not in model_run_usages:
+                model_run_order.append(run_key)
+            model_run_usages[run_key] = dict(usage)
+
+        def accumulated_model_usage() -> dict[str, Any]:
+            if len(model_run_order) == 1:
+                return dict(model_run_usages.get(model_run_order[0]) or {})
+            usage: dict[str, Any] = {}
+            for run_key in model_run_order:
+                usage = accumulate_usage(usage, model_run_usages.get(run_key) or {})
+            return usage
+
+        def latest_model_usage() -> dict[str, Any]:
+            for run_key in reversed(model_run_order):
+                usage = model_run_usages.get(run_key)
+                if usage:
+                    return dict(usage)
+            return {}
 
         if is_checkpoint_resume and callable(getattr(self._agent, "astream", None)):
             try:
                 async for chunk in self._stream_checkpoint_resume_updates(
+                    stream_input=self._checkpoint_resume_input(
+                        state,
+                        payload_provided=resume_payload_provided,
+                        interrupt_id=resume_interrupt_id,
+                    ),
                     config=config,
                     context=native_context,
                 ):
@@ -720,9 +964,23 @@ class LangGraphRunner(BaseRunner):
             return
 
         try:
-            stream_input = None if is_checkpoint_resume else (Command(resume=state) if is_resume else state)
+            stream_input = (
+                self._checkpoint_resume_input(
+                    state,
+                    payload_provided=resume_payload_provided,
+                    interrupt_id=resume_interrupt_id,
+                )
+                if is_checkpoint_resume
+                else (Command(resume=state) if is_resume else state)
+            )
+            # stream_mode 含 "custom" 才会产生 on_custom_stream 事件(custom writer);
+            # 保留默认 "values" 以兼容既有 on_chain_end/graph_update 消费。
             stream_kwargs = {"version": "v2", "config": config}
-            if native_context and self._callable_accepts_keyword(self._agent.astream_events, "context"):
+            if self._callable_accepts_keyword(self._agent.astream_events, "stream_mode"):
+                stream_kwargs["stream_mode"] = ["values", "custom"]
+            if native_context and self._callable_accepts_keyword(
+                self._agent.astream_events, "context"
+            ):
                 stream_kwargs["context"] = native_context
             async for event in self._agent.astream_events(stream_input, **stream_kwargs):
                 event_kind = event.get("event", "")
@@ -731,12 +989,25 @@ class LangGraphRunner(BaseRunner):
                     chunk = event.get("data", {}).get("chunk")
                     if not chunk:
                         continue
+                    chunk_usage = self._extract_usage(chunk)
+                    if chunk_usage:
+                        # Some LangChain providers attach cumulative usage to
+                        # every stream chunk, and LangChain may then sum those
+                        # cumulative snapshots into an inflated
+                        # on_chat_model_end usage. For a concrete model run,
+                        # keep the latest stream snapshot and ignore the later
+                        # end usage for that same run_id.
+                        latest_stream_usage = dict(chunk_usage)
+                        if event.get("run_id"):
+                            run_key = model_run_key(event)
+                            stream_usage_run_keys.add(run_key)
+                            record_model_usage(event, latest_stream_usage)
 
                     # 推理内容
                     reasoning = getattr(chunk, "reasoning_content", None)
                     if not reasoning and hasattr(chunk, "additional_kwargs"):
                         reasoning = chunk.additional_kwargs.get("reasoning_content")
-                    
+
                     if reasoning:
                         accumulated_reasoning += reasoning
                         yield {"delta": reasoning, "type": "thinking"}
@@ -746,9 +1017,9 @@ class LangGraphRunner(BaseRunner):
                         content = self._filter_tool_tags(chunk.content)
                         if isinstance(content, str):
                             if accumulated_reasoning and content.startswith(accumulated_reasoning):
-                                content = content[len(accumulated_reasoning):]
+                                content = content[len(accumulated_reasoning) :]
                             elif reasoning and content.startswith(reasoning):
-                                content = content[len(reasoning):]
+                                content = content[len(reasoning) :]
                         if content:
                             for part in inline_reasoning_parser.feed(content):
                                 if not part.text or not part.text.strip():
@@ -760,6 +1031,68 @@ class LangGraphRunner(BaseRunner):
                                     accumulated_text += part.text
                                     yield {"delta": part.text, "type": "text"}
 
+                elif event_kind == "on_chat_model_end":
+                    data = event.get("data") or {}
+                    output = data.get("output") if isinstance(data, Mapping) else None
+                    usage = self._extract_usage(output) or self._extract_usage(data)
+                    last_usage = self._extract_last_usage(output) or self._extract_last_usage(data)
+                    run_key = model_run_key(event)
+                    if run_key not in stream_usage_run_keys:
+                        record_model_usage(event, last_usage or usage)
+
+                elif event_kind == "on_chain_stream":
+                    # node 内 get_stream_writer() 写入的自定义数据,经 stream_mode 含
+                    # "custom" 时,astream_events 包成 on_chain_stream,chunk 为
+                    # (mode, value) tuple:("custom", value) 是 writer 透传内容,
+                    # ("values", state) 是 state 快照(忽略,终态走 on_chain_end)。
+                    # 编排方常用 custom writer 把"调远端 agent/子图"的流式增量透传出来。
+                    chunk = event.get("data", {}).get("chunk")
+                    if not (
+                        isinstance(chunk, tuple) and len(chunk) == 2 and chunk[0] == "custom"
+                    ):
+                        continue
+                    data = chunk[1]
+                    if isinstance(data, str):
+                        accumulated_text += data
+                        yield {"delta": data, "type": "text"}
+                        continue
+                    if isinstance(data, Mapping):
+                        custom_type = str(data.get("type") or "text")
+                        if custom_type in ("tool_call", "tool_result"):
+                            # 结构化工具事件:透传完整 payload(tool_name/tool_args/
+                            # tool_output 等),不计入正文,供 UI 渲染工具卡片。
+                            out = {"type": custom_type}
+                            out.update({k: v for k, v in data.items() if k != "type"})
+                            yield out
+                            continue
+                        custom_delta = ""
+                        for key in ("delta", "text", "content", "output", "data"):
+                            value = data.get(key)
+                            if isinstance(value, str) and value:
+                                custom_delta = value
+                                break
+                        if not custom_delta:
+                            continue
+                        replace = bool(data.get("replace"))
+                        if custom_type == "thinking":
+                            accumulated_reasoning = (
+                                custom_delta
+                                if replace
+                                else accumulated_reasoning + custom_delta
+                            )
+                        else:
+                            accumulated_text = (
+                                custom_delta if replace else accumulated_text + custom_delta
+                            )
+                        out = {"delta": custom_delta, "type": custom_type}
+                        if replace:
+                            out["replace"] = True
+                        yield out
+                        continue
+                    if data is not None:
+                        accumulated_text += str(data)
+                        yield {"delta": str(data), "type": "text"}
+
                 elif event_kind == "on_tool_start":
                     emitted_non_text_event = True
                     yield {
@@ -768,23 +1101,35 @@ class LangGraphRunner(BaseRunner):
                         "tool_args": event.get("data", {}).get("input", {}),
                         "run_id": event.get("run_id"),
                     }
-                
+
                 elif event_kind == "on_tool_end":
                     emitted_non_text_event = True
                     tool_output = event.get("data", {}).get("output", "")
+                    # LangGraph returns a ToolMessage here for normal tools.
+                    # Preserve its content instead of serializing the repr,
+                    # otherwise structured output such as A2UI envelopes becomes
+                    # unparsable. Keep the callback run_id below: it is paired
+                    # with the preceding ``on_tool_start`` event on this stream.
+                    normalized_output = getattr(tool_output, "content", tool_output)
+                    if isinstance(tool_output, Mapping) and "content" in tool_output:
+                        normalized_output = tool_output["content"]
                     yield {
                         "type": "tool_result",
                         "tool_name": event.get("name", "unknown"),
                         "tool_args": event.get("data", {}).get("input", {}),
-                        "tool_output": tool_output if isinstance(tool_output, dict) else (str(tool_output) if tool_output else ""),
+                        "tool_output": normalized_output,
                         "run_id": event.get("run_id"),
                     }
-                    
+
                 elif event_kind == "on_chain_end":
                     output = event.get("data", {}).get("output", {})
                     if isinstance(output, dict) and "__interrupt__" in output:
                         emitted_non_text_event = True
-                        yield {"type": "interrupt", "interrupt_info": output["__interrupt__"], "session_id": session_id}
+                        yield {
+                            "type": "interrupt",
+                            "interrupt_info": output["__interrupt__"],
+                            "session_id": session_id,
+                        }
                         return
                     extracted_output = self._extract_output(output)
                     if extracted_output:
@@ -794,10 +1139,41 @@ class LangGraphRunner(BaseRunner):
 
         except Exception as e:
             if "Interrupt" in type(e).__name__:
-                yield {"type": "interrupt", "interrupt_info": self._get_interrupt_info(self._agent.get_state(config)), "session_id": session_id}
+                yield {
+                    "type": "interrupt",
+                    "interrupt_info": self._get_interrupt_info(self._agent.get_state(config)),
+                    "session_id": session_id,
+                }
                 return
             raise
 
+        # goal-18(ksadk-web 人机交互):图因审批门(HITL)在流式中静默暂停时,
+        # 这里把审批详情(action_requests)作为 approval 事件冒出,供 UI 渲染审批卡。
+        # 此前流式路径只在 checkpoint 标 resumable,UI 拿不到"该批哪个工具/什么参数/允许哪些决定"。
+        # 注:get_state 在部分 agent 上是 async,统一按 awaitable 处理;取不到则跳过,不破坏事件流。
+        pending_approval = None
+        try:
+            _get_state = getattr(self._agent, "aget_state", None) or getattr(
+                self._agent, "get_state", None
+            )
+            if _get_state is not None:
+                _maybe_state = _get_state(config)
+                if inspect.isawaitable(_maybe_state):
+                    _maybe_state = await _maybe_state
+                pending_approval = self._get_interrupt_info(_maybe_state)
+        except Exception:
+            pending_approval = None
+        if pending_approval:
+            yield {
+                "type": "approval",
+                "interrupt_info": pending_approval,
+                "session_id": session_id,
+            }
+            metadata = await self._latest_checkpoint_metadata(config)
+            if metadata:
+                yield {"type": "checkpoint", "metadata": metadata}
+            return
+
         for part in inline_reasoning_parser.flush():
             if not part.text or not part.text.strip():
                 continue
@@ -811,32 +1187,51 @@ class LangGraphRunner(BaseRunner):
         if not accumulated_text:
             if final_output_text:
                 final_chunk = {"output": final_output_text, "type": "final"}
-                if final_output_usage:
-                    final_chunk["usage"] = final_output_usage
-                if final_output_last_usage:
-                    final_chunk.setdefault("metadata", {})["last_usage"] = final_output_last_usage
+                usage = accumulated_model_usage() or final_output_usage or latest_stream_usage
+                last_usage = (
+                    latest_model_usage() or final_output_last_usage or latest_stream_usage or usage
+                )
+                if usage:
+                    final_chunk["usage"] = usage
+                if last_usage:
+                    final_chunk.setdefault("metadata", {})["last_usage"] = last_usage
                 yield final_chunk
             elif not emitted_non_text_event:
-                result = await self.invoke(invoke_payload)
-                final_chunk = {"output": result.get("output", ""), "type": "final"}
+                result = await self.invoke({**invoke_payload, "_ksadk_force_graph_invoke": True})
+                fallback_chunk: dict[str, Any] = {
+                    "output": result.get("output", ""),
+                    "type": "final",
+                }
                 usage = self._extract_usage(result)
                 if usage:
-                    final_chunk["usage"] = usage
+                    fallback_chunk["usage"] = usage
                 last_usage = self._extract_last_usage(result)
                 if last_usage:
-                    final_chunk.setdefault("metadata", {})["last_usage"] = last_usage
-                yield final_chunk
-                metadata = result.get("metadata") if isinstance(result, dict) else None
-                if isinstance(metadata, dict) and metadata.get("agentengine"):
-                    yield {"type": "checkpoint", "metadata": metadata}
+                    fallback_chunk.setdefault("metadata", {})["last_usage"] = last_usage
+                yield fallback_chunk
+                checkpoint_metadata = result.get("metadata") if isinstance(result, dict) else None
+                if isinstance(checkpoint_metadata, dict) and checkpoint_metadata.get("agentengine"):
+                    yield {"type": "checkpoint", "metadata": checkpoint_metadata}
                     return
         else:
             final_chunk = {"output": accumulated_text, "type": "final"}
-            usage = await self._latest_state_usage(config)
+            state_usage = await self._latest_state_usage(config)
+            usage = (
+                accumulated_model_usage()
+                or state_usage
+                or final_output_usage
+                or latest_stream_usage
+            )
             if usage:
                 final_chunk["usage"] = usage
-                # _latest_state_usage 返回末个 message usage,单次调用场景即 last_usage
-                final_chunk.setdefault("metadata", {})["last_usage"] = usage
+                last_usage = (
+                    latest_model_usage()
+                    or state_usage
+                    or final_output_last_usage
+                    or latest_stream_usage
+                    or usage
+                )
+                final_chunk.setdefault("metadata", {})["last_usage"] = last_usage
             yield final_chunk
 
         metadata = await self._latest_checkpoint_metadata(config)
@@ -847,6 +1242,6 @@ class LangGraphRunner(BaseRunner):
         """过滤 <tool_call> 标签"""
         if not isinstance(content, str):
             return content
-        content = re.sub(r'<tool_call>.*?</tool_call>', '', content, flags=re.DOTALL)
-        content = re.sub(r'</?(?:tool_call|arg_key|arg_value)>', '', content)
+        content = re.sub(r"<tool_call>.*?</tool_call>", "", content, flags=re.DOTALL)
+        content = re.sub(r"</?(?:tool_call|arg_key|arg_value)>", "", content)
         return content