@langgraph-js/sdk 1.0.0 → 1.1.1

package/README.md

@@ -0,0 +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.

package/dist/LangGraphClient.d.ts

@@ -0,0 +1,101 @@
+import { Client, Thread, Message, Assistant, HumanMessage, ToolMessage, Command } from "@langchain/langgraph-sdk";
+import { ToolManager } from "./ToolManager";
+import { CallToolResult } from "./tool";
+import { AsyncCallerParams } from "@langchain/langgraph-sdk/dist/utils/async_caller";
+export type RenderMessage = Message & {
+    /** 工具入参 ，聚合而来*/
+    tool_input?: string;
+    additional_kwargs?: {
+        done?: boolean;
+        tool_calls?: {
+            function: {
+                arguments: string;
+            };
+        }[];
+    };
+    usage_metadata?: {
+        total_tokens: number;
+        input_tokens: number;
+        output_tokens: number;
+    };
+    response_metadata?: {
+        create_time: string;
+    };
+    /** 耗时 */
+    spend_time?: number;
+    /** 渲染时的唯一 id，聚合而来*/
+    unique_id?: string;
+};
+export interface LangGraphClientConfig {
+    apiUrl?: string;
+    apiKey?: string;
+    callerOptions?: AsyncCallerParams;
+    timeoutMs?: number;
+    defaultHeaders?: Record<string, string | null | undefined>;
+}
+export declare class StreamingMessageType {
+    static isUser(m: Message): m is HumanMessage;
+    static isTool(m: Message): m is ToolMessage;
+    static isAssistant(m: Message): boolean;
+    static isToolAssistant(m: Message): any;
+}
+type StreamingUpdateEvent = {
+    type: "message" | "value" | "update" | "error" | "thread" | "done";
+    data: any;
+};
+type StreamingUpdateCallback = (event: StreamingUpdateEvent) => void;
+export declare class LangGraphClient extends Client {
+    private currentAssistant;
+    private currentThread;
+    private streamingCallbacks;
+    tools: ToolManager;
+    stopController: AbortController | null;
+    constructor(config: LangGraphClientConfig);
+    availableAssistants: Assistant[];
+    private listAssistants;
+    initAssistant(agentName: string): Promise<void>;
+    createThread({ threadId, }?: {
+        threadId?: string;
+    }): Promise<Thread<import("@langchain/langgraph-sdk").DefaultValues>>;
+    listThreads<T>(): Promise<Thread<T>[]>;
+    /** 从历史中恢复数据 */
+    resetThread(agent: string, threadId: string): Promise<void>;
+    streamingMessage: RenderMessage[];
+    /** 图发过来的更新信息 */
+    graphMessages: RenderMessage[];
+    cloneMessage(message: Message): Message;
+    private replaceMessageWithValuesMessage;
+    /** 用于 UI 中的流式渲染中的消息 */
+    get renderMessage(): RenderMessage[];
+    attachInfoForMessage(result: RenderMessage[]): RenderMessage[];
+    composeToolMessages(messages: RenderMessage[]): RenderMessage[];
+    get tokenCounter(): {
+        total_tokens: number;
+        input_tokens: number;
+        output_tokens: number;
+    };
+    onStreamingUpdate(callback: StreamingUpdateCallback): () => void;
+    private emitStreamingUpdate;
+    graphState: any;
+    currentRun?: {
+        run_id: string;
+    };
+    cancelRun(): void;
+    sendMessage(input: string | Message[], { extraParams, _debug, command }?: {
+        extraParams?: Record<string, any>;
+        _debug?: {
+            streamResponse?: any;
+        };
+        command?: Command;
+    }): Promise<any[]>;
+    private runFETool;
+    private callFETool;
+    /** 恢复消息，当中断流时使用 */
+    resume(result: CallToolResult): Promise<any[]>;
+    /** 完成工具等待 */
+    doneFEToolWaiting(id: string, result: CallToolResult): void;
+    getCurrentThread(): Thread<import("@langchain/langgraph-sdk").DefaultValues> | null;
+    getCurrentAssistant(): Assistant | null;
+    reset(): Promise<void>;
+}
+export {};

package/dist/LangGraphClient.js

