@langgraph-js/sdk 1.0.0 → 1.1.1

package/src/SpendTime.ts

@@ -0,0 +1,29 @@
+export class SpendTime {
+    private timeCounter = new Map<string, [Date, Date] | [Date]>();
+
+    start(key: string) {
+        this.timeCounter.set(key, [new Date()]);
+    }
+
+    end(key: string) {
+        this.timeCounter.set(key, [this.timeCounter.get(key)?.[0] || new Date(), new Date()]);
+    }
+    setSpendTime(key: string) {
+        if (this.timeCounter.has(key)) {
+            this.end(key);
+        } else {
+            this.start(key);
+        }
+    }
+    getStartTime(key: string) {
+        return this.timeCounter.get(key)?.[0] || new Date();
+    }
+    getEndTime(key: string) {
+        return this.timeCounter.get(key)?.[1] || new Date();
+    }
+
+    getSpendTime(key: string) {
+        const [start, end = new Date()] = this.timeCounter.get(key) || [new Date(), new Date()];
+        return end.getTime() - start.getTime();
+    }
+}

package/src/ToolManager.ts

@@ -0,0 +1,100 @@
+import { ToolMessage } from "@langchain/langgraph-sdk";
+import { LangGraphClient } from "./LangGraphClient";
+import { CallToolResult, createJSONDefineTool, UnionTool } from "./tool/createTool";
+
+export class ToolManager {
+    private tools: Map<string, UnionTool<any>> = new Map();
+
+    /**
+     * 注册一个工具
+     * @param tool 要注册的工具
+     */
+    bindTool(tool: UnionTool<any>) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool with name ${tool.name} already exists`);
+        }
+        this.tools.set(tool.name, tool);
+    }
+
+    /**
+     * 注册多个工具
+     * @param tools 要注册的工具数组
+     */
+    bindTools(tools: UnionTool<any>[]) {
+        tools.forEach((tool) => this.bindTool(tool));
+    }
+
+    /**
+     * 获取所有已注册的工具
+     * @returns 工具数组
+     */
+    getAllTools(): UnionTool<any>[] {
+        return Array.from(this.tools.values());
+    }
+
+    /**
+     * 获取指定名称的工具
+     * @param name 工具名称
+     * @returns 工具实例或 undefined
+     */
+    getTool(name: string): UnionTool<any> | undefined {
+        return this.tools.get(name);
+    }
+
+    /**
+     * 移除指定名称的工具
+     * @param name 工具名称
+     * @returns 是否成功移除
+     */
+    removeTool(name: string): boolean {
+        return this.tools.delete(name);
+    }
+
+    /**
+     * 清空所有工具
+     */
+    clearTools() {
+        this.tools.clear();
+    }
+    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`);
+        }
+        return await tool.execute(args, context);
+    }
+    toJSON() {
+        return Array.from(this.tools.values()).map((i) => createJSONDefineTool(i));
+    }
+
+    // === 专门为前端设计的异步触发结构
+    private waitingMap: Map<string, (value: CallToolResult) => void> = new Map();
+    doneWaiting(id: string, value: CallToolResult) {
+        if (this.waitingMap.has(id)) {
+            this.waitingMap.get(id)!(value);
+            this.waitingMap.delete(id);
+            return true;
+        } else {
+            console.warn(`Waiting for tool ${id} not found`);
+            return false;
+        }
+    }
+    waitForDone(id: string) {
+        if (this.waitingMap.has(id)) {
+            return this.waitingMap.get(id);
+        }
+        const promise = new Promise((resolve, reject) => {
+            this.waitingMap.set(id, resolve);
+        });
+        return promise;
+    }
+    /** 等待用户输入
+     * @example
+     * // 继续 chat 流
+     * client.tools.doneWaiting(message.id!, (e.target as any).value);
+     */
+    static waitForUIDone<T>(_: T, context: { client: LangGraphClient; message: ToolMessage }) {
+        // console.log(context.message);
+        return context.client.tools.waitForDone(context.message.id!);
+    }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./LangGraphClient";
+export * from "./tool";
+export * from "@langchain/langgraph-sdk";
+export * from "./ui-store";
+export * from "./ToolManager";

package/src/tool/copilotkit-actions.ts

