@langgraph-js/sdk 1.7.10 → 1.8.0

package/README.md

@@ -1,163 +1,163 @@
-# @langgraph-js/sdk
-
-![npm version](https://img.shields.io/npm/v/@langgraph-js/sdk)
-![license](https://img.shields.io/npm/l/@langgraph-js/sdk)
-
-> The missing UI SDK for LangGraph - seamlessly integrate your AI agents with frontend interfaces
-
-## Why @langgraph-js/sdk?
-
-Building AI agent applications is complex, especially when you need to bridge the gap between LangGraph agents and interactive user interfaces. This SDK solves the critical challenges of frontend integration:
-
-- **Provides a complete UI integration layer** - no more complex custom code to handle tools, streaming, and state management
-- **Simplifies human-in-the-loop interactions** - easily incorporate user feedback within agent workflows
-- **Handles edge cases automatically** - interruptions, errors, token management and more
-- **Offers a rich set of UI components** - ready-to-use elements to display agent interactions
-
-[DOCS](https://langgraph-js.netlify.app)
-
-## Installation
-
-```bash
-# Using npm
-npm install @langgraph-js/sdk
-
-# Using yarn
-yarn add @langgraph-js/sdk
-
-# Using pnpm
-pnpm add @langgraph-js/sdk
-```
-
-## Key Features
-
-### Generative UI
-
-- ✅ Custom Tool Messages
-- ✅ Token Counter
-- ✅ Stop Graph Progress
-- ✅ Interrupt Handling
-- ✅ Error Handling
-- ✅ Spend Time Tracking
-- ✅ Time Persistence
-
-### Frontend Actions
-
-- ✅ Definition of Union Tools
-- ✅ Frontend Functions As Tools
-- ✅ Human-in-the-Loop Interaction
-- ✅ Interrupt Mode
-
-### Authorization
-
-- ✅ Cookie-Based Authentication
-- ✅ Custom Token Authentication
-
-### Persistence
-
-- ✅ Read History from LangGraph
-
-## Advanced Usage
-
-### Creating a Chat Store
-
-You can easily create a reactive store for your LangGraph client:
-
-```typescript
-import { createChatStore } from "@langgraph-js/sdk";
-
-export const globalChatStore = createChatStore(
-    "agent",
-    {
-        // Custom LangGraph backend interaction
-        apiUrl: "http://localhost:8123",
-        // Custom headers for authentication
-        defaultHeaders: JSON.parse(localStorage.getItem("code") || "{}"),
-        callerOptions: {
-            // Example for including cookies
-            // fetch(url: string, options: RequestInit) {
-            //     options.credentials = "include";
-            //     return fetch(url, options);
-            // },
-        },
-    },
-    {
-        onInit(client) {
-            client.tools.bindTools([]);
-        },
-    }
-);
-```
-
-### React Integration
-
-First, install the nanostores React integration:
-
-```bash
-pnpm i @nanostores/react
-```
-
-Then create a context provider for your chat:
-
-```tsx
-import React, { createContext, useContext, useEffect } from "react";
-import { globalChatStore } from "../store"; // Import your store
-import { UnionStore, useUnionStore } from "@langgraph-js/sdk";
-import { useStore } from "@nanostores/react";
-
-type ChatContextType = UnionStore<typeof globalChatStore>;
-
-const ChatContext = createContext<ChatContextType | undefined>(undefined);
-
-export const useChat = () => {
-    const context = useContext(ChatContext);
-    if (!context) {
-        throw new Error("useChat must be used within a ChatProvider");
-    }
-    return context;
-};
-
-export const ChatProvider = ({ children }) => {
-    // Use store to ensure React gets reactive state updates
-    const store = useUnionStore(globalChatStore, useStore);
-    
-    useEffect(() => {
-        // Initialize client
-        store.initClient().then(() => {
-            // Initialize conversation history
-            store.refreshHistoryList();
-        });
-    }, [store.currentAgent]);
-
-    return <ChatContext.Provider value={store}>{children}</ChatContext.Provider>;
-};
-```
-
-Use it in your components:
-
-```tsx
-export const MyChat = () => {
-    return (
-        <ChatProvider>
-            <ChatComp></ChatComp>
-        </ChatProvider>
-    );
-};
-
-function ChatComp() {
-    const chat = useChat();
-    // Use chat store methods and state here
-}
-```
-
-## Documentation
-
-For complete documentation, visit our [official docs](https://langgraph-js.netlify.app).
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## License
-
-This project is licensed under the Apache-2.0 License.
+# @langgraph-js/sdk
+
+![npm version](https://img.shields.io/npm/v/@langgraph-js/sdk)
+![license](https://img.shields.io/npm/l/@langgraph-js/sdk)
+
+> The missing UI SDK for LangGraph - seamlessly integrate your AI agents with frontend interfaces
+
+## Why @langgraph-js/sdk?
+
+Building AI agent applications is complex, especially when you need to bridge the gap between LangGraph agents and interactive user interfaces. This SDK solves the critical challenges of frontend integration:
+
+- **Provides a complete UI integration layer** - no more complex custom code to handle tools, streaming, and state management
+- **Simplifies human-in-the-loop interactions** - easily incorporate user feedback within agent workflows
+- **Handles edge cases automatically** - interruptions, errors, token management and more
+- **Offers a rich set of UI components** - ready-to-use elements to display agent interactions
+
+[DOCS](https://langgraph-js.netlify.app)
+
+## Installation
+
+```bash
+# Using npm
+npm install @langgraph-js/sdk
+
+# Using yarn
+yarn add @langgraph-js/sdk
+
+# Using pnpm
+pnpm add @langgraph-js/sdk
+```
+
+## Key Features
+
+### Generative UI
+
+- ✅ Custom Tool Messages
+- ✅ Token Counter
+- ✅ Stop Graph Progress
+- ✅ Interrupt Handling
+- ✅ Error Handling
+- ✅ Spend Time Tracking
+- ✅ Time Persistence
+
+### Frontend Actions
+
+- ✅ Definition of Union Tools
+- ✅ Frontend Functions As Tools
+- ✅ Human-in-the-Loop Interaction
+- ✅ Interrupt Mode
+
+### Authorization
+
+- ✅ Cookie-Based Authentication
+- ✅ Custom Token Authentication
+
+### Persistence
+
+- ✅ Read History from LangGraph
+
+## Advanced Usage
+
+### Creating a Chat Store
+
+You can easily create a reactive store for your LangGraph client:
+
+```typescript
+import { createChatStore } from "@langgraph-js/sdk";
+
+export const globalChatStore = createChatStore(
+    "agent",
+    {
+        // Custom LangGraph backend interaction
+        apiUrl: "http://localhost:8123",
+        // Custom headers for authentication
+        defaultHeaders: JSON.parse(localStorage.getItem("code") || "{}"),
+        callerOptions: {
+            // Example for including cookies
+            // fetch(url: string, options: RequestInit) {
+            //     options.credentials = "include";
+            //     return fetch(url, options);
+            // },
+        },
+    },
+    {
+        onInit(client) {
+            client.tools.bindTools([]);
+        },
+    }
+);
+```
+
+### React Integration
+
+First, install the nanostores React integration:
+
+```bash
+pnpm i @nanostores/react
+```
+
+Then create a context provider for your chat:
+
+```tsx
+import React, { createContext, useContext, useEffect } from "react";
+import { globalChatStore } from "../store"; // Import your store
+import { UnionStore, useUnionStore } from "@langgraph-js/sdk";
+import { useStore } from "@nanostores/react";
+
+type ChatContextType = UnionStore<typeof globalChatStore>;
+
+const ChatContext = createContext<ChatContextType | undefined>(undefined);
+
+export const useChat = () => {
+    const context = useContext(ChatContext);
+    if (!context) {
+        throw new Error("useChat must be used within a ChatProvider");
+    }
+    return context;
+};
+
+export const ChatProvider = ({ children }) => {
+    // Use store to ensure React gets reactive state updates
+    const store = useUnionStore(globalChatStore, useStore);
+    
+    useEffect(() => {
+        // Initialize client
+        store.initClient().then(() => {
+            // Initialize conversation history
+            store.refreshHistoryList();
+        });
+    }, [store.currentAgent]);
+
+    return <ChatContext.Provider value={store}>{children}</ChatContext.Provider>;
+};
+```
+
+Use it in your components:
+
+```tsx
+export const MyChat = () => {
+    return (
+        <ChatProvider>
+            <ChatComp></ChatComp>
+        </ChatProvider>
+    );
+};
+
+function ChatComp() {
+    const chat = useChat();
+    // Use chat store methods and state here
+}
+```
+
+## Documentation
+
+For complete documentation, visit our [official docs](https://langgraph-js.netlify.app).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the Apache-2.0 License.

package/dist/LangGraphClient.js

@@ -513,6 +513,9 @@ export class LangGraphClient extends Client {
     async callFETool(message, args) {
         const that = this; // 防止 this 被错误解析
         const result = await this.tools.callTool(message.name, args, { client: that, message });
+        if (!result) {
+            return;
+        }
         return this.resume(result);
     }
     /**

package/dist/ToolManager.d.ts

@@ -47,7 +47,7 @@ export declare class ToolManager {
     callTool(name: string, args: any, context: {
         client: LangGraphClient;
         message: ToolMessage;
-    }): Promise<CallToolResult>;
+    }): Promise<CallToolResult | undefined>;
     /**
      * @zh 将所有工具转换为 JSON 定义格式。
      * @en Converts all tools to JSON definition format.

package/dist/ToolManager.js

@@ -66,11 +66,12 @@ export class ToolManager {
      * @en Calls the tool with the specified name.
      */
     async callTool(name, args, context) {
+        var _a;
         const tool = this.getTool(name);
         if (!tool) {
             throw new Error(`Tool with name ${name} not found`);
         }
-        return await tool.execute(args, context);
+        return await ((_a = tool.execute) === null || _a === void 0 ? void 0 : _a.call(tool, args, context));
     }
     /**
      * @zh 将所有工具转换为 JSON 定义格式。

package/dist/server/createState.d.ts

@@ -0,0 +1,13 @@
+import { AnnotationRoot, StateDefinition } from "@langchain/langgraph";
+/**
+ * create state for langgraph
+ * @example
+ * export const GraphState = createState(createReactAgentAnnotation(), ModelState, SwarmState).build({
+ *   current_plan: createDefaultAnnotation<Plan | null>(() => null),
+ *   title: createDefaultAnnotation<string>(() => ""),
+ *});
+ */
+export declare const createState: <T extends readonly AnnotationRoot<any>[]>(...parents: T) => {
+    build: <D extends StateDefinition>(state?: D) => any;
+};
+export declare const createDefaultAnnotation: <T>(defaultValue: () => T) => any;

package/dist/server/createState.js

@@ -0,0 +1,20 @@
+import { Annotation } from "@langchain/langgraph";
+/**
+ * create state for langgraph
+ * @example
+ * export const GraphState = createState(createReactAgentAnnotation(), ModelState, SwarmState).build({
+ *   current_plan: createDefaultAnnotation<Plan | null>(() => null),
+ *   title: createDefaultAnnotation<string>(() => ""),
+ *});
+ */
+export const createState = (...parents) => {
+    return {
+        build: (state = {}) => {
+            return Annotation.Root(Object.assign({}, ...parents.map((p) => p.spec), state));
+        },
+    };
+};
+export const createDefaultAnnotation = (defaultValue) => Annotation({
+    reducer: (_, a) => a,
+    default: defaultValue,
+});

package/dist/server/feTools.d.ts

@@ -0,0 +1,16 @@
+import { DynamicStructuredTool } from "@langchain/core/tools";
+export declare const FEToolsState: any;
+export interface FEToolParameters {
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+}
+export interface FETool {
+    name: string;
+    description: string;
+    parameters: FEToolParameters[];
+}
+export declare const createFETool: (tool: FETool) => FETool;
+export declare const createFeTools: (tools: FETool[]) => DynamicStructuredTool[];
+export declare const actionToTool: (tool: FETool) => DynamicStructuredTool;

package/dist/server/feTools.js

@@ -0,0 +1,37 @@
+import { interrupt } from "@langchain/langgraph";
+import { createDefaultAnnotation } from "./createState.js";
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { createState } from "./createState.js";
+export const FEToolsState = createState().build({
+    fe_tools: createDefaultAnnotation(() => []),
+});
+export const createFETool = (tool) => {
+    return tool;
+};
+export const createFeTools = (tools) => {
+    return tools
+        .map((tool) => {
+        try {
+            return actionToTool(tool);
+        }
+        catch (e) {
+            console.error(e);
+            return null;
+        }
+    })
+        .filter((tool) => tool !== null);
+};
+export const actionToTool = (tool) => {
+    const callTool = async (args) => {
+        const data = interrupt(JSON.stringify(args));
+        return [data, null];
+    };
+    const schema = tool.parameters;
+    return new DynamicStructuredTool({
+        name: tool.name,
+        description: tool.description || "",
+        schema,
+        func: callTool,
+        responseFormat: "content_and_artifact",
+    });
+};

package/dist/server/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./createState.js";
+export * from "./feTools.js";
+export * from "./tools/index.js";

package/dist/server/index.js

@@ -0,0 +1,3 @@
+export * from "./createState.js";
+export * from "./feTools.js";
+export * from "./tools/index.js";

package/dist/server/interrupt/index.d.ts

@@ -0,0 +1,23 @@
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+export declare class InterruptModal {
+    private inputParams;
+    constructor(inputParams: {
+        action: "prompt" | string;
+    });
+    rawResponse?: {
+        response: string;
+        request: {
+            message: string;
+            action: "prompt" | string;
+        };
+    };
+    get response(): {
+        answer?: string;
+    };
+    interrupt(message: string): this;
+    isApprove(): string | undefined;
+    isReject(): boolean;
+    toMessages(options?: {
+        AIAskMessage?: boolean;
+    }): (false | HumanMessage | AIMessage | undefined)[];
+}

package/dist/server/interrupt/index.js

@@ -0,0 +1,36 @@
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { interrupt } from "@langchain/langgraph";
+export class InterruptModal {
+    constructor(inputParams) {
+        this.inputParams = inputParams;
+    }
+    get response() {
+        if (!this.rawResponse)
+            throw new Error("rawResponse is undefined");
+        return JSON.parse(this.rawResponse.response);
+    }
+    interrupt(message) {
+        const inputData = Object.assign({ message }, this.inputParams);
+        const input = JSON.stringify(inputData);
+        const response = interrupt(input);
+        this.rawResponse = {
+            request: inputData,
+            response,
+        };
+        return this;
+    }
+    isApprove() {
+        return this.response.answer;
+    }
+    isReject() {
+        return !this.response.answer;
+    }
+    toMessages(options) {
+        if (!this.rawResponse)
+            throw new Error("rawResponse is undefined");
+        return [
+            (options === null || options === void 0 ? void 0 : options.AIAskMessage) && new AIMessage(this.rawResponse.request.message),
+            new HumanMessage(this.response.answer),
+        ].filter(Boolean);
+    }
+}

package/dist/server/swarm/handoff.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { AnnotationRoot, CompiledStateGraph } from "@langchain/langgraph";
+declare const METADATA_KEY_HANDOFF_DESTINATION = "__handoff_destination";
+interface CreateHandoffToolParams {
+    agentName: string;
+    description?: string;
+    updateState?: (state: any) => Record<string, any>;
+}
+declare const createHandoffTool: ({ agentName, description, updateState }: CreateHandoffToolParams) => import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, {}, {}, any>;
+declare const getHandoffDestinations: <AnnotationRootT extends AnnotationRoot<any>>(agent: CompiledStateGraph<AnnotationRootT["State"], AnnotationRootT["Update"], string, AnnotationRootT["spec"], AnnotationRootT["spec"]>, toolNodeName?: string) => string[];
+export { createHandoffTool, getHandoffDestinations, METADATA_KEY_HANDOFF_DESTINATION };

package/dist/server/swarm/handoff.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { ToolMessage } from "@langchain/core/messages";
+import { tool } from "@langchain/core/tools";
+import { Command, getCurrentTaskInput, } from "@langchain/langgraph";
+const WHITESPACE_RE = /\s+/g;
+const METADATA_KEY_HANDOFF_DESTINATION = "__handoff_destination";
+function _normalizeAgentName(agentName) {
+    /**
+     * Normalize an agent name to be used inside the tool name.
+     */
+    return agentName.trim().replace(WHITESPACE_RE, "_").toLowerCase();
+}
+// type guard
+function isDynamicTool(tool) {
+    return "schema" in tool && "name" in tool && "description" in tool && "responseFormat" in tool;
+}
+const createHandoffTool = ({ agentName, description, updateState }) => {
+    /**
+     * Create a tool that can handoff control to the requested agent.
+     *
+     * @param agentName - The name of the agent to handoff control to, i.e.
+     *   the name of the agent node in the multi-agent graph.
+     *   Agent names should be simple, clear and unique, preferably in snake_case,
+     *   although you are only limited to the names accepted by LangGraph
+     *   nodes as well as the tool names accepted by LLM providers
+     *   (the tool name will look like this: `transfer_to_<agent_name>`).
+     * @param description - Optional description for the handoff tool.
+     * @param updateState - Optional function to customize state updates during handoff.
+     */
+    const toolName = `transfer_to_${_normalizeAgentName(agentName)}`;
+    const toolDescription = description || `Ask agent '${agentName}' for help`;
+    const handoffTool = tool(async (_, config) => {
+        /**
+         * Ask another agent for help.
+         */
+        const toolMessage = new ToolMessage({
+            content: `Successfully transferred to ${agentName}`,
+            name: toolName,
+            tool_call_id: config.toolCall.id,
+        });
+        // inject the current agent state
+        const state = getCurrentTaskInput();
+        // Base update object containing essential state updates
+        const baseUpdate = {
+            messages: state.messages.concat(toolMessage),
+            activeAgent: agentName,
+        };
+        // Merge custom updates with base updates if updateState function is provided
+        const finalUpdate = updateState ? { ...baseUpdate, ...updateState(state) } : baseUpdate;
+        return new Command({
+            goto: agentName,
+            graph: Command.PARENT,
+            update: finalUpdate,
+        });
+    }, {
+        name: toolName,
+        schema: z.object({}),
+        description: toolDescription,
+    });
+    handoffTool.metadata = { [METADATA_KEY_HANDOFF_DESTINATION]: agentName };
+    return handoffTool;
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const getHandoffDestinations = (agent, toolNodeName = "tools") => {
+    /**
+     * Get a list of destinations from agent's handoff tools.
+     *
+     * @param agent - The compiled state graph
+     * @param toolNodeName - The name of the tool node in the graph
+     */
+    const { nodes } = agent.getGraph();
+    if (!(toolNodeName in nodes)) {
+        return [];
+    }
+    const toolNode = nodes[toolNodeName].data;
+    if (!toolNode || !("tools" in toolNode) || !toolNode.tools) {
+        return [];
+    }
+    const { tools } = toolNode;
+    return tools
+        .filter((tool) => isDynamicTool(tool) && tool.metadata !== undefined && METADATA_KEY_HANDOFF_DESTINATION in tool.metadata)
+        .map((tool) => tool.metadata[METADATA_KEY_HANDOFF_DESTINATION]);
+};
+export { createHandoffTool, getHandoffDestinations, METADATA_KEY_HANDOFF_DESTINATION };

package/dist/server/swarm/keepState.d.ts

@@ -0,0 +1,6 @@
+import { SwarmState } from "@langchain/langgraph-swarm";
+/**
+ * 保留 langgraph-swarm 在 handoff 时丢失的 state
+ */
+export declare const keepAllStateInHandOff: (state: typeof SwarmState.State) => any;
+export declare const createHandoffCommand: <T>(name: string, state: T) => any;

package/dist/server/swarm/keepState.js

@@ -0,0 +1,21 @@
+import { Command } from "@langchain/langgraph";
+/**
+ * 保留 langgraph-swarm 在 handoff 时丢失的 state
+ */
+export const keepAllStateInHandOff = (state) => {
+    // omit activeAgent and messages
+    const { activeAgent, messages, ...rest } = state;
+    return {
+        ...rest,
+    };
+};
+export const createHandoffCommand = (name, state) => {
+    return new Command({
+        goto: name,
+        graph: Command.PARENT,
+        update: {
+            active_agent: name,
+            ...state,
+        },
+    });
+};

package/dist/server/tools/index.d.ts

@@ -0,0 +1 @@
+export * from "./sequential-thinking.js";

package/dist/server/tools/index.js

@@ -0,0 +1 @@
+export * from "./sequential-thinking.js";