@@ -0,0 +1,401 @@
+import { Client } from "@langchain/langgraph-sdk";
+import { ToolManager } from "./ToolManager";
+export class StreamingMessageType {
+    static isUser(m) {
+        return m.type === "human";
+    }
+    static isTool(m) {
+        return m.type === "tool";
+    }
+    static isAssistant(m) {
+        return m.type === "ai" && !this.isToolAssistant(m);
+    }
+    static isToolAssistant(m) {
+        var _a, _b;
+        /** @ts-ignore */
+        return m.type === "ai" && (((_a = m.tool_calls) === null || _a === void 0 ? void 0 : _a.length) || ((_b = m.tool_call_chunks) === null || _b === void 0 ? void 0 : _b.length));
+    }
+}
+export class LangGraphClient extends Client {
+    constructor(config) {
+        super(config);
+        this.currentAssistant = null;
+        this.currentThread = null;
+        this.streamingCallbacks = new Set();
+        this.tools = new ToolManager();
+        this.stopController = null;
+        this.availableAssistants = [];
+        this.streamingMessage = [];
+        /** 图发过来的更新信息 */
+        this.graphMessages = [];
+        this.graphState = {};
+    }
+    listAssistants() {
+        return this.assistants.search({
+            metadata: null,
+            offset: 0,
+            limit: 100,
+        });
+    }
+    async initAssistant(agentName) {
+        try {
+            const assistants = await this.listAssistants();
+            this.availableAssistants = assistants;
+            if (assistants.length > 0) {
+                this.currentAssistant = assistants.find((assistant) => assistant.name === agentName) || null;
+                if (!this.currentAssistant) {
+                    throw new Error("Agent not found");
+                }
+            }
+            else {
+                throw new Error("No assistants found");
+            }
+        }
+        catch (error) {
+            console.error("Failed to initialize LangGraphClient:", error);
+            throw error;
+        }
+    }
+    async createThread({ threadId, } = {}) {
+        try {
+            this.currentThread = await this.threads.create({
+                threadId,
+            });
+            return this.currentThread;
+        }
+        catch (error) {
+            console.error("Failed to create new thread:", error);
+            throw error;
+        }
+    }
+    async listThreads() {
+        return this.threads.search({
+            sortOrder: "desc",
+        });
+    }
+    /** 从历史中恢复数据 */
+    async resetThread(agent, threadId) {
+        await this.initAssistant(agent);
+        this.currentThread = await this.threads.get(threadId);
+        this.graphState = this.currentThread.values;
+        this.graphMessages = this.graphState.messages;
+        this.emitStreamingUpdate({
+            type: "value",
+            data: {
+                event: "messages/partial",
+                data: {
+                    messages: this.graphMessages,
+                },
+            },
+        });
+    }
+    cloneMessage(message) {
+        return JSON.parse(JSON.stringify(message));
+    }
+    replaceMessageWithValuesMessage(message, isTool = false) {
+        const key = (isTool ? "tool_call_id" : "id");
+        const valuesMessage = this.graphMessages.find((i) => i[key] === message[key]);
+        if (valuesMessage) {
+            return {
+                ...valuesMessage,
+                /** @ts-ignore */
+                tool_input: message.tool_input,
+            };
+        }
+        return message;
+    }
+    /** 用于 UI 中的流式渲染中的消息 */
+    get renderMessage() {
+        var _a;
+        const previousMessage = new Map();
+        const result = [];
+        const inputMessages = [...this.graphMessages, ...this.streamingMessage];
+        // 从后往前遍历，这样可以保证最新的消息在前面
+        for (let i = inputMessages.length - 1; i >= 0; i--) {
+            const message = this.cloneMessage(inputMessages[i]);
+            if (!message.id) {
+                result.unshift(message);
+                continue;
+            }
+            // 如果已经处理过这个 id 的消息，跳过
+            if (previousMessage.has(message.id)) {
+                continue;
+            }
+            if (StreamingMessageType.isToolAssistant(message)) {
+                const m = this.replaceMessageWithValuesMessage(message);
+                // 记录这个 id 的消息，并添加到结果中
+                previousMessage.set(message.id, m);
+                /** @ts-ignore */
+                const tool_calls = ((_a = m.tool_calls) === null || _a === void 0 ? void 0 : _a.length) ? m.tool_calls : m.tool_call_chunks;
+                const new_tool_calls = tool_calls.map((tool, index) => {
+                    var _a;
+                    return this.replaceMessageWithValuesMessage({
+                        type: "tool",
+                        additional_kwargs: {},
+                        /** @ts-ignore */
+                        tool_input: (_a = m.additional_kwargs) === null || _a === void 0 ? void 0 : _a.tool_calls[index].function.arguments,
+                        id: tool.id,
+                        name: tool.name,
+                        response_metadata: {},
+                        tool_call_id: tool.id,
+                    }, true);
+                });
+                for (const tool of new_tool_calls) {
+                    if (!previousMessage.has(tool.id)) {
+                        result.unshift(tool);
+                        previousMessage.set(tool.id, tool);
+                    }
+                }
+                result.unshift(m);
+            }
+            else {
+                // 记录这个 id 的消息，并添加到结果中
+                const m = this.replaceMessageWithValuesMessage(message);
+                previousMessage.set(message.id, m);
+                result.unshift(m);
+            }
+        }
+        return this.attachInfoForMessage(this.composeToolMessages(result));
+    }
+    attachInfoForMessage(result) {
+        var _a, _b, _c;
+        let lastMessage = null;
+        for (const message of result) {
+            const createTime = ((_a = message.response_metadata) === null || _a === void 0 ? void 0 : _a.create_time) || "";
+            // 用长度作为渲染 id，长度变了就要重新渲染
+            message.unique_id = message.id + JSON.stringify(message.content).length;
+            message.spend_time = new Date(createTime).getTime() - new Date(((_b = lastMessage === null || lastMessage === void 0 ? void 0 : lastMessage.response_metadata) === null || _b === void 0 ? void 0 : _b.create_time) || createTime).getTime();
+            if (!message.usage_metadata && ((_c = message.response_metadata) === null || _c === void 0 ? void 0 : _c.usage)) {
+                const usage = message.response_metadata.usage;
+                message.usage_metadata = {
+                    input_tokens: usage.prompt_tokens,
+                    output_tokens: usage.completion_tokens,
+                    total_tokens: usage.total_tokens,
+                };
+            }
+            lastMessage = message;
+        }
+        return result;
+    }
+    composeToolMessages(messages) {
+        var _a;
+        const result = [];
+        const assistantToolMessages = new Map();
+        const toolParentMessage = new Map();
+        for (const message of messages) {
+            if (StreamingMessageType.isToolAssistant(message)) {
+                /** @ts-ignore 只有 tool_call_chunks 的 args 才是文本 */
+                (_a = message.tool_call_chunks) === null || _a === void 0 ? void 0 : _a.forEach((element) => {
+                    assistantToolMessages.set(element.id, element);
+                    toolParentMessage.set(element.id, message);
+                });
+                if (!message.content)
+                    continue;
+            }
+            if (StreamingMessageType.isTool(message) && !message.tool_input) {
+                const assistantToolMessage = assistantToolMessages.get(message.tool_call_id);
+                const parentMessage = toolParentMessage.get(message.tool_call_id);
+                if (assistantToolMessage) {
+                    message.tool_input = assistantToolMessage.args;
+                    if (message.additional_kwargs) {
+                        message.additional_kwargs.done = true;
+                    }
+                    else {
+                        message.additional_kwargs = {
+                            done: true,
+                        };
+                    }
+                }
+                if (parentMessage) {
+                    message.usage_metadata = parentMessage.usage_metadata;
+                }
+            }
+            result.push(message);
+        }
+        return result;
+    }
+    get tokenCounter() {
+        return this.graphMessages.reduce((acc, message) => {
+            var _a, _b, _c, _d, _e;
+            if (message.usage_metadata) {
+                acc.total_tokens += ((_a = message.usage_metadata) === null || _a === void 0 ? void 0 : _a.total_tokens) || 0;
+                acc.input_tokens += ((_b = message.usage_metadata) === null || _b === void 0 ? void 0 : _b.input_tokens) || 0;
+                acc.output_tokens += ((_c = message.usage_metadata) === null || _c === void 0 ? void 0 : _c.output_tokens) || 0;
+            }
+            else if ((_d = message.response_metadata) === null || _d === void 0 ? void 0 : _d.usage) {
+                const usage = (_e = message.response_metadata) === null || _e === void 0 ? void 0 : _e.usage;
+                acc.total_tokens += usage.total_tokens || 0;
+                acc.input_tokens += usage.prompt_tokens || 0;
+                acc.output_tokens += usage.completion_tokens || 0;
+            }
+            return acc;
+        }, {
+            total_tokens: 0,
+            input_tokens: 0,
+            output_tokens: 0,
+        });
+    }
+    onStreamingUpdate(callback) {
+        this.streamingCallbacks.add(callback);
+        return () => {
+            this.streamingCallbacks.delete(callback);
+        };
+    }
+    emitStreamingUpdate(event) {
+        this.streamingCallbacks.forEach((callback) => callback(event));
+    }
+    cancelRun() {
+        var _a, _b;
+        if (((_a = this.currentThread) === null || _a === void 0 ? void 0 : _a.thread_id) && ((_b = this.currentRun) === null || _b === void 0 ? void 0 : _b.run_id)) {
+            this.runs.cancel(this.currentThread.thread_id, this.currentRun.run_id);
+        }
+    }
+    async sendMessage(input, { extraParams, _debug, command } = {}) {
+        if (!this.currentAssistant) {
+            throw new Error("Thread or Assistant not initialized");
+        }
+        if (!this.currentThread) {
+            await this.createThread();
+            this.emitStreamingUpdate({
+                type: "thread",
+                data: {
+                    event: "thread/create",
+                    data: {
+                        thread: this.currentThread,
+                    },
+                },
+            });
+        }
+        const messagesToSend = Array.isArray(input)
+            ? input
+            : [
+                {
+                    type: "human",
+                    content: input,
+                },
+            ];
+        const streamResponse = (_debug === null || _debug === void 0 ? void 0 : _debug.streamResponse) ||
+            this.runs.stream(this.currentThread.thread_id, this.currentAssistant.assistant_id, {
+                input: { ...this.graphState, ...(extraParams || {}), messages: messagesToSend, fe_tools: this.tools.toJSON() },
+                streamMode: ["messages", "values"],
+                streamSubgraphs: true,
+                command,
+            });
+        const streamRecord = [];
+        for await (const chunk of streamResponse) {
+            streamRecord.push(chunk);
+            if (chunk.event === "metadata") {
+                this.currentRun = chunk.data;
+            }
+            else if (chunk.event === "error") {
+                this.emitStreamingUpdate({
+                    type: "error",
+                    data: chunk,
+                });
+            }
+            else if (chunk.event === "messages/partial") {
+                for (const message of chunk.data) {
+                    this.streamingMessage.push(message);
+                }
+                this.emitStreamingUpdate({
+                    type: "message",
+                    data: chunk,
+                });
+                continue;
+            }
+            else if (chunk.event.startsWith("values")) {
+                const data = chunk.data;
+                if (data.messages) {
+                    const isResume = !!(command === null || command === void 0 ? void 0 : command.resume);
+                    const isLongerThanLocal = data.messages.length >= this.graphMessages.length;
+                    // resume 情况下，长度低于前端 message 的统统不接受
+                    if (!isResume || (isResume && isLongerThanLocal)) {
+                        this.graphMessages = data.messages;
+                        this.emitStreamingUpdate({
+                            type: "value",
+                            data: chunk,
+                        });
+                    }
+                }
+                this.graphState = chunk.data;
+                this.streamingMessage = [];
+                continue;
+            }
+        }
+        this.streamingMessage = [];
+        const data = await this.runFETool();
+        if (data)
+            streamRecord.push(...data);
+        this.emitStreamingUpdate({
+            type: "done",
+            data: {
+                event: "done",
+            },
+        });
+        return streamRecord;
+    }
+    runFETool() {
+        var _a;
+        const data = this.graphMessages;
+        const lastMessage = data[data.length - 1];
+        // 如果最后一条消息是前端工具消息，则调用工具
+        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);
+                }
+            });
+            return Promise.all(result);
+        }
+    }
+    async callFETool(message, args) {
+        const that = this; // 防止 this 被错误解析
+        const result = await this.tools.callTool(message.name, args, { client: that, message });
+        return this.resume(result);
+    }
+    /** 恢复消息，当中断流时使用 */
+    resume(result) {
+        return this.sendMessage([], {
+            command: {
+                resume: result,
+            },
+        });
+    }
+    /** 完成工具等待 */
+    doneFEToolWaiting(id, result) {
+        var _a;
+        const done = this.tools.doneWaiting(id, result);
+        if (!done && ((_a = this.currentThread) === null || _a === void 0 ? void 0 : _a.status) === "interrupted") {
+            this.resume(result);
+        }
+    }
+    getCurrentThread() {
+        return this.currentThread;
+    }
+    getCurrentAssistant() {
+        return this.currentAssistant;
+    }
+    async reset() {
+        var _a;
+        await this.initAssistant((_a = this.currentAssistant) === null || _a === void 0 ? void 0 : _a.name);
+        this.currentThread = null;
+        this.graphState = {};
+        this.graphMessages = [];
+        this.streamingMessage = [];
+        this.currentRun = undefined;
+        this.emitStreamingUpdate({
+            type: "value",
+            data: {
+                event: "messages/partial",
+            },
+        });
+    }
+}

package/dist/SpendTime.d.ts

@@ -0,0 +1,9 @@
+export declare class SpendTime {
+    private timeCounter;
+    start(key: string): void;
+    end(key: string): void;
+    setSpendTime(key: string): void;
+    getStartTime(key: string): Date;
+    getEndTime(key: string): Date;
+    getSpendTime(key: string): number;
+}