Skip to content

The Open Standard for Generative UI

Server: persist LangGraph conversation history (#1325)

AB23f985af5c70
diff --git a/.changeset/langgraph-conversation-history.md b/.changeset/langgraph-conversation-history.md
new file mode 100644
index 000000000..ae55b4be5
--- /dev/null
+++ b/.changeset/langgraph-conversation-history.md
@@ -0,0 +1,5 @@
+---
+"@openuidev/server": patch
+---
+
+Add LangGraph message conversion and conversation-history storage through the new langgraph entry point.
diff --git a/packages/server/README.md b/packages/server/README.md
index 6111c087a..1b9a9c2aa 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -131,3 +131,27 @@ chatCompletionMessagesToItems([
{ role: "assistant", content: "hi" },
]);
```
+
+### LangGraph
+
+Import `storeLangGraphHistory` from `@openuidev/server/langgraph`. Pass completed
+`BaseMessage` instances from `@langchain/core/messages`, the message types used
+by LangGraph. This entry point requires the optional `@langchain/core` peer
+dependency; other server entry points do not.
+
+```ts
+import { storeLangGraphHistory } from "@openuidev/server/langgraph";
+
+await storeLangGraphHistory({
+ apiKey: process.env.THESYS_API_KEY!,
+ conversationId: threadId,
+ messages: newTurnMessages,
+});
+```
+
+Store only the new turn, including tool calls and results. Passing the full
+replayed history or individual streaming chunks creates duplicate items.
+The conversation must already exist. System/developer instructions are skipped;
+text and user `image_url` blocks are supported. Use `langGraphMessagesToItems`
+for conversion without a network request. `apiBaseUrl` and `fetch` work as in
+`storeChatCompletionHistory`; storage failures reject the returned promise.
diff --git a/packages/server/package.json b/packages/server/package.json
index b23920574..2f87807b5 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -45,6 +45,16 @@
"types": "./dist/vercel/index.d.cts",
"default": "./dist/vercel/index.cjs"
}
+ },
+ "./langgraph": {
+ "import": {
+ "types": "./dist/langgraph/index.d.mts",
+ "default": "./dist/langgraph/index.mjs"
+ },
+ "require": {
+ "types": "./dist/langgraph/index.d.cts",
+ "default": "./dist/langgraph/index.cjs"
+ }
}
},
"scripts": {
@@ -80,6 +90,7 @@
"@openuidev/lang-core": "workspace:^"
},
"devDependencies": {
+ "@langchain/core": "^1.2.3",
"ai": "^7.0.10",
"openai": "^7.20.0",
"tsdown": "^0.21.7",
@@ -92,7 +103,18 @@
],
"vercel": [
"dist/vercel/index.d.cts"
+ ],
+ "langgraph": [
+ "dist/langgraph/index.d.cts"
]
}
+ },
+ "peerDependencies": {
+ "@langchain/core": "^1.2.3"
+ },
+ "peerDependenciesMeta": {
+ "@langchain/core": {
+ "optional": true
+ }
}
}
diff --git a/packages/server/src/langgraph/index.ts b/packages/server/src/langgraph/index.ts
new file mode 100644
index 000000000..b0515ac3b
--- /dev/null
+++ b/packages/server/src/langgraph/index.ts
@@ -0,0 +1,94 @@
+import {
+ isAIMessage,
+ isHumanMessage,
+ isToolMessage,
+ type BaseMessage,
+} from "@langchain/core/messages";
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import {
+ chatCompletionMessagesToItems,
+ storeChatCompletionHistory,
+} from "../openai/store-conversation-items.js";
+import type { StoreChatCompletionHistoryOptions } from "../openai/types.js";
+
+export type StoreLangGraphHistoryOptions = Omit<StoreChatCompletionHistoryOptions, "messages"> & {
+ /** Only completed messages from the new turn, never the full replay. */
+ messages: readonly BaseMessage[];
+};
+
+function toChatCompletionMessages(messages: readonly BaseMessage[]): ChatCompletionMessageParam[] {
+ const result: ChatCompletionMessageParam[] = [];
+ for (const message of messages) {
+ if (isHumanMessage(message)) {
+ // LangChain's text/image_url content blocks use the Chat Completions shape.
+ const content: Extract<ChatCompletionMessageParam, { role: "user" }>["content"] =
+ typeof message.content === "string" ? message.content : [];
+ if (Array.isArray(content) && Array.isArray(message.content)) {
+ for (const part of message.content) {
+ if (typeof part !== "object" || part === null) continue;
+ const block = part;
+ if (block.type === "text" && typeof block.text === "string") {
+ content.push({ type: "text", text: block.text });
+ } else if (block.type === "image_url") {
+ const image = block["image_url"];
+ if (typeof image === "string") {
+ content.push({ type: "image_url", image_url: { url: image } });
+ } else if (
+ typeof image === "object" &&
+ image !== null &&
+ "url" in image &&
+ typeof image.url === "string"
+ ) {
+ const detail = "detail" in image ? image.detail : undefined;
+ content.push({
+ type: "image_url",
+ image_url: {
+ url: image.url,
+ detail: detail === "low" || detail === "high" ? detail : "auto",
+ },
+ });
+ }
+ }
+ }
+ }
+ result.push({ role: "user", content });
+ } else if (isAIMessage(message)) {
+ result.push({
+ role: "assistant",
+ content: message.text,
+ tool_calls: (message.tool_calls ?? [])
+ .filter((call) => call.id && call.name)
+ .map((call) => ({
+ type: "function",
+ id: call.id!,
+ function: {
+ name: call.name,
+ arguments:
+ typeof call.args === "string" ? call.args : JSON.stringify(call.args ?? {}),
+ },
+ })),
+ });
+ } else if (isToolMessage(message) && message.tool_call_id) {
+ result.push({
+ role: "tool",
+ tool_call_id: message.tool_call_id,
+ content: message.text,
+ });
+ }
+ // System/developer instructions and unknown message types are not history.
+ }
+ return result;
+}
+
+/** Convert a new LangGraph turn, including tool calls/results, into conversation items. */
+export function langGraphMessagesToItems(messages: readonly BaseMessage[]) {
+ return chatCompletionMessagesToItems(toChatCompletionMessages(messages));
+}
+
+/** Append a new turn to an existing conversation. Do not pass replayed history or chunks. */
+export function storeLangGraphHistory(options: StoreLangGraphHistoryOptions) {
+ return storeChatCompletionHistory({
+ ...options,
+ messages: toChatCompletionMessages(options.messages),
+ });
+}
diff --git a/packages/server/tsdown.config.ts b/packages/server/tsdown.config.ts
index 1ba4a4023..c514c793d 100644
--- a/packages/server/tsdown.config.ts
+++ b/packages/server/tsdown.config.ts
@@ -30,4 +30,10 @@ export default defineConfig([
outDir: "dist/vercel",
clean: false,
},
+ {
+ ...shared,
+ entry: { index: "src/langgraph/index.ts" },
+ outDir: "dist/langgraph",
+ clean: false,
+ },
]);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 83471e93a..adb631dc3 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -930,6 +930,9 @@ importers:
specifier: workspace:^
version: link:../lang-core
devDependencies:
+ '@langchain/core':
+ specifier: ^1.2.3
ai:
specifier: ^7.0.10
version: 7.0.10([email protected])