@langchain/langgraph-api 1.2.2-rc.0 → 1.2.2

package/dist/src/api/assistants.d.mts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+declare const api: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default api;

package/dist/src/api/assistants.mjs

@@ -0,0 +1,194 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { v7 as uuid } from "uuid";
+import { z } from "zod/v3";
+import { getAssistantId, getCachedStaticGraphSchema, getGraph, } from "../graph/load.mjs";
+import { getRuntimeGraphSchema } from "../graph/parser/index.mjs";
+import { HTTPException } from "hono/http-exception";
+import * as schemas from "../schemas.mjs";
+import { assistants } from "../storage/context.mjs";
+const api = new Hono();
+const RunnableConfigSchema = z.object({
+    tags: z.array(z.string()).optional(),
+    metadata: z.record(z.unknown()).optional(),
+    run_name: z.string().optional(),
+    max_concurrency: z.number().optional(),
+    recursion_limit: z.number().optional(),
+    configurable: z.record(z.unknown()).optional(),
+    run_id: z.string().uuid().optional(),
+});
+const getRunnableConfig = (userConfig) => {
+    if (!userConfig)
+        return {};
+    return {
+        configurable: userConfig.configurable,
+        tags: userConfig.tags,
+        metadata: userConfig.metadata,
+        runName: userConfig.run_name,
+        maxConcurrency: userConfig.max_concurrency,
+        recursionLimit: userConfig.recursion_limit,
+        runId: userConfig.run_id,
+    };
+};
+api.post("/assistants", zValidator("json", schemas.AssistantCreate), async (c) => {
+    // Create Assistant
+    const payload = c.req.valid("json");
+    const assistant = await assistants().put(payload.assistant_id ?? uuid(), {
+        config: payload.config ?? {},
+        context: payload.context ?? {},
+        graph_id: payload.graph_id,
+        metadata: payload.metadata ?? {},
+        if_exists: payload.if_exists ?? "raise",
+        name: payload.name ?? "Untitled",
+        description: payload.description,
+    }, c.var.auth);
+    return c.json(assistant);
+});
+api.post("/assistants/search", zValidator("json", schemas.AssistantSearchRequest), async (c) => {
+    // Search Assistants
+    const payload = c.req.valid("json");
+    const result = [];
+    let total = 0;
+    for await (const item of assistants().search({
+        graph_id: payload.graph_id,
+        name: payload.name,
+        metadata: payload.metadata,
+        limit: payload.limit ?? 10,
+        offset: payload.offset ?? 0,
+        sort_by: payload.sort_by,
+        sort_order: payload.sort_order,
+        select: payload.select,
+    }, c.var.auth)) {
+        result.push(Object.fromEntries(Object.entries(item.assistant).filter(([k]) => !payload.select || payload.select.includes(k))));
+        if (total === 0) {
+            total = item.total;
+        }
+    }
+    if (total === payload.limit) {
+        c.res.headers.set("X-Pagination-Next", ((payload.offset ?? 0) + total).toString());
+        c.res.headers.set("X-Pagination-Total", ((payload.offset ?? 0) + total + 1).toString());
+    }
+    else {
+        c.res.headers.set("X-Pagination-Total", ((payload.offset ?? 0) + total).toString());
+    }
+    return c.json(result);
+});
+api.post("/assistants/count", zValidator("json", schemas.AssistantCountRequest), async (c) => {
+    const payload = c.req.valid("json");
+    const total = await assistants().count(payload, c.var.auth);
+    return c.json(total);
+});
+api.get("/assistants/:assistant_id", async (c) => {
+    // Get Assistant
+    const assistantId = getAssistantId(c.req.param("assistant_id"));
+    return c.json(await assistants().get(assistantId, c.var.auth));
+});
+api.delete("/assistants/:assistant_id", async (c) => {
+    // Delete Assistant
+    const assistantId = getAssistantId(c.req.param("assistant_id"));
+    const deleteThreads = c.req.query("delete_threads") === "true";
+    return c.json(await assistants().delete(assistantId, deleteThreads, c.var.auth));
+});
+api.patch("/assistants/:assistant_id", zValidator("json", schemas.AssistantPatch), async (c) => {
+    // Patch Assistant
+    const assistantId = getAssistantId(c.req.param("assistant_id"));
+    const payload = c.req.valid("json");
+    return c.json(await assistants().patch(assistantId, payload, c.var.auth));
+});
+api.get("/assistants/:assistant_id/graph", zValidator("query", z.object({ xray: schemas.coercedBoolean.optional() })), async (c) => {
+    // Get Assistant Graph
+    const assistantId = getAssistantId(c.req.param("assistant_id"));
+    const assistant = await assistants().get(assistantId, c.var.auth);
+    const { xray } = c.req.valid("query");
+    const config = getRunnableConfig(assistant.config);
+    const graph = await getGraph(assistant.graph_id, config);
+    const drawable = await graph.getGraphAsync({
+        ...config,
+        xray: xray ?? undefined,
+    });
+    return c.json(drawable.toJSON());
+});
+api.get("/assistants/:assistant_id/schemas", zValidator("json", z.object({ config: RunnableConfigSchema.optional() })), async (c) => {
+    // Get Assistant Schemas
+    const json = c.req.valid("json");
+    const assistantId = getAssistantId(c.req.param("assistant_id"));
+    const assistant = await assistants().get(assistantId, c.var.auth);
+    const config = getRunnableConfig(json.config);
+    const graph = await getGraph(assistant.graph_id, config);
+    const schema = await (async () => {
+        const runtimeSchema = await getRuntimeGraphSchema(graph);
+        if (runtimeSchema)
+            return runtimeSchema;
+        const graphSchema = await getCachedStaticGraphSchema(assistant.graph_id);
+        const rootGraphId = Object.keys(graphSchema).find((i) => !i.includes("|"));
+        if (!rootGraphId)
+            throw new HTTPException(404, { message: "Failed to find root graph" });
+        return graphSchema[rootGraphId];
+    })();
+    return c.json({
+        graph_id: assistant.graph_id,
+        input_schema: schema.input,
+        output_schema: schema.output,
+        state_schema: schema.state,
+        config_schema: schema.config,
+        // From JS PoV `configSchema` and `contextSchema` are indistinguishable,
+        // thus we use config_schema for context_schema.
+        context_schema: schema.config,
+    });
+});
+api.get("/assistants/:assistant_id/subgraphs/:namespace?", zValidator("param", z.object({ assistant_id: z.string(), namespace: z.string().optional() })), zValidator("query", z.object({ recurse: schemas.coercedBoolean.optional() })), async (c) => {
+    // Get Assistant Subgraphs
+    const { assistant_id, namespace } = c.req.valid("param");
+    const { recurse } = c.req.valid("query");
+    const assistantId = getAssistantId(assistant_id);
+    const assistant = await assistants().get(assistantId, c.var.auth);
+    const config = getRunnableConfig(assistant.config);
+    const graph = await getGraph(assistant.graph_id, config);
+    const result = [];
+    const subgraphsGenerator = "getSubgraphsAsync" in graph
+        ? graph.getSubgraphsAsync.bind(graph)
+        : // @ts-expect-error older versions of langgraph don't have getSubgraphsAsync
+            graph.getSubgraphs.bind(graph);
+    let graphSchemaPromise;
+    for await (const [ns, subgraph] of subgraphsGenerator(namespace, recurse)) {
+        const schema = await (async () => {
+            const runtimeSchema = await getRuntimeGraphSchema(subgraph);
+            if (runtimeSchema)
+                return runtimeSchema;
+            graphSchemaPromise ??= getCachedStaticGraphSchema(assistant.graph_id);
+            const graphSchema = await graphSchemaPromise;
+            const rootGraphId = Object.keys(graphSchema).find((i) => !i.includes("|"));
+            if (!rootGraphId) {
+                throw new HTTPException(404, {
+                    message: "Failed to find root graph",
+                });
+            }
+            return graphSchema[`${rootGraphId}|${ns}`] || graphSchema[rootGraphId];
+        })();
+        result.push([ns, schema]);
+    }
+    return c.json(Object.fromEntries(result));
+});
+api.post("/assistants/:assistant_id/latest", zValidator("json", schemas.AssistantLatestVersion), async (c) => {
+    // Set Latest Assistant Version
+    const assistantId = getAssistantId(c.req.param("assistant_id"));
+    const { version } = c.req.valid("json");
+    return c.json(await assistants().setLatest(assistantId, version, c.var.auth));
+});
+api.post("/assistants/:assistant_id/versions", zValidator("json", z.object({
+    limit: z.number().min(1).max(1000).optional().default(10),
+    offset: z.number().min(0).optional().default(0),
+    metadata: z.record(z.unknown()).optional(),
+})), async (c) => {
+    // Get Assistant Versions
+    const assistantId = getAssistantId(c.req.param("assistant_id"));
+    const { limit, offset, metadata } = c.req.valid("json");
+    const versions = await assistants().getVersions(assistantId, { limit, offset, metadata }, c.var.auth);
+    if (!versions?.length) {
+        throw new HTTPException(404, {
+            message: `Assistant "${assistantId}" not found.`,
+        });
+    }
+    return c.json(versions);
+});
+export default api;

