fix: honor checkpointer.serde.allowed_msgpack_modules in langgraph.json (#1500)

Author: radu-mocanu

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-langchain"
-version = "0.10.10"
+version = "0.10.11"
 description = "Python SDK that enables developers to build and deploy LangGraph agents to the UiPath Cloud Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

samples/checkpoint-allowlist/README.md

@@ -0,0 +1,15 @@
+# checkpoint-allowlist
+
+Shows how to silence langgraph's `Deserializing unregistered type` warning by declaring custom types in `langgraph.json`'s `serde.allowed_msgpack_modules` block.
+
+Graph: `START -> evaluate -> finalize -> END`. State carries a custom Pydantic `Score` value, which langgraph reconstructs on every checkpoint round-trip.
+
+## Run
+
+```bash
+uv sync
+uv run uipath init
+uv run uipath run agent --file input.json
+```
+
+Expect: agent completes, no `Deserializing unregistered type ...Score` warning. Remove the `serde` block from `langgraph.json` to see the warning return.

samples/checkpoint-allowlist/input.json

@@ -0,0 +1,3 @@
+{
+  "topic": "weather"
+}

samples/checkpoint-allowlist/langgraph.json

@@ -0,0 +1,14 @@
+{
+  "dependencies": ["."],
+  "graphs": {
+    "agent": "./main.py:graph"
+  },
+  "env": ".env",
+  "checkpointer": {
+    "serde": {
+      "allowed_msgpack_modules": [
+        ["main", "Score"]
+      ]
+    }
+  }
+}

samples/checkpoint-allowlist/main.py

@@ -0,0 +1,44 @@
+"""Minimal LangGraph agent with custom Pydantic types in graph state.
+
+LangGraph's `JsonPlusSerializer` warns whenever a checkpoint contains a custom
+class that has not been allowlisted (`Deserializing unregistered type ...`).
+This sample shows how to silence the warning by declaring the types in
+`langgraph.json`'s `serde.allowed_msgpack_modules` block. uipath-langchain
+unions the user's list with its own SDK interrupt models when the block is
+present.
+
+Two nodes, no LLM, no interrupt — the warning fires on the in-process
+checkpoint round-trip between nodes.
+"""
+
+from pydantic import BaseModel
+
+from langgraph.graph import END, START, StateGraph
+
+
+class Score(BaseModel):
+    label: str = ""
+    value: float = 0.0
+
+
+class State(BaseModel):
+    topic: str
+    score: Score | None = None
+
+
+async def evaluate(state: State) -> State:
+    return State(topic=state.topic, score=Score(label="ok", value=1.0))
+
+
+async def finalize(state: State) -> State:
+    return state
+
+
+builder = StateGraph(State)
+builder.add_node("evaluate", evaluate)
+builder.add_node("finalize", finalize)
+builder.add_edge(START, "evaluate")
+builder.add_edge("evaluate", "finalize")
+builder.add_edge("finalize", END)
+
+graph = builder.compile()

samples/checkpoint-allowlist/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "checkpoint-allowlist-sample"
+version = "0.0.1"
+description = "Sample showing how to allowlist custom types in langgraph.json's serde block"
+authors = [{ name = "UiPath" }]
+requires-python = ">=3.11"
+dependencies = [
+    "langgraph>=1.1.8,<2.0.0",
+    "langgraph-checkpoint-sqlite>=3.0.0",
+    "pydantic>=2.10.6",
+    "uipath",
+    "uipath-langchain",
+]

src/uipath_langchain/runtime/config.py

@@ -2,6 +2,7 @@
 
 import json
 import os
+from typing import Any
 
 
 class LangGraphConfig:
@@ -15,13 +16,25 @@ def __init__(self, config_path: str = "langgraph.json"):
             config_path: Path to langgraph.json file
         """
         self.config_path = config_path
-        self._graphs: dict[str, str] | None = None
+        self._raw: dict[str, Any] | None = None
 
     @property
     def exists(self) -> bool:
         """Check if langgraph.json exists."""
         return os.path.exists(self.config_path)
 
+    def _load(self) -> dict[str, Any]:
+        if self._raw is not None:
+            return self._raw
+        if not self.exists:
+            raise FileNotFoundError(f"Config file not found: {self.config_path}")
+        try:
+            with open(self.config_path, "r") as f:
+                self._raw = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {self.config_path}: {e}") from e
+        return self._raw
+
     @property
     def graphs(self) -> dict[str, str]:
         """
@@ -30,30 +43,62 @@ def graphs(self) -> dict[str, str]:
         Returns:
             Dictionary mapping graph names to file paths (e.g., {"agent": "agent.py:graph"})
         """
-        if self._graphs is None:
-            self._graphs = self._load_graphs()
-        return self._graphs
+        config = self._load()
+        if "graphs" not in config:
+            raise ValueError("Missing required 'graphs' field in langgraph.json")
+        graphs = config["graphs"]
+        if not isinstance(graphs, dict):
+            raise ValueError("'graphs' must be a dictionary")
+        return graphs
 
-    def _load_graphs(self) -> dict[str, str]:
-        """Load graph definitions from langgraph.json."""
-        if not self.exists:
-            raise FileNotFoundError(f"Config file not found: {self.config_path}")
-
-        try:
-            with open(self.config_path, "r") as f:
-                config = json.load(f)
-
-            if "graphs" not in config:
-                raise ValueError("Missing required 'graphs' field in langgraph.json")
+    @property
+    def allowed_msgpack_modules(self) -> list[tuple[str, str]] | None:
+        """Read `checkpointer.serde.allowed_msgpack_modules` from langgraph.json.
 
-            graphs = config["graphs"]
-            if not isinstance(graphs, dict):
-                raise ValueError("'graphs' must be a dictionary")
+        Returns the list of `(module, class_name)` pairs the user opted into,
+        or `None` if no opt-in — in which case the runtime keeps langgraph's
+        default permissive behavior.
 
-            return graphs
+        Schema (matches langgraph CLI's `CheckpointerConfig.serde`):
 
-        except json.JSONDecodeError as e:
-            raise ValueError(f"Invalid JSON in {self.config_path}: {e}") from e
+            {
+              "checkpointer": {
+                "serde": {
+                  "allowed_msgpack_modules": [
+                    ["my_app.state", "MyState"]
+                  ]
+                }
+              }
+            }
+        """
+        config = self._load()
+        checkpointer = config.get("checkpointer")
+        if not isinstance(checkpointer, dict):
+            return None
+        serde = checkpointer.get("serde")
+        if not isinstance(serde, dict):
+            return None
+        modules = serde.get("allowed_msgpack_modules")
+        if modules is None:
+            return None
+        if not isinstance(modules, list):
+            raise ValueError(
+                "'checkpointer.serde.allowed_msgpack_modules' must be a list "
+                "of [module, class_name] pairs"
+            )
+        result: list[tuple[str, str]] = []
+        for entry in modules:
+            if (
+                not isinstance(entry, list)
+                or len(entry) != 2
+                or not all(isinstance(part, str) for part in entry)
+            ):
+                raise ValueError(
+                    f"Invalid entry in checkpointer.serde.allowed_msgpack_modules: "
+                    f"{entry!r} (expected [module, class_name])"
+                )
+            result.append((entry[0], entry[1]))
+        return result
 
     @property
     def entrypoints(self) -> list[str]:

src/uipath_langchain/runtime/factory.py

@@ -1,7 +1,9 @@
 import asyncio
+import inspect
 import os
 from typing import Any, AsyncContextManager
 
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
 from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
 from langgraph.graph.state import CompiledStateGraph, StateGraph
 from openinference.instrumentation.langchain import (
@@ -30,6 +32,22 @@
 from uipath_langchain.runtime.storage import SqliteResumableStorage
 
 
+def _collect_sdk_interrupt_modules() -> list[tuple[str, str]]:
+    """Return `(module, class_name)` pairs for every SDK interrupt model.
+
+    These are the first-party types the SDK itself places into checkpoints
+    (`CreateTask`, `InvokeProcess`, `WaitJob`, …) and that users should not
+    have to register manually.
+    """
+    from uipath.platform.common import interrupt_models
+
+    return [
+        (cls.__module__, cls.__name__)
+        for _, cls in inspect.getmembers(interrupt_models, inspect.isclass)
+        if cls.__module__ == interrupt_models.__name__
+    ]
+
+
 class UiPathLangGraphRuntimeFactory:
     """Factory for creating LangGraph runtimes from langgraph.json configuration."""
 
@@ -95,8 +113,28 @@ async def _get_memory(self) -> AsyncSqliteSaver:
                 self._memory_cm = AsyncSqliteSaver.from_conn_string(connection_string)
                 self._memory = await self._memory_cm.__aenter__()
                 await self._memory.setup()
+                self._apply_msgpack_allowlist(self._memory)
         return self._memory
 
+    def _apply_msgpack_allowlist(self, memory: AsyncSqliteSaver) -> None:
+        """Replace the saver's serde when the user declared a msgpack allowlist.
+
+        When `langgraph.json` contains `serde.allowed_msgpack_modules`, build
+        a strict-mode `JsonPlusSerializer` whose allowlist is the union of the
+        SDK's interrupt models (so checkpoint payloads like `CreateTask` and
+        `InvokeProcess` keep round-tripping) and the user's declared types.
+
+        Without an opt-in, the saver keeps langgraph's default permissive
+        serde — preserving today's behavior for existing agents.
+        """
+        user_modules = self._load_config().allowed_msgpack_modules
+        if user_modules is None:
+            return
+        sdk_modules = _collect_sdk_interrupt_modules()
+        memory.serde = JsonPlusSerializer(
+            allowed_msgpack_modules=[*sdk_modules, *user_modules],
+        )
+
     def _load_config(self) -> LangGraphConfig:
         """Load langgraph.json configuration."""
         if self._config is None:

testcases/checkpoint-allowlist/pyproject.toml

@@ -0,0 +1,12 @@
+[project]
+name = "checkpoint-allowlist"
+version = "0.0.1"
+description = "Verifies serde.allowed_msgpack_modules in langgraph.json silences langgraph warnings"
+authors = [{ name = "UiPath" }]
+requires-python = ">=3.11"
+dependencies = [
+    "uipath-langchain",
+]
+
+[tool.uv.sources]
+uipath-langchain = { path = "../../", editable = true }

testcases/checkpoint-allowlist/run.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -e
+
+SAMPLE_DIR="../../samples/checkpoint-allowlist"
+
+echo "Copying sample files..."
+cp "$SAMPLE_DIR/main.py" main.py
+cp "$SAMPLE_DIR/langgraph.json" langgraph.json
+cp "$SAMPLE_DIR/input.json" input.json
+
+echo "Syncing dependencies..."
+uv sync
+
+echo "Authenticating with UiPath..."
+uv run uipath auth --client-id="$CLIENT_ID" --client-secret="$CLIENT_SECRET" --base-url="$BASE_URL"
+
+echo "Initializing the project..."
+uv run uipath init
+
+echo "Running agent (with serde block) — capturing log..."
+uv run uipath run agent --file input.json 2>&1 | tee local_run_output.log