@@ -0,0 +1,72 @@
+import { Message } from "@langchain/langgraph-sdk";
+/**
+ * copy and modify from copilotkit
+ * https://github.com/copilotkit/copilotkit
+ *
+ * MIT License
+ */
+type TypeMap = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    object: object;
+    "string[]": string[];
+    "number[]": number[];
+    "boolean[]": boolean[];
+    "object[]": object[];
+};
+
+type AbstractParameter = {
+    name: string;
+    type?: keyof TypeMap;
+    description?: string;
+    required?: boolean;
+};
+
+interface StringParameter extends AbstractParameter {
+    type: "string";
+    enum?: string[];
+}
+
+interface ObjectParameter extends AbstractParameter {
+    type: "object";
+    attributes?: Parameter[];
+}
+
+interface ObjectArrayParameter extends AbstractParameter {
+    type: "object[]";
+    attributes?: Parameter[];
+}
+
+type SpecialParameters = StringParameter | ObjectParameter | ObjectArrayParameter;
+interface BaseParameter extends AbstractParameter {
+    type?: Exclude<AbstractParameter["type"], SpecialParameters["type"]>;
+}
+
+export type Parameter = BaseParameter | SpecialParameters;
+
+type OptionalParameterType<P extends AbstractParameter> = P["required"] extends false ? undefined : never;
+
+type StringParameterType<P> = P extends StringParameter ? (P extends { enum?: Array<infer E> } ? E : string) : never;
+
+type ObjectParameterType<P> = P extends ObjectParameter ? (P extends { attributes?: infer Attributes extends Parameter[] } ? MappedParameterTypes<Attributes> : object) : never;
+
+type ObjectArrayParameterType<P> = P extends ObjectArrayParameter ? (P extends { attributes?: infer Attributes extends Parameter[] } ? MappedParameterTypes<Attributes>[] : any[]) : never;
+
+type MappedTypeOrString<T> = T extends keyof TypeMap ? TypeMap[T] : string;
+type BaseParameterType<P extends AbstractParameter> = P extends { type: infer T } ? (T extends BaseParameter["type"] ? MappedTypeOrString<T> : never) : string;
+
+export type MappedParameterTypes<T extends Parameter[] | [] = []> = T extends []
+    ? Record<string, any>
+    : {
+          [P in T[number] as P["name"]]: OptionalParameterType<P> | StringParameterType<P> | ObjectParameterType<P> | ObjectArrayParameterType<P> | BaseParameterType<P>;
+      };
+
+export type Action<T extends Parameter[] | [] = []> = {
+    name: string;
+    description?: string;
+    parameters?: T;
+    handler?: T extends [] ? () => any | Promise<any> : (args: MappedParameterTypes<T>, context?: any) => any | Promise<any>;
+    returnDirect?: boolean;
+    callbackMessage?: () => Message[];
+};

package/src/tool/createTool.ts