package/dist/src/api/meta.d.mts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+declare const api: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default api;

package/dist/src/api/meta.mjs

@@ -0,0 +1,65 @@
+import { Hono } from "hono";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as url from "node:url";
+const api = new Hono();
+// Get the version using the same pattern as semver/index.mts
+const packageJsonPath = path.resolve(url.fileURLToPath(import.meta.url), "../../../package.json");
+let version;
+let langgraph_js_version;
+let versionInfoLoaded = false;
+const loadVersionInfo = async () => {
+    try {
+        const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf-8"));
+        version = packageJson.version;
+    }
+    catch {
+        console.warn("Could not determine version of langgraph-api");
+    }
+    // Get the installed version of @langchain/langgraph
+    try {
+        const langgraphPkg = await import("@langchain/langgraph/package.json");
+        if (langgraphPkg?.default?.version) {
+            langgraph_js_version = langgraphPkg.default.version;
+        }
+    }
+    catch {
+        console.warn("Could not determine version of @langchain/langgraph");
+    }
+};
+// read env variable
+const env = process.env;
+api.get("/info", async (c) => {
+    if (!versionInfoLoaded) {
+        await loadVersionInfo();
+        versionInfoLoaded = true;
+    }
+    const langsmithApiKey = env["LANGSMITH_API_KEY"] || env["LANGCHAIN_API_KEY"];
+    const langsmithTracing = (() => {
+        if (langsmithApiKey) {
+            // Check if any tracing variable is explicitly set to "false"
+            const tracingVars = [
+                env["LANGCHAIN_TRACING_V2"],
+                env["LANGCHAIN_TRACING"],
+                env["LANGSMITH_TRACING_V2"],
+                env["LANGSMITH_TRACING"],
+            ];
+            // Return true unless explicitly disabled
+            return !tracingVars.some((val) => val === "false" || val === "False");
+        }
+        return undefined;
+    })();
+    return c.json({
+        version,
+        langgraph_js_version,
+        context: "js",
+        flags: {
+            assistants: true,
+            crons: false,
+            langsmith: !!langsmithTracing,
+            langsmith_tracing_replicas: true,
+        },
+    });
+});
+api.get("/ok", (c) => c.json({ ok: true }));
+export default api;

