@langgraph-js/sdk 3.4.0 → 3.5.0

package/dist/LangGraphClient.d.ts

@@ -18,7 +18,6 @@ export type RenderMessage = Message & {
             };
         }[];
     };
-    sub_agent_messages?: RenderMessage[];
     usage_metadata?: {
         total_tokens: number;
         input_tokens: number;
@@ -28,6 +27,7 @@ export type RenderMessage = Message & {
     response_metadata?: {
         create_time: string;
     };
+    sub_messages?: RenderMessage[];
     /** 耗时 */
     spend_time?: number;
     /** 渲染时的唯一 id，聚合而来*/
@@ -43,6 +43,20 @@ export type SendMessageOptions = {
     command?: Command;
     joinRunId?: string;
 };
+export type InterruptData = {
+    id: string;
+    value: {
+        actionRequests: {
+            name: string;
+            description: string;
+            args: any;
+        }[];
+        reviewConfigs: {
+            actionName: string;
+            allowedDecisions: ("approve" | "edit" | "reject")[];
+        }[];
+    };
+}[];
 export interface LangGraphClientConfig {
     apiUrl?: string;
     apiKey?: string;
@@ -119,8 +133,6 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
         run_id: string;
     };
     stopController: AbortController | null;
-    /** 用于存储 subAgent 状态数据的键 */
-    subAgentsKey: string;
     /** Message 处理器 */
     private messageProcessor;
     constructor(config: LangGraphClientConfig);
@@ -128,14 +140,13 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
     get assistants(): {
         search(query?: {
             graphId?: string;
-            metadata? /**
-             * Specify a custom fetch implementation.
-             *
-             * By default we expect the `fetch` is available in the global scope.
-             */: import("@langchain/langgraph-sdk").Metadata;
+            metadata?: import("@langchain/langgraph-sdk").Metadata;
             limit?: number;
             offset?: number;
-            sortBy?: import("@langgraph-js/pure-graph/dist/types.js").AssistantSortBy;
+            sortBy? /**
+             * The maximum number of retries that can be made for a single call,
+             * with an exponential backoff between each attempt. Defaults to 6.
+             */: import("@langgraph-js/pure-graph/dist/types.js").AssistantSortBy;
             sortOrder?: import("@langgraph-js/pure-graph/dist/types.js").SortOrder;
         }): Promise<Assistant[]>;
         getGraph(assistantId: string, options?: {
@@ -223,6 +234,7 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
         messages: Message[];
     }>;
     messagesMetadata: {};
+    humanInTheLoop: InterruptData | null;
     /**
      * @zh 发送消息到 LangGraph 后端。
      * @en Sends a message to the LangGraph backend.

package/dist/LangGraphClient.js

@@ -15,14 +15,13 @@ export class LangGraphClient extends EventEmitter {
         this.availableAssistants = [];
         this.graphState = {};
         this.stopController = null;
-        /** 用于存储 subAgent 状态数据的键 */
-        this.subAgentsKey = "task_store";
         this.messagesMetadata = {};
+        this.humanInTheLoop = null;
         /** 当前子图位置，但是依赖 stream，不太适合稳定使用*/
         this.graphPosition = "";
         this.extraParams = {};
         this.client = config.client;
-        this.messageProcessor = new MessageProcessor(this.subAgentsKey);
+        this.messageProcessor = new MessageProcessor();
     }
     /** 代理 assistants 属性到内部 client */
     get assistants() {
@@ -210,7 +209,6 @@ export class LangGraphClient extends EventEmitter {
      * @en Sends a message to the LangGraph backend.
      */
     async sendMessage(input, { joinRunId, extraParams, _debug, command } = {}) {
-        var _a;
         if (!this.currentAssistant) {
             throw new Error("Thread or Assistant not initialized");
         }
@@ -277,7 +275,10 @@ export class LangGraphClient extends EventEmitter {
             }
             else if (chunk.event === "values") {
                 const data = chunk.data;
-                if (data.messages) {
+                if (data.__interrupt__) {
+                    this.humanInTheLoop = data.__interrupt__;
+                }
+                else if (data.messages) {
                     const isResume = !!(command === null || command === void 0 ? void 0 : command.resume);
                     const isLongerThanLocal = data.messages.length >= this.messageProcessor.getGraphMessages().length;
                     // resume 情况下，长度低于前端 message 的统统不接受
@@ -290,10 +291,6 @@ export class LangGraphClient extends EventEmitter {
                 continue;
             }
             else if (chunk.event.startsWith("values|")) {
-                // 这个 values 必然是子 values
-                if ((_a = chunk.data) === null || _a === void 0 ? void 0 : _a.messages) {
-                    this.messageProcessor.mergeSubGraphMessagesToStreamingMessages(chunk.data.messages);
-                }
                 this.graphPosition = chunk.event.split("|")[1];
             }
         }
@@ -328,17 +325,15 @@ export class LangGraphClient extends EventEmitter {
         // 如果最后一条消息是前端工具消息，则调用工具
         if (lastMessage.type === "ai" && ((_a = lastMessage.tool_calls) === null || _a === void 0 ? void 0 : _a.length)) {
             const result = lastMessage.tool_calls.map((tool) => {
-                if (this.tools.getTool(tool.name)) {
-                    const toolMessage = {
-                        ...tool,
-                        tool_call_id: tool.id,
-                        /** @ts-ignore */
-                        tool_input: JSON.stringify(tool.args),
-                        additional_kwargs: {},
-                    };
-                    // json 校验
-                    return this.callFETool(toolMessage, tool.args);
-                }
+                const toolMessage = {
+                    ...tool,
+                    tool_call_id: tool.id,
+                    /** @ts-ignore */
+                    tool_input: JSON.stringify(tool.args),
+                    additional_kwargs: {},
+                };
+                // json 校验
+                return this.callFETool(toolMessage, tool.args);
             });
             this.currentThread.status = "interrupted"; // 修复某些机制下，状态不为 interrupted 与后端有差异
             return Promise.all(result);

package/dist/MessageProcessor.d.ts

@@ -13,12 +13,11 @@ export declare class StreamingMessageType {
  * @en The MessageProcessor class is used to uniformly handle Message-related logic and avoid duplicate processing.
  */
 export declare class MessageProcessor {
-    private subAgentsKey;
     /** 流式消息缓存 */
     private streamingMessage;
     /** 图发过来的更新信息 */
     private graphMessages;
-    constructor(subAgentsKey?: string);
+    constructor();
     /**
      * @zh 获取流式消息
      * @en Get streaming messages
@@ -54,11 +53,6 @@ export declare class MessageProcessor {
      * @en Combine graphMessages and streamingMessage and return a new message array
      */
     combineGraphMessagesWithStreamingMessages(): RenderMessage[];
-    /**
-     * @zh 子图的数据需要通过 merge 的方式重新进行合并更新
-     * @en Subgraph data needs to be merged and updated through merge method
-     */
-    mergeSubGraphMessagesToStreamingMessages(messages: Message[]): void;
     /**
      * @zh 克隆消息对象
      * @en Clone message object
@@ -74,27 +68,21 @@ export declare class MessageProcessor {
      * @en Composes tool messages, associating AI tool calls with tool execution results.
      */
     composeToolMessages(messages: RenderMessage[]): RenderMessage[];
-    /**
-     * @zh 转换 subAgent 消息为工具的子消息
-     * @en Convert subAgent messages to tool sub-messages
-     */
-    convertSubAgentMessages(messages: RenderMessage[], graphState: any, messagesMetadata: Record<string, {
-        subagent_id?: string;
-    }>): RenderMessage[];
     /**
      * @zh 生成用于 UI 中的流式渲染的消息
      * @en Generate messages used for streaming rendering in the UI
      */
     renderMessages(graphState: any, getGraphNodeNow: () => {
         name: string;
-    }, messagesMetadata: Record<string, {
-        subagent_id?: string;
-    }>): RenderMessage[];
+    }, messagesMetadata: Record<string, any>): RenderMessage[];
+    foldTreeMessages(messages: RenderMessage[], graphState?: {
+        task_store?: Record<string, {
+            messages: RenderMessage[];
+        }>;
+    }, messagesMetadata?: Record<string, any>): RenderMessage[];
     /**
      * @zh 统一的消息处理入口，按顺序执行所有处理步骤
      * @en Unified message processing entry point, executing all processing steps in order
      */
-    processMessages(messages: RenderMessage[], graphState: any, messagesMetadata: Record<string, {
-        subagent_id?: string;
-    }>): RenderMessage[];
+    processMessages(messages: RenderMessage[], graphState?: any, messagesMetadata?: Record<string, any>): RenderMessage[];
 }

package/dist/MessageProcessor.js

@@ -17,12 +17,11 @@ export class StreamingMessageType {
  * @en The MessageProcessor class is used to uniformly handle Message-related logic and avoid duplicate processing.
  */
 export class MessageProcessor {
-    constructor(subAgentsKey = "task_store") {
+    constructor() {
         /** 流式消息缓存 */
         this.streamingMessage = [];
         /** 图发过来的更新信息 */
         this.graphMessages = [];
-        this.subAgentsKey = subAgentsKey;
     }
     /**
      * @zh 获取流式消息
@@ -89,26 +88,6 @@ export class MessageProcessor {
             ...idMap.values(),
         ];
     }
-    /**
-     * @zh 子图的数据需要通过 merge 的方式重新进行合并更新
-     * @en Subgraph data needs to be merged and updated through merge method
-     */
-    mergeSubGraphMessagesToStreamingMessages(messages) {
-        const map = new Map(messages.filter((i) => i.id).map((i) => [i.id, i]));
-        this.streamingMessage.forEach((i) => {
-            if (map.has(i.id)) {
-                const newValue = map.get(i.id);
-                Object.assign(i, newValue);
-                map.delete(i.id);
-            }
-        });
-        // 剩余的 message 一定不在 streamMessage 中
-        map.forEach((i) => {
-            if (i.type === "tool" && i.tool_call_id) {
-                this.streamingMessage.push(i);
-            }
-        });
-    }
     /**
      * @zh 克隆消息对象
      * @en Clone message object
@@ -190,59 +169,6 @@ export class MessageProcessor {
         }
         return result;
     }
-    /**
-     * @zh 转换 subAgent 消息为工具的子消息
-     * @en Convert subAgent messages to tool sub-messages
-     */
-    convertSubAgentMessages(messages, graphState, messagesMetadata) {
-        const origin_task_store = graphState[this.subAgentsKey];
-        if (!origin_task_store)
-            return messages;
-        const task_store = JSON.parse(JSON.stringify(origin_task_store));
-        /** 获取 subAgent 消息的 id，用于流式过程中对数据进行标记 */
-        messages
-            .filter((i) => {
-            var _a, _b;
-            return ((_a = messagesMetadata[i.id]) === null || _a === void 0 ? void 0 : _a.subagent_id) || ((_b = i.node_name) === null || _b === void 0 ? void 0 : _b.startsWith("subagent_"));
-        })
-            .forEach((i) => {
-            var _a;
-            const tool_call_id = ((_a = messagesMetadata[i.id]) === null || _a === void 0 ? void 0 : _a.subagent_id) || i.node_name.replace("subagent_", "");
-            const store = task_store[tool_call_id];
-            if (store) {
-                // 根据 id 进行去重
-                const exists = store.messages.some((msg) => msg.id === i.id);
-                if (!exists) {
-                    store.messages.push(i);
-                }
-            }
-            else {
-                task_store[tool_call_id] = {
-                    messages: [i],
-                };
-            }
-        });
-        const ignoreIds = new Set();
-        Object.values(task_store).forEach((task) => {
-            task.messages.forEach((message) => {
-                ignoreIds.add(message.id);
-            });
-        });
-        const result = [];
-        for (const message of messages) {
-            if (message.type === "tool" && message.tool_call_id) {
-                const task = task_store[message.tool_call_id];
-                if (task) {
-                    // 递归处理子消息，但避免重复处理
-                    message.sub_agent_messages = this.processMessages(task.messages, task, messagesMetadata);
-                }
-            }
-            if (message.id && ignoreIds.has(message.id))
-                continue;
-            result.push(message);
-        }
-        return result;
-    }
     /**
      * @zh 生成用于 UI 中的流式渲染的消息
      * @en Generate messages used for streaming rendering in the UI
@@ -307,6 +233,51 @@ export class MessageProcessor {
         }
         return this.processMessages(result, graphState, messagesMetadata);
     }
+    foldTreeMessages(messages, graphState, messagesMetadata) {
+        const state_sub_messages = Object.entries((graphState === null || graphState === void 0 ? void 0 : graphState.task_store) || {}).map(([key, value]) => [key, value.messages]);
+        const state_sub_messages_map = new Map(state_sub_messages);
+        const nonRootMessageId = new Set();
+        const parentPointer = new Map(Object.entries(messagesMetadata || {})
+            .map(([childId, metadata]) => {
+            if (metadata === null || metadata === void 0 ? void 0 : metadata.parent_id) {
+                nonRootMessageId.add(childId);
+                return [childId, metadata === null || metadata === void 0 ? void 0 : metadata.parent_id];
+            }
+            return;
+        })
+            .filter((i) => i !== undefined));
+        // 第一遍遍历：构建 childrenMap，将子消息归类到父消息下
+        const childrenMap = state_sub_messages_map;
+        const rootMessages = [];
+        for (const message of messages) {
+            const isRoot = !nonRootMessageId.has(message.id);
+            if (!isRoot) {
+                // 处理子消息
+                const parentId = parentPointer.get(message.id);
+                const children = childrenMap.get(parentId);
+                if (children) {
+                    children.push(message);
+                }
+                else {
+                    childrenMap.set(parentId, [message]);
+                }
+            }
+            else {
+                // 收集根消息
+                rootMessages.push(message);
+            }
+        }
+        // 第二遍遍历：为所有根消息赋值 sub_messages
+        for (const rootMessage of rootMessages) {
+            rootMessage.sub_messages = childrenMap.get(rootMessage.id) || [];
+            if (rootMessage.type === "tool" && childrenMap.has(rootMessage.tool_call_id)) {
+                rootMessage.sub_messages.unshift(...childrenMap.get(rootMessage.tool_call_id));
+                // 根据 id 去重
+                rootMessage.sub_messages = rootMessage.sub_messages.filter((i, index, self) => self.findIndex((t) => t.id === i.id) === index);
+            }
+        }
+        return rootMessages;
+    }
     /**
      * @zh 统一的消息处理入口，按顺序执行所有处理步骤
      * @en Unified message processing entry point, executing all processing steps in order
@@ -316,10 +287,7 @@ export class MessageProcessor {
         const composedMessages = this.composeToolMessages(messages);
         // 2. 附加信息
         const messagesWithInfo = this.attachInfoForMessage(composedMessages);
-        // 3. 转换子代理消息（如果提供了 graphState）
-        if (graphState) {
-            return this.convertSubAgentMessages(messagesWithInfo, graphState, messagesMetadata);
-        }
-        return messagesWithInfo;
+        // 3. 折叠树状消息（如果提供了 messagesMetadata）
+        return this.foldTreeMessages(messagesWithInfo, graphState, messagesMetadata);
     }
 }

package/dist/TestKit.d.ts

@@ -178,7 +178,6 @@ export declare class TestLangGraphChat {
                 };
             }[];
         };
-        sub_agent_messages?: RenderMessage[];
         usage_metadata?: {
             total_tokens: number;
             input_tokens: number;
@@ -188,6 +187,7 @@ export declare class TestLangGraphChat {
         response_metadata?: {
             create_time: string;
         };
+        sub_messages?: RenderMessage[];
         spend_time?: number;
         unique_id?: string;
         done?: boolean;
@@ -252,7 +252,6 @@ export declare class TestLangGraphChat {
                 };
             }[];
         };
-        sub_agent_messages?: RenderMessage[];
         usage_metadata?: {
             total_tokens: number;
             input_tokens: number;
@@ -262,6 +261,7 @@ export declare class TestLangGraphChat {
         response_metadata?: {
             create_time: string;
         };
+        sub_messages?: RenderMessage[];
         spend_time?: number;
         unique_id?: string;
         done?: boolean;
@@ -299,7 +299,6 @@ export declare class TestLangGraphChat {
                 };
             }[];
         };
-        sub_agent_messages?: RenderMessage[];
         usage_metadata?: {
             total_tokens: number;
             input_tokens: number;
@@ -309,6 +308,7 @@ export declare class TestLangGraphChat {
         response_metadata?: {
             create_time: string;
         };
+        sub_messages?: RenderMessage[];
         spend_time?: number;
         unique_id?: string;
         done?: boolean;

package/dist/ToolManager.js

@@ -14,8 +14,8 @@ export class ToolManager {
      * @en Registers a tool.
      */
     bindTool(tool) {
-        if (this.tools.has(tool.name)) {
-            throw new Error(`Tool with name ${tool.name} already exists`);
+        if (this.tools.has(tool.name) && tool.name !== "__default__") {
+            console.warn(`Tool with name ${tool.name} already exists`);
         }
         this.tools.set(tool.name, tool);
     }
@@ -67,10 +67,7 @@ export class ToolManager {
      */
     async callTool(name, args, context) {
         var _a;
-        const tool = this.getTool(name);
-        if (!tool) {
-            throw new Error(`Tool with name ${name} not found`);
-        }
+        const tool = this.getTool(name) || this.getTool("__default__");
         return await ((_a = tool.execute) === null || _a === void 0 ? void 0 : _a.call(tool, args, context));
     }
     /**

package/dist/artifacts/types.d.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 export declare const ArtifactCommandSchema: {
-    command: z.ZodEnum<["create", "update", "rewrite"]>;
+    command: z.ZodEnum<{
+        create: "create";
+        update: "update";
+        rewrite: "rewrite";
+    }>;
     id: z.ZodString;
     title: z.ZodString;
     type: z.ZodString;

package/dist/tool/createTool.d.ts

@@ -1,4 +1,4 @@
-import { z, ZodRawShape, ZodTypeAny } from "zod";
+import { z, ZodRawShape } from "zod";
 import { Action, Parameter } from "./copilotkit-actions.js";
 import { Message } from "@langchain/langgraph-sdk";
 import { ToolRenderData } from "./ToolUI.js";
@@ -11,8 +11,8 @@ export interface UnionTool<Args extends ZodRawShape, Child extends Object = Obje
     execute?: ToolCallback<Args>;
     /** 工具执行成功后触发的附加消息 */
     callbackMessage?: (result: CallToolResult) => Message[];
-    handler?: (args: z.objectOutputType<Args, ZodTypeAny>, context?: any) => ResponseType | Promise<ResponseType>;
-    render?: (tool: ToolRenderData<z.objectOutputType<Args, ZodTypeAny>, ResponseType>) => Child;
+    handler?: (args: z.infer<z.ZodObject<Args>>, context?: any) => ResponseType | Promise<ResponseType>;
+    render?: (tool: ToolRenderData<z.infer<z.ZodObject<Args>>, ResponseType>) => Child;
     onlyRender?: boolean;
     /** 只允许指定的 agent 使用该工具，如果未指定，则所有 agent 都可以使用 */
     allowAgent?: string[];
@@ -21,7 +21,7 @@ export interface UnionTool<Args extends ZodRawShape, Child extends Object = Obje
     /** 是否是纯净的 json schema 参数，而不是 zod 参数 */
     isPureParams?: boolean;
 }
-export type ToolCallback<Args extends ZodRawShape> = (args: z.objectOutputType<Args, ZodTypeAny>, context?: any) => CallToolResult | Promise<CallToolResult>;
+export type ToolCallback<Args extends ZodRawShape> = (args: z.infer<z.ZodObject<Args>>, context?: any) => CallToolResult | Promise<CallToolResult>;
 export type CallToolResult = string | {
     type: "text";
     text: string;
@@ -70,7 +70,7 @@ export declare const createJSONDefineTool: <Args extends ZodRawShape>(tool: Unio
             [key: string]: import("zod-to-json-schema").JsonSchema7Type;
         } | undefined;
     }) | ({
-        type: ("string" | "number" | "boolean" | "integer" | "null") | ("string" | "number" | "boolean" | "integer" | "null")[];
+        type: ("string" | "number" | "boolean" | "null" | "integer") | ("string" | "number" | "boolean" | "null" | "integer")[];
     } & {
         title?: string;
         default?: any;
@@ -149,7 +149,7 @@ export declare const createJSONDefineTool: <Args extends ZodRawShape>(tool: Unio
         } | undefined;
     });
 };
-export declare const createMCPTool: <Args extends ZodRawShape>(tool: UnionTool<Args>) => (string | Args | ((args: z.objectOutputType<Args, ZodTypeAny>) => Promise<{
+export declare const createMCPTool: <Args extends ZodRawShape>(tool: UnionTool<Args>) => (string | Args | ((args: z.infer<z.ZodObject<Args>>) => Promise<{
     content: {
         type: string;
         text: string;

package/dist/tool/createTool.js

@@ -17,6 +17,9 @@ export const createUITool = (tool) => {
                 if (typeof result === "string") {
                     return [{ type: "text", text: result }];
                 }
+                else if (result.decisions) {
+                    return result;
+                }
                 return [{ type: "text", text: JSON.stringify(result) }];
             }
             catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langgraph-js/sdk",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "The UI SDK for LangGraph - seamlessly integrate your AI agents with frontend interfaces",
   "main": "dist/index.js",
   "type": "module",
@@ -49,7 +49,7 @@
     "jsonrepair": "^3.12.0",
     "nanostores": "^1.0.1",
     "ts-debounce": "^4.0.0",
-    "zod": "^3.25.17",
+    "zod": "^4",
     "zod-to-json-schema": "^3.24.5"
   },
   "peerDependencies": {

package/src/LangGraphClient.ts

@@ -21,7 +21,6 @@ export type RenderMessage = Message & {
             };
         }[];
     };
-    sub_agent_messages?: RenderMessage[];
     usage_metadata?: {
         total_tokens: number;
         input_tokens: number;
@@ -31,6 +30,8 @@ export type RenderMessage = Message & {
     response_metadata?: {
         create_time: string;
     };
+    // 子消息
+    sub_messages?: RenderMessage[];
     /** 耗时 */
     spend_time?: number;
     /** 渲染时的唯一 id，聚合而来*/
@@ -44,6 +45,20 @@ export type SendMessageOptions = {
     command?: Command;
     joinRunId?: string;
 };
+export type InterruptData = {
+    id: string;
+    value: {
+        actionRequests: {
+            name: string;
+            description: string;
+            args: any;
+        }[];
+        reviewConfigs: {
+            actionName: string;
+            allowedDecisions: ("approve" | "edit" | "reject")[];
+        }[];
+    };
+}[];
 export interface LangGraphClientConfig {
     apiUrl?: string;
     apiKey?: string;
@@ -101,15 +116,13 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
     graphState: any = {};
     currentRun?: { run_id: string };
     stopController: AbortController | null = null;
-    /** 用于存储 subAgent 状态数据的键 */
-    subAgentsKey = "task_store";
     /** Message 处理器 */
     private messageProcessor: MessageProcessor;
 
     constructor(config: LangGraphClientConfig) {
         super();
         this.client = config.client;
-        this.messageProcessor = new MessageProcessor(this.subAgentsKey);
+        this.messageProcessor = new MessageProcessor();
     }
 
     /** 代理 assistants 属性到内部 client */
@@ -305,6 +318,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
         return state;
     }
     public messagesMetadata = {};
+    public humanInTheLoop: InterruptData | null = null;
     /**
      * @zh 发送消息到 LangGraph 后端。
      * @en Sends a message to the LangGraph backend.
@@ -358,6 +372,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
         this.emit("start", {
             event: "start",
         });
+
         for await (const chunk of streamResponse) {
             streamRecord.push(chunk);
             if (chunk.event === "metadata") {
@@ -374,9 +389,14 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
                 this.emit("message", chunk);
                 continue;
             } else if (chunk.event === "values") {
-                const data = chunk.data as { messages: Message[] };
+                const data = chunk.data as {
+                    __interrupt__?: InterruptData;
+                    messages: Message[];
+                };
 
-                if (data.messages) {
+                if (data.__interrupt__) {
+                    this.humanInTheLoop = data.__interrupt__;
+                } else if (data.messages) {
                     const isResume = !!command?.resume;
                     const isLongerThanLocal = data.messages.length >= this.messageProcessor.getGraphMessages().length;
                     // resume 情况下，长度低于前端 message 的统统不接受
@@ -388,10 +408,6 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
                 }
                 continue;
             } else if (chunk.event.startsWith("values|")) {
-                // 这个 values 必然是子 values
-                if (chunk.data?.messages) {
-                    this.messageProcessor.mergeSubGraphMessagesToStreamingMessages(chunk.data.messages);
-                }
                 this.graphPosition = chunk.event.split("|")[1];
             }
         }
@@ -426,17 +442,15 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
         // 如果最后一条消息是前端工具消息，则调用工具
         if (lastMessage.type === "ai" && lastMessage.tool_calls?.length) {
             const result = lastMessage.tool_calls.map((tool) => {
-                if (this.tools.getTool(tool.name!)) {
-                    const toolMessage: ToolMessage = {
-                        ...tool,
-                        tool_call_id: tool.id!,
-                        /** @ts-ignore */
-                        tool_input: JSON.stringify(tool.args),
-                        additional_kwargs: {},
-                    };
-                    // json 校验
-                    return this.callFETool(toolMessage, tool.args);
-                }
+                const toolMessage: ToolMessage = {
+                    ...tool,
+                    tool_call_id: tool.id!,
+                    /** @ts-ignore */
+                    tool_input: JSON.stringify(tool.args),
+                    additional_kwargs: {},
+                };
+                // json 校验
+                return this.callFETool(toolMessage, tool.args);
             });
             this.currentThread!.status = "interrupted"; // 修复某些机制下，状态不为 interrupted 与后端有差异
             return Promise.all(result);

package/src/MessageProcessor.ts

@@ -21,15 +21,12 @@ export class StreamingMessageType {
  * @en The MessageProcessor class is used to uniformly handle Message-related logic and avoid duplicate processing.
  */
 export class MessageProcessor {
-    private subAgentsKey: string;
     /** 流式消息缓存 */
     private streamingMessage: RenderMessage[] = [];
     /** 图发过来的更新信息 */
     private graphMessages: RenderMessage[] = [];
 
-    constructor(subAgentsKey: string = "task_store") {
-        this.subAgentsKey = subAgentsKey;
-    }
+    constructor() {}
 
     /**
      * @zh 获取流式消息
@@ -103,27 +100,6 @@ export class MessageProcessor {
         ];
     }
 
-    /**
-     * @zh 子图的数据需要通过 merge 的方式重新进行合并更新
-     * @en Subgraph data needs to be merged and updated through merge method
-     */
-    mergeSubGraphMessagesToStreamingMessages(messages: Message[]): void {
-        const map = new Map(messages.filter((i) => i.id).map((i) => [i.id!, i]));
-        this.streamingMessage.forEach((i) => {
-            if (map.has(i.id!)) {
-                const newValue = map.get(i.id!)!;
-                Object.assign(i, newValue);
-                map.delete(i.id!);
-            }
-        });
-        // 剩余的 message 一定不在 streamMessage 中
-        map.forEach((i) => {
-            if (i.type === "tool" && i.tool_call_id) {
-                this.streamingMessage.push(i as RenderMessage);
-            }
-        });
-    }
-
     /**
      * @zh 克隆消息对象
      * @en Clone message object
@@ -212,82 +188,11 @@ export class MessageProcessor {
         return result;
     }
 
-    /**
-     * @zh 转换 subAgent 消息为工具的子消息
-     * @en Convert subAgent messages to tool sub-messages
-     */
-    convertSubAgentMessages(
-        messages: RenderMessage[],
-        graphState: any,
-        messagesMetadata: Record<
-            string,
-            {
-                subagent_id?: string;
-            }
-        >
-    ): RenderMessage[] {
-        const origin_task_store = graphState[this.subAgentsKey];
-        if (!origin_task_store) return messages;
-
-        const task_store = JSON.parse(JSON.stringify(origin_task_store));
-
-        /** 获取 subAgent 消息的 id，用于流式过程中对数据进行标记 */
-        messages
-            .filter((i) => {
-                return messagesMetadata[i.id!]?.subagent_id || i.node_name?.startsWith("subagent_");
-            })
-            .forEach((i) => {
-                const tool_call_id = messagesMetadata[i.id!]?.subagent_id || i.node_name!.replace("subagent_", "");
-                const store = task_store[tool_call_id];
-                if (store) {
-                    // 根据 id 进行去重
-                    const exists = (store.messages as RenderMessage[]).some((msg) => msg.id === i.id);
-                    if (!exists) {
-                        (store.messages as RenderMessage[]).push(i);
-                    }
-                } else {
-                    task_store[tool_call_id] = {
-                        messages: [i],
-                    };
-                }
-            });
-
-        const ignoreIds = new Set<string>();
-        Object.values(task_store).forEach((task: any) => {
-            task.messages.forEach((message: RenderMessage) => {
-                ignoreIds.add(message.id!);
-            });
-        });
-
-        const result: RenderMessage[] = [];
-        for (const message of messages) {
-            if (message.type === "tool" && message.tool_call_id) {
-                const task = task_store[message.tool_call_id];
-                if (task) {
-                    // 递归处理子消息，但避免重复处理
-                    message.sub_agent_messages = this.processMessages(task.messages, task, messagesMetadata);
-                }
-            }
-            if (message.id && ignoreIds.has(message.id)) continue;
-            result.push(message);
-        }
-        return result;
-    }
-
     /**
      * @zh 生成用于 UI 中的流式渲染的消息
      * @en Generate messages used for streaming rendering in the UI
      */
-    renderMessages(
-        graphState: any,
-        getGraphNodeNow: () => { name: string },
-        messagesMetadata: Record<
-            string,
-            {
-                subagent_id?: string;
-            }
-        >
-    ): RenderMessage[] {
+    renderMessages(graphState: any, getGraphNodeNow: () => { name: string }, messagesMetadata: Record<string, any>): RenderMessage[] {
         const previousMessage = new Map<string, Message>();
         const closedToolCallIds = new Set<string>();
         const result: Message[] = [];
@@ -349,31 +254,78 @@ export class MessageProcessor {
         return this.processMessages(result as RenderMessage[], graphState, messagesMetadata);
     }
 
+    foldTreeMessages(
+        messages: RenderMessage[],
+        graphState?: {
+            task_store?: Record<
+                string,
+                {
+                    messages: RenderMessage[];
+                }
+            >;
+        },
+        messagesMetadata?: Record<string, any>
+    ): RenderMessage[] {
+        const state_sub_messages = Object.entries(graphState?.task_store || {}).map(([key, value]) => [key, value.messages] as [string, RenderMessage[]]);
+        const state_sub_messages_map = new Map<string, RenderMessage[]>(state_sub_messages);
+
+        const nonRootMessageId = new Set<string>();
+        const parentPointer = new Map(
+            Object.entries(messagesMetadata || {})
+                .map(([childId, metadata]) => {
+                    if (metadata?.parent_id) {
+                        nonRootMessageId.add(childId);
+                        return [childId, metadata?.parent_id];
+                    }
+                    return;
+                })
+                .filter((i): i is [string, string] => i !== undefined)
+        );
+
+        // 第一遍遍历：构建 childrenMap，将子消息归类到父消息下
+        const childrenMap = state_sub_messages_map;
+        const rootMessages: RenderMessage[] = [];
+
+        for (const message of messages) {
+            const isRoot = !nonRootMessageId.has(message.id!);
+            if (!isRoot) {
+                // 处理子消息
+                const parentId = parentPointer.get(message.id!)!;
+                const children = childrenMap.get(parentId);
+                if (children) {
+                    children.push(message);
+                } else {
+                    childrenMap.set(parentId, [message]);
+                }
+            } else {
+                // 收集根消息
+                rootMessages.push(message);
+            }
+        }
+
+        // 第二遍遍历：为所有根消息赋值 sub_messages
+        for (const rootMessage of rootMessages) {
+            rootMessage.sub_messages = childrenMap.get(rootMessage.id!) || [];
+            if (rootMessage.type === "tool" && childrenMap.has(rootMessage.tool_call_id)) {
+                rootMessage.sub_messages.unshift(...childrenMap.get(rootMessage.tool_call_id)!);
+                // 根据 id 去重
+                rootMessage.sub_messages = rootMessage.sub_messages.filter((i, index, self) => self.findIndex((t) => t.id === i.id) === index);
+            }
+        }
+        return rootMessages;
+    }
     /**
      * @zh 统一的消息处理入口，按顺序执行所有处理步骤
      * @en Unified message processing entry point, executing all processing steps in order
      */
-    processMessages(
-        messages: RenderMessage[],
-        graphState: any,
-        messagesMetadata: Record<
-            string,
-            {
-                subagent_id?: string;
-            }
-        >
-    ): RenderMessage[] {
+    processMessages(messages: RenderMessage[], graphState?: any, messagesMetadata?: Record<string, any>): RenderMessage[] {
         // 1. 组合工具消息
         const composedMessages = this.composeToolMessages(messages);
 
         // 2. 附加信息
         const messagesWithInfo = this.attachInfoForMessage(composedMessages);
 
-        // 3. 转换子代理消息（如果提供了 graphState）
-        if (graphState) {
-            return this.convertSubAgentMessages(messagesWithInfo, graphState, messagesMetadata);
-        }
-
-        return messagesWithInfo;
+        // 3. 折叠树状消息（如果提供了 messagesMetadata）
+        return this.foldTreeMessages(messagesWithInfo, graphState, messagesMetadata);
     }
 }

package/src/ToolManager.ts

@@ -15,8 +15,8 @@ export class ToolManager {
      * @en Registers a tool.
      */
     bindTool(tool: UnionTool<any>) {
-        if (this.tools.has(tool.name)) {
-            throw new Error(`Tool with name ${tool.name} already exists`);
+        if (this.tools.has(tool.name) && tool.name !== "__default__") {
+            console.warn(`Tool with name ${tool.name} already exists`);
         }
         this.tools.set(tool.name, tool);
     }
@@ -73,10 +73,7 @@ export class ToolManager {
      * @en Calls the tool with the specified name.
      */
     async callTool(name: string, args: any, context: { client: LangGraphClient; message: ToolMessage }) {
-        const tool = this.getTool(name);
-        if (!tool) {
-            throw new Error(`Tool with name ${name} not found`);
-        }
+        const tool = this.getTool(name) || this.getTool("__default__")!;
         return await tool.execute?.(args, context);
     }
 

package/src/tool/createTool.ts

@@ -1,5 +1,5 @@
 import { actionParametersToJsonSchema, convertJsonSchemaToZodRawShape } from "./utils.js";
-import { z, ZodRawShape, ZodTypeAny } from "zod";
+import { z, ZodRawShape } from "zod";
 import { Action, Parameter } from "./copilotkit-actions.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { Message } from "@langchain/langgraph-sdk";
@@ -14,8 +14,8 @@ export interface UnionTool<Args extends ZodRawShape, Child extends Object = Obje
     execute?: ToolCallback<Args>;
     /** 工具执行成功后触发的附加消息 */
     callbackMessage?: (result: CallToolResult) => Message[];
-    handler?: (args: z.objectOutputType<Args, ZodTypeAny>, context?: any) => ResponseType | Promise<ResponseType>;
-    render?: (tool: ToolRenderData<z.objectOutputType<Args, ZodTypeAny>, ResponseType>) => Child;
+    handler?: (args: z.infer<z.ZodObject<Args>>, context?: any) => ResponseType | Promise<ResponseType>;
+    render?: (tool: ToolRenderData<z.infer<z.ZodObject<Args>>, ResponseType>) => Child;
     onlyRender?: boolean;
     /** 只允许指定的 agent 使用该工具，如果未指定，则所有 agent 都可以使用 */
     allowAgent?: string[];
@@ -24,7 +24,7 @@ export interface UnionTool<Args extends ZodRawShape, Child extends Object = Obje
     /** 是否是纯净的 json schema 参数，而不是 zod 参数 */
     isPureParams?: boolean;
 }
-export type ToolCallback<Args extends ZodRawShape> = (args: z.objectOutputType<Args, ZodTypeAny>, context?: any) => CallToolResult | Promise<CallToolResult>;
+export type ToolCallback<Args extends ZodRawShape> = (args: z.infer<z.ZodObject<Args>>, context?: any) => CallToolResult | Promise<CallToolResult>;
 
 export type CallToolResult = string | { type: "text"; text: string }[];
 
@@ -44,6 +44,8 @@ export const createUITool = <Args extends ZodRawShape, Child extends Object = {}
                 const result = await tool.handler?.(args, context);
                 if (typeof result === "string") {
                     return [{ type: "text", text: result }];
+                } else if (result.decisions) {
+                    return result;
                 }
                 return [{ type: "text", text: JSON.stringify(result) }];
             } catch (error) {
@@ -80,7 +82,7 @@ export const createFETool = <const T extends Parameter[], Args extends ZodRawSha
         allowGraph: tool.allowGraph,
         async execute(args, context) {
             try {
-                const result = await tool.handler?.(args, context);
+                const result = await tool.handler?.(args as any, context);
                 if (typeof result === "string") {
                     return [{ type: "text", text: result }];
                 }
@@ -106,7 +108,7 @@ export const createMCPTool = <Args extends ZodRawShape>(tool: UnionTool<Args>) =
         tool.name,
         tool.description,
         tool.parameters,
-        async (args: z.objectOutputType<Args, ZodTypeAny>) => {
+        async (args: z.infer<z.ZodObject<Args>>) => {
             try {
                 const result = await tool.execute?.(args);
                 if (typeof result === "string") {