@@ -0,0 +1,78 @@
+import { actionParametersToJsonSchema, convertJsonSchemaToZodRawShape } from "./utils";
+import { z, ZodRawShape, ZodTypeAny } from "zod";
+import { Action, Parameter } from "./copilotkit-actions";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { Message } from "@langchain/langgraph-sdk";
+
+export interface UnionTool<Args extends ZodRawShape> {
+    name: string;
+    description: string;
+    parameters: Args;
+    /** 是否直接返回工具结果，而不是通过消息返回 */
+    returnDirect?: boolean;
+    execute: ToolCallback<Args>;
+    /** 工具执行成功后触发的附加消息 */
+    callbackMessage?: (result: CallToolResult) => Message[];
+}
+export type ToolCallback<Args extends ZodRawShape> = (args: z.objectOutputType<Args, ZodTypeAny>, context?: any) => CallToolResult | Promise<CallToolResult>;
+
+export type CallToolResult = string | { type: "text"; text: string }[];
+
+/** 用于格式校验 */
+export const createTool = <Args extends ZodRawShape>(tool: UnionTool<Args>) => {
+    return tool;
+};
+
+/** 提供一种兼容 copilotkit 的定义方式，简化定义形式
+ * 来自 copilotkit 的 frontend action
+ */
+export const createFETool = <const T extends Parameter[], Args extends ZodRawShape>(tool: Action<T>): UnionTool<Args> => {
+    return {
+        name: tool.name,
+        description: tool.description || "",
+        parameters: convertJsonSchemaToZodRawShape(actionParametersToJsonSchema(tool.parameters || [])) as any,
+        returnDirect: tool.returnDirect,
+        callbackMessage: tool.callbackMessage,
+        async execute(args, context) {
+            try {
+                const result = await tool.handler?.(args, context);
+                if (typeof result === "string") {
+                    return [{ type: "text", text: result }];
+                }
+                return [{ type: "text", text: JSON.stringify(result) }];
+            } catch (error) {
+                return [{ type: "text", text: `Error: ${error}` }];
+            }
+        },
+    };
+};
+
+///======= UnionTool 到 各种工具的辅助函数
+export const createJSONDefineTool = <Args extends ZodRawShape>(tool: UnionTool<Args>) => {
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: zodToJsonSchema(z.object(tool.parameters)),
+    };
+};
+
+export const createMCPTool = <Args extends ZodRawShape>(tool: UnionTool<Args>) => {
+    return [
+        tool.name,
+        tool.description,
+        tool.parameters,
+        async (args: z.objectOutputType<Args, ZodTypeAny>) => {
+            try {
+                const result = await tool.execute(args);
+                if (typeof result === "string") {
+                    return { content: [{ type: "text", text: result }] };
+                }
+                return {
+                    content: result,
+                };
+            } catch (error) {
+                return { content: [{ type: "text", text: `Error: ${error}` }], isError: true };
+            }
+        },
+    ];
+};

package/src/tool/index.ts

@@ -0,0 +1,2 @@
+export * from "./createTool";
+export * from "./copilotkit-actions";

package/src/tool/utils.ts