package/dist/src/api/protocol.d.mts

@@ -0,0 +1,7 @@
+import { Hono } from "hono";
+import type { UpgradeWebSocket } from "hono/ws";
+import type { Ops } from "../storage/types.mjs";
+/**
+ * Register thread-centric protocol transport routes for LangGraph API.
+ */
+export default function createProtocolApi(upgradeWebSocket: UpgradeWebSocket, ops: Ops): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/src/api/protocol.mjs

@@ -0,0 +1,157 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { v7 as uuid7 } from "uuid";
+import { z } from "zod/v3";
+import { ProtocolService } from "../protocol/service.mjs";
+import { jsonExtra } from "../utils/hono.mjs";
+import { serialiseAsDict } from "../utils/serde.mjs";
+const ThreadIdSchema = z.object({ thread_id: z.string() });
+const EventsFilterSchema = z
+    .object({
+    channels: z.array(z.string()),
+    namespaces: z.array(z.array(z.string())).optional(),
+    depth: z.number().int().nonnegative().optional(),
+    since: z.number().int().nonnegative().optional(),
+})
+    .strict();
+const ProtocolCommandSchema = z.object({
+    id: z.number().int().nonnegative(),
+    method: z.string(),
+    params: z.record(z.unknown()).optional(),
+});
+/**
+ * Normalize browser/node websocket message payloads into UTF-8 text so the
+ * protocol layer only needs to handle JSON strings.
+ */
+const parseSocketPayload = async (event) => {
+    if (typeof event.data === "string")
+        return event.data;
+    if (event.data instanceof ArrayBuffer) {
+        return new TextDecoder().decode(new Uint8Array(event.data));
+    }
+    if (event.data instanceof Blob) {
+        const buffer = await event.data.arrayBuffer();
+        return new TextDecoder().decode(new Uint8Array(buffer));
+    }
+    return String(event.data);
+};
+/**
+ * Register thread-centric protocol transport routes for LangGraph API.
+ */
+export default function createProtocolApi(upgradeWebSocket, ops) {
+    const api = new Hono();
+    const protocolService = new ProtocolService({
+        runs: ops.runs,
+        threads: ops.threads,
+    });
+    api.get("/threads/:thread_id/stream/events", zValidator("param", ThreadIdSchema), upgradeWebSocket((c) => {
+        const { thread_id } = c.req.valid("param");
+        const record = protocolService.ensureThread({
+            threadId: thread_id,
+            transport: "websocket",
+            auth: c.var.auth,
+        });
+        return {
+            async onOpen(_event, ws) {
+                await protocolService.attachEventSink(thread_id, (event) => {
+                    ws.send(serialiseAsDict(event));
+                });
+            },
+            async onMessage(event, ws) {
+                let payload;
+                try {
+                    payload = JSON.parse(await parseSocketPayload(event));
+                }
+                catch {
+                    ws.send(serialiseAsDict({
+                        type: "error",
+                        id: null,
+                        error: "invalid_argument",
+                        message: "Protocol commands must be valid JSON.",
+                    }));
+                    return;
+                }
+                if (typeof payload !== "object" ||
+                    payload == null ||
+                    typeof payload.id !== "number" ||
+                    typeof payload.method !== "string") {
+                    ws.send(serialiseAsDict({
+                        type: "error",
+                        id: null,
+                        error: "invalid_argument",
+                        message: "Protocol commands must include an integer id and string method.",
+                    }));
+                    return;
+                }
+                const response = await protocolService.handleCommand(record.threadId, payload);
+                // `null` means the session already wrote the response through
+                // the shared transport queue (see
+                // `ProtocolSession.handleSubscribeForResponse`). Sending again
+                // here would double-deliver the success and break ordering.
+                if (response != null) {
+                    ws.send(serialiseAsDict(response));
+                }
+            },
+            onClose() {
+                void protocolService.closeThread(record.threadId);
+            },
+            onError() {
+                void protocolService.closeThread(record.threadId);
+            },
+        };
+    }));
+    api.post("/threads/:thread_id/commands", zValidator("param", ThreadIdSchema), zValidator("json", ProtocolCommandSchema), async (c) => {
+        const { thread_id } = c.req.valid("param");
+        protocolService.ensureThread({
+            threadId: thread_id,
+            transport: "sse-http",
+            auth: c.var.auth,
+        });
+        const payload = c.req.valid("json");
+        return jsonExtra(c, await protocolService.handleCommand(thread_id, payload));
+    });
+    api.post("/threads/:thread_id/stream/events", zValidator("param", ThreadIdSchema), zValidator("json", EventsFilterSchema), async (c) => {
+        const { thread_id } = c.req.valid("param");
+        protocolService.ensureThread({
+            threadId: thread_id,
+            transport: "sse-http",
+            auth: c.var.auth,
+        });
+        const body = c.req.valid("json");
+        const sinkId = uuid7();
+        const filter = {
+            channels: new Set(body.channels),
+            namespaces: body.namespaces,
+            depth: body.depth,
+            since: body.since,
+        };
+        return streamSSE(c, async (stream) => {
+            const delivered = new Set();
+            const writeSse = async (event) => {
+                if (event.event_id == null)
+                    return;
+                if (delivered.has(event.event_id))
+                    return;
+                delivered.add(event.event_id);
+                await stream.writeSSE({
+                    id: event.event_id,
+                    event: event.method,
+                    data: serialiseAsDict(event),
+                });
+            };
+            await protocolService.attachFilteredEventSink(thread_id, {
+                id: sinkId,
+                filter,
+                send: writeSse,
+            });
+            stream.onAbort(() => {
+                protocolService.detachEventSink(thread_id, sinkId);
+            });
+            await new Promise((resolve) => {
+                stream.onAbort(() => resolve());
+            });
+        });
+    });
+    return api;
+}

package/dist/src/api/runs.d.mts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+declare const api: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default api;