@@ -0,0 +1,158 @@
+/**
+ * copy and modify from copilotkit
+ * https://github.com/copilotkit/copilotkit
+ *
+ * MIT License
+ */
+import { z, ZodRawShape } from "zod";
+import { Parameter } from "./copilotkit-actions";
+
+export type JSONSchemaString = {
+    type: "string";
+    description?: string;
+    enum?: string[];
+};
+
+export type JSONSchemaNumber = {
+    type: "number";
+    description?: string;
+};
+
+export type JSONSchemaBoolean = {
+    type: "boolean";
+    description?: string;
+};
+
+export type JSONSchemaObject = {
+    type: "object";
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    description?: string;
+};
+
+export type JSONSchemaArray = {
+    type: "array";
+    items: JSONSchema;
+    description?: string;
+};
+
+export type JSONSchema = JSONSchemaString | JSONSchemaNumber | JSONSchemaBoolean | JSONSchemaObject | JSONSchemaArray;
+
+export function actionParametersToJsonSchema(actionParameters: Parameter[]): JSONSchema {
+    // Create the parameters object based on the argumentAnnotations
+    let parameters: { [key: string]: any } = {};
+    for (let parameter of actionParameters || []) {
+        parameters[parameter.name] = convertAttribute(parameter);
+    }
+
+    let requiredParameterNames: string[] = [];
+    for (let arg of actionParameters || []) {
+        if (arg.required !== false) {
+            requiredParameterNames.push(arg.name);
+        }
+    }
+
+    // Create the ChatCompletionFunctions object
+    return {
+        type: "object",
+        properties: parameters,
+        required: requiredParameterNames,
+    };
+}
+
+function convertAttribute(attribute: Parameter): JSONSchema {
+    switch (attribute.type) {
+        case "string":
+            return {
+                type: "string",
+                description: attribute.description,
+                ...(attribute.enum && { enum: attribute.enum }),
+            };
+        case "number":
+        case "boolean":
+            return {
+                type: attribute.type,
+                description: attribute.description,
+            };
+        case "object":
+        case "object[]":
+            const properties = attribute.attributes?.reduce(
+                (acc, attr) => {
+                    acc[attr.name] = convertAttribute(attr);
+                    return acc;
+                },
+                {} as Record<string, any>
+            );
+            const required = attribute.attributes?.filter((attr) => attr.required !== false).map((attr) => attr.name);
+            if (attribute.type === "object[]") {
+                return {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        ...(properties && { properties }),
+                        ...(required && required.length > 0 && { required }),
+                    },
+                    description: attribute.description,
+                };
+            }
+            return {
+                type: "object",
+                description: attribute.description,
+                ...(properties && { properties }),
+                ...(required && required.length > 0 && { required }),
+            };
+        default:
+            // Handle arrays of primitive types and undefined attribute.type
+            if (attribute.type?.endsWith("[]")) {
+                const itemType = attribute.type.slice(0, -2);
+                return {
+                    type: "array",
+                    items: { type: itemType as any },
+                    description: attribute.description,
+                };
+            }
+            // Fallback for undefined type or any other unexpected type
+            return {
+                type: "string",
+                description: attribute.description,
+            };
+    }
+}
+
+export function convertJsonSchemaToZodRawShape(jsonSchema: any): ZodRawShape {
+    const spec: { [key: string]: z.ZodSchema } = {};
+    for (const [key, value] of Object.entries(jsonSchema.properties)) {
+        spec[key] = convertJsonSchemaToZodSchema(value, jsonSchema.required ? jsonSchema.required.includes(key) : false);
+    }
+    return spec;
+}
+
+export function convertJsonSchemaToZodSchema(jsonSchema: any, required: boolean): z.ZodSchema {
+    if (jsonSchema.type === "object") {
+        const spec: { [key: string]: z.ZodSchema } = {};
+
+        if (!jsonSchema.properties || !Object.keys(jsonSchema.properties).length) {
+            return !required ? z.object(spec).optional() : z.object(spec);
+        }
+
+        for (const [key, value] of Object.entries(jsonSchema.properties)) {
+            spec[key] = convertJsonSchemaToZodSchema(value, jsonSchema.required ? jsonSchema.required.includes(key) : false);
+        }
+        let schema = z.object(spec).describe(jsonSchema.description);
+        return required ? schema : schema.optional();
+    } else if (jsonSchema.type === "string") {
+        let schema = z.string().describe(jsonSchema.description);
+        return required ? schema : schema.optional();
+    } else if (jsonSchema.type === "number") {
+        let schema = z.number().describe(jsonSchema.description);
+        return required ? schema : schema.optional();
+    } else if (jsonSchema.type === "boolean") {
+        let schema = z.boolean().describe(jsonSchema.description);
+        return required ? schema : schema.optional();
+    } else if (jsonSchema.type === "array") {
+        let itemSchema = convertJsonSchemaToZodSchema(jsonSchema.items, true);
+        let schema = z.array(itemSchema).describe(jsonSchema.description);
+        return required ? schema : schema.optional();
+    }
+    throw new Error("Invalid JSON schema");
+}

package/src/ui-store/UnionStore.ts

@@ -0,0 +1,20 @@
+import { atom, PreinitializedWritableAtom, StoreValue } from "nanostores";
+export type UnionStore<T extends { data: Record<string, PreinitializedWritableAtom<any>>; mutations: Record<string, any> }> = {
+    [k in keyof T["data"]]: StoreValue<T["data"][k]>;
+} & T["mutations"];
+
+export const useUnionStore = <T extends { data: Record<string, any>; mutations: Record<string, any> }>(
+    store: T,
+    useStore: (store: PreinitializedWritableAtom<any>) => StoreValue<T["data"][keyof T["data"]]>
+): UnionStore<T> => {
+    const data: any = Object.fromEntries(
+        Object.entries(store.data as any).map(([key, value]) => {
+            return [key, useStore(value as any)];
+        })
+    );
+
+    return {
+        ...data,
+        ...store.mutations,
+    };
+};

package/src/ui-store/createChatStore.ts

@@ -0,0 +1,153 @@
+import { atom } from "nanostores";
+import { LangGraphClient, LangGraphClientConfig, RenderMessage } from "../LangGraphClient";
+import { Message, Thread } from "@langchain/langgraph-sdk";
+export const formatTime = (date: Date) => {
+    return date.toLocaleTimeString("en-US");
+};
+
+export const formatTokens = (tokens: number) => {
+    return tokens.toLocaleString("en");
+};
+export const getMessageContent = (content: any) => {
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((item) => {
+                if (typeof item === "string") return item;
+                if (item.type === "text") return item.text;
+                if (item.type === "image_url") return `[图片]`;
+                return JSON.stringify(item);
+            })
+            .join("");
+    }
+    return JSON.stringify(content);
+};
+export const createChatStore = (
+    initClientName: string,
+    config: LangGraphClientConfig,
+    context: {
+        onInit?: (client: LangGraphClient) => void;
+    } = {}
+) => {
+    const client = atom<LangGraphClient | null>(null);
+    const renderMessages = atom<RenderMessage[]>([]);
+    const userInput = atom<string>("");
+    const loading = atom<boolean>(false);
+    const collapsedTools = atom<string[]>([]);
+    const inChatError = atom<string | null>(null);
+    const showHistory = atom<boolean>(true);
+    const currentAgent = atom<string>(initClientName);
+    const currentChatId = atom<string | null>(null);
+
+    const initClient = async () => {
+        const newClient = new LangGraphClient(config);
+        await newClient.initAssistant(currentAgent.get());
+        // 不再需要创建，sendMessage 会自动创建
+        // await newClient.createThread();
+
+        newClient.onStreamingUpdate((event) => {
+            if (event.type === "thread" || event.type === "done") {
+                // console.log(event.data);
+                // 创建新会话时，需要自动刷新历史面板
+                return refreshHistoryList();
+            }
+            if (event.type === "error") {
+                loading.set(false);
+                inChatError.set(event.data?.message || "发生错误");
+            }
+            console.log(newClient.renderMessage);
+            renderMessages.set(newClient.renderMessage);
+        });
+        context.onInit?.(newClient);
+        // newClient.tools.bindTools([fileTool, askUserTool]);
+        newClient.graphState = {};
+        client.set(newClient);
+    };
+
+    const sendMessage = async () => {
+        if (!userInput.get().trim() || loading.get() || !client.get()) return;
+
+        loading.set(true);
+        inChatError.set(null);
+
+        await client.get()?.sendMessage(userInput.get());
+
+        userInput.set("");
+        loading.set(false);
+    };
+
+    const interruptMessage = () => {
+        client.get()?.cancelRun();
+    };
+
+    const toggleToolCollapse = (toolId: string) => {
+        const prev = collapsedTools.get();
+        collapsedTools.set(prev.includes(toolId) ? prev.filter((id) => id !== toolId) : [...prev, toolId]);
+    };
+
+    const toggleHistoryVisible = () => {
+        showHistory.set(!showHistory.get());
+    };
+    const historyList = atom<Thread<{ messages: Message[] }>[]>([]);
+    const refreshHistoryList = async () => {
+        if (!client.get()) return;
+        try {
+            const response = await client.get()?.listThreads<{ messages: Message[] }>();
+            historyList.set(response || []);
+        } catch (error) {
+            console.error("Failed to fetch threads:", error);
+        }
+    };
+
+    const addToHistory = (thread: Thread<{ messages: Message[] }>) => {
+        const prev = historyList.get();
+        historyList.set([thread, ...prev]);
+    };
+
+    return {
+        data: {
+            client,
+            renderMessages,
+            userInput,
+            loading,
+            inChatError,
+            currentAgent,
+            collapsedTools,
+            showHistory,
+            historyList,
+            currentChatId,
+        },
+        mutations: {
+            initClient,
+            sendMessage,
+            interruptMessage,
+            toggleToolCollapse,
+            toggleHistoryVisible,
+            refreshHistoryList,
+            addToHistory,
+            setUserInput(input: string) {
+                userInput.set(input);
+            },
+            setCurrentAgent(agent: string) {
+                currentAgent.set(agent);
+                return initClient().then(() => {
+                    refreshHistoryList();
+                });
+            },
+            createNewChat() {
+                client.get()?.reset();
+            },
+            toHistoryChat(
+                thread: Thread<{
+                    messages: Message[];
+                }>
+            ) {
+                client.get()?.resetThread(thread.metadata?.graph_id as string, thread.thread_id);
+            },
+            async deleteHistoryChat(thread: Thread<{ messages: Message[] }>) {
+                await client.get()?.threads.delete(thread.thread_id);
+                await refreshHistoryList();
+            },
+        },
+    };
+};

package/src/ui-store/index.ts

@@ -0,0 +1,2 @@
+export * from "./createChatStore";
+export * from "./UnionStore";