Add default TTL in store & CLI (#3786)

While working on langchain-ai/langgraphjs#984 I ported the test I was
debugging over to python so I could compare behavior. Figured I might as
well add it to this codebase, as I don't think we had this particular
case covered previously.

.github/workflows/_lint.yml

@@ -54,7 +54,7 @@ jobs:
         if: steps.changed-files.outputs.all
         shell: bash
         working-directory: ${{ inputs.working-directory }}
-        run: poetry lock --check
+        run: poetry check --lock
 
       - name: Install dependencies
         if: steps.changed-files.outputs.all

.github/workflows/_test.yml

@@ -39,6 +39,12 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_RO_TOKEN }}
 
+      - name: Check Lock
+        shell: bash
+        working-directory: ${{ inputs.working-directory }}
+        run: |
+          poetry check --lock
+
       - name: Install dependencies
         shell: bash
         working-directory: ${{ inputs.working-directory }}

.github/workflows/ci.yml

@@ -114,6 +114,42 @@ jobs:
       - name: Run check_sdk_methods script
         run: python .github/scripts/check_sdk_methods.py
 
+  check-schema:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
+    name: "Check CLI schema hasn't changed #${{ matrix.python-version }}"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.11"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }} + Poetry ${{ env.POETRY_VERSION }}
+        uses: "./.github/actions/poetry_setup"
+        with:
+          python-version: "3.11"
+          poetry-version: ${{ env.POETRY_VERSION }}
+          cache-key: schema-check-cli
+      - name: Install CLI dependencies
+        run: |
+          cd libs/cli
+          poetry install
+      - name: Generate schema and check for changes
+        run: |
+          cd libs/cli
+          # Create a temporary copy of the current schema
+          cp schemas/schema.json schemas/schema.current.json
+          # Generate new schema
+          poetry run python generate_schema.py
+          # Compare the new schema with the original
+          if ! diff -q schemas/schema.json schemas/schema.current.json > /dev/null; then
+            echo "Error: Langgraph.json configuration schema has changed. Please run 'poetry run python generate_schema.py' in the libs/cli directory and commit the changes."
+            diff schemas/schema.json schemas/schema.current.json
+            exit 1
+          fi
+          echo "Schema check passed - no changes detected"
+
   integration-test:
     needs: changes
     if: needs.changes.outputs.python == 'true'
@@ -180,6 +216,8 @@ jobs:
         test,
         test-langgraph,
         test-scheduler-kafka,
+        check-sdk-methods,
+        check-schema,
         integration-test,
         test-js,
       ]

README.md

@@ -1,6 +1,6 @@
 # 🦜🕸️LangGraph
 
-![Version](https://img.shields.io/pypi/v/langgraph)
+[![Version](https://img.shields.io/pypi/v/langgraph.svg)](https://pypi.org/project/langgraph/)
 [![Downloads](https://static.pepy.tech/badge/langgraph/month)](https://pepy.tech/project/langgraph)
 [![Open Issues](https://img.shields.io/github/issues-raw/langchain-ai/langgraph)](https://github.com/langchain-ai/langgraph/issues)
 [![Docs](https://img.shields.io/badge/docs-latest-blue)](https://langchain-ai.github.io/langgraph/)

docs/_scripts/third_party_page/packages.yml

@@ -23,4 +23,10 @@ packages:
     description: "Build swarm-style multi-agent systems using LangGraph."
   - name: "delve-taxonomy-generator"
     repo: "andrestorres123/delve"
-    description: "A taxonomy generator for unstructured data"
+    description: "A taxonomy generator for unstructured data"
+  - name: "nodeology"
+    repo: "xyin-anl/Nodeology"
+    description: "Enable researcher to build scientific workflows easily with simplified interface."
+  - name: "langgraph-bigtool"
+    repo: "langchain-ai/langgraph-bigtool"
+    description: "Build LangGraph agents with large numbers of tools."

docs/docs/cloud/deployment/semantic_search.md

@@ -17,7 +17,7 @@ This guide explains how to add semantic search to your LangGraph deployment's cr
     ...
     "store": {
         "index": {
-            "embed": "openai:text-embeddings-3-small",
+            "embed": "openai:text-embedding-3-small",
             "dims": 1536,
             "fields": ["$"]
         }
@@ -27,7 +27,7 @@ This guide explains how to add semantic search to your LangGraph deployment's cr
 
 This configuration:
 
-- Uses OpenAI's text-embeddings-3-small model for generating embeddings
+- Uses OpenAI's text-embedding-3-small model for generating embeddings
 - Sets the embedding dimension to 1536 (matching the model's output)
 - Indexes all fields in your stored data (`["$"]` means index everything, or specify specific fields like `["text", "metadata.title"]`)
 

docs/docs/how-tos/memory/add-summary-conversation-history.ipynb

@@ -10,6 +10,7 @@
     "One of the most common use cases for persistence is to use it to keep track of conversation history. This is great - it makes it easy to continue conversations. As conversations get longer and longer, however, this conversation history can build up and take up more and more of the context window. This can often be undesirable as it leads to more expensive and longer calls to the LLM, and potentially ones that error. One way to work around that is to create a summary of the conversation to date, and use that with the past N messages. This guide will go through an example of how to do that.\n",
     "\n",
     "This will involve a few steps:\n",
+    "\n",
     "- Check if the conversation is too long (can be done by checking number of messages or length of messages)\n",
     "- If yes, the create summary (will need a prompt for this)\n",
     "- Then remove all except the last N messages\n",

docs/docs/llms.txt

@@ -0,0 +1,191 @@
+# LangGraph
+
+## Quickstart
+
+These guides are designed to help you get started with LangGraph.
+
+- [LangGraph Quickstart](https://langchain-ai.github.io/langgraph/tutorials/introduction/): Build a chatbot that can use tools and keep track of conversation history. Add human-in-the-loop capabilities and explore how time-travel works.
+- [Common Workflows](https://langchain-ai.github.io/langgraph/tutorials/workflows/): Overview of the most common workflows using LLMs implemented with LangGraph.
+- [LangGraph Server Quickstart](https://langchain-ai.github.io/langgraph/tutorials/langgraph-platform/local-server/): Launch a LangGraph server locally and interact with it using REST API and LangGraph Studio Web UI.
+- [Deploy with LangGraph Cloud Quickstart](https://langchain-ai.github.io/langgraph/cloud/quick_start/): Deploy a LangGraph app using LangGraph Cloud.
+
+## Concepts
+
+These guides provide explanations of the key concepts behind the LangGraph framework.
+
+- [Why LangGraph?](https://langchain-ai.github.io/langgraph/concepts/high_level/): Motivation for LangGraph, a library for building agentic applications with LLMs.
+- [LangGraph Glossary](https://langchain-ai.github.io/langgraph/concepts/low_level/): LangGraph workflows are designed as graphs, with nodes representing different components and edges representing the flow of information between them. This guide provides an overview of the key concepts associated with LangGraph graph primitives.
+- [Common Agentic Patterns](https://langchain-ai.github.io/langgraph/concepts/agentic_concepts/): An agent uses an LLM to pick its own control flow to solve more complex problems! Agents are a key building block in many LLM applications. This guide explains the different types of agent architectures and how they can be used to control the flow of an application.
+- [Multi-Agent Systems](https://langchain-ai.github.io/langgraph/concepts/multi_agent/): Complex LLM applications can often be broken down into multiple agents, each responsible for a different part of the application. This guide explains common patterns for building multi-agent systems.
+- [Breakpoints](https://langchain-ai.github.io/langgraph/concepts/breakpoints/): Breakpoints allow pausing the execution of a graph at specific points. Breakpoints allow stepping through graph execution for debugging purposes.
+- [Human-in-the-Loop](https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/): Explains different ways of integrating human feedback into a LangGraph application.
+- [Time Travel](https://langchain-ai.github.io/langgraph/concepts/time-travel/): Time travel allows you to replay past actions in your LangGraph application to explore alternative paths and debug issues.
+- [Persistence](https://langchain-ai.github.io/langgraph/concepts/persistence/): LangGraph has a built-in persistence layer, implemented through checkpointers. This persistence layer helps to support powerful capabilities like human-in-the-loop, memory, time travel, and fault-tolerance.
+- [Memory](https://langchain-ai.github.io/langgraph/concepts/memory/): Memory in AI applications refers to the ability to process, store, and effectively recall information from past interactions. With memory, your agents can learn from feedback and adapt to users' preferences.
+- [Streaming](https://langchain-ai.github.io/langgraph/concepts/streaming/): Streaming is crucial for enhancing the responsiveness of applications built on LLMs. By displaying output progressively, even before a complete response is ready, streaming significantly improves user experience (UX), particularly when dealing with the latency of LLMs.
+- [Functional API](https://langchain-ai.github.io/langgraph/concepts/functional_api/): `@entrypoint` and `@task` decorators that allow you to add LangGraph functionality to an existing codebase.
+- [Durable Execution](https://langchain-ai.github.io/langgraph/concepts/durable_execution/): LangGraph's built-in [persistence](https://langchain-ai.github.io/langgraph/concepts/persistence/) layer provides durable execution for workflows, ensuring that the state of each execution step is saved to a durable store. 
+- [Pregel](https://langchain-ai.github.io/langgraph/concepts/pregel/): Pregel is LangGraph's runtime, which is responsible for managing the execution of LangGraph applications.
+- [FAQ](https://langchain-ai.github.io/langgraph/concepts/faq/): Frequently asked questions about LangGraph.
+
+## How-tos
+
+Here you’ll find answers to “How do I...?” types of questions. 
+
+These guides are **goal-oriented** and concrete. 
+
+They're meant to help you complete a specific task.
+
+### Graph API Basics
+
+- [How to update graph state from nodes](https://langchain-ai.github.io/langgraph/how-tos/state-reducers/)
+- [How to create a sequence of steps](https://langchain-ai.github.io/langgraph/how-tos/sequence/)
+- [How to create branches for parallel execution](https://langchain-ai.github.io/langgraph/how-tos/branching/)
+- [How to create and control loops with recursion limits](https://langchain-ai.github.io/langgraph/how-tos/recursion-limit/)
+- [How to visualize your graph](https://langchain-ai.github.io/langgraph/how-tos/visualization/)
+
+### Fine-grained Control
+
+These guides demonstrate LangGraph features that grant fine-grained control over the execution of your graph.
+
+- [How to create map-reduce branches for parallel execution](https://langchain-ai.github.io/langgraph/how-tos/map-reduce/)
+- [How to update state and jump to nodes in graphs and subgraphs](https://langchain-ai.github.io/langgraph/how-tos/command/)
+- [How to add runtime configuration to your graph](https://langchain-ai.github.io/langgraph/how-tos/configuration/)
+- [How to add node retries](https://langchain-ai.github.io/langgraph/how-tos/node-retries/)
+- [How to return state before hitting recursion limit](https://langchain-ai.github.io/langgraph/how-tos/return-when-recursion-limit-hits/)
+
+### Persistence
+ 
+Persistence makes it easy to persist state across graph runs (per-thread persistence) and across threads (cross-thread persistence). 
+
+These how-to guides show how to add persistence to your graph.
+
+- [How to add thread-level persistence to your graph](https://langchain-ai.github.io/langgraph/how-tos/persistence/)
+- [How to add thread-level persistence to a subgraph](https://langchain-ai.github.io/langgraph/how-tos/subgraph-persistence/)
+- [How to add cross-thread persistence to your graph](https://langchain-ai.github.io/langgraph/how-tos/cross-thread-persistence/)
+- [How to use Postgres checkpointer for persistence](https://langchain-ai.github.io/langgraph/how-tos/persistence_postgres/)
+- [How to use MongoDB checkpointer for persistence](https://langchain-ai.github.io/langgraph/how-tos/persistence_mongodb/)
+- [How to create a custom checkpointer using Redis](https://langchain-ai.github.io/langgraph/how-tos/persistence_redis/)
+
+See the below guides for how-to add persistence to your workflow using the [Functional API](https://langchain-ai.github.io/langgraph/concepts/functional_api/):
+
+- [How to add thread-level persistence (functional API)](https://langchain-ai.github.io/langgraph/how-tos/persistence-functional/)
+- [How to add cross-thread persistence (functional API)](https://langchain-ai.github.io/langgraph/how-tos/cross-thread-persistence-functional/)
+
+### Memory
+
+LangGraph makes it easy to manage conversation memory in your graph. These how-to guides show how to implement different strategies for that.
+
+- [How to manage conversation history](https://langchain-ai.github.io/langgraph/how-tos/memory/manage-conversation-history/)
+- [How to delete messages](https://langchain-ai.github.io/langgraph/how-tos/memory/delete-messages/)
+- [How to add summary conversation memory](https://langchain-ai.github.io/langgraph/how-tos/memory/add-summary-conversation-history/)
+- [How to add long-term memory (cross-thread)](https://langchain-ai.github.io/langgraph/how-tos/memory/cross-thread-persistence/)
+- [How to use semantic search for long-term memory](https://langchain-ai.github.io/langgraph/how-tos/memory/semantic-search/)
+
+### Human-in-the-loop
+
+Human-in-the-loop functionality allows you to involve humans in the decision-making process of your graph.
+
+These how-to guides show how to implement human-in-the-loop workflows in your graph.
+
+- [How to wait for user input](https://langchain-ai.github.io/langgraph/how-tos/human_in_the_loop/wait-user-input/): A basic example that shows how to implement a human-in-the-loop workflow in your graph using the `interrupt` function.
+- [How to review tool calls](https://langchain-ai.github.io/langgraph/how-tos/human_in_the_loop/review-tool-calls/): Incorporate human-in-the-loop for reviewing/editing/accepting tool call requests before they executed using the `interrupt` function.
+- [How to add static breakpoints](https://langchain-ai.github.io/langgraph/how-tos/human_in_the_loop/breakpoints/): Use for debugging purposes. For human-in-the-loop workflows, we recommend the [`interrupt` function](https://langchain-ai.github.io/langgraph/reference/types/#langgraph.types.interrupt) instead.
+- [How to edit graph state](https://langchain-ai.github.io/langgraph/how-tos/human_in_the_loop/edit-graph-state/): Edit graph state using `graph.update_state` method. Use this if implementing a **human-in-the-loop** workflow via **static breakpoints**.
+
+See the below guides for how-to implement human-in-the-loop workflows with the Functional API.
+
+- [How to wait for user input (Functional API)](https://langchain-ai.github.io/langgraph/how-tos/wait-user-input-functional/)
+- [How to review tool calls (Functional API)](https://langchain-ai.github.io/langgraph/how-tos/review-tool-calls-functional/)
+
+### Time Travel
+
+[Time travel](https://langchain-ai.github.io/langgraph/concepts/time-travel/) allows you to replay past actions in your LangGraph application to explore alternative paths and debug issues. These how-to guides show how to use time travel in your graph.
+
+- [How to view and update past graph state](https://langchain-ai.github.io/langgraph/how-tos/time-travel/)
+
+### Streaming
+
+[Streaming](https://langchain-ai.github.io/langgraph/concepts/streaming/) is crucial for enhancing the responsiveness of applications built on LLMs. By displaying output progressively, even before a complete response is ready, streaming significantly improves user experience (UX), particularly when dealing with the latency of LLMs.
+
+- [How to stream](https://langchain-ai.github.io/langgraph/how-tos/streaming/)
+- [How to stream LLM tokens](https://langchain-ai.github.io/langgraph/how-tos/streaming-tokens/)
+- [How to stream LLM tokens from specific nodes](https://langchain-ai.github.io/langgraph/how-tos/streaming-specific-nodes/)
+- [How to stream data from within a tool](https://langchain-ai.github.io/langgraph/how-tos/streaming-events-from-within-tools/)
+- [How to stream from subgraphs](https://langchain-ai.github.io/langgraph/how-tos/streaming-subgraphs/)
+- [How to disable streaming for models that don't support it](https://langchain-ai.github.io/langgraph/how-tos/disable-streaming/)
+
+### Tool calling
+
+[Tool calling](https://python.langchain.com/docs/concepts/tool_calling/) is a type of [chat model](https://python.langchain.com/docs/concepts/chat_models/) API.
+
+It accepts tool schemas, along with messages, as input and returns invocations of those tools as part of the output message.
+
+These how-to guides show common patterns for tool calling with LangGraph:
+
+- [How to call tools using ToolNode](https://langchain-ai.github.io/langgraph/how-tos/tool-calling/)
+- [How to handle tool calling errors](https://langchain-ai.github.io/langgraph/how-tos/tool-calling-errors/)
+- [How to pass runtime values to tools](https://langchain-ai.github.io/langgraph/how-tos/pass-run-time-values-to-tools/)
+- [How to pass config to tools](https://langchain-ai.github.io/langgraph/how-tos/pass-config-to-tools/)
+- [How to update graph state from tools](https://langchain-ai.github.io/langgraph/how-tos/update-state-from-tools/)
+- [How to handle large numbers of tools](https://langchain-ai.github.io/langgraph/how-tos/many-tools/)
+
+### Subgraphs
+
+Subgraphs allow you to reuse an existing graph from another graph. 
+
+These how-to guides show how to use subgraphs:
+
+- [How to use subgraphs](https://langchain-ai.github.io/langgraph/how-tos/subgraph/)
+- [How to view and update state in subgraphs](https://langchain-ai.github.io/langgraph/how-tos/subgraphs-manage-state/)
+- [How to transform inputs and outputs of a subgraph](https://langchain-ai.github.io/langgraph/how-tos/subgraph-transform-state/)
+
+### Multi-agent
+
+Multi-agent systems are useful to break down complex LLM applications into multiple agents, each responsible for a different part of the application. 
+
+These how-to guides show how to implement multi-agent systems in LangGraph:
+
+- [How to implement handoffs between agents](https://langchain-ai.github.io/langgraph/how-tos/agent-handoffs/)
+- [How to build a multi-agent network](https://langchain-ai.github.io/langgraph/how-tos/multi-agent-network/)
+- [How to add multi-turn conversation in a multi-agent application](https://langchain-ai.github.io/langgraph/how-tos/multi-agent-multi-turn-convo/)
+
+### State Management
+
+- [How to use Pydantic model as graph state](https://langchain-ai.github.io/langgraph/how-tos/state-model/)
+- [How to define input/output schema for your graph](https://langchain-ai.github.io/langgraph/how-tos/input_output_schema/)
+- [How to pass private state between nodes inside the graph](https://langchain-ai.github.io/langgraph/how-tos/pass_private_state/)
+
+### Other
+
+- [How to run graph asynchronously](https://langchain-ai.github.io/langgraph/how-tos/async/)
+- [How to force tool-calling agent to structure output](https://langchain-ai.github.io/langgraph/how-tos/react-agent-structured-output/)
+- [How to pass custom LangSmith run ID for graph runs](https://langchain-ai.github.io/langgraph/how-tos/run-id-langsmith/)
+- [How to integrate LangGraph with AutoGen, CrewAI, and other frameworks](https://langchain-ai.github.io/langgraph/how-tos/autogen-integration/)
+
+## Use cases 
+
+Explore practical implementations tailored for specific scenarios:
+
+### Chatbots
+
+- [Customer Support](https://langchain-ai.github.io/langgraph/tutorials/customer-support/customer-support/): Build a multi-functional support bot for flights, hotels, and car rentals.
+- [Prompt Generation from User Requirements](https://langchain-ai.github.io/langgraph/tutorials/chatbots/information-gather-prompting/): Build an information gathering chatbot.
+- [Code Assistant](https://langchain-ai.github.io/langgraph/tutorials/code_assistant/langgraph_code_assistant/): Build a code analysis and generation assistant.
+
+### RAG
+
+- [Agentic RAG](https://langchain-ai.github.io/langgraph/tutorials/rag/langgraph_agentic_rag/): Use an agent to figure out how to retrieve the most relevant information before using the retrieved information to answer the user's question.
+- [Adaptive RAG](https://langchain-ai.github.io/langgraph/tutorials/rag/langgraph_adaptive_rag/): Adaptive RAG is a strategy for RAG that unites (1) query analysis with (2) active / self-corrective RAG. Implementation of: https://arxiv.org/abs/2403.14403
+    - For a version that uses a local LLM: [Adaptive RAG using local LLMs](https://langchain-ai.github.io/langgraph/tutorials/rag/langgraph_adaptive_rag_local/)
+- [Corrective RAG](https://langchain-ai.github.io/langgraph/tutorials/rag/langgraph_crag/): Uses an LLM to grade the quality of the retrieved information from the given source, and if the quality is low, it will try to retrieve the information from another source. Implementation of: https://arxiv.org/pdf/2401.15884.pdf 
+    - For a version that uses a local LLM: [Corrective RAG using local LLMs](https://langchain-ai.github.io/langgraph/tutorials/rag/langgraph_crag_local/)
+- [Self-RAG](https://langchain-ai.github.io/langgraph/tutorials/rag/langgraph_self_rag/): Self-RAG is a strategy for RAG that incorporates self-reflection / self-grading on retrieved documents and generations. Implementation of https://arxiv.org/abs/2310.11511.
+    - For a version that uses a local LLM: [Self-RAG using local LLMs](https://langchain-ai.github.io/langgraph/tutorials/rag/langgraph_self_rag_local/) 
+- [SQL Agent](https://langchain-ai.github.io/langgraph/tutorials/sql-agent/): Build a SQL agent that can answer questions about a SQL database.
+
+### Multi-Agent Systems
+
+- [Network](https://langchain-ai.github.io/langgraph/tutorials/multi_agent/multi-agent-collaboration/): Enable two or more agents to collaborate on a task
+- [Supervisor](https://langchain-ai.github.io/langgraph/tutorials/multi_agent/agent_supervisor/): Use an LLM to orchestrate and delegate to individual agents
+- [Hierarchical Teams](https://langchain-ai.github.io/langgraph/tutorials/multi_agent/hierarchical_agent_teams/): Orchestrate nested teams of agents to solve problems

libs/checkpoint-postgres/langgraph/store/postgres/aio.py

@@ -20,7 +20,7 @@ from langgraph.store.base import (
 )
 from langgraph.store.base.batch import AsyncBatchedBaseStore
 from langgraph.store.postgres.base import (
-    _PLACEHOLDER,
+    PLACEHOLDER,
     BasePostgresStore,
     PoolConfig,
     PostgresIndexConfig,
@@ -360,7 +360,7 @@ class AsyncPostgresStore(AsyncBatchedBaseStore, BasePostgresStore[_ainternal.Con
             for (idx, _), vector in zip(embedding_requests, vectors):
                 _paramslist = queries[idx][1]
                 for i in range(len(_paramslist)):
-                    if _paramslist[i] is _PLACEHOLDER:
+                    if _paramslist[i] is PLACEHOLDER:
                         _paramslist[i] = vector
 
         for (idx, _), (query, params) in zip(search_ops, queries):

libs/checkpoint-postgres/langgraph/store/postgres/base.py

@@ -39,6 +39,7 @@ from langgraph.store.base import (
     Result,
     SearchItem,
     SearchOp,
+    TTLConfig,
     ensure_embeddings,
     get_text_at_path,
     tokenize_path,
@@ -370,7 +371,7 @@ class BasePostgresStore(Generic[C]):
             if op.query and self.index_config:
                 embedding_requests.append((idx, op.query))
 
-                score_operator, post_operator = _get_distance_operator(self)
+                score_operator, post_operator = get_distance_operator(self)
                 vector_type = (
                     cast(PostgresIndexConfig, self.index_config)
                     .get("ann_index_config", {})
@@ -430,10 +431,10 @@ class BasePostgresStore(Generic[C]):
                     OFFSET %s
                 """
                 params = [
-                    _PLACEHOLDER,  # Vector placeholder
+                    PLACEHOLDER,  # Vector placeholder
                     *ns_args,
                     *filter_params,
-                    _PLACEHOLDER,
+                    PLACEHOLDER,
                     expanded_limit,
                     op.limit,
                     op.offset,
@@ -622,6 +623,7 @@ class PostgresStore(BaseStore, BasePostgresStore[_pg_internal.Conn]):
             Callable[[Union[bytes, orjson.Fragment]], dict[str, Any]]
         ] = None,
         index: Optional[PostgresIndexConfig] = None,
+        ttl: Optional[TTLConfig] = None,
     ) -> None:
         super().__init__()
         self._deserializer = deserializer
@@ -634,6 +636,7 @@ class PostgresStore(BaseStore, BasePostgresStore[_pg_internal.Conn]):
             self.embeddings, self.index_config = _ensure_index_config(self.index_config)
         else:
             self.embeddings = None
+        self.ttl_config = ttl
 
     @classmethod
     @contextmanager
@@ -828,7 +831,7 @@ class PostgresStore(BaseStore, BasePostgresStore[_pg_internal.Conn]):
             for (idx, _), embedding in zip(embedding_requests, embeddings):
                 _paramslist = queries[idx][1]
                 for i in range(len(_paramslist)):
-                    if _paramslist[i] is _PLACEHOLDER:
+                    if _paramslist[i] is PLACEHOLDER:
                         _paramslist[i] = embedding
 
         for (idx, _), (query, params) in zip(search_ops, queries):
@@ -1055,7 +1058,7 @@ def _decode_ns_bytes(namespace: Union[str, bytes, list]) -> tuple[str, ...]:
     return tuple(namespace.split("."))
 
 
-def _get_distance_operator(store: Any) -> tuple[str, str]:
+def get_distance_operator(store: Any) -> tuple[str, str]:
     """Get the distance operator and score expression based on config."""
     # Note: Today, we are not using ANN indices due to restrictions
     # on PGVector's support for mixing vector and non-vector filters
@@ -1121,4 +1124,4 @@ def _ensure_index_config(
     return embeddings, index_config
 
 
-_PLACEHOLDER = object()
+PLACEHOLDER = object()

libs/checkpoint-postgres/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint-postgres"
-version = "2.0.15"
+version = "2.0.16"
 description = "Library with a Postgres implementation of LangGraph checkpoint saver."
 authors = []
 license = "MIT"

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py

@@ -530,6 +530,7 @@ class AsyncSqliteSaver(BaseCheckpointSaver[str]):
                     for idx, (channel, value) in enumerate(writes)
                 ],
             )
+            await self.conn.commit()
 
     def get_next_version(self, current: Optional[str], channel: ChannelProtocol) -> str:
         """Generate the next version ID for a channel.

libs/checkpoint-sqlite/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint-sqlite"
-version = "2.0.5"
+version = "2.0.6"
 description = "Library with a SQLite implementation of LangGraph checkpoint saver."
 authors = []
 license = "MIT"

libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py

@@ -487,7 +487,12 @@ def _msgpack_ext_hook(code: int, data: bytes) -> Any:
             except Exception:
                 return cls.construct(**tup[2])
         except Exception:
-            return
+            # for pydantic objects we can't find/reconstruct
+            # let's return the kwargs dict instead
+            try:
+                return tup[2]
+            except NameError:
+                return
     elif code == EXT_PYDANTIC_V2:
         try:
             tup = msgpack.unpackb(
@@ -500,7 +505,12 @@ def _msgpack_ext_hook(code: int, data: bytes) -> Any:
             except Exception:
                 return cls.model_construct(**tup[2])
         except Exception:
-            return
+            # for pydantic objects we can't find/reconstruct
+            # let's return the kwargs dict instead
+            try:
+                return tup[2]
+            except NameError:
+                return
 
 
 def _msgpack_enc(data: Any) -> bytes:

libs/checkpoint/langgraph/store/base/__init__.py

@@ -11,9 +11,19 @@ Core types:
 
 from abc import ABC, abstractmethod
 from datetime import datetime
-from typing import Any, Iterable, Literal, NamedTuple, Optional, TypedDict, Union, cast
+from typing import (
+    Any,
+    Iterable,
+    Literal,
+    NamedTuple,
+    Optional,
+    TypedDict,
+    Union,
+    cast,
+)
 
 from langchain_core.embeddings import Embeddings
+from typing_extensions import override
 
 from langgraph.store.base.embed import (
     AEmbeddingsFunc,
@@ -24,6 +34,20 @@ from langgraph.store.base.embed import (
 )
 
 
+class NotProvided:
+    """Sentinel singleton."""
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    @override
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_PROVIDED = NotProvided()
+
+
 class Item:
     """Represents a stored item with metadata.
 
@@ -59,7 +83,7 @@ class Item:
             else created_at
         )
         self.updated_at = (
-            datetime.fromisoformat(cast(str, created_at))
+            datetime.fromisoformat(cast(str, updated_at))
             if isinstance(updated_at, str)
             else updated_at
         )
@@ -166,6 +190,13 @@ class GetOp(NamedTuple):
         "doc456"  # For a document
         ```
     """
+    refresh_ttl: bool = True
+    """Whether to refresh TTLs for the returned item.
+
+    If no TTL was specified for the original item(s),
+    or if TTL support is not enabled for your adapter,
+    this argument is ignored.
+    """
 
 
 class SearchOp(NamedTuple):
@@ -260,6 +291,13 @@ class SearchOp(NamedTuple):
         - "technical documentation about REST APIs"
         - "machine learning papers from 2023"
     """
+    refresh_ttl: bool = True
+    """Whether to refresh TTLs for the returned item.
+
+    If no TTL was specified for the original item(s),
+    or if TTL support is not enabled for your adapter,
+    this argument is ignored.
+    """
 
 
 # Type representing a namespace path that can include wildcards
@@ -463,6 +501,15 @@ class PutOp(NamedTuple):
         ]
         ```
     """
+    ttl: Optional[float] = None
+    """Controls the TTL (time-to-live) for the item in minutes.
+
+    If provided, and if the store you are using supports this feature, the item
+    will expire this many minutes after it was last accessed. The expiration timer
+    refreshes on both read operations (get/search) and write operations (put/update).
+    When the TTL expires, the item will be scheduled for deletion on a best-effort basis.
+    Defaults to None (no expiration).
+    """
 
 
 Op = Union[GetOp, SearchOp, PutOp, ListNamespacesOp]
@@ -473,6 +520,25 @@ class InvalidNamespaceError(ValueError):
     """Provided namespace is invalid."""
 
 
+class TTLConfig(TypedDict, total=False):
+    """Configuration for TTL (time-to-live) behavior in the store."""
+
+    refresh_on_read: bool
+    """Default behavior for refreshing TTLs on read operations (GET and SEARCH).
+    
+    If True, TTLs will be refreshed on read operations (get/search) by default.
+    This can be overridden per-operation by explicitly setting refresh_ttl.
+    Defaults to True if not configured.
+    """
+    default_ttl: Optional[float]
+    """Default TTL (time-to-live) in minutes for new items.
+    
+    If provided, new items will expire after this many minutes after their last access.
+    The expiration timer refreshes on both read and write operations.
+    Defaults to None (no expiration).
+    """
+
+
 class IndexConfig(TypedDict, total=False):
     """Configuration for indexing documents for semantic search in the store.
 
@@ -612,8 +678,14 @@ class BaseStore(ABC):
         by providing an `index` configuration at creation time. Without this
         configuration, semantic search is disabled and any `index` arguments
         to storage operations will have no effect.
+
+        Similarly, TTL (time-to-live) support is disabled by default.
+        Subclasses must explicitly set `supports_ttl = True` to enable this feature.
     """
 
+    supports_ttl: bool = False
+    ttl_config: Optional[TTLConfig] = None
+
     __slots__ = ("__weakref__",)
 
     @abstractmethod
@@ -640,17 +712,28 @@ class BaseStore(ABC):
             The order of results matches the order of input operations.
         """
 
-    def get(self, namespace: tuple[str, ...], key: str) -> Optional[Item]:
+    def get(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+        *,
+        refresh_ttl: Optional[bool] = None,
+    ) -> Optional[Item]:
         """Retrieve a single item.
 
         Args:
             namespace: Hierarchical path for the item.
             key: Unique identifier within the namespace.
+            refresh_ttl: Whether to refresh TTLs for the returned item.
+                If None (default), uses the store's default refresh_ttl setting.
+                If no TTL is specified, this argument is ignored.
 
         Returns:
             The retrieved item or None if not found.
         """
-        return self.batch([GetOp(namespace, key)])[0]
+        return self.batch(
+            [GetOp(namespace, str(key), _ensure_refresh(self.ttl_config, refresh_ttl))]
+        )[0]
 
     def search(
         self,
@@ -661,6 +744,7 @@ class BaseStore(ABC):
         filter: Optional[dict[str, Any]] = None,
         limit: int = 10,
         offset: int = 0,
+        refresh_ttl: Optional[bool] = None,
     ) -> list[SearchItem]:
         """Search for items within a namespace prefix.
 
@@ -670,6 +754,8 @@ class BaseStore(ABC):
             filter: Key-value pairs to filter results.
             limit: Maximum number of items to return.
             offset: Number of items to skip before returning results.
+            refresh_ttl: Whether to refresh TTLs for the returned items.
+                If no TTL is specified, this argument is ignored.
 
         Returns:
             List of items matching the search criteria.
@@ -707,7 +793,18 @@ class BaseStore(ABC):
             Note: Natural language search support depends on your store implementation
             and requires proper embedding configuration.
         """
-        return self.batch([SearchOp(namespace_prefix, filter, limit, offset, query)])[0]
+        return self.batch(
+            [
+                SearchOp(
+                    namespace_prefix,
+                    filter,
+                    limit,
+                    offset,
+                    query,
+                    _ensure_refresh(self.ttl_config, refresh_ttl),
+                )
+            ]
+        )[0]
 
     def put(
         self,
@@ -715,6 +812,8 @@ class BaseStore(ABC):
         key: str,
         value: dict[str, Any],
         index: Optional[Union[Literal[False], list[str]]] = None,
+        *,
+        ttl: Union[Optional[float], "NotProvided"] = NOT_PROVIDED,
     ) -> None:
         """Store or update an item in the store.
 
@@ -735,12 +834,20 @@ class BaseStore(ABC):
                     - Nested fields: "metadata.title"
                     - Array access: "chapters[*].content" (each indexed separately)
                     - Specific indices: "authors[0].name"
+            ttl: Time to live in minutes. Support for this argument depends on your store adapter.
+                If specified, the item will expire after this many minutes from when it was last accessed.
+                None means no expiration. Expired runs will be deleted opportunistically.
+                By default, the expiration timer refreshes on both read operations (get/search)
+                and write operations (put/update), whenever the item is included in the operation.
 
         Note:
             Indexing support depends on your store implementation.
             If you do not initialize the store with indexing capabilities,
             the `index` parameter will be ignored.
 
+            Similarly, TTL support depends on the specific store implementation.
+            Some implementations may not support expiration of items.
+
         ???+ example "Examples"
             Store item. Indexing depends on how you configure the store.
             ```python
@@ -759,7 +866,22 @@ class BaseStore(ABC):
             ```
         """
         _validate_namespace(namespace)
-        self.batch([PutOp(namespace, key, value, index=index)])
+        if ttl not in (NOT_PROVIDED, None) and not self.supports_ttl:
+            raise NotImplementedError(
+                f"TTL is not supported by {self.__class__.__name__}. "
+                f"Use a store implementation that supports TTL or set ttl=None."
+            )
+        self.batch(
+            [
+                PutOp(
+                    namespace,
+                    str(key),
+                    value,
+                    index=index,
+                    ttl=_ensure_ttl(self.ttl_config, ttl),
+                )
+            ]
+        )
 
     def delete(self, namespace: tuple[str, ...], key: str) -> None:
         """Delete an item.
@@ -768,7 +890,7 @@ class BaseStore(ABC):
             namespace: Hierarchical path for the item.
             key: Unique identifier within the namespace.
         """
-        self.batch([PutOp(namespace, key, None)])
+        self.batch([PutOp(namespace, str(key), None, ttl=None)])
 
     def list_namespaces(
         self,
@@ -823,7 +945,13 @@ class BaseStore(ABC):
         )
         return self.batch([op])[0]
 
-    async def aget(self, namespace: tuple[str, ...], key: str) -> Optional[Item]:
+    async def aget(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+        *,
+        refresh_ttl: Optional[bool] = None,
+    ) -> Optional[Item]:
         """Asynchronously retrieve a single item.
 
         Args:
@@ -833,7 +961,17 @@ class BaseStore(ABC):
         Returns:
             The retrieved item or None if not found.
         """
-        return (await self.abatch([GetOp(namespace, key)]))[0]
+        return (
+            await self.abatch(
+                [
+                    GetOp(
+                        namespace,
+                        str(key),
+                        _ensure_refresh(self.ttl_config, refresh_ttl),
+                    )
+                ]
+            )
+        )[0]
 
     async def asearch(
         self,
@@ -844,6 +982,7 @@ class BaseStore(ABC):
         filter: Optional[dict[str, Any]] = None,
         limit: int = 10,
         offset: int = 0,
+        refresh_ttl: Optional[bool] = None,
     ) -> list[SearchItem]:
         """Asynchronously search for items within a namespace prefix.
 
@@ -853,6 +992,9 @@ class BaseStore(ABC):
             filter: Key-value pairs to filter results.
             limit: Maximum number of items to return.
             offset: Number of items to skip before returning results.
+            refresh_ttl: Whether to refresh TTLs for the returned items.
+                If None (default), uses the store's TTLConfig.refresh_default setting.
+                If TTLConfig is not provided or no TTL is specified, this argument is ignored.
 
         Returns:
             List of items matching the search criteria.
@@ -892,7 +1034,16 @@ class BaseStore(ABC):
         """
         return (
             await self.abatch(
-                [SearchOp(namespace_prefix, filter, limit, offset, query)]
+                [
+                    SearchOp(
+                        namespace_prefix,
+                        filter,
+                        limit,
+                        offset,
+                        query,
+                        _ensure_refresh(self.ttl_config, refresh_ttl),
+                    )
+                ]
             )
         )[0]
 
@@ -902,6 +1053,8 @@ class BaseStore(ABC):
         key: str,
         value: dict[str, Any],
         index: Optional[Union[Literal[False], list[str]]] = None,
+        *,
+        ttl: Union[Optional[float], "NotProvided"] = NOT_PROVIDED,
     ) -> None:
         """Asynchronously store or update an item in the store.
 
@@ -922,12 +1075,20 @@ class BaseStore(ABC):
                     - Nested fields: "metadata.title"
                     - Array access: "chapters[*].content" (each indexed separately)
                     - Specific indices: "authors[0].name"
+            ttl: Time to live in minutes. Support for this argument depends on your store adapter.
+                If specified, the item will expire after this many minutes from when it was last accessed.
+                None means no expiration. Expired runs will be deleted opportunistically.
+                By default, the expiration timer refreshes on both read operations (get/search)
+                and write operations (put/update), whenever the item is included in the operation.
 
         Note:
             Indexing support depends on your store implementation.
             If you do not initialize the store with indexing capabilities,
             the `index` parameter will be ignored.
 
+            Similarly, TTL support depends on the specific store implementation.
+            Some implementations may not support expiration of items.
+
         ???+ example "Examples"
             Store item. Indexing depends on how you configure the store.
             ```python
@@ -954,7 +1115,22 @@ class BaseStore(ABC):
             ```
         """
         _validate_namespace(namespace)
-        await self.abatch([PutOp(namespace, key, value, index=index)])
+        if ttl not in (NOT_PROVIDED, None) and not self.supports_ttl:
+            raise NotImplementedError(
+                f"TTL is not supported by {self.__class__.__name__}. "
+                f"Use a store implementation that supports TTL or set ttl=None."
+            )
+        await self.abatch(
+            [
+                PutOp(
+                    namespace,
+                    str(key),
+                    value,
+                    index=index,
+                    ttl=_ensure_ttl(self.ttl_config, ttl),
+                )
+            ]
+        )
 
     async def adelete(self, namespace: tuple[str, ...], key: str) -> None:
         """Asynchronously delete an item.
@@ -963,7 +1139,7 @@ class BaseStore(ABC):
             namespace: Hierarchical path for the item.
             key: Unique identifier within the namespace.
         """
-        await self.abatch([PutOp(namespace, key, None)])
+        await self.abatch([PutOp(namespace, str(key), None)])
 
     async def alist_namespaces(
         self,
@@ -1043,6 +1219,27 @@ def _validate_namespace(namespace: tuple[str, ...]) -> None:
         )
 
 
+def _ensure_refresh(
+    ttl_config: Optional[TTLConfig], refresh_ttl: Optional[bool] = None
+) -> bool:
+    if refresh_ttl is not None:
+        return refresh_ttl
+    if ttl_config is not None:
+        return ttl_config.get("refresh_on_read", True)
+    return True
+
+
+def _ensure_ttl(
+    ttl_config: Optional[TTLConfig],
+    ttl: Union[Optional[float], "NotProvided"] = NOT_PROVIDED,
+) -> Optional[float]:
+    if ttl is NOT_PROVIDED:
+        if ttl_config:
+            return ttl_config.get("default_ttl")
+        return None
+    return ttl
+
+
 __all__ = [
     "BaseStore",
     "Item",

libs/checkpoint/langgraph/store/base/batch.py

@@ -5,17 +5,21 @@ from collections.abc import Iterable
 from typing import Any, Callable, Literal, Optional, TypeVar, Union
 
 from langgraph.store.base import (
+    NOT_PROVIDED,
     BaseStore,
     GetOp,
     Item,
     ListNamespacesOp,
     MatchCondition,
     NamespacePath,
+    NotProvided,
     Op,
     PutOp,
     Result,
     SearchItem,
     SearchOp,
+    _ensure_refresh,
+    _ensure_ttl,
     _validate_namespace,
 )
 
@@ -68,10 +72,21 @@ class AsyncBatchedBaseStore(BaseStore):
         self,
         namespace: tuple[str, ...],
         key: str,
+        *,
+        refresh_ttl: Optional[bool] = None,
     ) -> Optional[Item]:
         assert not self._task.done()
         fut = self._loop.create_future()
-        self._aqueue.put_nowait((fut, GetOp(namespace, key)))
+        self._aqueue.put_nowait(
+            (
+                fut,
+                GetOp(
+                    namespace,
+                    key,
+                    refresh_ttl=_ensure_refresh(self.ttl_config, refresh_ttl),
+                ),
+            )
+        )
         return await fut
 
     async def asearch(
@@ -83,11 +98,22 @@ class AsyncBatchedBaseStore(BaseStore):
         filter: Optional[dict[str, Any]] = None,
         limit: int = 10,
         offset: int = 0,
+        refresh_ttl: Optional[bool] = None,
     ) -> list[SearchItem]:
         assert not self._task.done()
         fut = self._loop.create_future()
         self._aqueue.put_nowait(
-            (fut, SearchOp(namespace_prefix, filter, limit, offset, query))
+            (
+                fut,
+                SearchOp(
+                    namespace_prefix,
+                    filter,
+                    limit,
+                    offset,
+                    query,
+                    refresh_ttl=_ensure_refresh(self.ttl_config, refresh_ttl),
+                ),
+            )
         )
         return await fut
 
@@ -97,11 +123,20 @@ class AsyncBatchedBaseStore(BaseStore):
         key: str,
         value: dict[str, Any],
         index: Optional[Union[Literal[False], list[str]]] = None,
+        *,
+        ttl: Union[Optional[float], "NotProvided"] = NOT_PROVIDED,
     ) -> None:
         assert not self._task.done()
         _validate_namespace(namespace)
         fut = self._loop.create_future()
-        self._aqueue.put_nowait((fut, PutOp(namespace, key, value, index)))
+        self._aqueue.put_nowait(
+            (
+                fut,
+                PutOp(
+                    namespace, key, value, index, ttl=_ensure_ttl(self.ttl_config, ttl)
+                ),
+            )
+        )
         return await fut
 
     async def adelete(
@@ -149,9 +184,11 @@ class AsyncBatchedBaseStore(BaseStore):
         self,
         namespace: tuple[str, ...],
         key: str,
+        *,
+        refresh_ttl: Optional[bool] = None,
     ) -> Optional[Item]:
         return asyncio.run_coroutine_threadsafe(
-            self.aget(namespace, key=key), self._loop
+            self.aget(namespace, key=key, refresh_ttl=refresh_ttl), self._loop
         ).result()
 
     @_check_loop
@@ -164,10 +201,16 @@ class AsyncBatchedBaseStore(BaseStore):
         filter: Optional[dict[str, Any]] = None,
         limit: int = 10,
         offset: int = 0,
+        refresh_ttl: Optional[bool] = None,
     ) -> list[SearchItem]:
         return asyncio.run_coroutine_threadsafe(
             self.asearch(
-                namespace_prefix, query=query, filter=filter, limit=limit, offset=offset
+                namespace_prefix,
+                query=query,
+                filter=filter,
+                limit=limit,
+                offset=offset,
+                refresh_ttl=refresh_ttl,
             ),
             self._loop,
         ).result()
@@ -179,10 +222,19 @@ class AsyncBatchedBaseStore(BaseStore):
         key: str,
         value: dict[str, Any],
         index: Optional[Union[Literal[False], list[str]]] = None,
+        *,
+        ttl: Union[Optional[float], "NotProvided"] = NOT_PROVIDED,
     ) -> None:
         _validate_namespace(namespace)
         asyncio.run_coroutine_threadsafe(
-            self.aput(namespace, key=key, value=value, index=index), self._loop
+            self.aput(
+                namespace,
+                key=key,
+                value=value,
+                index=index,
+                ttl=_ensure_ttl(self.ttl_config, ttl),
+            ),
+            self._loop,
         ).result()
 
     @_check_loop

libs/checkpoint/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint"
-version = "2.0.16"
+version = "2.0.19"
 description = "Library with base interfaces for LangGraph checkpoint savers."
 authors = []
 license = "MIT"

libs/checkpoint/tests/test_jsonplus.py

@@ -130,7 +130,7 @@ def test_serde_jsonplus() -> None:
             key="my-key",
             namespace=("a", "name", " "),
             created_at=datetime(2024, 9, 24, 17, 29, 10, 128397),
-            updated_at=datetime(2024, 9, 24, 17, 29, 10, 128397),
+            updated_at=datetime(2024, 9, 24, 17, 29, 11, 128397),
         ),
     }
 

libs/checkpoint/tests/test_store.py

@@ -148,8 +148,8 @@ async def test_async_batch_store(mocker: MockerFixture) -> None:
     assert abatch.call_count == 1
     assert [tuple(c.args[0]) for c in abatch.call_args_list] == [
         (
-            GetOp(("a",), "b"),
-            GetOp(("c",), "d"),
+            GetOp(("a",), "b", refresh_ttl=True),
+            GetOp(("c",), "d", refresh_ttl=True),
         ),
     ]
 
@@ -467,8 +467,8 @@ async def test_async_batch_store_deduplication(mocker: MockerFixture) -> None:
     assert len(abatch.call_args_list) == 1
     ops = list(abatch.call_args_list[0].args[1])
     assert len(ops) == 2
-    assert GetOp(("test",), "same") in ops
-    assert GetOp(("test",), "different") in ops
+    assert GetOp(("test",), "same", refresh_ttl=True) in ops
+    assert GetOp(("test",), "different", refresh_ttl=True) in ops
 
     abatch.reset_mock()
 

libs/cli/generate_schema.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+Script to generate a JSON schema for the langgraph-cli Config class.
+
+This script creates a schema.json file that can be referenced in langgraph.json files
+to provide IDE autocompletion and validation.
+"""
+
+import inspect
+import json
+import textwrap
+from pathlib import Path
+
+import msgspec
+
+from langgraph_cli.config import (
+    AuthConfig,
+    Config,
+    CorsConfig,
+    HttpConfig,
+    IndexConfig,
+    SecurityConfig,
+    StoreConfig,
+)
+
+
+def add_descriptions_to_schema(schema, cls):
+    """Add docstring descriptions to the schema properties."""
+    if schema.get("description"):
+        schema["description"] = inspect.cleandoc(schema["description"])
+    elif class_doc := inspect.getdoc(cls):
+        schema["description"] = inspect.cleandoc(class_doc)
+    # Get attribute docstrings from the class
+    attr_docs = {}
+
+    # Also check class annotations for docstrings
+    source_lines = inspect.getsourcelines(cls)[0]
+    current_attr = None
+    docstring_lines = []
+
+    for line in source_lines:
+        line = line.strip()
+
+        # Check for attribute definition (TypedDict style)
+        if ":" in line and not line.startswith("#") and not line.startswith('"""'):
+            parts = line.split(":", 1)
+            if len(parts) == 2 and parts[0].strip().isidentifier():
+                # If we were collecting a docstring, save it for the previous attribute
+                if current_attr and docstring_lines:
+                    attr_docs[current_attr] = "\n".join(docstring_lines).strip('"')
+                    docstring_lines = []
+
+                current_attr = parts[0].strip()
+
+        # Check for docstring after attribute
+        elif line.startswith('"""') and current_attr:
+            # Start or end of a docstring
+            if len(line) > 3 and line.endswith('"""'):
+                # Single line docstring
+                attr_docs[current_attr] = line.strip('"')
+                current_attr = None
+            elif docstring_lines:
+                # End of multi-line docstring
+                docstring_lines.append(line.rstrip('"'))
+                attr_docs[current_attr] = "\n".join(docstring_lines).strip('"')
+                docstring_lines = []
+                current_attr = None
+            else:
+                # Start of multi-line docstring
+                docstring_lines.append(line.lstrip('"'))
+
+        # Continue multi-line docstring
+        elif docstring_lines and current_attr:
+            docstring_lines.append(line.strip('"'))
+
+    # Add the last docstring if there is one
+    if current_attr and docstring_lines:
+        attr_docs[current_attr] = "\n".join(docstring_lines).strip('"')
+
+    # Add descriptions to properties
+    if "properties" in schema:
+        for prop_name, prop_schema in schema["properties"].items():
+            # First try to get from attribute docstrings
+            if prop_name in attr_docs and "description" not in prop_schema:
+                prop_schema["description"] = textwrap.dedent(attr_docs[prop_name])
+            # Fall back to class docstring parsing
+            elif class_doc:
+                for line in class_doc.split("\n"):
+                    if line.strip().startswith(
+                        f"{prop_name}:"
+                    ) or line.strip().startswith(f'"{prop_name}"'):
+                        description = line.split(":", 1)[1].strip()
+                        if description and "description" not in prop_schema:
+                            prop_schema["description"] = description
+                            break
+
+    # Recursively process nested definitions
+    if "$defs" in schema:
+        for def_name, def_schema in schema["$defs"].items():
+            # Find the class that corresponds to this definition
+            for potential_cls in [
+                Config,
+                StoreConfig,
+                IndexConfig,
+                AuthConfig,
+                SecurityConfig,
+                HttpConfig,
+                CorsConfig,
+            ]:
+                if potential_cls.__name__ == def_name:
+                    add_descriptions_to_schema(def_schema, potential_cls)
+                    break
+
+    return schema
+
+
+def generate_schema():
+    """Generate a JSON schema for the Config class using msgspec."""
+    # Generate the basic schema
+    schema = msgspec.json.schema(Config)
+
+    # Add title and description
+    schema["title"] = "LangGraph CLI Configuration"
+    schema["description"] = "Configuration schema for langgraph-cli"
+
+    # Add docstring descriptions
+    schema = add_descriptions_to_schema(schema, Config)
+
+    # Add constraint that only one of python_version or node_version should be specified
+    config_schema = schema["$defs"]["Config"]
+
+    # Create two subschemas: one with python_version and one with node_version
+    # Define properties specific to Python projects
+    python_specific_props = ["python_version", "pip_config_file"]
+    # Define properties specific to Node.js projects
+    node_specific_props = ["node_version"]
+    # Define properties common to both project types
+    common_props = [
+        k
+        for k in config_schema["properties"]
+        if k not in python_specific_props and k not in node_specific_props
+    ]
+
+    # Create Python schema with python_version and pip_config_file
+    python_schema = {
+        "type": "object",
+        "properties": {
+            # Include Python-specific properties
+            **{k: config_schema["properties"][k].copy() for k in python_specific_props},
+            # Include common properties
+            **{k: config_schema["properties"][k].copy() for k in common_props},
+        },
+        "required": ["dependencies", "graphs"],
+    }
+
+    # Add enum constraint for python_version
+    if "python_version" in python_schema["properties"]:
+        python_schema["properties"]["python_version"]["enum"] = ["3.11", "3.12"]
+
+    # Create Node.js schema with node_version
+    node_schema = {
+        "type": "object",
+        "properties": {
+            # Include Node-specific properties
+            **{k: config_schema["properties"][k].copy() for k in node_specific_props},
+            # Include common properties
+            **{k: config_schema["properties"][k].copy() for k in common_props},
+        },
+        "required": ["node_version", "graphs"],
+    }
+
+    # Add enum constraint for node_version
+    if "node_version" in node_schema["properties"]:
+        node_schema["properties"]["node_version"]["anyOf"] = [
+            {"type": "string", "enum": ["20"]},
+            {"type": "null"},
+        ]
+
+    # Replace the Config schema with a oneOf constraint
+    config_schema["oneOf"] = [python_schema, node_schema]
+
+    # Remove the properties field as it's now defined in the oneOf subschemas
+    if "properties" in config_schema:
+        del config_schema["properties"]
+
+    return schema
+
+
+def main():
+    """Generate the schema and write it to a file."""
+    schema = generate_schema()
+
+    # Add versioning to the schema
+    import importlib.metadata
+
+    try:
+        version = importlib.metadata.version("langgraph_cli").split(".")
+        schema_version = f"v{version[0]}"
+    except importlib.metadata.PackageNotFoundError:
+        schema_version = "v1"
+
+    # Add version to schema
+    schema["version"] = schema_version
+
+    config_dir = Path(__file__).parent / "schemas"
+
+    # Create versioned schema file
+    versioned_path = config_dir / f"schema.{schema_version}.json"
+    with open(versioned_path, "w") as f:
+        json.dump(schema, f, indent=2)
+
+    # Also create a latest version
+    latest_path = config_dir / "schema.json"
+    with open(latest_path, "w") as f:
+        json.dump(schema, f, indent=2)
+
+    print(f"Schema written to {versioned_path} and {latest_path}")
+    print(
+        f"You can now add '$schema: https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.json'"
+        f" or '$schema: https://raw.githubusercontent.com/langchain-ai/langgraph/refs/heads/main/libs/cli/schemas/schema.{schema_version}.json'"
+        " to your langgraph.json files"
+    )
+
+
+if __name__ == "__main__":
+    main()

libs/cli/langgraph_cli/config.py

@@ -3,7 +3,7 @@ import os
 import pathlib
 import textwrap
 from collections import Counter
-from typing import NamedTuple, Optional, TypedDict, Union
+from typing import Any, NamedTuple, Optional, TypedDict, Union
 
 import click
 
@@ -11,13 +11,37 @@ MIN_NODE_VERSION = "20"
 MIN_PYTHON_VERSION = "3.11"
 
 
+class TTLConfig(TypedDict, total=False):
+    """Configuration for TTL (time-to-live) behavior in the store."""
+
+    refresh_on_read: bool
+    """Default behavior for refreshing TTLs on read operations (GET and SEARCH).
+    
+    If True, TTLs will be refreshed on read operations (get/search) by default.
+    This can be overridden per-operation by explicitly setting refresh_ttl.
+    Defaults to True if not configured.
+    """
+    default_ttl: Optional[float]
+    """Optional. Default TTL (time-to-live) in minutes for new items.
+    
+    If provided, all new items will have this TTL unless explicitly overridden.
+    If omitted, items will have no TTL by default.
+    """
+
+
 class IndexConfig(TypedDict, total=False):
-    """Configuration for indexing documents for semantic search in the store."""
+    """Configuration for indexing documents for semantic search in the store.
+
+    This governs how text is converted into embeddings and stored for vector-based lookups.
+    """
 
     dims: int
-    """Number of dimensions in the embedding vectors.
+    """Required. Dimensionality of the embedding vectors you will store.
     
-    Common embedding models have the following dimensions:
+    Must match the output dimension of your selected embedding model or custom embed function.
+    If mismatched, you will likely encounter shape/size errors when inserting or querying vectors.
+    
+    Common embedding model output dimensions:
         - openai:text-embedding-3-large: 3072
         - openai:text-embedding-3-small: 1536
         - openai:text-embedding-ada-002: 1536
@@ -28,42 +52,130 @@ class IndexConfig(TypedDict, total=False):
     """
 
     embed: str
-    """Optional model (string) to generate embeddings from text or path to model or function.
+    """Required. Identifier or reference to the embedding model or a custom embedding function.
     
-    Examples:
+    The format can vary:
+      - "<provider>:<model_name>" for recognized providers (e.g., "openai:text-embedding-3-large")
+      - "path/to/module.py:function_name" for your own local embedding function
+      - "my_custom_embed" if it's a known alias in your system
+
+     Examples:
         - "openai:text-embedding-3-large"
         - "cohere:embed-multilingual-v3.0"
-        - "src/app.py:embeddings
+        - "src/app.py:embeddings"
+    
+    Note: Must return embeddings of dimension `dims`.
     """
 
     fields: Optional[list[str]]
-    """Fields to extract text from for embedding generation.
+    """Optional. List of JSON fields to extract before generating embeddings.
     
-    Defaults to the root ["$"], which embeds the json object as a whole.
+    Defaults to ["$"], which means the entire JSON object is embedded as one piece of text.
+    If you provide multiple fields (e.g. ["title", "content"]), each is extracted and embedded separately,
+    often saving token usage if you only care about certain parts of the data.
+    
+    Example:
+        fields=["title", "abstract", "author.biography"]
     """
 
 
 class StoreConfig(TypedDict, total=False):
-    embed: Optional[IndexConfig]
-    """Configuration for vector embeddings in store."""
+    """Configuration for the built-in long-term memory store.
+
+    This store can optionally perform semantic search. If you omit `index`,
+    the store will just handle traditional (non-embedded) data without vector lookups.
+    """
+
+    index: Optional[IndexConfig]
+    """Optional. Defines the vector-based semantic search configuration.
+    
+    If provided, the store will:
+      - Generate embeddings according to `index.embed`
+      - Enforce the embedding dimension given by `index.dims`
+      - Embed only specified JSON fields (if any) from `index.fields`
+    
+    If omitted, no vector index is initialized.
+    """
+
+    ttl: Optional[TTLConfig]
+    """Optional. Defines the TTL (time-to-live) behavior configuration.
+    
+    If provided, the store will apply TTL settings according to the configuration.
+    If omitted, no TTL behavior is configured.
+    """
 
 
 class SecurityConfig(TypedDict, total=False):
-    securitySchemes: dict
-    security: list
+    """Configuration for OpenAPI security definitions and requirements.
+
+    Useful for specifying global or path-level authentication and authorization flows
+    (e.g., OAuth2, API key headers, etc.).
+    """
+
+    securitySchemes: dict[str, dict[str, Any]]
+    """Required. Dict describing each security scheme recognized by your OpenAPI spec.
+    
+    Keys are scheme names (e.g. "OAuth2", "ApiKeyAuth") and values are their definitions.
+    Example:
+        {
+            "OAuth2": {
+                "type": "oauth2",
+                "flows": {
+                    "password": {
+                        "tokenUrl": "/token",
+                        "scopes": {"read": "Read data", "write": "Write data"}
+                    }
+                }
+            }
+        }
+    """
+    security: list[dict[str, list[str]]]
+    """Optional. Global security requirements across all endpoints.
+    
+    Each element in the list maps a security scheme (e.g. "OAuth2") to a list of scopes (e.g. ["read", "write"]).
+    Example:
+        [
+            {"OAuth2": ["read", "write"]},
+            {"ApiKeyAuth": []}
+        ]
+    """
     # path => {method => security}
-    paths: dict[str, dict[str, list]]
+    paths: dict[str, dict[str, list[dict[str, list[str]]]]]
+    """Optional. Path-specific security overrides.
+    
+    Keys are path templates (e.g., "/items/{item_id}"), mapping to:
+      - Keys that are HTTP methods (e.g., "GET", "POST"),
+      - Values are lists of security definitions (just like `security`) for that method.
+    
+    Example:
+        {
+            "/private_data": {
+                "GET": [{"OAuth2": ["read"]}],
+                "POST": [{"OAuth2": ["write"]}]
+            }
+        }
+    """
 
 
 class AuthConfig(TypedDict, total=False):
-    path: str
-    """Path to the authentication function in a Python file."""
-    disable_studio_auth: bool
-    """Whether to disable auth when connecting from the LangSmith Studio."""
-    openapi: SecurityConfig
-    """The schema to use for updating the openapi spec.
+    """Configuration for custom authentication logic and how it integrates into the OpenAPI spec."""
 
-    Example:
+    path: str
+    """Required. Path to an instance of the Auth() class that implements custom authentication.
+    
+    Format: "path/to/file.py:my_auth"
+    """
+    disable_studio_auth: bool
+    """Optional. Whether to disable LangSmith API-key authentication for requests originating the Studio. 
+    
+    Defaults to False, meaning that if a particular header is set, the server will verify the `x-api-key` header
+    value is a valid API key for the deployment's workspace. If True, all requests will go through your custom
+    authentication logic, regardless of origin of the request.
+    """
+    openapi: SecurityConfig
+    """Required. Detailed security configuration that merges into your deployment's OpenAPI spec.
+    
+    Example (OAuth2):
         {
             "securitySchemes": {
                 "OAuth2": {
@@ -71,88 +183,185 @@ class AuthConfig(TypedDict, total=False):
                     "flows": {
                         "password": {
                             "tokenUrl": "/token",
-                            "scopes": {
-                                "me": "Read information about the current user",
-                                "items": "Access to create and manage items"
-                            }
+                            "scopes": {"me": "Read user info", "items": "Manage items"}
                         }
                     }
                 }
             },
             "security": [
-                {"OAuth2": ["me"]}  # Default security requirement for all endpoints
+                {"OAuth2": ["me"]}
             ]
         }
     """
 
 
 class CorsConfig(TypedDict, total=False):
+    """Specifies Cross-Origin Resource Sharing (CORS) rules for your server.
+
+    If omitted, defaults are typically very restrictive (often no cross-origin requests).
+    Configure carefully if you want to allow usage from browsers hosted on other domains.
+    """
+
     allow_origins: list[str]
+    """Optional. List of allowed origins (e.g., "https://example.com").
+    
+    Default is often an empty list (no external origins). 
+    Use "*" only if you trust all origins, as that bypasses most restrictions.
+    """
     allow_methods: list[str]
+    """Optional. HTTP methods permitted for cross-origin requests (e.g. ["GET", "POST"]).
+    
+    Default might be ["GET", "POST", "OPTIONS"] depending on your server framework.
+    """
     allow_headers: list[str]
+    """Optional. HTTP headers that can be used in cross-origin requests (e.g. ["Content-Type", "Authorization"])."""
     allow_credentials: bool
+    """Optional. If True, cross-origin requests can include credentials (cookies, auth headers).
+    
+    Default False to avoid accidentally exposing secured endpoints to untrusted sites.
+    """
     allow_origin_regex: str
+    """Optional. A regex pattern for matching allowed origins, used if you have dynamic subdomains.
+    
+    Example: "^https://.*\.mycompany\.com$"
+    """
     expose_headers: list[str]
+    """Optional. List of headers that browsers are allowed to read from the response in cross-origin contexts."""
     max_age: int
+    """Optional. How many seconds the browser may cache preflight responses.
+    
+    Default might be 600 (10 minutes). Larger values reduce preflight requests but can cause stale configurations.
+    """
 
 
 class HttpConfig(TypedDict, total=False):
+    """Configuration for the built-in HTTP server that powers your deployment's routes and endpoints."""
+
     app: str
-    """Import path for a custom Starlette/FastAPI app to mount"""
+    """Optional. Import path to a custom Starlette/FastAPI application to mount.
+    
+    Format: "path/to/module.py:app_var"
+    If provided, it can override or extend the default routes.
+    """
     disable_assistants: bool
-    """Disable /assistants routes"""
+    """Optional. If True, /assistants routes are removed from the server.
+    
+    Default is False (meaning /assistants is enabled).
+    """
     disable_threads: bool
-    """Disable /threads routes"""
+    """Optional. If True, /threads routes are removed.
+    
+    Default is False.
+    """
     disable_runs: bool
-    """Disable /runs routes"""
+    """Optional. If True, /runs routes are removed.
+    
+    Default is False.
+    """
     disable_store: bool
-    """Disable /store routes"""
+    """Optional. If True, /store routes are removed, disabling direct store interactions via HTTP.
+    
+    Default is False.
+    """
     disable_meta: bool
-    """Disable /ok, /info, /metrics, and /docs routes"""
+    """Optional. If True, all meta endpoints (/ok, /info, /metrics, /docs) are disabled.
+    
+    Default is False.
+    """
     cors: Optional[CorsConfig]
-    """Cross-Origin Resource Sharing (CORS) configuration"""
+    """Optional. Defines CORS restrictions. If omitted, no special rules are set and 
+    cross-origin behavior depends on default server settings.
+    """
 
 
 class Config(TypedDict, total=False):
-    """Configuration for langgraph-cli."""
+    """Top-level config for langgraph-cli or similar deployment tooling."""
 
     python_version: str
-    """Python version to use."""
+    """Optional. Python version in 'major.minor' format (e.g. '3.11'). 
+    Must be at least 3.11 or greater for this deployment to function properly.
+    """
 
     node_version: Optional[str]
-    """Node.js version to use."""
+    """Optional. Node.js version as a major version (e.g. '20'), if your deployment needs Node.
+    Must be >= 20 if provided.
+    """
 
     pip_config_file: Optional[str]
-    """Path to a pip configuration file."""
+    """Optional. Path to a pip config file (e.g., "/etc/pip.conf" or "pip.ini") for controlling
+    package installation (custom indices, credentials, etc.).
+    
+    Only relevant if Python dependencies are installed via pip. If omitted, default pip settings are used.
+    """
 
     dockerfile_lines: list[str]
-    """Additional lines to add to the Dockerfile."""
+    """Optional. Additional Docker instructions that will be appended to your base Dockerfile.
+    
+    Useful for installing OS packages, setting environment variables, etc. 
+    Example:
+        dockerfile_lines=[
+            "RUN apt-get update && apt-get install -y libmagic-dev",
+            "ENV MY_CUSTOM_VAR=hello_world"
+        ]
+    """
 
     dependencies: list[str]
-    """Additional Python dependencies to install."""
+    """List of Python dependencies to install, either from PyPI or local paths.
+    
+    Examples:
+      - "." or "./src" if you have a local Python package
+      - str (aka "anthropic") for a PyPI package
+      - "git+https://github.com/org/repo.git@main" for a Git-based package
+    Defaults to an empty list, meaning no additional packages installed beyond your base environment.
+    """
 
     graphs: dict[str, str]
-    """Mapping of graph names to their definitions."""
+    """Optional. Named definitions of graphs, each pointing to a Python object.
+
+    
+    Graphs can be StateGraph, @entrypoint, or any other Pregel object OR they can point to (async) context
+    managers that accept a single configuration argument (of type RunnableConfig) and return a pregel object
+    (instance of Stategraph, etc.).
+    
+    Keys are graph names, values are "path/to/file.py:object_name".
+    Example:
+        {
+            "mygraph": "graphs/my_graph.py:graph_definition",
+            "anothergraph": "graphs/another.py:get_graph"
+        }
+    """
 
     env: Union[dict[str, str], str]
-    """Environment variables to set.
-
-    If a dictionary is provided, the keys are environment variable names
-    and the values are the corresponding environment variable values.
-
-    If a string is provided, it is interpreted as a path to a file containing
-    environment variables in the format KEY=VALUE, with one environment variable
-    per line.
+    """Optional. Environment variables to set for your deployment.
+    
+    - If given as a dict, keys are variable names and values are their values.
+    - If given as a string, it must be a path to a file containing lines in KEY=VALUE format.
+    
+    Example as a dict:
+        env={"API_TOKEN": "abc123", "DEBUG": "true"}
+    Example as a file path:
+        env=".env"
     """
 
     store: Optional[StoreConfig]
-    """Configuration for vector embeddings in store."""
+    """Optional. Configuration for the built-in long-term memory store, including semantic search indexing.
+    
+    If omitted, no vector index is set up (the object store will still be present, however).
+    """
 
     auth: Optional[AuthConfig]
-    """Configuration for authentication."""
+    """Optional. Custom authentication config, including the path to your Python auth logic and 
+    the OpenAPI security definitions it uses.
+    """
 
     http: Optional[HttpConfig]
-    """Configuration for HTTP server."""
+    """Optional. Configuration for the built-in HTTP server, controlling which custom routes are exposed
+    and how cross-origin requests are handled.
+    """
+
+    ui: Optional[dict[str, str]]
+    """Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file.
+    """
 
 
 def _parse_version(version_str: str) -> tuple[int, int]:
@@ -189,6 +398,7 @@ def validate_config(config: Config) -> Config:
             "store": config.get("store"),
             "auth": config.get("auth"),
             "http": config.get("http"),
+            "ui": config.get("ui"),
         }
         if config.get("node_version")
         else {
@@ -201,6 +411,7 @@ def validate_config(config: Config) -> Config:
             "store": config.get("store"),
             "auth": config.get("auth"),
             "http": config.get("http"),
+            "ui": config.get("ui"),
         }
     )
 
@@ -687,9 +898,11 @@ def python_config_to_docker(
     pip_pkgs_str = f"RUN {pip_install} {' '.join(pypi_deps)}" if pypi_deps else ""
     if local_deps.pip_reqs:
         pip_reqs_str = os.linesep.join(
-            f"COPY --from=__outer_{reqpath.name} requirements.txt {destpath}"
-            if reqpath.parent in local_deps.additional_contexts
-            else f"ADD {reqpath.relative_to(config_path.parent)} {destpath}"
+            (
+                f"COPY --from=__outer_{reqpath.name} requirements.txt {destpath}"
+                if reqpath.parent in local_deps.additional_contexts
+                else f"ADD {reqpath.relative_to(config_path.parent)} {destpath}"
+            )
             for reqpath, destpath in local_deps.pip_reqs
         )
         pip_reqs_str += f'{os.linesep}RUN {pip_install} {" ".join("-r " + r for _,r in local_deps.pip_reqs)}'
@@ -724,13 +937,15 @@ RUN set -ex && \\
     )
 
     local_pkgs_str = os.linesep.join(
-        f"""# -- Adding local package {relpath} --
+        (
+            f"""# -- Adding local package {relpath} --
 COPY --from={name} . /deps/{name}
 # -- End of local package {relpath} --"""
-        if fullpath in local_deps.additional_contexts
-        else f"""# -- Adding local package {relpath} --
+            if fullpath in local_deps.additional_contexts
+            else f"""# -- Adding local package {relpath} --
 ADD {relpath} /deps/{name}
 # -- End of local package {relpath} --"""
+        )
         for fullpath, (relpath, name) in local_deps.real_pkgs.items()
     )
 
@@ -845,6 +1060,7 @@ ADD . {faux_path}
 RUN cd {faux_path} && {install_cmd}
 {env_additional_config}
 ENV LANGSERVE_GRAPHS='{json.dumps(config["graphs"])}'
+{f"ENV LANGGRAPH_UI='{json.dumps(config['ui'])}'" if config.get("ui") else ""}
 
 WORKDIR {faux_path}
 

libs/cli/poetry.lock

@@ -707,6 +707,58 @@ files = [
     {file = "msgpack-1.1.0.tar.gz", hash = "sha256:dd432ccc2c72b914e4cb77afce64aab761c1137cc698be3984eee260bcb2896e"},
 ]
 
+[[package]]
+name = "msgspec"
+version = "0.19.0"
+description = "A fast serialization and validation library, with builtin support for JSON, MessagePack, YAML, and TOML."
+optional = false
+python-versions = ">=3.9"
+files = [
+    {file = "msgspec-0.19.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d8dd848ee7ca7c8153462557655570156c2be94e79acec3561cf379581343259"},
+    {file = "msgspec-0.19.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:0553bbc77662e5708fe66aa75e7bd3e4b0f209709c48b299afd791d711a93c36"},
+    {file = "msgspec-0.19.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fe2c4bf29bf4e89790b3117470dea2c20b59932772483082c468b990d45fb947"},
+    {file = "msgspec-0.19.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:00e87ecfa9795ee5214861eab8326b0e75475c2e68a384002aa135ea2a27d909"},
+    {file = "msgspec-0.19.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:3c4ec642689da44618f68c90855a10edbc6ac3ff7c1d94395446c65a776e712a"},
+    {file = "msgspec-0.19.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:2719647625320b60e2d8af06b35f5b12d4f4d281db30a15a1df22adb2295f633"},
+    {file = "msgspec-0.19.0-cp310-cp310-win_amd64.whl", hash = "sha256:695b832d0091edd86eeb535cd39e45f3919f48d997685f7ac31acb15e0a2ed90"},
+    {file = "msgspec-0.19.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:aa77046904db764b0462036bc63ef71f02b75b8f72e9c9dd4c447d6da1ed8f8e"},
+    {file = "msgspec-0.19.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:047cfa8675eb3bad68722cfe95c60e7afabf84d1bd8938979dd2b92e9e4a9551"},
+    {file = "msgspec-0.19.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e78f46ff39a427e10b4a61614a2777ad69559cc8d603a7c05681f5a595ea98f7"},
+    {file = "msgspec-0.19.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c7adf191e4bd3be0e9231c3b6dc20cf1199ada2af523885efc2ed218eafd011"},
+    {file = "msgspec-0.19.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:f04cad4385e20be7c7176bb8ae3dca54a08e9756cfc97bcdb4f18560c3042063"},
+    {file = "msgspec-0.19.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:45c8fb410670b3b7eb884d44a75589377c341ec1392b778311acdbfa55187716"},
+    {file = "msgspec-0.19.0-cp311-cp311-win_amd64.whl", hash = "sha256:70eaef4934b87193a27d802534dc466778ad8d536e296ae2f9334e182ac27b6c"},
+    {file = "msgspec-0.19.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:f98bd8962ad549c27d63845b50af3f53ec468b6318400c9f1adfe8b092d7b62f"},
+    {file = "msgspec-0.19.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:43bbb237feab761b815ed9df43b266114203f53596f9b6e6f00ebd79d178cdf2"},
+    {file = "msgspec-0.19.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4cfc033c02c3e0aec52b71710d7f84cb3ca5eb407ab2ad23d75631153fdb1f12"},
+    {file = "msgspec-0.19.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d911c442571605e17658ca2b416fd8579c5050ac9adc5e00c2cb3126c97f73bc"},
+    {file = "msgspec-0.19.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:757b501fa57e24896cf40a831442b19a864f56d253679f34f260dcb002524a6c"},
+    {file = "msgspec-0.19.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5f0f65f29b45e2816d8bded36e6b837a4bf5fb60ec4bc3c625fa2c6da4124537"},
+    {file = "msgspec-0.19.0-cp312-cp312-win_amd64.whl", hash = "sha256:067f0de1c33cfa0b6a8206562efdf6be5985b988b53dd244a8e06f993f27c8c0"},
+    {file = "msgspec-0.19.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:f12d30dd6266557aaaf0aa0f9580a9a8fbeadfa83699c487713e355ec5f0bd86"},
+    {file = "msgspec-0.19.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:82b2c42c1b9ebc89e822e7e13bbe9d17ede0c23c187469fdd9505afd5a481314"},
+    {file = "msgspec-0.19.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:19746b50be214a54239aab822964f2ac81e38b0055cca94808359d779338c10e"},
+    {file = "msgspec-0.19.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:60ef4bdb0ec8e4ad62e5a1f95230c08efb1f64f32e6e8dd2ced685bcc73858b5"},
+    {file = "msgspec-0.19.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ac7f7c377c122b649f7545810c6cd1b47586e3aa3059126ce3516ac7ccc6a6a9"},
+    {file = "msgspec-0.19.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:a5bc1472223a643f5ffb5bf46ccdede7f9795078194f14edd69e3aab7020d327"},
+    {file = "msgspec-0.19.0-cp313-cp313-win_amd64.whl", hash = "sha256:317050bc0f7739cb30d257ff09152ca309bf5a369854bbf1e57dffc310c1f20f"},
+    {file = "msgspec-0.19.0-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:15c1e86fff77184c20a2932cd9742bf33fe23125fa3fcf332df9ad2f7d483044"},
+    {file = "msgspec-0.19.0-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:3b5541b2b3294e5ffabe31a09d604e23a88533ace36ac288fa32a420aa38d229"},
+    {file = "msgspec-0.19.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0f5c043ace7962ef188746e83b99faaa9e3e699ab857ca3f367b309c8e2c6b12"},
+    {file = "msgspec-0.19.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ca06aa08e39bf57e39a258e1996474f84d0dd8130d486c00bec26d797b8c5446"},
+    {file = "msgspec-0.19.0-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:e695dad6897896e9384cf5e2687d9ae9feaef50e802f93602d35458e20d1fb19"},
+    {file = "msgspec-0.19.0-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:3be5c02e1fee57b54130316a08fe40cca53af92999a302a6054cd451700ea7db"},
+    {file = "msgspec-0.19.0-cp39-cp39-win_amd64.whl", hash = "sha256:0684573a821be3c749912acf5848cce78af4298345cb2d7a8b8948a0a5a27cfe"},
+    {file = "msgspec-0.19.0.tar.gz", hash = "sha256:604037e7cd475345848116e89c553aa9a233259733ab51986ac924ab1b976f8e"},
+]
+
+[package.extras]
+dev = ["attrs", "coverage", "eval-type-backport", "furo", "ipython", "msgpack", "mypy", "pre-commit", "pyright", "pytest", "pyyaml", "sphinx", "sphinx-copybutton", "sphinx-design", "tomli", "tomli_w"]
+doc = ["furo", "ipython", "sphinx", "sphinx-copybutton", "sphinx-design"]
+test = ["attrs", "eval-type-backport", "msgpack", "pytest", "pyyaml", "tomli", "tomli_w"]
+toml = ["tomli", "tomli_w"]
+yaml = ["pyyaml"]
+
 [[package]]
 name = "mypy"
 version = "1.15.0"
@@ -1665,4 +1717,4 @@ inmem = ["langgraph-api", "python-dotenv"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.9.0,<4.0"
-content-hash = "04a0b0e203ae00f30cca7e454c632be0b41cbb4820d0c05315a346d514b5f98e"
+content-hash = "d0e2bdcb600ad031867413025fcc58bb162609209359d63ca99a77060cf8cbb4"

libs/cli/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-cli"
-version = "0.1.74"
+version = "0.1.76"
 description = "CLI for interacting with LangGraph API"
 authors = []
 license = "MIT"
@@ -25,6 +25,7 @@ pytest-asyncio = "^0.21.1"
 pytest-mock = "^3.11.1"
 pytest-watch = "^4.2.0"
 mypy = "^1.10.0"
+msgspec = "^0.19.0"
 
 [tool.poetry.extras]
 inmem = ["langgraph-api", "python-dotenv"]

libs/cli/schemas/schema.json

@@ -0,0 +1,470 @@
+{
+  "$ref": "#/$defs/Config",
+  "$defs": {
+    "Config": {
+      "title": "Config",
+      "description": "Top-level config for langgraph-cli or similar deployment tooling.",
+      "type": "object",
+      "required": [],
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "python_version": {
+              "type": "string",
+              "description": "Optional. Python version in 'major.minor' format (e.g. '3.11').\nMust be at least 3.11 or greater for this deployment to function properly.\n",
+              "enum": [
+                "3.11",
+                "3.12"
+              ]
+            },
+            "pip_config_file": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Path to a pip config file (e.g., \"/etc/pip.conf\" or \"pip.ini\") for controlling\npackage installation (custom indices, credentials, etc.).\n\nOnly relevant if Python dependencies are installed via pip. If omitted, default pip settings are used.\n"
+            },
+            "auth": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/AuthConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom authentication config, including the path to your Python auth logic and\nthe OpenAPI security definitions it uses.\n"
+            },
+            "dependencies": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "List of Python dependencies to install, either from PyPI or local paths.\n"
+            },
+            "dockerfile_lines": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional. Additional Docker instructions that will be appended to your base Dockerfile.\n\nUseful for installing OS packages, setting environment variables, etc."
+            },
+            "env": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "string"
+                }
+              ],
+              "description": "Optional. Environment variables to set for your deployment.\n\n- If given as a dict, keys are variable names and values are their values.\n- If given as a string, it must be a path to a file containing lines in KEY=VALUE format.\n\nenv=\".env\n"
+            },
+            "graphs": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "Optional. Named definitions of graphs, each pointing to a Python object.\n\n\nGraphs can be StateGraph, @entrypoint, or any other Pregel object OR they can point to (async) context\nmanagers that accept a single configuration argument (of type RunnableConfig) and return a pregel object\n(instance of Stategraph, etc.).\n"
+            },
+            "http": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/HttpConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in HTTP server, controlling which custom routes are exposed\nand how cross-origin requests are handled.\n"
+            },
+            "store": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/StoreConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in long-term memory store, including semantic search indexing.\n\nIf omitted, no vector index is set up (the object store will still be present, however).\n"
+            },
+            "ui": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file.\n"
+            }
+          },
+          "required": [
+            "dependencies",
+            "graphs"
+          ]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "node_version": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "enum": [
+                    "20"
+                  ]
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Node.js version as a major version (e.g. '20'), if your deployment needs Node.\nMust be >= 20 if provided.\n"
+            },
+            "auth": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/AuthConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom authentication config, including the path to your Python auth logic and\nthe OpenAPI security definitions it uses.\n"
+            },
+            "dependencies": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "List of Python dependencies to install, either from PyPI or local paths.\n"
+            },
+            "dockerfile_lines": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional. Additional Docker instructions that will be appended to your base Dockerfile.\n\nUseful for installing OS packages, setting environment variables, etc."
+            },
+            "env": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "string"
+                }
+              ],
+              "description": "Optional. Environment variables to set for your deployment.\n\n- If given as a dict, keys are variable names and values are their values.\n- If given as a string, it must be a path to a file containing lines in KEY=VALUE format.\n\nenv=\".env\n"
+            },
+            "graphs": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "Optional. Named definitions of graphs, each pointing to a Python object.\n\n\nGraphs can be StateGraph, @entrypoint, or any other Pregel object OR they can point to (async) context\nmanagers that accept a single configuration argument (of type RunnableConfig) and return a pregel object\n(instance of Stategraph, etc.).\n"
+            },
+            "http": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/HttpConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in HTTP server, controlling which custom routes are exposed\nand how cross-origin requests are handled.\n"
+            },
+            "store": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/StoreConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in long-term memory store, including semantic search indexing.\n\nIf omitted, no vector index is set up (the object store will still be present, however).\n"
+            },
+            "ui": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file.\n"
+            }
+          },
+          "required": [
+            "node_version",
+            "graphs"
+          ]
+        }
+      ]
+    },
+    "AuthConfig": {
+      "title": "AuthConfig",
+      "description": "Configuration for custom authentication logic and how it integrates into the OpenAPI spec.",
+      "type": "object",
+      "properties": {
+        "disable_studio_auth": {
+          "type": "boolean",
+          "description": "Optional. Whether to disable LangSmith API-key authentication for requests originating the Studio.\n\nDefaults to False, meaning that if a particular header is set, the server will verify the `x-api-key` header\nvalue is a valid API key for the deployment's workspace. If True, all requests will go through your custom\nauthentication logic, regardless of origin of the request.\n"
+        },
+        "openapi": {
+          "$ref": "#/$defs/SecurityConfig",
+          "description": "Required. Detailed security configuration that merges into your deployment's OpenAPI spec.\n\n{\n}\n}\n}\n},\n]\n}\n"
+        },
+        "path": {
+          "type": "string",
+          "description": "Required. Path to an instance of the Auth() class that implements custom authentication.\n"
+        }
+      },
+      "required": []
+    },
+    "SecurityConfig": {
+      "title": "SecurityConfig",
+      "description": "Configuration for OpenAPI security definitions and requirements.\n\nUseful for specifying global or path-level authentication and authorization flows\n(e.g., OAuth2, API key headers, etc.).",
+      "type": "object",
+      "properties": {
+        "paths": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "description": "Optional. Path-specific security overrides.\n\n- Keys that are HTTP methods (e.g., \"GET\", \"POST\"),\n- Values are lists of security definitions (just like `security`) for that method.\n"
+        },
+        "security": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "Optional. Global security requirements across all endpoints.\n\nEach element in the list maps a security scheme (e.g. \"OAuth2\") to a list of scopes (e.g. [\"read\", \"write\"])."
+        },
+        "securitySchemes": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          },
+          "description": "Required. Dict describing each security scheme recognized by your OpenAPI spec.\n\nKeys are scheme names (e.g. \"OAuth2\", \"ApiKeyAuth\") and values are their definitions."
+        }
+      },
+      "required": []
+    },
+    "HttpConfig": {
+      "title": "HttpConfig",
+      "description": "Configuration for the built-in HTTP server that powers your deployment's routes and endpoints.",
+      "type": "object",
+      "properties": {
+        "app": {
+          "type": "string",
+          "description": "Optional. Import path to a custom Starlette/FastAPI application to mount.\n"
+        },
+        "cors": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/CorsConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. Defines CORS restrictions. If omitted, no special rules are set and\ncross-origin behavior depends on default server settings.\n"
+        },
+        "disable_assistants": {
+          "type": "boolean",
+          "description": "Optional. If True, /assistants routes are removed from the server.\n\nDefault is False (meaning /assistants is enabled).\n"
+        },
+        "disable_meta": {
+          "type": "boolean",
+          "description": "Optional. If True, all meta endpoints (/ok, /info, /metrics, /docs) are disabled.\n\nDefault is False.\n"
+        },
+        "disable_runs": {
+          "type": "boolean",
+          "description": "Optional. If True, /runs routes are removed.\n\nDefault is False.\n"
+        },
+        "disable_store": {
+          "type": "boolean",
+          "description": "Optional. If True, /store routes are removed, disabling direct store interactions via HTTP.\n\nDefault is False.\n"
+        },
+        "disable_threads": {
+          "type": "boolean",
+          "description": "Optional. If True, /threads routes are removed.\n\nDefault is False.\n"
+        }
+      },
+      "required": []
+    },
+    "CorsConfig": {
+      "title": "CorsConfig",
+      "description": "Specifies Cross-Origin Resource Sharing (CORS) rules for your server.\n\nIf omitted, defaults are typically very restrictive (often no cross-origin requests).\nConfigure carefully if you want to allow usage from browsers hosted on other domains.",
+      "type": "object",
+      "properties": {
+        "allow_credentials": {
+          "type": "boolean",
+          "description": "Optional. If True, cross-origin requests can include credentials (cookies, auth headers).\n\nDefault False to avoid accidentally exposing secured endpoints to untrusted sites.\n"
+        },
+        "allow_headers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. HTTP headers that can be used in cross-origin requests (e.g. [\"Content-Type\", \"Authorization\"])."
+        },
+        "allow_methods": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. HTTP methods permitted for cross-origin requests (e.g. [\"GET\", \"POST\"]).\n\nDefault might be [\"GET\", \"POST\", \"OPTIONS\"] depending on your server framework.\n"
+        },
+        "allow_origin_regex": {
+          "type": "string",
+          "description": "Optional. A regex pattern for matching allowed origins, used if you have dynamic subdomains.\n"
+        },
+        "allow_origins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. List of allowed origins (e.g., \"https://example.com\").\n\nDefault is often an empty list (no external origins).\nUse \"*\" only if you trust all origins, as that bypasses most restrictions.\n"
+        },
+        "expose_headers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. List of headers that browsers are allowed to read from the response in cross-origin contexts."
+        },
+        "max_age": {
+          "type": "integer",
+          "description": "Optional. How many seconds the browser may cache preflight responses.\n\nDefault might be 600 (10 minutes). Larger values reduce preflight requests but can cause stale configurations.\n"
+        }
+      },
+      "required": []
+    },
+    "StoreConfig": {
+      "title": "StoreConfig",
+      "description": "Configuration for the built-in long-term memory store.\n\nThis store can optionally perform semantic search. If you omit `index`,\nthe store will just handle traditional (non-embedded) data without vector lookups.",
+      "type": "object",
+      "properties": {
+        "index": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/IndexConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. Defines the vector-based semantic search configuration.\n\n- Generate embeddings according to `index.embed`\n- Enforce the embedding dimension given by `index.dims`\n- Embed only specified JSON fields (if any) from `index.fields`\n\nIf omitted, no vector index is initialized.\n"
+        },
+        "ttl": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/TTLConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. Defines the TTL (time-to-live) behavior configuration.\n\nIf provided, the store will apply TTL settings according to the configuration.\nIf omitted, no TTL behavior is configured.\n"
+        }
+      },
+      "required": []
+    },
+    "IndexConfig": {
+      "title": "IndexConfig",
+      "description": "Configuration for indexing documents for semantic search in the store.\n\nThis governs how text is converted into embeddings and stored for vector-based lookups.",
+      "type": "object",
+      "properties": {
+        "dims": {
+          "type": "integer",
+          "description": "Required. Dimensionality of the embedding vectors you will store.\n\nMust match the output dimension of your selected embedding model or custom embed function.\nIf mismatched, you will likely encounter shape/size errors when inserting or querying vectors.\n\n"
+        },
+        "embed": {
+          "type": "string",
+          "description": "Required. Identifier or reference to the embedding model or a custom embedding function.\n\n- \"my_custom_embed\" if it's a known alias in your system\n"
+        },
+        "fields": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. List of JSON fields to extract before generating embeddings.\n\nDefaults to [\"$\"], which means the entire JSON object is embedded as one piece of text.\nIf you provide multiple fields (e.g. [\"title\", \"content\"]), each is extracted and embedded separately,\noften saving token usage if you only care about certain parts of the data.\n"
+        }
+      },
+      "required": []
+    },
+    "TTLConfig": {
+      "title": "TTLConfig",
+      "description": "Configuration for TTL (time-to-live) behavior in the store.",
+      "type": "object",
+      "properties": {
+        "default_ttl": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "refresh_on_read": {
+          "type": "boolean"
+        }
+      },
+      "required": []
+    }
+  },
+  "title": "LangGraph CLI Configuration",
+  "description": "Configuration schema for langgraph-cli",
+  "version": "v0"
+}

libs/cli/schemas/schema.v0.json

@@ -0,0 +1,470 @@
+{
+  "$ref": "#/$defs/Config",
+  "$defs": {
+    "Config": {
+      "title": "Config",
+      "description": "Top-level config for langgraph-cli or similar deployment tooling.",
+      "type": "object",
+      "required": [],
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "python_version": {
+              "type": "string",
+              "description": "Optional. Python version in 'major.minor' format (e.g. '3.11').\nMust be at least 3.11 or greater for this deployment to function properly.\n",
+              "enum": [
+                "3.11",
+                "3.12"
+              ]
+            },
+            "pip_config_file": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Path to a pip config file (e.g., \"/etc/pip.conf\" or \"pip.ini\") for controlling\npackage installation (custom indices, credentials, etc.).\n\nOnly relevant if Python dependencies are installed via pip. If omitted, default pip settings are used.\n"
+            },
+            "auth": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/AuthConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom authentication config, including the path to your Python auth logic and\nthe OpenAPI security definitions it uses.\n"
+            },
+            "dependencies": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "List of Python dependencies to install, either from PyPI or local paths.\n"
+            },
+            "dockerfile_lines": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional. Additional Docker instructions that will be appended to your base Dockerfile.\n\nUseful for installing OS packages, setting environment variables, etc."
+            },
+            "env": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "string"
+                }
+              ],
+              "description": "Optional. Environment variables to set for your deployment.\n\n- If given as a dict, keys are variable names and values are their values.\n- If given as a string, it must be a path to a file containing lines in KEY=VALUE format.\n\nenv=\".env\n"
+            },
+            "graphs": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "Optional. Named definitions of graphs, each pointing to a Python object.\n\n\nGraphs can be StateGraph, @entrypoint, or any other Pregel object OR they can point to (async) context\nmanagers that accept a single configuration argument (of type RunnableConfig) and return a pregel object\n(instance of Stategraph, etc.).\n"
+            },
+            "http": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/HttpConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in HTTP server, controlling which custom routes are exposed\nand how cross-origin requests are handled.\n"
+            },
+            "store": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/StoreConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in long-term memory store, including semantic search indexing.\n\nIf omitted, no vector index is set up (the object store will still be present, however).\n"
+            },
+            "ui": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file.\n"
+            }
+          },
+          "required": [
+            "dependencies",
+            "graphs"
+          ]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "node_version": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "enum": [
+                    "20"
+                  ]
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Node.js version as a major version (e.g. '20'), if your deployment needs Node.\nMust be >= 20 if provided.\n"
+            },
+            "auth": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/AuthConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom authentication config, including the path to your Python auth logic and\nthe OpenAPI security definitions it uses.\n"
+            },
+            "dependencies": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "List of Python dependencies to install, either from PyPI or local paths.\n"
+            },
+            "dockerfile_lines": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional. Additional Docker instructions that will be appended to your base Dockerfile.\n\nUseful for installing OS packages, setting environment variables, etc."
+            },
+            "env": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "string"
+                }
+              ],
+              "description": "Optional. Environment variables to set for your deployment.\n\n- If given as a dict, keys are variable names and values are their values.\n- If given as a string, it must be a path to a file containing lines in KEY=VALUE format.\n\nenv=\".env\n"
+            },
+            "graphs": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "Optional. Named definitions of graphs, each pointing to a Python object.\n\n\nGraphs can be StateGraph, @entrypoint, or any other Pregel object OR they can point to (async) context\nmanagers that accept a single configuration argument (of type RunnableConfig) and return a pregel object\n(instance of Stategraph, etc.).\n"
+            },
+            "http": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/HttpConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in HTTP server, controlling which custom routes are exposed\nand how cross-origin requests are handled.\n"
+            },
+            "store": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/StoreConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Configuration for the built-in long-term memory store, including semantic search indexing.\n\nIf omitted, no vector index is set up (the object store will still be present, however).\n"
+            },
+            "ui": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file.\n"
+            }
+          },
+          "required": [
+            "node_version",
+            "graphs"
+          ]
+        }
+      ]
+    },
+    "AuthConfig": {
+      "title": "AuthConfig",
+      "description": "Configuration for custom authentication logic and how it integrates into the OpenAPI spec.",
+      "type": "object",
+      "properties": {
+        "disable_studio_auth": {
+          "type": "boolean",
+          "description": "Optional. Whether to disable LangSmith API-key authentication for requests originating the Studio.\n\nDefaults to False, meaning that if a particular header is set, the server will verify the `x-api-key` header\nvalue is a valid API key for the deployment's workspace. If True, all requests will go through your custom\nauthentication logic, regardless of origin of the request.\n"
+        },
+        "openapi": {
+          "$ref": "#/$defs/SecurityConfig",
+          "description": "Required. Detailed security configuration that merges into your deployment's OpenAPI spec.\n\n{\n}\n}\n}\n},\n]\n}\n"
+        },
+        "path": {
+          "type": "string",
+          "description": "Required. Path to an instance of the Auth() class that implements custom authentication.\n"
+        }
+      },
+      "required": []
+    },
+    "SecurityConfig": {
+      "title": "SecurityConfig",
+      "description": "Configuration for OpenAPI security definitions and requirements.\n\nUseful for specifying global or path-level authentication and authorization flows\n(e.g., OAuth2, API key headers, etc.).",
+      "type": "object",
+      "properties": {
+        "paths": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "description": "Optional. Path-specific security overrides.\n\n- Keys that are HTTP methods (e.g., \"GET\", \"POST\"),\n- Values are lists of security definitions (just like `security`) for that method.\n"
+        },
+        "security": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "Optional. Global security requirements across all endpoints.\n\nEach element in the list maps a security scheme (e.g. \"OAuth2\") to a list of scopes (e.g. [\"read\", \"write\"])."
+        },
+        "securitySchemes": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          },
+          "description": "Required. Dict describing each security scheme recognized by your OpenAPI spec.\n\nKeys are scheme names (e.g. \"OAuth2\", \"ApiKeyAuth\") and values are their definitions."
+        }
+      },
+      "required": []
+    },
+    "HttpConfig": {
+      "title": "HttpConfig",
+      "description": "Configuration for the built-in HTTP server that powers your deployment's routes and endpoints.",
+      "type": "object",
+      "properties": {
+        "app": {
+          "type": "string",
+          "description": "Optional. Import path to a custom Starlette/FastAPI application to mount.\n"
+        },
+        "cors": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/CorsConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. Defines CORS restrictions. If omitted, no special rules are set and\ncross-origin behavior depends on default server settings.\n"
+        },
+        "disable_assistants": {
+          "type": "boolean",
+          "description": "Optional. If True, /assistants routes are removed from the server.\n\nDefault is False (meaning /assistants is enabled).\n"
+        },
+        "disable_meta": {
+          "type": "boolean",
+          "description": "Optional. If True, all meta endpoints (/ok, /info, /metrics, /docs) are disabled.\n\nDefault is False.\n"
+        },
+        "disable_runs": {
+          "type": "boolean",
+          "description": "Optional. If True, /runs routes are removed.\n\nDefault is False.\n"
+        },
+        "disable_store": {
+          "type": "boolean",
+          "description": "Optional. If True, /store routes are removed, disabling direct store interactions via HTTP.\n\nDefault is False.\n"
+        },
+        "disable_threads": {
+          "type": "boolean",
+          "description": "Optional. If True, /threads routes are removed.\n\nDefault is False.\n"
+        }
+      },
+      "required": []
+    },
+    "CorsConfig": {
+      "title": "CorsConfig",
+      "description": "Specifies Cross-Origin Resource Sharing (CORS) rules for your server.\n\nIf omitted, defaults are typically very restrictive (often no cross-origin requests).\nConfigure carefully if you want to allow usage from browsers hosted on other domains.",
+      "type": "object",
+      "properties": {
+        "allow_credentials": {
+          "type": "boolean",
+          "description": "Optional. If True, cross-origin requests can include credentials (cookies, auth headers).\n\nDefault False to avoid accidentally exposing secured endpoints to untrusted sites.\n"
+        },
+        "allow_headers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. HTTP headers that can be used in cross-origin requests (e.g. [\"Content-Type\", \"Authorization\"])."
+        },
+        "allow_methods": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. HTTP methods permitted for cross-origin requests (e.g. [\"GET\", \"POST\"]).\n\nDefault might be [\"GET\", \"POST\", \"OPTIONS\"] depending on your server framework.\n"
+        },
+        "allow_origin_regex": {
+          "type": "string",
+          "description": "Optional. A regex pattern for matching allowed origins, used if you have dynamic subdomains.\n"
+        },
+        "allow_origins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. List of allowed origins (e.g., \"https://example.com\").\n\nDefault is often an empty list (no external origins).\nUse \"*\" only if you trust all origins, as that bypasses most restrictions.\n"
+        },
+        "expose_headers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional. List of headers that browsers are allowed to read from the response in cross-origin contexts."
+        },
+        "max_age": {
+          "type": "integer",
+          "description": "Optional. How many seconds the browser may cache preflight responses.\n\nDefault might be 600 (10 minutes). Larger values reduce preflight requests but can cause stale configurations.\n"
+        }
+      },
+      "required": []
+    },
+    "StoreConfig": {
+      "title": "StoreConfig",
+      "description": "Configuration for the built-in long-term memory store.\n\nThis store can optionally perform semantic search. If you omit `index`,\nthe store will just handle traditional (non-embedded) data without vector lookups.",
+      "type": "object",
+      "properties": {
+        "index": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/IndexConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. Defines the vector-based semantic search configuration.\n\n- Generate embeddings according to `index.embed`\n- Enforce the embedding dimension given by `index.dims`\n- Embed only specified JSON fields (if any) from `index.fields`\n\nIf omitted, no vector index is initialized.\n"
+        },
+        "ttl": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/TTLConfig"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. Defines the TTL (time-to-live) behavior configuration.\n\nIf provided, the store will apply TTL settings according to the configuration.\nIf omitted, no TTL behavior is configured.\n"
+        }
+      },
+      "required": []
+    },
+    "IndexConfig": {
+      "title": "IndexConfig",
+      "description": "Configuration for indexing documents for semantic search in the store.\n\nThis governs how text is converted into embeddings and stored for vector-based lookups.",
+      "type": "object",
+      "properties": {
+        "dims": {
+          "type": "integer",
+          "description": "Required. Dimensionality of the embedding vectors you will store.\n\nMust match the output dimension of your selected embedding model or custom embed function.\nIf mismatched, you will likely encounter shape/size errors when inserting or querying vectors.\n\n"
+        },
+        "embed": {
+          "type": "string",
+          "description": "Required. Identifier or reference to the embedding model or a custom embedding function.\n\n- \"my_custom_embed\" if it's a known alias in your system\n"
+        },
+        "fields": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional. List of JSON fields to extract before generating embeddings.\n\nDefaults to [\"$\"], which means the entire JSON object is embedded as one piece of text.\nIf you provide multiple fields (e.g. [\"title\", \"content\"]), each is extracted and embedded separately,\noften saving token usage if you only care about certain parts of the data.\n"
+        }
+      },
+      "required": []
+    },
+    "TTLConfig": {
+      "title": "TTLConfig",
+      "description": "Configuration for TTL (time-to-live) behavior in the store.",
+      "type": "object",
+      "properties": {
+        "default_ttl": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "refresh_on_read": {
+          "type": "boolean"
+        }
+      },
+      "required": []
+    }
+  },
+  "title": "LangGraph CLI Configuration",
+  "description": "Configuration schema for langgraph-cli",
+  "version": "v0"
+}

libs/cli/tests/unit_tests/test_config.py

@@ -33,6 +33,7 @@ def test_validate_config():
         "store": None,
         "auth": None,
         "http": None,
+        "ui": None,
         **expected_config,
     }
     actual_config = validate_config(expected_config)
@@ -52,6 +53,7 @@ def test_validate_config():
         "store": None,
         "auth": None,
         "http": None,
+        "ui": None,
     }
     actual_config = validate_config(expected_config)
     assert actual_config == expected_config
@@ -467,6 +469,7 @@ def test_config_to_docker_nodejs():
                 "node_version": "20",
                 "graphs": graphs,
                 "dockerfile_lines": ["ARG meow", "ARG foo"],
+                "ui": {"agent": "./graphs/agent.ui.jsx"},
             }
         ),
         "langchain/langgraphjs-api",
@@ -477,6 +480,7 @@ ARG foo
 ADD . /deps/unit_tests
 RUN cd /deps/unit_tests && npm i
 ENV LANGSERVE_GRAPHS='{"agent": "./graphs/agent.js:graph"}'
+ENV LANGGRAPH_UI='{"agent": "./graphs/agent.ui.jsx"}'
 WORKDIR /deps/unit_tests
 RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts"""
 

libs/langgraph/README.md

@@ -1,6 +1,6 @@
 # 🦜🕸️LangGraph
 
-![Version](https://img.shields.io/pypi/v/langgraph)
+[![Version](https://img.shields.io/pypi/v/langgraph.svg)](https://pypi.org/project/langgraph/)
 [![Downloads](https://static.pepy.tech/badge/langgraph/month)](https://pepy.tech/project/langgraph)
 [![Open Issues](https://img.shields.io/github/issues-raw/langchain-ai/langgraph)](https://github.com/langchain-ai/langgraph/issues)
 [![Docs](https://img.shields.io/badge/docs-latest-blue)](https://langchain-ai.github.io/langgraph/)

libs/langgraph/langgraph/func/__init__.py

@@ -36,23 +36,31 @@ from langgraph.types import _DC_KWARGS, RetryPolicy, StreamMode
 
 @overload
 def task(
-    *, name: Optional[str] = None, retry: Optional[RetryPolicy] = None
-) -> Callable[[Callable[P, T]], Callable[P, SyncAsyncFuture[T]]]: ...
+    *,
+    name: Optional[str] = None,
+    retry: Optional[RetryPolicy] = None,
+) -> Callable[
+    [Union[Callable[P, Awaitable[T]], Callable[P, T]]],
+    Callable[P, SyncAsyncFuture[T]],
+]: ...
 
 
 @overload
 def task(
-    __func_or_none__: Callable[P, T],
+    __func_or_none__: Union[Callable[P, Awaitable[T]], Callable[P, T]],
 ) -> Callable[P, SyncAsyncFuture[T]]: ...
 
 
 def task(
-    __func_or_none__: Optional[Union[Callable[P, T], Callable[P, Awaitable[T]]]] = None,
+    __func_or_none__: Optional[Union[Callable[P, Awaitable[T]], Callable[P, T]]] = None,
     *,
     name: Optional[str] = None,
     retry: Optional[RetryPolicy] = None,
 ) -> Union[
-    Callable[[Callable[P, T]], Callable[P, SyncAsyncFuture[T]]],
+    Callable[
+        [Union[Callable[P, Awaitable[T]], Callable[P, T]]],
+        Callable[P, SyncAsyncFuture[T]],
+    ],
     Callable[P, SyncAsyncFuture[T]],
 ]:
     """Define a LangGraph task using the `task` decorator.
@@ -345,7 +353,7 @@ class entrypoint:
         value: R
         """Value to return. A value will always be returned even if it is None."""
         save: S
-        """The value for the state for the next checkpoint. 
+        """The value for the state for the next checkpoint.
 
         A value will always be saved even if it is None.
         """

libs/langgraph/langgraph/graph/branch.py

@@ -0,0 +1,215 @@
+import asyncio
+from inspect import (
+    isfunction,
+    ismethod,
+    signature,
+)
+from types import FunctionType
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Hashable,
+    Literal,
+    NamedTuple,
+    Optional,
+    Sequence,
+    Type,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from langchain_core.runnables import (
+    Runnable,
+    RunnableConfig,
+    RunnableLambda,
+)
+
+from langgraph.constants import END, START
+from langgraph.errors import InvalidUpdateError
+from langgraph.pregel.write import ChannelWrite
+from langgraph.types import Send
+from langgraph.utils.runnable import (
+    RunnableCallable,
+)
+
+
+def _get_branch_path_input_schema(
+    path: Union[
+        Callable[..., Union[Hashable, list[Hashable]]],
+        Callable[..., Awaitable[Union[Hashable, list[Hashable]]]],
+        Runnable[Any, Union[Hashable, list[Hashable]]],
+    ],
+) -> Optional[Type[Any]]:
+    input = None
+    # detect input schema annotation in the branch callable
+    try:
+        callable_: Optional[
+            Union[
+                Callable[..., Union[Hashable, list[Hashable]]],
+                Callable[..., Awaitable[Union[Hashable, list[Hashable]]]],
+            ]
+        ] = None
+        if isinstance(path, (RunnableCallable, RunnableLambda)):
+            if isfunction(path.func) or ismethod(path.func):
+                callable_ = path.func
+            elif (callable_method := getattr(path.func, "__call__", None)) and ismethod(
+                callable_method
+            ):
+                callable_ = callable_method
+            elif isfunction(path.afunc) or ismethod(path.afunc):
+                callable_ = path.afunc
+            elif (
+                callable_method := getattr(path.afunc, "__call__", None)
+            ) and ismethod(callable_method):
+                callable_ = callable_method
+        elif callable(path):
+            callable_ = path
+
+        if callable_ is not None and (hints := get_type_hints(callable_)):
+            first_parameter_name = next(
+                iter(signature(cast(FunctionType, callable_)).parameters.keys())
+            )
+            if input_hint := hints.get(first_parameter_name):
+                if isinstance(input_hint, type) and get_type_hints(input_hint):
+                    input = input_hint
+    except (TypeError, StopIteration):
+        pass
+
+    return input
+
+
+class Branch(NamedTuple):
+    path: Runnable[Any, Union[Hashable, list[Hashable]]]
+    ends: Optional[dict[Hashable, str]]
+    then: Optional[str] = None
+    input_schema: Optional[Type[Any]] = None
+
+    @classmethod
+    def from_path(
+        cls,
+        path: Runnable[Any, Union[Hashable, list[Hashable]]],
+        path_map: Optional[Union[dict[Hashable, str], list[str]]],
+        then: Optional[str] = None,
+        infer_schema: bool = False,
+    ) -> "Branch":
+        # coerce path_map to a dictionary
+        path_map_: Optional[dict[Hashable, str]] = None
+        try:
+            if isinstance(path_map, dict):
+                path_map_ = path_map.copy()
+            elif isinstance(path_map, list):
+                path_map_ = {name: name for name in path_map}
+            else:
+                # find func
+                func: Optional[Callable] = None
+                if isinstance(path, (RunnableCallable, RunnableLambda)):
+                    func = path.func or path.afunc
+                if func is not None:
+                    # find callable method
+                    if (cal := getattr(path, "__call__", None)) and ismethod(cal):
+                        func = cal
+                    # get the return type
+                    if rtn_type := get_type_hints(func).get("return"):
+                        if get_origin(rtn_type) is Literal:
+                            path_map_ = {name: name for name in get_args(rtn_type)}
+        except Exception:
+            pass
+        # infer input schema
+        input_schema = _get_branch_path_input_schema(path) if infer_schema else None
+        # create branch
+        return cls(path=path, ends=path_map_, then=then, input_schema=input_schema)
+
+    def run(
+        self,
+        writer: Callable[
+            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
+        ],
+        reader: Optional[Callable[[RunnableConfig], Any]] = None,
+    ) -> RunnableCallable:
+        return ChannelWrite.register_writer(
+            RunnableCallable(
+                func=self._route,
+                afunc=self._aroute,
+                writer=writer,
+                reader=reader,
+                name=None,
+                trace=False,
+            )
+        )
+
+    def _route(
+        self,
+        input: Any,
+        config: RunnableConfig,
+        *,
+        reader: Optional[Callable[[RunnableConfig], Any]],
+        writer: Callable[
+            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
+        ],
+    ) -> Runnable:
+        if reader:
+            value = reader(config)
+            # passthrough additional keys from node to branch
+            # only doable when using dict states
+            if (
+                isinstance(value, dict)
+                and isinstance(input, dict)
+                and self.input_schema is None
+            ):
+                value = {**input, **value}
+        else:
+            value = input
+        result = self.path.invoke(value, config)
+        return self._finish(writer, input, result, config)
+
+    async def _aroute(
+        self,
+        input: Any,
+        config: RunnableConfig,
+        *,
+        reader: Optional[Callable[[RunnableConfig], Any]],
+        writer: Callable[
+            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
+        ],
+    ) -> Runnable:
+        if reader:
+            value = await asyncio.to_thread(reader, config)
+            # passthrough additional keys from node to branch
+            # only doable when using dict states
+            if (
+                isinstance(value, dict)
+                and isinstance(input, dict)
+                and self.input_schema is None
+            ):
+                value = {**input, **value}
+        else:
+            value = input
+        result = await self.path.ainvoke(value, config)
+        return self._finish(writer, input, result, config)
+
+    def _finish(
+        self,
+        writer: Callable[
+            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
+        ],
+        input: Any,
+        result: Any,
+        config: RunnableConfig,
+    ) -> Union[Runnable, Any]:
+        if not isinstance(result, (list, tuple)):
+            result = [result]
+        if self.ends:
+            destinations: Sequence[Union[Send, str]] = [
+                r if isinstance(r, Send) else self.ends[r] for r in result
+            ]
+        else:
+            destinations = cast(Sequence[Union[Send, str]], result)
+        if any(dest is None or dest == START for dest in destinations):
+            raise ValueError("Branch did not return a valid destination")
+        if any(p.node == END for p in destinations if isinstance(p, Send)):
+            raise InvalidUpdateError("Cannot send a packet to the END node")
+        return writer(destinations, config) or input

libs/langgraph/langgraph/graph/graph.py

@@ -1,4 +1,3 @@
-import asyncio
 import logging
 from collections import defaultdict
 from typing import (
@@ -6,15 +5,11 @@ from typing import (
     Awaitable,
     Callable,
     Hashable,
-    Literal,
     NamedTuple,
     Optional,
     Sequence,
     Union,
     cast,
-    get_args,
-    get_origin,
-    get_type_hints,
     overload,
 )
 
@@ -34,12 +29,12 @@ from langgraph.constants import (
     TAG_HIDDEN,
     Send,
 )
-from langgraph.errors import InvalidUpdateError
+from langgraph.graph.branch import Branch
 from langgraph.pregel import Channel, Pregel
 from langgraph.pregel.read import PregelNode
 from langgraph.pregel.write import ChannelWrite, ChannelWriteEntry
 from langgraph.types import All, Checkpointer
-from langgraph.utils.runnable import RunnableCallable, RunnableLike, coerce_to_runnable
+from langgraph.utils.runnable import RunnableLike, coerce_to_runnable
 
 logger = logging.getLogger(__name__)
 
@@ -50,95 +45,6 @@ class NodeSpec(NamedTuple):
     ends: Optional[Union[tuple[str, ...], dict[str, str]]] = EMPTY_SEQ
 
 
-class Branch(NamedTuple):
-    path: Runnable[Any, Union[Hashable, list[Hashable]]]
-    ends: Optional[dict[Hashable, str]]
-    then: Optional[str] = None
-
-    def run(
-        self,
-        writer: Callable[
-            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
-        ],
-        reader: Optional[Callable[[RunnableConfig], Any]] = None,
-    ) -> RunnableCallable:
-        return ChannelWrite.register_writer(
-            RunnableCallable(
-                func=self._route,
-                afunc=self._aroute,
-                writer=writer,
-                reader=reader,
-                name=None,
-                trace=False,
-            )
-        )
-
-    def _route(
-        self,
-        input: Any,
-        config: RunnableConfig,
-        *,
-        reader: Optional[Callable[[RunnableConfig], Any]],
-        writer: Callable[
-            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
-        ],
-    ) -> Runnable:
-        if reader:
-            value = reader(config)
-            # passthrough additional keys from node to branch
-            # only doable when using dict states
-            if isinstance(value, dict) and isinstance(input, dict):
-                value = {**input, **value}
-        else:
-            value = input
-        result = self.path.invoke(value, config)
-        return self._finish(writer, input, result, config)
-
-    async def _aroute(
-        self,
-        input: Any,
-        config: RunnableConfig,
-        *,
-        reader: Optional[Callable[[RunnableConfig], Any]],
-        writer: Callable[
-            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
-        ],
-    ) -> Runnable:
-        if reader:
-            value = await asyncio.to_thread(reader, config)
-            # passthrough additional keys from node to branch
-            # only doable when using dict states
-            if isinstance(value, dict) and isinstance(input, dict):
-                value = {**input, **value}
-        else:
-            value = input
-        result = await self.path.ainvoke(value, config)
-        return self._finish(writer, input, result, config)
-
-    def _finish(
-        self,
-        writer: Callable[
-            [Sequence[Union[str, Send]], RunnableConfig], Optional[ChannelWrite]
-        ],
-        input: Any,
-        result: Any,
-        config: RunnableConfig,
-    ) -> Union[Runnable, Any]:
-        if not isinstance(result, (list, tuple)):
-            result = [result]
-        if self.ends:
-            destinations: Sequence[Union[Send, str]] = [
-                r if isinstance(r, Send) else self.ends[r] for r in result
-            ]
-        else:
-            destinations = cast(Sequence[Union[Send, str]], result)
-        if any(dest is None or dest == START for dest in destinations):
-            raise ValueError("Branch did not return a valid destination")
-        if any(p.node == END for p in destinations if isinstance(p, Send)):
-            raise InvalidUpdateError("Cannot send a packet to the END node")
-        return writer(destinations, config) or input
-
-
 class Graph:
     def __init__(self) -> None:
         self.nodes: dict[str, NodeSpec] = {}
@@ -267,25 +173,7 @@ class Graph:
                 "Adding an edge to a graph that has already been compiled. This will "
                 "not be reflected in the compiled graph."
             )
-        # coerce path_map to a dictionary
-        try:
-            if isinstance(path_map, dict):
-                path_map_ = path_map.copy()
-            elif isinstance(path_map, list):
-                path_map_ = {name: name for name in path_map}
-            elif isinstance(path, Runnable):
-                path_map_ = None
-            elif rtn_type := get_type_hints(path.__call__).get(  # type: ignore[operator]
-                "return"
-            ) or get_type_hints(path).get("return"):
-                if get_origin(rtn_type) is Literal:
-                    path_map_ = {name: name for name in get_args(rtn_type)}
-                else:
-                    path_map_ = None
-            else:
-                path_map_ = None
-        except Exception:
-            path_map_ = None
+
         # find a name for the condition
         path = coerce_to_runnable(path, name=None, trace=True)
         name = path.name or "condition"
@@ -295,7 +183,7 @@ class Graph:
                 f"Branch with name `{path.name}` already exists for node " f"`{source}`"
             )
         # save it
-        self.branches[source][name] = Branch(path, path_map_, then)
+        self.branches[source][name] = Branch.from_path(path, path_map, then, False)
         return self
 
     def set_entry_point(self, key: str) -> Self:
@@ -584,7 +472,7 @@ class CompiledGraph(Pregel):
                 )
                 subgraph.trim_first_node()
                 subgraph.trim_last_node()
-                if len(subgraph.nodes) > 1:
+                if len(subgraph.nodes) >= 1:
                     e, s = graph.extend(subgraph, prefix=key)
                     if e is None:
                         raise ValueError(

libs/langgraph/langgraph/graph/state.py

@@ -7,7 +7,9 @@ from inspect import isclass, isfunction, ismethod, signature
 from types import FunctionType
 from typing import (
     Any,
+    Awaitable,
     Callable,
+    Hashable,
     Literal,
     NamedTuple,
     Optional,
@@ -40,7 +42,14 @@ from langgraph.errors import (
     ParentCommand,
     create_error_message,
 )
-from langgraph.graph.graph import END, START, Branch, CompiledGraph, Graph, Send
+from langgraph.graph.branch import Branch
+from langgraph.graph.graph import (
+    END,
+    START,
+    CompiledGraph,
+    Graph,
+    Send,
+)
 from langgraph.managed.base import (
     ChannelKeyPlaceholder,
     ChannelTypePlaceholder,
@@ -461,6 +470,57 @@ class StateGraph(Graph):
         self.waiting_edges.add((tuple(start_key), end_key))
         return self
 
+    def add_conditional_edges(
+        self,
+        source: str,
+        path: Union[
+            Callable[..., Union[Hashable, list[Hashable]]],
+            Callable[..., Awaitable[Union[Hashable, list[Hashable]]]],
+            Runnable[Any, Union[Hashable, list[Hashable]]],
+        ],
+        path_map: Optional[Union[dict[Hashable, str], list[str]]] = None,
+        then: Optional[str] = None,
+    ) -> Self:
+        """Add a conditional edge from the starting node to any number of destination nodes.
+
+        Args:
+            source (str): The starting node. This conditional edge will run when
+                exiting this node.
+            path (Union[Callable, Runnable]): The callable that determines the next
+                node or nodes. If not specifying `path_map` it should return one or
+                more nodes. If it returns END, the graph will stop execution.
+            path_map (Optional[dict[Hashable, str]]): Optional mapping of paths to node
+                names. If omitted the paths returned by `path` should be node names.
+            then (Optional[str]): The name of a node to execute after the nodes
+                selected by `path`.
+
+        Returns:
+            Self: The instance of the graph, allowing for method chaining.
+
+        Note: Without typehints on the `path` function's return value (e.g., `-> Literal["foo", "__end__"]:`)
+            or a path_map, the graph visualization assumes the edge could transition to any node in the graph.
+
+        """  # noqa: E501
+        if self.compiled:
+            logger.warning(
+                "Adding an edge to a graph that has already been compiled. This will "
+                "not be reflected in the compiled graph."
+            )
+
+        # find a name for the condition
+        path = coerce_to_runnable(path, name=None, trace=True)
+        name = path.name or "condition"
+        # validate the condition
+        if name in self.branches[source]:
+            raise ValueError(
+                f"Branch with name `{path.name}` already exists for node " f"`{source}`"
+            )
+        # save it
+        self.branches[source][name] = Branch.from_path(path, path_map, then, True)
+        if schema := self.branches[source][name].input_schema:
+            self._add_schema(schema)
+        return self
+
     def add_sequence(
         self,
         nodes: Sequence[Union[RunnableLike, tuple[str, RunnableLike]]],
@@ -566,6 +626,11 @@ class StateGraph(Graph):
         compiled = CompiledStateGraph(
             builder=self,
             config_type=self.config_schema,
+            input_model=self.input
+            if len(self.channels) > 1
+            and isclass(self.input)
+            and issubclass(self.input, (BaseModel, BaseModelV1))
+            else None,
             nodes={},
             channels={
                 **self.channels,
@@ -752,11 +817,7 @@ class CompiledStateGraph(CompiledGraph):
                 # read state keys and managed values
                 channels=(list(input_values) if is_single_input else input_values),
                 # coerce state dict to schema class (eg. pydantic model)
-                mapper=(
-                    None
-                    if is_single_input or issubclass(input_schema, dict)
-                    else partial(_coerce_state, input_schema)
-                ),
+                mapper=_pick_mapper(list(input_values), input_schema),
                 writers=[
                     # publish to this channel and state keys
                     ChannelWrite(
@@ -826,12 +887,12 @@ class CompiledStateGraph(CompiledGraph):
                     config, cast(Sequence[Union[Send, ChannelWriteEntry]], writes)
                 )
 
-        # attach branch publisher
-        schema = (
+        schema = branch.input_schema or (
             self.builder.nodes[start].input
             if start in self.builder.nodes
             else self.builder.schema
         )
+        # attach branch publisher
         self.nodes[start] |= branch.run(
             branch_writer,
             _get_state_reader(self.builder, schema) if with_reader else None,
@@ -871,14 +932,34 @@ def _get_state_reader(
         select=select[0] if select == ["__root__"] else select,
         fresh=True,
         # coerce state dict to schema class (eg. pydantic model)
-        mapper=(
-            None
-            if state_keys == ["__root__"] or issubclass(schema, dict)
-            else partial(_coerce_state, schema)
-        ),
+        mapper=_pick_mapper(state_keys, schema),
     )
 
 
+def _pick_mapper(
+    state_keys: Sequence[str], schema: Type[Any]
+) -> Optional[Callable[[Any], Any]]:
+    if state_keys == ["__root__"]:
+        return None
+    if issubclass(schema, dict):
+        return None
+    if issubclass(schema, BaseModel):
+        return partial(_coerce_state_pydantic, schema)
+    if issubclass(schema, BaseModelV1):
+        return partial(_coerce_state_pydantic_v1, schema)
+    return partial(_coerce_state, schema)
+
+
+def _coerce_state_pydantic(schema: Type[Any], input: dict[str, Any]) -> dict[str, Any]:
+    return schema.model_construct(**input)
+
+
+def _coerce_state_pydantic_v1(
+    schema: Type[Any], input: dict[str, Any]
+) -> dict[str, Any]:
+    return schema.construct(**input)
+
+
 def _coerce_state(schema: Type[Any], input: dict[str, Any]) -> dict[str, Any]:
     return schema(**input)
 

libs/langgraph/langgraph/pregel/__init__.py

@@ -18,6 +18,7 @@ from typing import (
     Type,
     Union,
     cast,
+    get_type_hints,
     overload,
 )
 from uuid import UUID, uuid5
@@ -119,7 +120,7 @@ from langgraph.utils.config import (
     recast_checkpoint_ns,
 )
 from langgraph.utils.fields import get_enhanced_type_hints
-from langgraph.utils.pydantic import create_model
+from langgraph.utils.pydantic import create_model, is_supported_by_pydantic
 from langgraph.utils.queue import AsyncQueue, SyncQueue  # type: ignore[attr-defined]
 
 WriteValue = Union[Callable[[Input], Output], Any]
@@ -495,6 +496,8 @@ class Pregel(PregelProtocol):
 
     config_type: Optional[Type[Any]] = None
 
+    input_model: Optional[Type[BaseModel]] = None
+
     config: Optional[RunnableConfig] = None
 
     name: str = "LangGraph"
@@ -518,6 +521,7 @@ class Pregel(PregelProtocol):
         store: Optional[BaseStore] = None,
         retry_policy: Optional[RetryPolicy] = None,
         config_type: Optional[Type[Any]] = None,
+        input_model: Optional[Type[BaseModel]] = None,
         config: Optional[RunnableConfig] = None,
         name: str = "LangGraph",
     ) -> None:
@@ -536,6 +540,7 @@ class Pregel(PregelProtocol):
         self.store = store
         self.retry_policy = retry_policy
         self.config_type = config_type
+        self.input_model = input_model
         self.config = config
         self.name = name
         if auto_validate:
@@ -609,6 +614,36 @@ class Pregel(PregelProtocol):
             ]
         ]
 
+    def config_schema(
+        self, *, include: Optional[Sequence[str]] = None
+    ) -> Type[BaseModel]:
+        # If the config type is not set explicitly, we will try to infer it.
+        # If the config type is provided, but isn't directly supported by pydantic
+        # (e.g., vanilla python class), we will also delegate to the parent class,
+        # which handles cases where Pydantic doesn't support the type.
+        if self.config_type is None or not is_supported_by_pydantic(self.config_type):
+            return super().config_schema(include=include)
+
+        include = include or []
+        fields = {
+            "configurable": (self.config_type, None),
+            **{
+                field_name: (field_type, None)
+                for field_name, field_type in get_type_hints(RunnableConfig).items()
+                if field_name in [i for i in include if i != "configurable"]
+            },
+        }
+        return create_model(self.get_name("Config"), field_definitions=fields)
+
+    def get_config_jsonschema(
+        self, *, include: Optional[Sequence[str]] = None
+    ) -> Dict[str, Any]:
+        schema = self.config_schema(include=include)
+        if hasattr(schema, "model_json_schema"):
+            return schema.model_json_schema()
+        else:
+            return schema.schema()
+
     @property
     def InputType(self) -> Any:
         if isinstance(self.input_channels, str):
@@ -619,6 +654,8 @@ class Pregel(PregelProtocol):
     def get_input_schema(
         self, config: Optional[RunnableConfig] = None
     ) -> Type[BaseModel]:
+        if self.input_model is not None:
+            return self.input_model
         config = merge_configs(self.config, config)
         if isinstance(self.input_channels, str):
             return super().get_input_schema(config)
@@ -634,7 +671,7 @@ class Pregel(PregelProtocol):
 
     def get_input_jsonschema(
         self, config: Optional[RunnableConfig] = None
-    ) -> Dict[All, Any]:
+    ) -> Dict[str, Any]:
         schema = self.get_input_schema(config)
         if hasattr(schema, "model_json_schema"):
             return schema.model_json_schema()
@@ -666,7 +703,7 @@ class Pregel(PregelProtocol):
 
     def get_output_jsonschema(
         self, config: Optional[RunnableConfig] = None
-    ) -> Dict[All, Any]:
+    ) -> Dict[str, Any]:
         schema = self.get_output_schema(config)
         if hasattr(schema, "model_json_schema"):
             return schema.model_json_schema()
@@ -1936,6 +1973,7 @@ class Pregel(PregelProtocol):
                 )
             with SyncPregelLoop(
                 input,
+                input_model=self.input_model,
                 stream=StreamProtocol(stream.put, stream_modes),
                 config=config,
                 store=store,
@@ -2226,6 +2264,7 @@ class Pregel(PregelProtocol):
                 )
             async with AsyncPregelLoop(
                 input,
+                input_model=self.input_model,
                 stream=StreamProtocol(stream.put_nowait, stream_modes),
                 config=config,
                 store=store,

libs/langgraph/langgraph/pregel/loop.py

@@ -2,7 +2,6 @@ import asyncio
 import concurrent.futures
 from collections import defaultdict, deque
 from contextlib import AsyncExitStack, ExitStack
-from dataclasses import replace
 from inspect import signature
 from types import TracebackType
 from typing import (
@@ -24,6 +23,7 @@ from typing import (
 
 from langchain_core.callbacks import AsyncParentRunManager, ParentRunManager
 from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel
 from typing_extensions import ParamSpec, Self
 
 from langgraph.channels.base import BaseChannel
@@ -55,6 +55,7 @@ from langgraph.constants import (
     ERROR,
     INPUT,
     INTERRUPT,
+    MISSING,
     NS_SEP,
     NULL_TASK_ID,
     PUSH,
@@ -67,7 +68,6 @@ from langgraph.errors import (
     EmptyInputError,
     GraphDelegate,
     GraphInterrupt,
-    ParentCommand,
 )
 from langgraph.managed.base import (
     ManagedValueMapping,
@@ -126,6 +126,7 @@ P = ParamSpec("P")
 
 INPUT_DONE = object()
 INPUT_RESUMING = object()
+INPUT_SHOULD_VALIDATE = object()
 SPECIAL_CHANNELS = (ERROR, INTERRUPT, SCHEDULED)
 
 
@@ -140,6 +141,7 @@ def DuplexStream(*streams: StreamProtocol) -> StreamProtocol:
 
 class PregelLoop(LoopProtocol):
     input: Optional[Any]
+    input_model: Optional[Type[BaseModel]]
     checkpointer: Optional[BaseCheckpointSaver]
     nodes: Mapping[str, PregelNode]
     specs: Mapping[str, Union[BaseChannel, ManagedValueSpec]]
@@ -203,6 +205,7 @@ class PregelLoop(LoopProtocol):
         interrupt_after: Union[All, Sequence[str]] = EMPTY_SEQ,
         interrupt_before: Union[All, Sequence[str]] = EMPTY_SEQ,
         manager: Union[None, AsyncParentRunManager, ParentRunManager] = None,
+        input_model: Optional[Type[BaseModel]] = None,
         debug: bool = False,
     ) -> None:
         super().__init__(
@@ -213,6 +216,7 @@ class PregelLoop(LoopProtocol):
             store=store,
         )
         self.input = input
+        self.input_model = input_model
         self.checkpointer = checkpointer
         self.nodes = nodes
         self.specs = specs
@@ -396,7 +400,7 @@ class PregelLoop(LoopProtocol):
         if self.status != "pending":
             raise RuntimeError("Cannot tick when status is no longer 'pending'")
 
-        if self.input not in (INPUT_DONE, INPUT_RESUMING):
+        if self.input not in (INPUT_DONE, INPUT_RESUMING, INPUT_SHOULD_VALIDATE):
             self._first(input_keys=input_keys)
         elif self.to_interrupt:
             # if we need to interrupt, do so
@@ -426,6 +430,13 @@ class PregelLoop(LoopProtocol):
             # apply writes to managed values
             for key, values in mv_writes.items():
                 self._update_mv(key, values)
+            # validate input if requested
+            if self.input is INPUT_SHOULD_VALIDATE:
+                self.input = INPUT_DONE
+                # validate
+                cast(Type[BaseModel], self.input_model)(
+                    **read_channels(self.channels, self.stream_keys)
+                )
             # produce values output
             self._emit(
                 "values", map_output_values, self.output_keys, writes, self.channels
@@ -566,7 +577,13 @@ class PregelLoop(LoopProtocol):
         is_resuming = bool(self.checkpoint["channel_versions"]) and bool(
             configurable.get(
                 CONFIG_KEY_RESUMING,
-                self.input is None or isinstance(self.input, Command),
+                self.input is None
+                or isinstance(self.input, Command)
+                or (
+                    not self.is_nested
+                    and self.config.get("metadata", {}).get("run_id")
+                    == self.checkpoint_metadata.get("run_id", MISSING)
+                ),
             )
         )
 
@@ -617,6 +634,8 @@ class PregelLoop(LoopProtocol):
             self._emit(
                 "values", map_output_values, self.output_keys, True, self.channels
             )
+            # set flag
+            self.input = INPUT_RESUMING
         # map inputs to channel updates
         elif input_writes := deque(map_input(input_keys, self.input)):
             # TODO shouldn't these writes be passed to put_writes too?
@@ -657,10 +676,19 @@ class PregelLoop(LoopProtocol):
             assert not mv_writes, "Can't write to SharedValues in graph input"
             # save input checkpoint
             self._put_checkpoint({"source": "input", "writes": dict(input_writes)})
+            # set flag
+            if (
+                self.input_model is not None
+                and not isinstance(self.input, self.input_model)
+                and not isinstance(self.stream_keys, str)
+            ):
+                self.input = INPUT_SHOULD_VALIDATE
+            else:
+                self.input = INPUT_DONE
         elif CONFIG_KEY_RESUMING not in configurable:
             raise EmptyInputError(f"Received no input for {input_keys}")
-        # done with input
-        self.input = INPUT_RESUMING if is_resuming else INPUT_DONE
+        else:
+            self.input = INPUT_DONE
         # update config
         if not self.is_nested:
             self.config = patch_configurable(
@@ -742,15 +770,6 @@ class PregelLoop(LoopProtocol):
         exc_value: Optional[BaseException],
         traceback: Optional[TracebackType],
     ) -> Optional[bool]:
-        # add current state to parent command
-        if isinstance(exc_value, ParentCommand):
-            cmd = exc_value.args[0]
-            state = (
-                [(self.output_keys, read_channels(self.channels, self.output_keys))]
-                if isinstance(self.output_keys, str)
-                else list(read_channels(self.channels, self.output_keys).items())
-            )
-            exc_value.args = (replace(cmd, update=[*state, *cmd._update_as_tuples()]),)
         # suppress interrupt
         suppress = isinstance(exc_value, GraphInterrupt) and not self.is_nested
         if suppress:
@@ -844,10 +863,12 @@ class SyncPregelLoop(PregelLoop, ContextManager):
         interrupt_before: Union[All, Sequence[str]] = EMPTY_SEQ,
         output_keys: Union[str, Sequence[str]] = EMPTY_SEQ,
         stream_keys: Union[str, Sequence[str]] = EMPTY_SEQ,
+        input_model: Optional[Type[BaseModel]] = None,
         debug: bool = False,
     ) -> None:
         super().__init__(
             input,
+            input_model=input_model,
             stream=stream,
             config=config,
             checkpointer=checkpointer,
@@ -983,10 +1004,12 @@ class AsyncPregelLoop(PregelLoop, AsyncContextManager):
         manager: Union[None, AsyncParentRunManager, ParentRunManager] = None,
         output_keys: Union[str, Sequence[str]] = EMPTY_SEQ,
         stream_keys: Union[str, Sequence[str]] = EMPTY_SEQ,
+        input_model: Optional[Type[BaseModel]] = None,
         debug: bool = False,
     ) -> None:
         super().__init__(
             input,
+            input_model=input_model,
             stream=stream,
             config=config,
             checkpointer=checkpointer,

libs/langgraph/langgraph/utils/pydantic.py

@@ -1,5 +1,9 @@
+import sys
+import typing
+from dataclasses import is_dataclass
 from typing import Any, Dict, Optional, Union
 
+import typing_extensions
 from pydantic import BaseModel
 from pydantic.v1 import BaseModel as BaseModelV1
 
@@ -35,3 +39,31 @@ def create_model(
             v1_kwargs["__root__"] = root
 
         return create_model(model_name, **v1_kwargs, **(field_definitions or {}))
+
+
+def is_supported_by_pydantic(type_: Any) -> bool:
+    """Check if a given "complex" type is supported by pydantic.
+
+    This will return False for primitive types like int, str, etc.
+
+    The check is meant for container types like dataclasses, TypedDicts, etc.
+    """
+    if is_dataclass(type_):
+        return True
+
+    # Pydantic does not support mixing .v1 and root namespaces, so
+    # we only check for BaseModel (not pydantic.v1.BaseModel).
+    if isinstance(type_, type) and issubclass(type_, BaseModel):
+        return True
+
+    if hasattr(type_, "__orig_bases__"):
+        for base in type_.__orig_bases__:
+            if base is typing_extensions.TypedDict:
+                return True
+            elif base is typing.TypedDict:  # noqa: TID251
+                # ignoring TID251 since it's OK to use typing.TypedDict in this case.
+                # Pydantic supports typing.TypedDict from Python 3.12
+                # For older versions, only typing_extensions.TypedDict is supported.
+                if sys.version_info >= (3, 12):
+                    return True
+    return False

libs/langgraph/poetry.lock

@@ -1324,19 +1324,19 @@ files = [
 
 [[package]]
 name = "langchain-core"
-version = "0.3.30"
+version = "0.3.44"
 description = "Building applications with LLMs through composability"
 optional = false
 python-versions = "<4.0,>=3.9"
 groups = ["main", "dev"]
 files = [
-    {file = "langchain_core-0.3.30-py3-none-any.whl", hash = "sha256:0a4c4e02fac5968b67fbb0142c00c2b976c97e45fce62c7ac9eb1636a6926493"},
-    {file = "langchain_core-0.3.30.tar.gz", hash = "sha256:0f1281b4416977df43baf366633ad18e96c5dcaaeae6fcb8a799f9889c853243"},
+    {file = "langchain_core-0.3.44-py3-none-any.whl", hash = "sha256:d989ce8bd62f1d07765acd575e6ec1254aec0cf7775aaea39fe4af8102377459"},
+    {file = "langchain_core-0.3.44.tar.gz", hash = "sha256:7c0a01e78360f007cbca448178fe7e032404068e6431dbe8ce905f84febbdfa5"},
 ]
 
 [package.dependencies]
 jsonpatch = ">=1.33,<2.0"
-langsmith = ">=0.1.125,<0.3"
+langsmith = ">=0.1.125,<0.4"
 packaging = ">=23.2,<25"
 pydantic = [
     {version = ">=2.5.2,<3.0.0", markers = "python_full_version < \"3.12.4\""},
@@ -1348,7 +1348,7 @@ typing-extensions = ">=4.7"
 
 [[package]]
 name = "langgraph-checkpoint"
-version = "2.0.16"
+version = "2.0.18"
 description = "Library with base interfaces for LangGraph checkpoint savers."
 optional = false
 python-versions = "^3.9.0,<4.0"
@@ -1366,7 +1366,7 @@ url = "../checkpoint"
 
 [[package]]
 name = "langgraph-checkpoint-postgres"
-version = "2.0.15"
+version = "2.0.16"
 description = "Library with a Postgres implementation of LangGraph checkpoint saver."
 optional = false
 python-versions = "^3.9.0,<4.0"
@@ -1386,7 +1386,7 @@ url = "../checkpoint-postgres"
 
 [[package]]
 name = "langgraph-checkpoint-sqlite"
-version = "2.0.5"
+version = "2.0.6"
 description = "Library with a SQLite implementation of LangGraph checkpoint saver."
 optional = false
 python-versions = "^3.9.0"
@@ -1404,7 +1404,7 @@ url = "../checkpoint-sqlite"
 
 [[package]]
 name = "langgraph-prebuilt"
-version = "0.1.1"
+version = "0.1.2"
 description = "Library with high-level APIs for creating and executing LangGraph agents and tools."
 optional = false
 python-versions = "^3.9.0,<4.0"
@@ -1422,7 +1422,7 @@ url = "../prebuilt"
 
 [[package]]
 name = "langgraph-sdk"
-version = "0.1.53"
+version = "0.1.55"
 description = "SDK for interacting with LangGraph API"
 optional = false
 python-versions = "^3.9.0,<4.0"

libs/langgraph/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph"
-version = "0.3.2"
+version = "0.3.7"
 description = "Building stateful, multi-actor applications with LLMs"
 authors = []
 license = "MIT"

libs/langgraph/tests/__snapshots__/test_large_cases.ambr

@@ -3116,8 +3116,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -3126,6 +3124,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -3141,8 +3141,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -3151,6 +3149,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -3166,8 +3166,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -3176,6 +3174,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -3191,8 +3191,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -3201,6 +3199,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -3216,8 +3216,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -3226,6 +3224,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -3241,8 +3241,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -3251,6 +3249,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2

libs/langgraph/tests/__snapshots__/test_large_cases_async.ambr

@@ -6,8 +6,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -16,6 +14,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -31,8 +31,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -41,6 +39,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -56,8 +56,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -66,6 +64,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -81,8 +81,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -91,6 +89,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -106,8 +106,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -116,6 +114,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2
@@ -131,8 +131,6 @@
   	__start__([<p>__start__</p>]):::first
   	router_node(router_node)
   	normal_llm_node(normal_llm_node)
-  	weather_graph_model_node(model_node)
-  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> router_node;
   	normal_llm_node --> __end__;
@@ -141,6 +139,8 @@
   	router_node -.-> weather_graph_model_node;
   	router_node -.-> __end__;
   	subgraph weather_graph
+  	weather_graph_model_node(model_node)
+  	weather_graph_weather_node(weather_node<hr/><small><em>__interrupt = before</em></small>)
   	weather_graph_model_node --> weather_graph_weather_node;
   	end
   	classDef default fill:#f2f0ff,line-height:1.2

libs/langgraph/tests/__snapshots__/test_pregel.ambr

@@ -1217,6 +1217,426 @@
     'type': 'object',
   })
 # ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[memory]
+  '''
+  graph TD;
+  	__start__ --> rewrite_query;
+  	analyzer_one --> retriever_one;
+  	qa --> __end__;
+  	retriever_one --> qa;
+  	retriever_two --> qa;
+  	rewrite_query --> analyzer_one;
+  	rewrite_query -.-> retriever_two;
+  
+  '''
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[memory].1
+  dict({
+    '$defs': dict({
+      'InnerObject': dict({
+        'properties': dict({
+          'yo': dict({
+            'title': 'Yo',
+            'type': 'integer',
+          }),
+        }),
+        'required': list([
+          'yo',
+        ]),
+        'title': 'InnerObject',
+        'type': 'object',
+      }),
+    }),
+    'properties': dict({
+      'inner': dict({
+        '$ref': '#/$defs/InnerObject',
+      }),
+      'query': dict({
+        'title': 'Query',
+        'type': 'string',
+      }),
+    }),
+    'required': list([
+      'query',
+      'inner',
+    ]),
+    'title': 'Input',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[memory].2
+  dict({
+    'properties': dict({
+      'answer': dict({
+        'title': 'Answer',
+        'type': 'string',
+      }),
+      'docs': dict({
+        'items': dict({
+          'type': 'string',
+        }),
+        'title': 'Docs',
+        'type': 'array',
+      }),
+    }),
+    'required': list([
+      'answer',
+      'docs',
+    ]),
+    'title': 'Output',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres]
+  '''
+  graph TD;
+  	__start__ --> rewrite_query;
+  	analyzer_one --> retriever_one;
+  	qa --> __end__;
+  	retriever_one --> qa;
+  	retriever_two --> qa;
+  	rewrite_query --> analyzer_one;
+  	rewrite_query -.-> retriever_two;
+  
+  '''
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres].1
+  dict({
+    '$defs': dict({
+      'InnerObject': dict({
+        'properties': dict({
+          'yo': dict({
+            'title': 'Yo',
+            'type': 'integer',
+          }),
+        }),
+        'required': list([
+          'yo',
+        ]),
+        'title': 'InnerObject',
+        'type': 'object',
+      }),
+    }),
+    'properties': dict({
+      'inner': dict({
+        '$ref': '#/$defs/InnerObject',
+      }),
+      'query': dict({
+        'title': 'Query',
+        'type': 'string',
+      }),
+    }),
+    'required': list([
+      'query',
+      'inner',
+    ]),
+    'title': 'Input',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres].2
+  dict({
+    'properties': dict({
+      'answer': dict({
+        'title': 'Answer',
+        'type': 'string',
+      }),
+      'docs': dict({
+        'items': dict({
+          'type': 'string',
+        }),
+        'title': 'Docs',
+        'type': 'array',
+      }),
+    }),
+    'required': list([
+      'answer',
+      'docs',
+    ]),
+    'title': 'Output',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_pipe]
+  '''
+  graph TD;
+  	__start__ --> rewrite_query;
+  	analyzer_one --> retriever_one;
+  	qa --> __end__;
+  	retriever_one --> qa;
+  	retriever_two --> qa;
+  	rewrite_query --> analyzer_one;
+  	rewrite_query -.-> retriever_two;
+  
+  '''
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_pipe].1
+  dict({
+    '$defs': dict({
+      'InnerObject': dict({
+        'properties': dict({
+          'yo': dict({
+            'title': 'Yo',
+            'type': 'integer',
+          }),
+        }),
+        'required': list([
+          'yo',
+        ]),
+        'title': 'InnerObject',
+        'type': 'object',
+      }),
+    }),
+    'properties': dict({
+      'inner': dict({
+        '$ref': '#/$defs/InnerObject',
+      }),
+      'query': dict({
+        'title': 'Query',
+        'type': 'string',
+      }),
+    }),
+    'required': list([
+      'query',
+      'inner',
+    ]),
+    'title': 'Input',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_pipe].2
+  dict({
+    'properties': dict({
+      'answer': dict({
+        'title': 'Answer',
+        'type': 'string',
+      }),
+      'docs': dict({
+        'items': dict({
+          'type': 'string',
+        }),
+        'title': 'Docs',
+        'type': 'array',
+      }),
+    }),
+    'required': list([
+      'answer',
+      'docs',
+    ]),
+    'title': 'Output',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_pool]
+  '''
+  graph TD;
+  	__start__ --> rewrite_query;
+  	analyzer_one --> retriever_one;
+  	qa --> __end__;
+  	retriever_one --> qa;
+  	retriever_two --> qa;
+  	rewrite_query --> analyzer_one;
+  	rewrite_query -.-> retriever_two;
+  
+  '''
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_pool].1
+  dict({
+    '$defs': dict({
+      'InnerObject': dict({
+        'properties': dict({
+          'yo': dict({
+            'title': 'Yo',
+            'type': 'integer',
+          }),
+        }),
+        'required': list([
+          'yo',
+        ]),
+        'title': 'InnerObject',
+        'type': 'object',
+      }),
+    }),
+    'properties': dict({
+      'inner': dict({
+        '$ref': '#/$defs/InnerObject',
+      }),
+      'query': dict({
+        'title': 'Query',
+        'type': 'string',
+      }),
+    }),
+    'required': list([
+      'query',
+      'inner',
+    ]),
+    'title': 'Input',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_pool].2
+  dict({
+    'properties': dict({
+      'answer': dict({
+        'title': 'Answer',
+        'type': 'string',
+      }),
+      'docs': dict({
+        'items': dict({
+          'type': 'string',
+        }),
+        'title': 'Docs',
+        'type': 'array',
+      }),
+    }),
+    'required': list([
+      'answer',
+      'docs',
+    ]),
+    'title': 'Output',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_shallow]
+  '''
+  graph TD;
+  	__start__ --> rewrite_query;
+  	analyzer_one --> retriever_one;
+  	qa --> __end__;
+  	retriever_one --> qa;
+  	retriever_two --> qa;
+  	rewrite_query --> analyzer_one;
+  	rewrite_query -.-> retriever_two;
+  
+  '''
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_shallow].1
+  dict({
+    '$defs': dict({
+      'InnerObject': dict({
+        'properties': dict({
+          'yo': dict({
+            'title': 'Yo',
+            'type': 'integer',
+          }),
+        }),
+        'required': list([
+          'yo',
+        ]),
+        'title': 'InnerObject',
+        'type': 'object',
+      }),
+    }),
+    'properties': dict({
+      'inner': dict({
+        '$ref': '#/$defs/InnerObject',
+      }),
+      'query': dict({
+        'title': 'Query',
+        'type': 'string',
+      }),
+    }),
+    'required': list([
+      'query',
+      'inner',
+    ]),
+    'title': 'Input',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[postgres_shallow].2
+  dict({
+    'properties': dict({
+      'answer': dict({
+        'title': 'Answer',
+        'type': 'string',
+      }),
+      'docs': dict({
+        'items': dict({
+          'type': 'string',
+        }),
+        'title': 'Docs',
+        'type': 'array',
+      }),
+    }),
+    'required': list([
+      'answer',
+      'docs',
+    ]),
+    'title': 'Output',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[sqlite]
+  '''
+  graph TD;
+  	__start__ --> rewrite_query;
+  	analyzer_one --> retriever_one;
+  	qa --> __end__;
+  	retriever_one --> qa;
+  	retriever_two --> qa;
+  	rewrite_query --> analyzer_one;
+  	rewrite_query -.-> retriever_two;
+  
+  '''
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[sqlite].1
+  dict({
+    '$defs': dict({
+      'InnerObject': dict({
+        'properties': dict({
+          'yo': dict({
+            'title': 'Yo',
+            'type': 'integer',
+          }),
+        }),
+        'required': list([
+          'yo',
+        ]),
+        'title': 'InnerObject',
+        'type': 'object',
+      }),
+    }),
+    'properties': dict({
+      'inner': dict({
+        '$ref': '#/$defs/InnerObject',
+      }),
+      'query': dict({
+        'title': 'Query',
+        'type': 'string',
+      }),
+    }),
+    'required': list([
+      'query',
+      'inner',
+    ]),
+    'title': 'Input',
+    'type': 'object',
+  })
+# ---
+# name: test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input[sqlite].2
+  dict({
+    'properties': dict({
+      'answer': dict({
+        'title': 'Answer',
+        'type': 'string',
+      }),
+      'docs': dict({
+        'items': dict({
+          'type': 'string',
+        }),
+        'title': 'Docs',
+        'type': 'array',
+      }),
+    }),
+    'required': list([
+      'answer',
+      'docs',
+    ]),
+    'title': 'Output',
+    'type': 'object',
+  })
+# ---
 # name: test_in_one_fan_out_state_graph_waiting_edge_via_branch[memory]
   '''
   graph TD;
@@ -1302,13 +1722,13 @@
   	__start__([<p>__start__</p>]):::first
   	uno(uno)
   	dos(dos)
-  	subgraph_one(one)
-  	subgraph_two(two)
-  	subgraph_three(three)
   	__start__ --> uno;
   	uno -.-> dos;
   	uno -.-> subgraph_one;
   	subgraph subgraph
+  	subgraph_one(one)
+  	subgraph_two(two)
+  	subgraph_three(three)
   	subgraph_one -.-> subgraph_two;
   	subgraph_one -.-> subgraph_three;
   	end
@@ -1332,12 +1752,14 @@
   %%{init: {'flowchart': {'curve': 'linear'}}}%%
   graph TD;
   	__start__([<p>__start__</p>]):::first
-  	inner(inner)
   	side(side)
   	__end__([<p>__end__</p>]):::last
-  	__start__ --> inner;
-  	inner --> side;
+  	__start__ --> inner_up;
+  	inner_up --> side;
   	side --> __end__;
+  	subgraph inner
+  	inner_up(up)
+  	end
   	classDef default fill:#f2f0ff,line-height:1.2
   	classDef first fill-opacity:0
   	classDef last fill:#bfb6fc
@@ -1475,10 +1897,6 @@
   graph TD;
   	__start__([<p>__start__</p>]):::first
   	tool_one(tool_one)
-  	tool_two___start__(<p>__start__</p>)
-  	tool_two_tool_two_slow(tool_two_slow)
-  	tool_two_tool_two_fast(tool_two_fast)
-  	tool_two___end__(<p>__end__</p>)
   	tool_three(tool_three)
   	__end__([<p>__end__</p>]):::last
   	__start__ -.-> tool_one;
@@ -1488,6 +1906,10 @@
   	__start__ -.-> tool_three;
   	tool_three --> __end__;
   	subgraph tool_two
+  	tool_two___start__(<p>__start__</p>)
+  	tool_two_tool_two_slow(tool_two_slow)
+  	tool_two_tool_two_fast(tool_two_fast)
+  	tool_two___end__(<p>__end__</p>)
   	tool_two___start__ -.-> tool_two_tool_two_slow;
   	tool_two_tool_two_slow --> tool_two___end__;
   	tool_two___start__ -.-> tool_two_tool_two_fast;
@@ -1528,7 +1950,7 @@
   '''
 # ---
 # name: test_state_graph_w_config_inherited_state_keys
-  '{"$defs": {"Configurable": {"properties": {"tools": {"default": null, "items": {"type": "string"}, "title": "Tools", "type": "array"}}, "title": "Configurable", "type": "object"}}, "properties": {"configurable": {"$ref": "#/$defs/Configurable", "default": null}}, "title": "LangGraphConfig", "type": "object"}'
+  '{"$defs": {"Config": {"properties": {"tools": {"items": {"type": "string"}, "title": "Tools", "type": "array"}}, "title": "Config", "type": "object"}}, "properties": {"configurable": {"$ref": "#/$defs/Config", "default": null}}, "title": "LangGraphConfig", "type": "object"}'
 # ---
 # name: test_state_graph_w_config_inherited_state_keys.1
   '{"$defs": {"AgentAction": {"description": "Represents a request to execute an action by an agent.\\n\\nThe action consists of the name of the tool to execute and the input to pass\\nto the tool. The log is used to pass along extra information about the action.", "properties": {"tool": {"title": "Tool", "type": "string"}, "tool_input": {"anyOf": [{"type": "string"}, {"type": "object"}], "title": "Tool Input"}, "log": {"title": "Log", "type": "string"}, "type": {"const": "AgentAction", "default": "AgentAction", "enum": ["AgentAction"], "title": "Type", "type": "string"}}, "required": ["tool", "tool_input", "log"], "title": "AgentAction", "type": "object"}, "AgentFinish": {"description": "Final return value of an ActionAgent.\\n\\nAgents return an AgentFinish when they have reached a stopping condition.", "properties": {"return_values": {"title": "Return Values", "type": "object"}, "log": {"title": "Log", "type": "string"}, "type": {"const": "AgentFinish", "default": "AgentFinish", "enum": ["AgentFinish"], "title": "Type", "type": "string"}}, "required": ["return_values", "log"], "title": "AgentFinish", "type": "object"}}, "properties": {"input": {"title": "Input", "type": "string"}, "agent_outcome": {"anyOf": [{"$ref": "#/$defs/AgentAction"}, {"$ref": "#/$defs/AgentFinish"}, {"type": "null"}], "default": null, "title": "Agent Outcome"}, "intermediate_steps": {"default": null, "items": {"maxItems": 2, "minItems": 2, "prefixItems": [{"$ref": "#/$defs/AgentAction"}, {"type": "string"}], "type": "array"}, "title": "Intermediate Steps", "type": "array"}}, "required": ["input"], "title": "LangGraphInput", "type": "object"}'
@@ -1542,24 +1964,24 @@
   graph TD;
   	__start__([<p>__start__</p>]):::first
   	gp_one(gp_one)
-  	gp_two___start__(<p>__start__</p>)
-  	gp_two_p_one(p_one)
-  	gp_two_p_two___start__(<p>__start__</p>)
-  	gp_two_p_two_c_one(c_one)
-  	gp_two_p_two_c_two(c_two)
-  	gp_two_p_two___end__(<p>__end__</p>)
-  	gp_two___end__(<p>__end__</p>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> gp_one;
   	gp_two___end__ --> gp_one;
   	gp_one -. &nbsp;0&nbsp; .-> gp_two___start__;
   	gp_one -. &nbsp;1&nbsp; .-> __end__;
   	subgraph gp_two
+  	gp_two___start__(<p>__start__</p>)
+  	gp_two_p_one(p_one)
+  	gp_two___end__(<p>__end__</p>)
   	gp_two___start__ --> gp_two_p_one;
   	gp_two_p_two___end__ --> gp_two_p_one;
   	gp_two_p_one -. &nbsp;0&nbsp; .-> gp_two_p_two___start__;
   	gp_two_p_one -. &nbsp;1&nbsp; .-> gp_two___end__;
   	subgraph p_two
+  	gp_two_p_two___start__(<p>__start__</p>)
+  	gp_two_p_two_c_one(c_one)
+  	gp_two_p_two_c_two(c_two)
+  	gp_two_p_two___end__(<p>__end__</p>)
   	gp_two_p_two___start__ --> gp_two_p_two_c_one;
   	gp_two_p_two_c_two --> gp_two_p_two_c_one;
   	gp_two_p_two_c_one -. &nbsp;0&nbsp; .-> gp_two_p_two_c_two;
@@ -1578,16 +2000,16 @@
   graph TD;
   	__start__([<p>__start__</p>]):::first
   	p_one(p_one)
-  	p_two___start__(<p>__start__</p>)
-  	p_two_c_one(c_one)
-  	p_two_c_two(c_two)
-  	p_two___end__(<p>__end__</p>)
   	__end__([<p>__end__</p>]):::last
   	__start__ --> p_one;
   	p_two___end__ --> p_one;
   	p_one -. &nbsp;0&nbsp; .-> p_two___start__;
   	p_one -. &nbsp;1&nbsp; .-> __end__;
   	subgraph p_two
+  	p_two___start__(<p>__start__</p>)
+  	p_two_c_one(c_one)
+  	p_two_c_two(c_two)
+  	p_two___end__(<p>__end__</p>)
   	p_two___start__ --> p_two_c_one;
   	p_two_c_two --> p_two_c_one;
   	p_two_c_one -. &nbsp;0&nbsp; .-> p_two_c_two;

libs/langgraph/tests/test_large_cases.py

@@ -2827,7 +2827,7 @@ def test_state_graph_packets(
         }
 
     # Define decision-making logic
-    def should_continue(data: AgentState) -> str:
+    def should_continue(data: dict) -> str:
         assert isinstance(data["session"], httpx.Client)
         assert (
             data["something_extra"] == "hi there"

libs/langgraph/tests/test_pregel.py

@@ -10,7 +10,7 @@ import warnings
 from collections import Counter, deque
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from random import randrange
 from typing import (
     Annotated,
@@ -275,6 +275,61 @@ def test_checkpoint_errors() -> None:
         graph.invoke("", {"configurable": {"thread_id": "thread-1"}})
 
 
+def test_config_json_schema() -> None:
+    """Test that config json schema is generated properly."""
+    chain = Channel.subscribe_to("input") | Channel.write_to("output")
+
+    @dataclass
+    class Foo:
+        x: int
+        y: str = field(default="foo")
+
+    app = Pregel(
+        nodes={
+            "one": chain,
+        },
+        channels={
+            "ephemeral": EphemeralValue(Any),
+            "input": LastValue(int),
+            "output": LastValue(int),
+        },
+        input_channels=["input", "ephemeral"],
+        output_channels="output",
+        config_type=Foo,
+    )
+
+    assert app.get_config_jsonschema() == {
+        "$defs": {
+            "Foo": {
+                "properties": {
+                    "x": {
+                        "title": "X",
+                        "type": "integer",
+                    },
+                    "y": {
+                        "default": "foo",
+                        "title": "Y",
+                        "type": "string",
+                    },
+                },
+                "required": [
+                    "x",
+                ],
+                "title": "Foo",
+                "type": "object",
+            },
+        },
+        "properties": {
+            "configurable": {
+                "$ref": "#/$defs/Foo",
+                "default": None,
+            },
+        },
+        "title": "LangGraphConfig",
+        "type": "object",
+    }
+
+
 def test_node_schemas_custom_output() -> None:
     class State(TypedDict):
         hello: str
@@ -1444,7 +1499,7 @@ def test_imp_task(request: pytest.FixtureRequest, checkpointer_name: str) -> Non
     checkpointer = request.getfixturevalue(f"checkpointer_{checkpointer_name}")
     mapper_calls = 0
 
-    class Config:
+    class Configurable:
         model: str
 
     @task()
@@ -1454,7 +1509,7 @@ def test_imp_task(request: pytest.FixtureRequest, checkpointer_name: str) -> Non
         time.sleep(input / 100)
         return str(input) * 2
 
-    @entrypoint(checkpointer=checkpointer, config_schema=Config)
+    @entrypoint(checkpointer=checkpointer, config_schema=Configurable)
     def graph(input: list[int]) -> list[str]:
         futures = [mapper(i) for i in input]
         mapped = [f.result() for f in futures]
@@ -2839,6 +2894,139 @@ def test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic2(
         }
 
 
+@pytest.mark.parametrize("checkpointer_name", ALL_CHECKPOINTERS_SYNC)
+def test_in_one_fan_out_state_graph_waiting_edge_custom_state_class_pydantic_input(
+    snapshot: SnapshotAssertion,
+    mocker: MockerFixture,
+    request: pytest.FixtureRequest,
+    checkpointer_name: str,
+) -> None:
+    from pydantic import BaseModel
+
+    checkpointer = request.getfixturevalue(f"checkpointer_{checkpointer_name}")
+
+    def sorted_add(
+        x: list[str], y: Union[list[str], list[tuple[str, str]]]
+    ) -> list[str]:
+        if isinstance(y[0], tuple):
+            for rem, _ in y:
+                x.remove(rem)
+            y = [t[1] for t in y]
+        return sorted(operator.add(x, y))
+
+    class InnerObject(BaseModel):
+        yo: int
+
+    class QueryModel(BaseModel):
+        query: str
+
+    class State(QueryModel):
+        inner: InnerObject
+        answer: Optional[str] = None
+        docs: Annotated[list[str], sorted_add]
+
+    class StateUpdate(BaseModel):
+        query: Optional[str] = None
+        answer: Optional[str] = None
+        docs: Optional[list[str]] = None
+
+    class Input(QueryModel):
+        inner: InnerObject
+
+    class Output(BaseModel):
+        answer: str
+        docs: list[str]
+
+    def rewrite_query(data: State) -> State:
+        return {"query": f"query: {data.query}"}
+
+    def analyzer_one(data: State) -> State:
+        return StateUpdate(query=f"analyzed: {data.query}")
+
+    def retriever_one(data: State) -> State:
+        return {"docs": ["doc1", "doc2"]}
+
+    def retriever_two(data: State) -> State:
+        time.sleep(0.1)
+        return {"docs": ["doc3", "doc4"]}
+
+    def qa(data: State) -> State:
+        return {"answer": ",".join(data.docs)}
+
+    def decider(data: State) -> str:
+        assert isinstance(data, State)
+        return "retriever_two"
+
+    workflow = StateGraph(State, input=Input, output=Output)
+
+    workflow.add_node("rewrite_query", rewrite_query)
+    workflow.add_node("analyzer_one", analyzer_one)
+    workflow.add_node("retriever_one", retriever_one)
+    workflow.add_node("retriever_two", retriever_two)
+    workflow.add_node("qa", qa)
+
+    workflow.set_entry_point("rewrite_query")
+    workflow.add_edge("rewrite_query", "analyzer_one")
+    workflow.add_edge("analyzer_one", "retriever_one")
+    workflow.add_conditional_edges(
+        "rewrite_query", decider, {"retriever_two": "retriever_two"}
+    )
+    workflow.add_edge(["retriever_one", "retriever_two"], "qa")
+    workflow.set_finish_point("qa")
+
+    app = workflow.compile()
+
+    assert app.invoke(
+        Input(query="what is weather in sf", inner=InnerObject(yo=1))
+    ) == {
+        "docs": ["doc1", "doc2", "doc3", "doc4"],
+        "answer": "doc1,doc2,doc3,doc4",
+    }
+
+    assert [
+        *app.stream(Input(query="what is weather in sf", inner=InnerObject(yo=1)))
+    ] == [
+        {"rewrite_query": {"query": "query: what is weather in sf"}},
+        {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
+        {"retriever_two": {"docs": ["doc3", "doc4"]}},
+        {"retriever_one": {"docs": ["doc1", "doc2"]}},
+        {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
+    ]
+
+    app_w_interrupt = workflow.compile(
+        checkpointer=checkpointer,
+        interrupt_after=["retriever_one"],
+    )
+    config = {"configurable": {"thread_id": "1"}}
+
+    assert [
+        c
+        for c in app_w_interrupt.stream(
+            Input(query="what is weather in sf", inner=InnerObject(yo=1)), config
+        )
+    ] == [
+        {"rewrite_query": {"query": "query: what is weather in sf"}},
+        {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
+        {"retriever_two": {"docs": ["doc3", "doc4"]}},
+        {"retriever_one": {"docs": ["doc1", "doc2"]}},
+        {"__interrupt__": ()},
+    ]
+
+    assert [c for c in app_w_interrupt.stream(None, config)] == [
+        {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
+    ]
+
+    assert app_w_interrupt.update_state(
+        config, {"docs": ["doc5"]}, as_node="rewrite_query"
+    ) == {
+        "configurable": {
+            "thread_id": "1",
+            "checkpoint_id": AnyStr(),
+            "checkpoint_ns": "",
+        }
+    }
+
+
 @pytest.mark.parametrize("checkpointer_name", ALL_CHECKPOINTERS_SYNC)
 def test_in_one_fan_out_state_graph_waiting_edge_plus_regular(
     request: pytest.FixtureRequest, checkpointer_name: str
@@ -2905,14 +3093,24 @@ def test_in_one_fan_out_state_graph_waiting_edge_plus_regular(
         "answer": "doc1,doc2,doc3,doc4",
     }
 
-    assert [*app.stream({"query": "what is weather in sf"})] == [
-        {"rewrite_query": {"query": "query: what is weather in sf"}},
-        {"qa": {"answer": ""}},
-        {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
-        {"retriever_two": {"docs": ["doc3", "doc4"]}},
-        {"retriever_one": {"docs": ["doc1", "doc2"]}},
-        {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
-    ]
+    assert [*app.stream({"query": "what is weather in sf"})] in (
+        [
+            {"rewrite_query": {"query": "query: what is weather in sf"}},
+            {"qa": {"answer": ""}},
+            {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
+            {"retriever_two": {"docs": ["doc3", "doc4"]}},
+            {"retriever_one": {"docs": ["doc1", "doc2"]}},
+            {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
+        ],
+        [
+            {"rewrite_query": {"query": "query: what is weather in sf"}},
+            {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
+            {"qa": {"answer": ""}},
+            {"retriever_two": {"docs": ["doc3", "doc4"]}},
+            {"retriever_one": {"docs": ["doc1", "doc2"]}},
+            {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
+        ],
+    )
 
     app_w_interrupt = workflow.compile(
         checkpointer=checkpointer,
@@ -4883,13 +5081,6 @@ def test_parent_command(request: pytest.FixtureRequest, checkpointer_name: str)
             "source": "loop",
             "writes": {
                 "alice": {
-                    "messages": [
-                        _AnyIdHumanMessage(
-                            content="get user name",
-                            additional_kwargs={},
-                            response_metadata={},
-                        ),
-                    ],
                     "user_name": "Meow",
                 }
             },
@@ -6229,151 +6420,6 @@ def test_multiple_subgraphs_checkpointer(
     ]
 
 
-def test_merging_updates_command_parent():
-    # simple reducer
-    def append_unique(left, right):
-        combined = list(left)
-        for item in right:
-            if item in combined:
-                continue
-            else:
-                combined.append(item)
-        return combined
-
-    class State(TypedDict):
-        foo: str
-        bar: Annotated[list[str], append_unique]
-
-    # Define subgraph
-    def subgraph_node_1(state: State):
-        return Command(
-            goto="subgraph_node_2",
-            update={
-                "foo": "foo",
-                "bar": ["subgraph_node_1"],
-            },
-        )
-
-    def subgraph_node_2(state: State):
-        return Command(
-            goto="node_3",
-            update={"bar": ["subgraph_node_2"]},
-            graph=Command.PARENT,
-        )
-
-    subgraph_builder = StateGraph(State)
-    subgraph_builder.add_node(subgraph_node_1)
-    subgraph_builder.add_node(subgraph_node_2)
-    subgraph_builder.add_edge(START, "subgraph_node_1")
-
-    # Define main graph
-    def node_1(state: State):
-        return Command(
-            goto="node_2",
-            update={"bar": ["node_1"]},
-        )
-
-    def node_3(state: State, store):
-        return Command(
-            update={"bar": ["node_3"]},
-        )
-
-    main_builder = StateGraph(State)
-    main_builder.add_node("node_1", node_1)
-    main_builder.add_node("node_2", subgraph_builder.compile())
-    main_builder.add_node("node_3", node_3)
-    main_builder.add_edge(START, "node_1")
-    main_builder.add_edge("node_2", "node_3")
-    main_graph = main_builder.compile()
-
-    assert main_graph.invoke({"foo": ""}) == {
-        "foo": "foo",
-        "bar": ["node_1", "subgraph_node_1", "subgraph_node_2", "node_3"],
-    }
-
-    assert list(
-        main_graph.stream({"foo": ""}, stream_mode="updates", subgraphs=True)
-    ) == [
-        ((), {"node_1": {"bar": ["node_1"]}}),
-        (
-            (AnyStr("node_2:"),),
-            {"subgraph_node_1": {"foo": "foo", "bar": ["subgraph_node_1"]}},
-        ),
-        (
-            (),
-            {
-                "node_2": [
-                    {"foo": "foo"},
-                    {"bar": ["node_1", "subgraph_node_1"]},
-                    {"bar": ["subgraph_node_2"]},
-                ]
-            },
-        ),
-        ((), {"node_3": {"bar": ["node_3"]}}),
-    ]
-
-
-def test_merging_non_overlapping_updates_command_parent():
-    # simple reducer
-    def append_unique(left, right):
-        combined = list(left)
-        for item in right:
-            if item in combined:
-                continue
-            else:
-                combined.append(item)
-        return combined
-
-    class State(TypedDict):
-        foo: Annotated[list, append_unique]
-
-    # Define subgraph
-    def subgraph_node_1(state: State):
-        return Command(
-            goto="subgraph_node_2",
-            update={
-                "foo": ["bar"],
-                "bar": ["subgraph_node_1"],
-            },
-        )
-
-    def subgraph_node_2(state: State):
-        return Command(
-            goto="node_3",
-            update={"bar": ["subgraph_node_2"]},
-            graph=Command.PARENT,
-        )
-
-    subgraph_builder = StateGraph(State)
-    subgraph_builder.add_node(subgraph_node_1)
-    subgraph_builder.add_node(subgraph_node_2)
-    subgraph_builder.add_edge(START, "subgraph_node_1")
-
-    # Define main graph
-    def node_1(state: State):
-        return Command(
-            goto="node_2",
-            update={"foo": ["foo"]},
-        )
-
-    def node_3(state: State, store):
-        return Command(
-            update={"foo": ["baz"]},
-        )
-
-    main_builder = StateGraph(State)
-    main_builder.add_node("node_1", node_1)
-    main_builder.add_node("node_2", subgraph_builder.compile())
-    main_builder.add_node("node_3", node_3)
-    main_builder.add_edge(START, "node_1")
-    main_builder.add_edge("node_2", "node_3")
-    main_graph = main_builder.compile()
-
-    assert main_graph.invoke({"foo": []}) == {
-        "foo": ["foo", "bar", "baz"],
-    }
-
-
 def test_entrypoint_output_schema_with_return_and_save() -> None:
     """Test output schema inference with entrypoint.final."""
 

libs/langgraph/tests/test_pregel_async.py

@@ -6148,13 +6148,6 @@ async def test_parent_command(checkpointer_name: str) -> None:
                 "source": "loop",
                 "writes": {
                     "alice": {
-                        "messages": [
-                            _AnyIdHumanMessage(
-                                content="get user name",
-                                additional_kwargs={},
-                                response_metadata={},
-                            ),
-                        ],
                         "user_name": "Meow",
                     }
                 },
@@ -7704,3 +7697,56 @@ async def test_interrupt_subgraph_reenter_checkpointer_true(
         }
         # confirm that we preserve the state values from the previous invocation
         assert bar_values == [None, "barbaz", "quxbaz"]
+
+
+@NEEDS_CONTEXTVARS
+async def test_handles_multiple_interrupts_from_tasks() -> None:
+    @task
+    async def add_participant(name: str) -> str:
+        feedback = interrupt(f"Hey do you want to add {name}?")
+
+        if feedback is False:
+            return f"The user changed their mind and doesn't want to add {name}!"
+
+        if feedback is True:
+            return f"Added {name}!"
+
+        raise ValueError("Invalid feedback")
+
+    @entrypoint(checkpointer=MemorySaver())
+    async def program(_state: Any) -> list[str]:
+        first = await add_participant("James")
+        second = await add_participant("Will")
+        return [first, second]
+
+    config = {"configurable": {"thread_id": "1"}}
+
+    result = await program.ainvoke("this is ignored", config=config)
+    assert result is None
+
+    state = await program.aget_state(config=config)
+    assert len(state.tasks[0].interrupts) == 1
+    task_interrupt = state.tasks[0].interrupts[0]
+    assert task_interrupt.resumable is True
+    assert len(task_interrupt.ns) == 2
+    assert task_interrupt.ns[0].startswith("program:")
+    assert task_interrupt.ns[1].startswith("add_participant:")
+    assert task_interrupt.value == "Hey do you want to add James?"
+
+    result = await program.ainvoke(Command(resume=True), config=config)
+    assert result is None
+
+    state = await program.aget_state(config=config)
+    assert len(state.tasks[0].interrupts) == 1
+    task_interrupt = state.tasks[0].interrupts[0]
+    assert task_interrupt.resumable is True
+    assert len(task_interrupt.ns) == 2
+    assert task_interrupt.ns[0].startswith("program:")
+    assert task_interrupt.ns[1].startswith("add_participant:")
+    assert task_interrupt.value == "Hey do you want to add Will?"
+
+    result = await program.ainvoke(Command(resume=True), config=config)
+    assert result is not None
+    assert len(result) == 2
+    assert result[0] == "Added James!"
+    assert result[1] == "Added Will!"

libs/langgraph/tests/test_pydantic.py

@@ -0,0 +1,43 @@
+import sys
+import typing
+
+import pydantic
+import typing_extensions
+
+from langgraph.utils.pydantic import is_supported_by_pydantic
+
+
+def test_is_supported_by_pydantic() -> None:
+    """Test if types are supported by pydantic."""
+
+    class TypedDictExtensions(typing_extensions.TypedDict):
+        x: int
+
+    assert is_supported_by_pydantic(TypedDictExtensions) is True
+
+    class VanillaClass:
+        x: int
+
+    assert is_supported_by_pydantic(VanillaClass) is False
+
+    class BuiltinTypedDict(typing.TypedDict):  # noqa: TID251
+        x: int
+
+    if sys.version_info >= (3, 12):
+        assert is_supported_by_pydantic(BuiltinTypedDict) is True
+    else:
+        assert is_supported_by_pydantic(BuiltinTypedDict) is False
+
+    class PydanticModel(pydantic.BaseModel):
+        x: int
+
+    assert is_supported_by_pydantic(PydanticModel) is True
+
+    if hasattr(pydantic, "v1"):
+
+        class PydanticModelV1(pydantic.v1.BaseModel):
+            x: int
+
+        assert is_supported_by_pydantic(PydanticModelV1) is False
+
+    assert is_supported_by_pydantic(int) is False

libs/langgraph/tests/test_state.py

@@ -1,4 +1,5 @@
 import inspect
+import operator
 import warnings
 from dataclasses import dataclass, field
 from typing import Annotated as Annotated2
@@ -328,3 +329,74 @@ def test__get_node_name() -> None:
 
     # class method
     assert _get_node_name(MyClass().class_method) == "class_method"
+
+
+def test_input_schema_conditional_edge():
+    class OverallState(TypedDict):
+        foo: Annotated[int, operator.add]
+        bar: str
+
+    class PrivateState(TypedDict):
+        baz: str
+
+    builder = StateGraph(OverallState)
+
+    def node_1(state: OverallState):
+        return {"foo": 1, "baz": "bar"}
+
+    def node_2(state: PrivateState):
+        return {"foo": 1, "bar": state["baz"], "something_else": "meow"}
+
+    def node_3(state: OverallState):
+        return {"foo": 1}
+
+    def router(state: OverallState):
+        assert state == {"foo": 2, "bar": "bar"}
+        if state["foo"] == 2:
+            return "node_3"
+        else:
+            return "__end__"
+
+    builder.add_node(node_1)
+    builder.add_node(node_2)
+    builder.add_node(node_3)
+    builder.add_conditional_edges("node_2", router)
+    builder.add_edge("__start__", "node_1")
+    builder.add_edge("node_1", "node_2")
+    graph = builder.compile()
+    assert graph.invoke({"foo": 0}) == {"foo": 3, "bar": "bar"}
+
+
+def test_private_input_schema_conditional_edge():
+    class OverallState(TypedDict):
+        foo: Annotated[int, operator.add]
+        bar: str
+
+    class RouterState(TypedDict):
+        baz: str
+
+    class Node2State(TypedDict):
+        foo: Annotated[int, operator.add]
+        baz: str
+
+    builder = StateGraph(OverallState)
+
+    def node_1(state: OverallState):
+        return {"foo": 1, "baz": "meow"}
+
+    def node_2(state: Node2State):
+        return {"foo": 1, "bar": state["baz"]}
+
+    def router(state: RouterState):
+        assert state == {"baz": "meow"}
+        if state["baz"] == "meow":
+            return "node_2"
+        else:
+            return "__end__"
+
+    builder.add_node(node_1)
+    builder.add_node(node_2)
+    builder.add_conditional_edges("node_1", router)
+    builder.add_edge("__start__", "node_1")
+    graph = builder.compile()
+    assert graph.invoke({"foo": 0}) == {"foo": 2, "bar": "meow"}

libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py

@@ -10,6 +10,7 @@ from typing import (
     TypeVar,
     Union,
     cast,
+    get_type_hints,
 )
 
 from langchain_core.language_models import (
@@ -22,6 +23,7 @@ from langchain_core.runnables import (
     Runnable,
     RunnableBinding,
     RunnableConfig,
+    RunnableSequence,
 )
 from langchain_core.tools import BaseTool
 from pydantic import BaseModel
@@ -56,13 +58,27 @@ class AgentState(TypedDict):
     remaining_steps: RemainingSteps
 
 
+class AgentStatePydantic(BaseModel):
+    """The state of the agent."""
+
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+
+    remaining_steps: RemainingSteps = 25
+
+
 class AgentStateWithStructuredResponse(AgentState):
     """The state of the agent with a structured response."""
 
     structured_response: StructuredResponse
 
 
-StateSchema = TypeVar("StateSchema", bound=AgentState)
+class AgentStateWithStructuredResponsePydantic(AgentStatePydantic):
+    """The state of the agent with a structured response."""
+
+    structured_response: StructuredResponse
+
+
+StateSchema = TypeVar("StateSchema", bound=Union[AgentState, AgentStatePydantic])
 StateSchemaType = Type[StateSchema]
 
 PROMPT_RUNNABLE_NAME = "Prompt"
@@ -75,21 +91,29 @@ Prompt = Union[
 ]
 
 
+def _get_state_value(state: StateSchema, key: str, default: Any = None) -> Any:
+    return (
+        state.get(key, default)
+        if isinstance(state, dict)
+        else getattr(state, key, default)
+    )
+
+
 def _get_prompt_runnable(prompt: Optional[Prompt]) -> Runnable:
     prompt_runnable: Runnable
     if prompt is None:
         prompt_runnable = RunnableCallable(
-            lambda state: state["messages"], name=PROMPT_RUNNABLE_NAME
+            lambda state: _get_state_value(state, "messages"), name=PROMPT_RUNNABLE_NAME
         )
     elif isinstance(prompt, str):
         _system_message: BaseMessage = SystemMessage(content=prompt)
         prompt_runnable = RunnableCallable(
-            lambda state: [_system_message] + state["messages"],
+            lambda state: [_system_message] + _get_state_value(state, "messages"),
             name=PROMPT_RUNNABLE_NAME,
         )
     elif isinstance(prompt, SystemMessage):
         prompt_runnable = RunnableCallable(
-            lambda state: [prompt] + state["messages"],
+            lambda state: [prompt] + _get_state_value(state, "messages"),
             name=PROMPT_RUNNABLE_NAME,
         )
     elif inspect.iscoroutinefunction(prompt):
@@ -133,6 +157,16 @@ def _convert_modifier_to_prompt(func: F) -> F:
 
 
 def _should_bind_tools(model: LanguageModelLike, tools: Sequence[BaseTool]) -> bool:
+    if isinstance(model, RunnableSequence):
+        model = next(
+            (
+                step
+                for step in model.steps
+                if isinstance(step, (RunnableBinding, BaseChatModel))
+            ),
+            model,
+        )
+
     if not isinstance(model, RunnableBinding):
         return True
 
@@ -168,6 +202,16 @@ def _should_bind_tools(model: LanguageModelLike, tools: Sequence[BaseTool]) -> b
 
 def _get_model(model: LanguageModelLike) -> BaseChatModel:
     """Get the underlying model from a RunnableBinding or return the model itself."""
+    if isinstance(model, RunnableSequence):
+        model = next(
+            (
+                step
+                for step in model.steps
+                if isinstance(step, (RunnableBinding, BaseChatModel))
+            ),
+            model,
+        )
+
     if isinstance(model, RunnableBinding):
         model = model.bound
 
@@ -262,7 +306,7 @@ def create_react_agent(
                 The graph will make a separate call to the LLM to generate the structured response after the agent loop is finished.
                 This is not the only strategy to get structured responses, see more options in [this guide](https://langchain-ai.github.io/langgraph/how-tos/react-agent-structured-output/).
         state_schema: An optional state schema that defines graph state.
-            Must have `messages` and `is_last_step` keys.
+            Must have `messages` and `remaining_steps` keys.
             Defaults to `AgentState` that defines those two keys.
         config_schema: An optional schema for configuration.
             Use this to expose configurable parameters via agent.config_specs.
@@ -574,7 +618,8 @@ def create_react_agent(
         if response_format is not None:
             required_keys.add("structured_response")
 
-        if missing_keys := required_keys - set(state_schema.__annotations__):
+        schema_keys = set(get_type_hints(state_schema))
+        if missing_keys := required_keys - set(schema_keys):
             raise ValueError(f"Missing required key(s) {missing_keys} in state_schema")
 
     if state_schema is None:
@@ -615,35 +660,34 @@ def create_react_agent(
     # our graph needs to check if these were called
     should_return_direct = {t.name for t in tool_classes if t.return_direct}
 
-    # Define the function that calls the model
-    def call_model(state: AgentState, config: RunnableConfig) -> AgentState:
-        _validate_chat_history(state["messages"])
-        response = cast(AIMessage, model_runnable.invoke(state, config))
-        # add agent name to the AIMessage
-        response.name = name
+    def _are_more_steps_needed(state: StateSchema, response: BaseMessage) -> bool:
         has_tool_calls = isinstance(response, AIMessage) and response.tool_calls
         all_tools_return_direct = (
             all(call["name"] in should_return_direct for call in response.tool_calls)
             if isinstance(response, AIMessage)
             else False
         )
-        if (
-            (
-                "remaining_steps" not in state
-                and state.get("is_last_step", False)
-                and has_tool_calls
-            )
+        remaining_steps = _get_state_value(state, "remaining_steps", None)
+        is_last_step = _get_state_value(state, "is_last_step", False)
+        return (
+            (remaining_steps is None and is_last_step and has_tool_calls)
             or (
-                "remaining_steps" in state
-                and state["remaining_steps"] < 1
+                remaining_steps is not None
+                and remaining_steps < 1
                 and all_tools_return_direct
             )
-            or (
-                "remaining_steps" in state
-                and state["remaining_steps"] < 2
-                and has_tool_calls
-            )
-        ):
+            or (remaining_steps is not None and remaining_steps < 2 and has_tool_calls)
+        )
+
+    # Define the function that calls the model
+    def call_model(state: StateSchema, config: RunnableConfig) -> StateSchema:
+        messages = _get_state_value(state, "messages")
+        _validate_chat_history(messages)
+        response = cast(AIMessage, model_runnable.invoke(state, config))
+        # add agent name to the AIMessage
+        response.name = name
+
+        if _are_more_steps_needed(state, response):
             return {
                 "messages": [
                     AIMessage(
@@ -655,34 +699,13 @@ def create_react_agent(
         # We return a list, because this will get added to the existing list
         return {"messages": [response]}
 
-    async def acall_model(state: AgentState, config: RunnableConfig) -> AgentState:
-        _validate_chat_history(state["messages"])
+    async def acall_model(state: StateSchema, config: RunnableConfig) -> StateSchema:
+        messages = _get_state_value(state, "messages")
+        _validate_chat_history(messages)
         response = cast(AIMessage, await model_runnable.ainvoke(state, config))
         # add agent name to the AIMessage
         response.name = name
-        has_tool_calls = isinstance(response, AIMessage) and response.tool_calls
-        all_tools_return_direct = (
-            all(call["name"] in should_return_direct for call in response.tool_calls)
-            if isinstance(response, AIMessage)
-            else False
-        )
-        if (
-            (
-                "remaining_steps" not in state
-                and state.get("is_last_step", False)
-                and has_tool_calls
-            )
-            or (
-                "remaining_steps" in state
-                and state["remaining_steps"] < 1
-                and all_tools_return_direct
-            )
-            or (
-                "remaining_steps" in state
-                and state["remaining_steps"] < 2
-                and has_tool_calls
-            )
-        ):
+        if _are_more_steps_needed(state, response):
             return {
                 "messages": [
                     AIMessage(
@@ -695,11 +718,11 @@ def create_react_agent(
         return {"messages": [response]}
 
     def generate_structured_response(
-        state: AgentState, config: RunnableConfig
-    ) -> AgentState:
+        state: StateSchema, config: RunnableConfig
+    ) -> StateSchema:
         # NOTE: we exclude the last message because there is enough information
         # for the LLM to generate the structured response
-        messages = state["messages"][:-1]
+        messages = _get_state_value(state, "messages")[:-1]
         structured_response_schema = response_format
         if isinstance(response_format, tuple):
             system_prompt, structured_response_schema = response_format
@@ -712,11 +735,11 @@ def create_react_agent(
         return {"structured_response": response}
 
     async def agenerate_structured_response(
-        state: AgentState, config: RunnableConfig
-    ) -> AgentState:
+        state: StateSchema, config: RunnableConfig
+    ) -> StateSchema:
         # NOTE: we exclude the last message because there is enough information
         # for the LLM to generate the structured response
-        messages = state["messages"][:-1]
+        messages = _get_state_value(state, "messages")[:-1]
         structured_response_schema = response_format
         if isinstance(response_format, tuple):
             system_prompt, structured_response_schema = response_format
@@ -752,8 +775,8 @@ def create_react_agent(
         )
 
     # Define the function that determines whether to continue or not
-    def should_continue(state: AgentState) -> Union[str, list]:
-        messages = state["messages"]
+    def should_continue(state: StateSchema) -> Union[str, list]:
+        messages = _get_state_value(state, "messages")
         last_message = messages[-1]
         # If there is no function call, then we finish
         if not isinstance(last_message, AIMessage) or not last_message.tool_calls:
@@ -803,8 +826,8 @@ def create_react_agent(
         path_map=should_continue_destinations,
     )
 
-    def route_tool_responses(state: AgentState) -> Literal["agent", "__end__"]:
-        for m in reversed(state["messages"]):
+    def route_tool_responses(state: StateSchema) -> Literal["agent", "__end__"]:
+        for m in reversed(_get_state_value(state, "messages")):
             if not isinstance(m, ToolMessage):
                 break
             if m.name in should_return_direct:

libs/prebuilt/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-prebuilt"
-version = "0.1.1"
+version = "0.1.2"
 description = "Library with high-level APIs for creating and executing LangGraph agents and tools."
 authors = []
 license = "MIT"

libs/prebuilt/tests/test_react_agent.py

@@ -5,6 +5,7 @@ from functools import partial
 from typing import (
     Annotated,
     List,
+    Optional,
     Type,
     TypeVar,
     Union,
@@ -35,6 +36,10 @@ from langgraph.prebuilt import (
 )
 from langgraph.prebuilt.chat_agent_executor import (
     AgentState,
+    AgentStatePydantic,
+    StateSchemaType,
+    _get_model,
+    _should_bind_tools,
     _validate_chat_history,
 )
 from langgraph.prebuilt.tool_node import (
@@ -526,22 +531,31 @@ def test_react_agent_with_structured_response(version: str) -> None:
         assert response["messages"][-2].content == "The weather is sunny and 75°F."
 
 
+class CustomState(AgentState):
+    user_name: str
+
+
+class CustomStatePydantic(AgentStatePydantic):
+    user_name: Optional[str] = None
+
+
 @pytest.mark.skipif(
     not IS_LANGCHAIN_CORE_030_OR_GREATER,
     reason="Langchain core 0.3.0 or greater is required",
 )
 @pytest.mark.parametrize("checkpointer_name", ALL_CHECKPOINTERS_SYNC)
 @pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
+@pytest.mark.parametrize("state_schema", [CustomState, CustomStatePydantic])
 def test_react_agent_update_state(
-    request: pytest.FixtureRequest, checkpointer_name: str, version: str
+    request: pytest.FixtureRequest,
+    checkpointer_name: str,
+    version: str,
+    state_schema: StateSchemaType,
 ) -> None:
     checkpointer: BaseCheckpointSaver = request.getfixturevalue(
         "checkpointer_" + checkpointer_name
     )
 
-    class State(AgentState):
-        user_name: str
-
     @dec_tool
     def get_user_name(tool_call_id: Annotated[str, InjectedToolCallId]):
         """Retrieve user name"""
@@ -557,20 +571,31 @@ def test_react_agent_update_state(
             }
         )
 
-    def prompt(state: State):
-        user_name = state.get("user_name")
-        if user_name is None:
-            return state["messages"]
+    if issubclass(state_schema, AgentStatePydantic):
 
-        system_msg = f"User name is {user_name}"
-        return [{"role": "system", "content": system_msg}] + state["messages"]
+        def prompt(state: CustomStatePydantic):
+            user_name = state.user_name
+            if user_name is None:
+                return state.messages
+
+            system_msg = f"User name is {user_name}"
+            return [{"role": "system", "content": system_msg}] + state.messages
+    else:
+
+        def prompt(state: CustomState):
+            user_name = state.get("user_name")
+            if user_name is None:
+                return state["messages"]
+
+            system_msg = f"User name is {user_name}"
+            return [{"role": "system", "content": system_msg}] + state["messages"]
 
     tool_calls = [[{"args": {}, "id": "1", "name": "get_user_name"}]]
     model = FakeToolCallingModel(tool_calls=tool_calls)
     agent = create_react_agent(
         model,
         [get_user_name],
-        state_schema=State,
+        state_schema=state_schema,
         prompt=prompt,
         checkpointer=checkpointer,
         version=version,
@@ -800,23 +825,45 @@ def test_tool_node_inject_state(schema_: Type[T]) -> None:
     assert tool_message.content == "hi?"
 
 
-@pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
-def test_create_react_agent_inject_vars(version: str) -> None:
-    class AgentStateExtraKey(AgentState):
-        foo: int
+class AgentStateExtraKey(AgentState):
+    foo: int
 
+
+class AgentStateExtraKeyPydantic(AgentStatePydantic):
+    foo: int
+
+
+@pytest.mark.parametrize("version", REACT_TOOL_CALL_VERSIONS)
+@pytest.mark.parametrize(
+    "state_schema", [AgentStateExtraKey, AgentStateExtraKeyPydantic]
+)
+def test_create_react_agent_inject_vars(
+    version: str, state_schema: StateSchemaType
+) -> None:
     store = InMemoryStore()
     namespace = ("test",)
     store.put(namespace, "test_key", {"bar": 3})
 
-    def tool1(
-        some_val: int,
-        state: Annotated[dict, InjectedState],
-        store: Annotated[BaseStore, InjectedStore()],
-    ) -> str:
-        """Tool 1 docstring."""
-        store_val = store.get(namespace, "test_key").value["bar"]
-        return some_val + state["foo"] + store_val
+    if issubclass(state_schema, AgentStatePydantic):
+
+        def tool1(
+            some_val: int,
+            state: Annotated[AgentStateExtraKeyPydantic, InjectedState],
+            store: Annotated[BaseStore, InjectedStore()],
+        ) -> str:
+            """Tool 1 docstring."""
+            store_val = store.get(namespace, "test_key").value["bar"]
+            return some_val + state.foo + store_val
+    else:
+
+        def tool1(
+            some_val: int,
+            state: Annotated[dict, InjectedState],
+            store: Annotated[BaseStore, InjectedStore()],
+        ) -> str:
+            """Tool 1 docstring."""
+            store_val = store.get(namespace, "test_key").value["bar"]
+            return some_val + state["foo"] + store_val
 
     tool_call = {
         "name": "tool1",
@@ -828,7 +875,7 @@ def test_create_react_agent_inject_vars(version: str) -> None:
     agent = create_react_agent(
         model,
         [tool1],
-        state_schema=AgentStateExtraKey,
+        state_schema=state_schema,
         store=store,
         version=version,
     )
@@ -1324,3 +1371,66 @@ def test_tool_node_node_interrupt(
             ns=[AnyStr("tools:")],
         ),
     )
+
+
+@pytest.mark.parametrize("tool_style", ["openai", "anthropic"])
+def test_should_bind_tools(tool_style: str) -> None:
+    @dec_tool
+    def some_tool(some_val: int) -> str:
+        """Tool docstring."""
+        return "meow"
+
+    @dec_tool
+    def some_other_tool(some_val: int) -> str:
+        """Tool docstring."""
+        return "meow"
+
+    model = FakeToolCallingModel(tool_style=tool_style)
+    # should bind when a regular model
+    assert _should_bind_tools(model, [])
+    assert _should_bind_tools(model, [some_tool])
+
+    # should bind when a seq
+    seq = model | RunnableLambda(lambda message: message)
+    assert _should_bind_tools(seq, [])
+    assert _should_bind_tools(seq, [some_tool])
+
+    # should not bind when a model with tools
+    assert not _should_bind_tools(model.bind_tools([some_tool]), [some_tool])
+    # should not bind when a seq with tools
+    seq_with_tools = model.bind_tools([some_tool]) | RunnableLambda(
+        lambda message: message
+    )
+    assert not _should_bind_tools(seq_with_tools, [some_tool])
+
+    # should raise on invalid inputs
+    with pytest.raises(ValueError):
+        _should_bind_tools(model.bind_tools([some_tool]), [])
+    with pytest.raises(ValueError):
+        _should_bind_tools(model.bind_tools([some_tool]), [some_other_tool])
+    with pytest.raises(ValueError):
+        _should_bind_tools(model.bind_tools([some_tool]), [some_tool, some_other_tool])
+
+
+def test_get_model() -> None:
+    model = FakeToolCallingModel(tool_calls=[])
+    assert _get_model(model) == model
+
+    @dec_tool
+    def some_tool(some_val: int) -> str:
+        """Tool docstring."""
+        return "meow"
+
+    model_with_tools = model.bind_tools([some_tool])
+    assert _get_model(model_with_tools) == model
+
+    seq = model | RunnableLambda(lambda message: message)
+    assert _get_model(seq) == model
+
+    seq_with_tools = model.bind_tools([some_tool]) | RunnableLambda(
+        lambda message: message
+    )
+    assert _get_model(seq_with_tools) == model
+
+    with pytest.raises(TypeError):
+        _get_model(RunnableLambda(lambda message: message))

libs/sdk-js/.gitignore

@@ -10,6 +10,14 @@ react.cjs
 react.js
 react.d.ts
 react.d.cts
+react-ui.cjs
+react-ui.js
+react-ui.d.ts
+react-ui.d.cts
+react-ui/server.cjs
+react-ui/server.js
+react-ui/server.d.ts
+react-ui/server.d.cts
 node_modules
 dist
 .yarn

libs/sdk-js/langchain.config.js

@@ -11,7 +11,13 @@ function abs(relativePath) {
 
 export const config = {
   internals: [/react/],
-  entrypoints: { index: "index", client: "client", react: "react/index" },
+  entrypoints: {
+    index: "index",
+    client: "client",
+    react: "react/index",
+    "react-ui": "react-ui/index",
+    "react-ui/server": "react-ui/server/index",
+  },
   tsConfigPath: resolve("./tsconfig.json"),
   cjsSource: "./dist-cjs",
   cjsDestination: "./dist",

libs/sdk-js/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.45",
+  "version": "0.0.53",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "packageManager": "yarn@1.22.19",
   "scripts": {
     "clean": "rm -rf dist/ dist-cjs/",
     "build": "yarn clean && yarn lc_build --create-entrypoints --pre --tree-shaking",
-    "prepublish": "yarn run build",
+    "prepack": "yarn run build",
     "format": "prettier --write src",
     "lint": "prettier --check src && tsc --noEmit",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --testPathIgnorePatterns=\\.int\\.test.ts",
@@ -29,7 +29,8 @@
     "@types/jest": "^29.5.12",
     "@types/node": "^20.12.12",
     "@types/uuid": "^9.0.1",
-    "@types/react": "18.3.2",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
     "concat-md": "^0.5.1",
     "jest": "^29.7.0",
     "prettier": "^3.2.5",
@@ -37,7 +38,8 @@
     "typedoc": "^0.27.7",
     "typedoc-plugin-markdown": "^4.4.2",
     "typescript": "^5.4.5",
-    "react": "^18.3.1"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
@@ -79,6 +81,24 @@
       "import": "./react.js",
       "require": "./react.cjs"
     },
+    "./react-ui": {
+      "types": {
+        "import": "./react-ui.d.ts",
+        "require": "./react-ui.d.cts",
+        "default": "./react-ui.d.ts"
+      },
+      "import": "./react-ui.js",
+      "require": "./react-ui.cjs"
+    },
+    "./react-ui/server": {
+      "types": {
+        "import": "./react-ui/server.d.ts",
+        "require": "./react-ui/server.d.cts",
+        "default": "./react-ui/server.d.ts"
+      },
+      "import": "./react-ui/server.js",
+      "require": "./react-ui/server.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -94,6 +114,14 @@
     "react.cjs",
     "react.js",
     "react.d.ts",
-    "react.d.cts"
+    "react.d.cts",
+    "react-ui.cjs",
+    "react-ui.js",
+    "react-ui.d.ts",
+    "react-ui.d.cts",
+    "react-ui/server.cjs",
+    "react-ui/server.js",
+    "react-ui/server.d.ts",
+    "react-ui/server.d.cts"
   ]
 }

libs/sdk-js/src/client.ts

@@ -1088,12 +1088,28 @@ export class StoreClient extends BaseClient {
    * @param namespace A list of strings representing the namespace path.
    * @param key The unique identifier for the item within the namespace.
    * @param value A dictionary containing the item's data.
+   * @param options.index Controls search indexing - null (use defaults), false (disable), or list of field paths to index.
+   * @param options.ttl Optional time-to-live in minutes for the item, or null for no expiration.
    * @returns Promise<void>
+   *
+   * @example
+   * ```typescript
+   * await client.store.putItem(
+   *   ["documents", "user123"],
+   *   "item456",
+   *   { title: "My Document", content: "Hello World" },
+   *   { ttl: 60 } // expires in 60 minutes
+   * );
+   * ```
    */
   async putItem(
     namespace: string[],
     key: string,
     value: Record<string, any>,
+    options?: {
+      index?: false | string[] | null;
+      ttl?: number | null;
+    },
   ): Promise<void> {
     namespace.forEach((label) => {
       if (label.includes(".")) {
@@ -1107,6 +1123,8 @@ export class StoreClient extends BaseClient {
       namespace,
       key,
       value,
+      index: options?.index,
+      ttl: options?.ttl,
     };
 
     return this.fetch<void>("/store/items", {
@@ -1120,9 +1138,33 @@ export class StoreClient extends BaseClient {
    *
    * @param namespace A list of strings representing the namespace path.
    * @param key The unique identifier for the item.
+   * @param options.refreshTtl Whether to refresh the TTL on this read operation. If null, uses the store's default behavior.
    * @returns Promise<Item>
+   *
+   * @example
+   * ```typescript
+   * const item = await client.store.getItem(
+   *   ["documents", "user123"],
+   *   "item456",
+   *   { refreshTtl: true }
+   * );
+   * console.log(item);
+   * // {
+   * //   namespace: ["documents", "user123"],
+   * //   key: "item456",
+   * //   value: { title: "My Document", content: "Hello World" },
+   * //   createdAt: "2024-07-30T12:00:00Z",
+   * //   updatedAt: "2024-07-30T12:00:00Z"
+   * // }
+   * ```
    */
-  async getItem(namespace: string[], key: string): Promise<Item | null> {
+  async getItem(
+    namespace: string[],
+    key: string,
+    options?: {
+      refreshTtl?: boolean | null;
+    },
+  ): Promise<Item | null> {
     namespace.forEach((label) => {
       if (label.includes(".")) {
         throw new Error(
@@ -1131,8 +1173,17 @@ export class StoreClient extends BaseClient {
       }
     });
 
+    const params: Record<string, any> = {
+      namespace: namespace.join("."),
+      key,
+    };
+
+    if (options?.refreshTtl !== undefined) {
+      params.refresh_ttl = options.refreshTtl;
+    }
+
     const response = await this.fetch<APIItem>("/store/items", {
-      params: { namespace: namespace.join("."), key },
+      params,
     });
 
     return response
@@ -1174,7 +1225,33 @@ export class StoreClient extends BaseClient {
    * @param options.limit Maximum number of items to return (default is 10).
    * @param options.offset Number of items to skip before returning results (default is 0).
    * @param options.query Optional search query.
+   * @param options.refreshTtl Whether to refresh the TTL on items returned by this search. If null, uses the store's default behavior.
    * @returns Promise<SearchItemsResponse>
+   *
+   * @example
+   * ```typescript
+   * const results = await client.store.searchItems(
+   *   ["documents"],
+   *   {
+   *     filter: { author: "John Doe" },
+   *     limit: 5,
+   *     refreshTtl: true
+   *   }
+   * );
+   * console.log(results);
+   * // {
+   * //   items: [
+   * //     {
+   * //       namespace: ["documents", "user123"],
+   * //       key: "item789",
+   * //       value: { title: "Another Document", author: "John Doe" },
+   * //       createdAt: "2024-07-30T12:00:00Z",
+   * //       updatedAt: "2024-07-30T12:00:00Z"
+   * //     },
+   * //     // ... additional items ...
+   * //   ]
+   * // }
+   * ```
    */
   async searchItems(
     namespacePrefix: string[],
@@ -1183,6 +1260,7 @@ export class StoreClient extends BaseClient {
       limit?: number;
       offset?: number;
       query?: string;
+      refreshTtl?: boolean | null;
     },
   ): Promise<SearchItemsResponse> {
     const payload = {
@@ -1191,6 +1269,7 @@ export class StoreClient extends BaseClient {
       limit: options?.limit ?? 10,
       offset: options?.offset ?? 0,
       query: options?.query,
+      refresh_ttl: options?.refreshTtl,
     };
 
     const response = await this.fetch<APISearchItemsResponse>(
@@ -1241,6 +1320,40 @@ export class StoreClient extends BaseClient {
   }
 }
 
+class UiClient extends BaseClient {
+  private static promiseCache: Record<string, Promise<unknown> | undefined> =
+    {};
+
+  private static getOrCached<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    if (UiClient.promiseCache[key] != null) {
+      return UiClient.promiseCache[key] as Promise<T>;
+    }
+
+    const promise = fn();
+    UiClient.promiseCache[key] = promise;
+    return promise;
+  }
+
+  async getComponent(assistantId: string, agentName: string): Promise<string> {
+    return UiClient["getOrCached"](
+      `${this.apiUrl}-${assistantId}-${agentName}`,
+      async () => {
+        const response = await this.asyncCaller.fetch(
+          ...this.prepareFetchOptions(`/ui/${assistantId}`, {
+            headers: {
+              Accept: "text/html",
+              "Content-Type": "application/json",
+            },
+            method: "POST",
+            json: { name: agentName },
+          }),
+        );
+        return response.text();
+      },
+    );
+  }
+}
+
 export class Client<
   TStateType = DefaultValues,
   TUpdateType = TStateType,
@@ -1271,11 +1384,18 @@ export class Client<
    */
   public store: StoreClient;
 
+  /**
+   * The client for interacting with the UI.
+   * @internal Used by LoadExternalComponent and the API might change in the future.
+   */
+  public "~ui": UiClient;
+
   constructor(config?: ClientConfig) {
     this.assistants = new AssistantsClient(config);
     this.threads = new ThreadsClient(config);
     this.runs = new RunsClient(config);
     this.crons = new CronsClient(config);
     this.store = new StoreClient(config);
+    this["~ui"] = new UiClient(config);
   }
 }

libs/sdk-js/src/index.ts

@@ -1,6 +1,7 @@
 export { Client } from "./client.js";
 
 export type {
+  AssistantBase,
   Assistant,
   AssistantVersion,
   AssistantGraph,

libs/sdk-js/src/react-ui/client.tsx

@@ -0,0 +1,230 @@
+"use client";
+
+import { useStream } from "../react/index.js";
+import type { UIMessage } from "./types.js";
+
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+import * as JsxRuntime from "react/jsx-runtime";
+import type { UseStream } from "../react/stream.js";
+
+const UseStreamContext = React.createContext<{
+  stream: ReturnType<typeof useStream>;
+  meta: unknown;
+}>(null!);
+
+type BagTemplate = {
+  ConfigurableType?: Record<string, unknown>;
+  InterruptType?: unknown;
+  CustomEventType?: unknown;
+  UpdateType?: unknown;
+  MetaType?: unknown;
+};
+
+type GetMetaType<Bag extends BagTemplate> = Bag extends { MetaType: unknown }
+  ? Bag["MetaType"]
+  : unknown;
+
+interface UseStreamContext<
+  StateType extends Record<string, unknown> = Record<string, unknown>,
+  Bag extends BagTemplate = BagTemplate,
+> extends UseStream<StateType, Bag> {
+  meta?: GetMetaType<Bag>;
+}
+
+export function useStreamContext<
+  StateType extends Record<string, unknown> = Record<string, unknown>,
+  Bag extends {
+    ConfigurableType?: Record<string, unknown>;
+    InterruptType?: unknown;
+    CustomEventType?: unknown;
+    UpdateType?: unknown;
+    MetaType?: unknown;
+  } = BagTemplate,
+>(): UseStreamContext<StateType, Bag> {
+  const ctx = React.useContext(UseStreamContext);
+  if (!ctx) {
+    throw new Error(
+      "useStreamContext must be used within a LoadExternalComponent",
+    );
+  }
+
+  return new Proxy(ctx, {
+    get(target, prop: keyof UseStreamContext<StateType, Bag>) {
+      if (prop === "meta") return target.meta;
+      return target.stream[prop];
+    },
+  }) as unknown as UseStreamContext<StateType, Bag>;
+}
+
+interface ComponentTarget {
+  comp: React.FunctionComponent | React.ComponentClass;
+  target: HTMLElement;
+}
+
+class ComponentStore {
+  private cache: Record<string, ComponentTarget> = {};
+  private boundCache: Record<
+    string,
+    {
+      subscribe: (onStoreChange: () => void) => () => void;
+      getSnapshot: () => ComponentTarget | undefined;
+    }
+  > = {};
+  private callbacks: Record<
+    string,
+    ((
+      comp: React.FunctionComponent | React.ComponentClass,
+      el: HTMLElement,
+    ) => void)[]
+  > = {};
+
+  respond(
+    shadowRootId: string,
+    comp: React.FunctionComponent | React.ComponentClass,
+    targetElement: HTMLElement,
+  ) {
+    this.cache[shadowRootId] = { comp, target: targetElement };
+    this.callbacks[shadowRootId]?.forEach((c) => c(comp, targetElement));
+  }
+
+  getBoundStore(shadowRootId: string) {
+    this.boundCache[shadowRootId] ??= {
+      subscribe: (onStoreChange: () => void) => {
+        this.callbacks[shadowRootId] ??= [];
+        this.callbacks[shadowRootId].push(onStoreChange);
+        return () => {
+          this.callbacks[shadowRootId] = this.callbacks[shadowRootId].filter(
+            (c) => c !== onStoreChange,
+          );
+        };
+      },
+      getSnapshot: () => this.cache[shadowRootId],
+    };
+
+    return this.boundCache[shadowRootId];
+  }
+}
+
+const COMPONENT_STORE = new ComponentStore();
+const EXT_STORE_SYMBOL = Symbol.for("LGUI_EXT_STORE");
+const REQUIRE_SYMBOL = Symbol.for("LGUI_REQUIRE");
+
+interface LoadExternalComponentProps
+  extends Pick<React.HTMLAttributes<HTMLDivElement>, "style" | "className"> {
+  /** Stream of the assistant */
+  stream: ReturnType<typeof useStream>;
+
+  /** UI message to be rendered */
+  message: UIMessage;
+
+  /** Additional context to be passed to the child component */
+  meta?: unknown;
+
+  /** Fallback to be rendered when the component is loading */
+  fallback?: React.ReactNode;
+
+  /**
+   * Map of components that can be rendered directly without fetching the UI code
+   * from the server.
+   */
+  components?: Record<string, React.FunctionComponent | React.ComponentClass>;
+}
+
+export function LoadExternalComponent({
+  stream,
+  message,
+  meta,
+  fallback,
+  components,
+  ...props
+}: LoadExternalComponentProps) {
+  const ref = React.useRef<HTMLDivElement>(null);
+  const id = React.useId();
+  const shadowRootId = `child-shadow-${id}`;
+
+  const store = React.useMemo(
+    () => COMPONENT_STORE.getBoundStore(shadowRootId),
+    [shadowRootId],
+  );
+  const state = React.useSyncExternalStore(store.subscribe, store.getSnapshot);
+
+  const clientComponent = components?.[message.name];
+  const hasClientComponent = clientComponent != null;
+
+  const uiClient = stream.client["~ui"];
+  React.useEffect(() => {
+    if (hasClientComponent) return;
+    uiClient.getComponent(stream.assistantId, message.name).then((html) => {
+      const dom = ref.current;
+      if (!dom) return;
+      const root = dom.shadowRoot ?? dom.attachShadow({ mode: "open" });
+      const fragment = document
+        .createRange()
+        .createContextualFragment(
+          html.replace("{{shadowRootId}}", shadowRootId),
+        );
+      root.appendChild(fragment);
+    });
+  }, [
+    uiClient,
+    stream.assistantId,
+    message.name,
+    shadowRootId,
+    hasClientComponent,
+  ]);
+
+  if (hasClientComponent) {
+    return React.createElement(clientComponent, message.props);
+  }
+
+  return (
+    <>
+      <div id={shadowRootId} ref={ref} {...props} />
+
+      <UseStreamContext.Provider value={{ stream, meta }}>
+        {state?.target != null
+          ? ReactDOM.createPortal(
+              React.createElement(state.comp, message.props),
+              state.target,
+            )
+          : fallback}
+      </UseStreamContext.Provider>
+    </>
+  );
+}
+
+declare global {
+  interface Window {
+    [EXT_STORE_SYMBOL]: ComponentStore;
+    [REQUIRE_SYMBOL]: (name: string) => unknown;
+  }
+}
+
+export function bootstrapUiContext() {
+  if (typeof window === "undefined") {
+    console.warn(
+      "Attempting to bootstrap UI context outside of browser environment. " +
+        "Avoid importing from `@langchain/langgraph-sdk/react-ui` in server context.",
+    );
+    return;
+  }
+
+  window[EXT_STORE_SYMBOL] = COMPONENT_STORE;
+  window[REQUIRE_SYMBOL] = (name: string) => {
+    if (name === "react") return React;
+    if (name === "react-dom") return ReactDOM;
+    if (name === "react/jsx-runtime") return JsxRuntime;
+    if (name === "@langchain/langgraph-sdk/react") return { useStream };
+    if (name === "@langchain/langgraph-sdk/react-ui") {
+      return {
+        useStreamContext,
+        LoadExternalComponent: () => {
+          throw new Error("Nesting LoadExternalComponent is not supported");
+        },
+      };
+    }
+
+    throw new Error(`Unknown module...: ${name}`);
+  };
+}

libs/sdk-js/src/react-ui/index.ts

@@ -0,0 +1,9 @@
+import { bootstrapUiContext } from "./client.js";
+bootstrapUiContext();
+
+export { useStreamContext, LoadExternalComponent } from "./client.js";
+export {
+  uiMessageReducer,
+  type UIMessage,
+  type RemoveUIMessage,
+} from "./types.js";

libs/sdk-js/src/react-ui/server/index.ts

@@ -0,0 +1,6 @@
+export { typedUi } from "./server.js";
+export {
+  uiMessageReducer,
+  type UIMessage,
+  type RemoveUIMessage,
+} from "../types.js";

libs/sdk-js/src/react-ui/server/server.ts

@@ -0,0 +1,62 @@
+import { v4 as uuidv4 } from "uuid";
+import type { ComponentPropsWithoutRef, ElementType } from "react";
+import type { RemoveUIMessage, UIMessage } from "../types.js";
+
+interface MessageLike {
+  id?: string;
+}
+
+export const typedUi = <Decl extends Record<string, ElementType>>(config: {
+  writer?: (chunk: unknown) => void;
+  runId?: string;
+  metadata?: Record<string, unknown>;
+  tags?: string[];
+  runName?: string;
+}) => {
+  type PropMap = { [K in keyof Decl]: ComponentPropsWithoutRef<Decl[K]> };
+  let items: (UIMessage | RemoveUIMessage)[] = [];
+
+  const runId = (config.metadata?.run_id as string | undefined) ?? config.runId;
+  if (!runId) throw new Error("run_id is required");
+
+  const metadata = {
+    ...config.metadata,
+    tags: config.tags,
+    name: config.runName,
+    run_id: runId,
+  };
+
+  const handlePush = <K extends keyof PropMap & string>(
+    message: {
+      id?: string;
+      name: K;
+      props: PropMap[K];
+      metadata?: Record<string, unknown>;
+    },
+    options?: { message?: MessageLike },
+  ): UIMessage => {
+    const evt: UIMessage = {
+      type: "ui" as const,
+      id: message?.id ?? uuidv4(),
+      name: message?.name,
+      props: message?.props,
+      metadata: {
+        ...metadata,
+        ...message?.metadata,
+        ...(options?.message ? { message_id: options.message.id } : null),
+      },
+    };
+    items.push(evt);
+    config.writer?.(evt);
+    return evt;
+  };
+
+  const handleDelete = (id: string): RemoveUIMessage => {
+    const evt: RemoveUIMessage = { type: "remove-ui", id };
+    items.push(evt);
+    config.writer?.(evt);
+    return evt;
+  };
+
+  return { push: handlePush, delete: handleDelete, items };
+};

libs/sdk-js/src/react-ui/types.ts

@@ -0,0 +1,41 @@
+export interface UIMessage {
+  type: "ui";
+
+  id: string;
+  name: string;
+  props: Record<string, unknown>;
+  metadata: {
+    run_id: string;
+    message_id?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface RemoveUIMessage {
+  type: "remove-ui";
+  id: string;
+}
+
+export function uiMessageReducer(
+  state: UIMessage[],
+  update: UIMessage | RemoveUIMessage | (UIMessage | RemoveUIMessage)[],
+) {
+  const events = Array.isArray(update) ? update : [update];
+  let newState = state.slice();
+
+  for (const event of events) {
+    if (event.type === "remove-ui") {
+      newState = newState.filter((ui) => ui.id !== event.id);
+      continue;
+    }
+
+    const index = state.findIndex((ui) => ui.id === event.id);
+    if (index !== -1) {
+      newState[index] = event;
+    } else {
+      newState.push(event);
+    }
+  }
+
+  return newState;
+}

libs/sdk-js/src/react/stream.tsx

@@ -366,11 +366,11 @@ const useControllableThreadId = (options?: {
     onThreadIdRef.current?.(threadId);
   }, []);
 
-  if (typeof options?.threadId === "undefined") {
+  if (!options || !("threadId" in options)) {
     return [localThreadId, onThreadId];
   }
 
-  return [options.threadId, onThreadId];
+  return [options.threadId ?? null, onThreadId];
 };
 
 type BagTemplate = {
@@ -424,6 +424,16 @@ interface UseStreamOptions<
    */
   apiKey?: ClientConfig["apiKey"];
 
+  /**
+   * Custom call options, such as custom fetch implementation.
+   */
+  callerOptions?: ClientConfig["callerOptions"];
+
+  /**
+   * Default headers to send with requests.
+   */
+  defaultHeaders?: ClientConfig["defaultHeaders"];
+
   /**
    * Specify the key within the state that contains messages.
    * Defaults to "messages".
@@ -454,6 +464,11 @@ interface UseStreamOptions<
    */
   onCustomEvent?: (
     data: CustomStreamEvent<GetCustomEventType<Bag>>["data"],
+    options: {
+      mutate: (
+        update: Partial<StateType> | ((prev: StateType) => Partial<StateType>),
+      ) => void;
+    },
   ) => void;
 
   /**
@@ -472,7 +487,7 @@ interface UseStreamOptions<
   onThreadId?: (threadId: string) => void;
 }
 
-interface UseStream<
+export interface UseStream<
   StateType extends Record<string, unknown> = Record<string, unknown>,
   Bag extends BagTemplate = BagTemplate,
 > {
@@ -548,6 +563,16 @@ interface UseStream<
     message: Message,
     index?: number,
   ) => MessageMetadata<StateType> | undefined;
+
+  /**
+   * LangGraph SDK client used to send request and receive responses.
+   */
+  client: Client;
+
+  /**
+   * The ID of the assistant to use.
+   */
+  assistantId: string;
 }
 
 type ConfigWithConfigurable<ConfigurableType extends Record<string, unknown>> =
@@ -603,9 +628,21 @@ export function useStream<
   messagesKey ??= "messages";
 
   const client = useMemo(
-    () => new Client({ apiUrl: options.apiUrl, apiKey: options.apiKey }),
-    [options.apiKey, options.apiUrl],
+    () =>
+      new Client({
+        apiUrl: options.apiUrl,
+        apiKey: options.apiKey,
+        callerOptions: options.callerOptions,
+        defaultHeaders: options.defaultHeaders,
+      }),
+    [
+      options.apiKey,
+      options.apiUrl,
+      options.callerOptions,
+      options.defaultHeaders,
+    ],
   );
+
   const [threadId, onThreadId] = useControllableThreadId(options);
 
   const [branch, setBranch] = useState<string>("");
@@ -623,9 +660,12 @@ export function useStream<
   >([]);
 
   const trackStreamMode = useCallback(
-    (mode: Exclude<StreamMode, "debug" | "messages">) => {
-      if (!trackStreamModeRef.current.includes(mode))
-        trackStreamModeRef.current.push(mode);
+    (...mode: Exclude<StreamMode, "debug" | "messages">[]) => {
+      for (const m of mode) {
+        if (!trackStreamModeRef.current.includes(m)) {
+          trackStreamModeRef.current.push(m);
+        }
+      }
     },
     [],
   );
@@ -810,7 +850,18 @@ export function useStream<
         }
 
         if (event === "updates") options.onUpdateEvent?.(data);
-        if (event === "custom") options.onCustomEvent?.(data);
+        if (event === "custom")
+          options.onCustomEvent?.(data, {
+            mutate: (update) =>
+              setStreamValues((prev) => {
+                // should not happen
+                if (prev == null) return prev;
+                return {
+                  ...prev,
+                  ...(typeof update === "function" ? update(prev) : update),
+                };
+              }),
+          });
         if (event === "metadata") options.onMetadataEvent?.(data);
 
         if (event === "values") setStreamValues(data);
@@ -879,6 +930,9 @@ export function useStream<
       return values;
     },
 
+    client,
+    assistantId,
+
     error,
     isLoading,
 
@@ -908,7 +962,7 @@ export function useStream<
     },
 
     get messages() {
-      trackStreamMode("messages-tuple");
+      trackStreamMode("messages-tuple", "values");
       return getMessages(values);
     },
 
@@ -916,7 +970,7 @@ export function useStream<
       message: Message,
       index?: number,
     ): MessageMetadata<StateType> | undefined {
-      trackStreamMode("messages-tuple");
+      trackStreamMode("messages-tuple", "values");
       return messageMetadata?.find(
         (m) => m.messageId === (message.id ?? index),
       );

libs/sdk-js/src/schema.ts

@@ -110,6 +110,9 @@ export interface AssistantBase {
 
   /** The version of the assistant. */
   version: number;
+
+  /** The name of the assistant */
+  name: string;
 }
 
 export interface AssistantVersion extends AssistantBase {}
@@ -117,9 +120,6 @@ export interface AssistantVersion extends AssistantBase {}
 export interface Assistant extends AssistantBase {
   /** The last time the assistant was updated. */
   updated_at: string;
-
-  /** The name of the assistant */
-  name: string;
 }
 
 export interface AssistantGraph {

libs/sdk-js/src/types.messages.ts

@@ -26,7 +26,7 @@ export type AIMessage = {
   tool_calls?:
     | {
         name: string;
-        args: { [x: string]: { [x: string]: any } };
+        args: { [x: string]: any };
         id?: string | undefined;
         type?: "tool_call" | undefined;
       }[]

libs/sdk-js/yarn.lock

@@ -1005,17 +1005,16 @@
   resolved "https://registry.yarnpkg.com/@types/normalize-package-data/-/normalize-package-data-2.4.4.tgz#56e2cc26c397c038fab0e3a917a12d5c5909e901"
   integrity sha512-37i+OaWTh9qeK4LSHPsyRC7NahnGotNuZvjLSgcPzblpHB3rrCJxAOgI5gCdKm7coonsaX1Of0ILiTcnZjbfxA==
 
-"@types/prop-types@*":
-  version "15.7.14"
-  resolved "https://registry.yarnpkg.com/@types/prop-types/-/prop-types-15.7.14.tgz#1433419d73b2a7ebfc6918dcefd2ec0d5cd698f2"
-  integrity sha512-gNMvNH49DJ7OJYv+KAKn0Xp45p8PLl6zo2YnvDIbTd4J6MER2BmWN49TG7n9LvkyihINxeKW8+3bfS2yDC9dzQ==
+"@types/react-dom@^19.0.3":
+  version "19.0.3"
+  resolved "https://registry.yarnpkg.com/@types/react-dom/-/react-dom-19.0.3.tgz#0804dfd279a165d5a0ad8b53a5b9e65f338050a4"
+  integrity sha512-0Knk+HJiMP/qOZgMyNFamlIjw9OFCsyC2ZbigmEEyXXixgre6IQpm/4V+r3qH4GC1JPvRJKInw+on2rV6YZLeA==
 
-"@types/react@18.3.2":
-  version "18.3.2"
-  resolved "https://registry.yarnpkg.com/@types/react/-/react-18.3.2.tgz#462ae4904973bc212fa910424d901e3d137dbfcd"
-  integrity sha512-Btgg89dAnqD4vV7R3hlwOxgqobUQKgx3MmrQRi0yYbs/P0ym8XozIAlkqVilPqHQwXs4e9Tf63rrCgl58BcO4w==
+"@types/react@^19.0.8":
+  version "19.0.9"
+  resolved "https://registry.yarnpkg.com/@types/react/-/react-19.0.9.tgz#675255eb7d978bdaf71f9d08f6b740d41b0b7f32"
+  integrity sha512-FedNTYgmMwSZmD1Sru/W1gJKuiYCN/3SuBkmZkcxX+FpO5zL76B22A9YNfAKg4HQO3Neh/30AiynP6BELdU0qQ==
   dependencies:
-    "@types/prop-types" "*"
     csstype "^3.0.2"
 
 "@types/retry@0.12.0":
@@ -1178,9 +1177,9 @@ available-typed-arrays@^1.0.7:
     possible-typed-array-names "^1.0.0"
 
 axios@^1.6.7:
-  version "1.7.7"
-  resolved "https://registry.yarnpkg.com/axios/-/axios-1.7.7.tgz#2f554296f9892a72ac8d8e4c5b79c14a91d0a47f"
-  integrity sha512-S4kL7XrjgBmvdGut0sN3yJxqYzrDOnivkBiN0OFs6hLiUam3UPvswUo0kqGyhqUZGEOytHyumEdXsAkgCOUf3Q==
+  version "1.8.2"
+  resolved "https://registry.yarnpkg.com/axios/-/axios-1.8.2.tgz#fabe06e241dfe83071d4edfbcaa7b1c3a40f7979"
+  integrity sha512-ls4GYBm5aig9vWx8AWDSGLpnpDQRtWAfrjU+EuytuODrFBkqesN2RkOQCBzrA1RQNHw1SmRMSDDDSwzNAYQ6Rg==
   dependencies:
     follow-redirects "^1.15.6"
     form-data "^4.0.0"
@@ -2896,7 +2895,7 @@ js-tiktoken@^1.0.12:
   dependencies:
     base64-js "^1.5.1"
 
-"js-tokens@^3.0.0 || ^4.0.0", js-tokens@^4.0.0:
+js-tokens@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499"
   integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==
@@ -2991,13 +2990,6 @@ longest-streak@^2.0.0:
   resolved "https://registry.yarnpkg.com/longest-streak/-/longest-streak-2.0.4.tgz#b8599957da5b5dab64dee3fe316fa774597d90e4"
   integrity sha512-vM6rUVCVUJJt33bnmHiZEvr7wPT78ztX7rojL+LW51bHtLh6HTjx84LA5W4+oa6aKEJA7jJu5LR6vQRBpA5DVg==
 
-loose-envify@^1.1.0:
-  version "1.4.0"
-  resolved "https://registry.yarnpkg.com/loose-envify/-/loose-envify-1.4.0.tgz#71ee51fa7be4caec1a63839f7e682d8132d30caf"
-  integrity sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==
-  dependencies:
-    js-tokens "^3.0.0 || ^4.0.0"
-
 lru-cache@^10.2.0:
   version "10.4.3"
   resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-10.4.3.tgz#410fc8a17b70e598013df257c2446b7f3383f119"
@@ -3640,17 +3632,22 @@ quick-lru@^4.0.1:
   resolved "https://registry.yarnpkg.com/quick-lru/-/quick-lru-4.0.1.tgz#5b8878f113a58217848c6482026c73e1ba57727f"
   integrity sha512-ARhCpm70fzdcvNQfPoy49IaanKkTlRWF2JMzqhcJbhSFRZv7nPTvZJdcY7301IPmvW+/p0RgIWnQDLJxifsQ7g==
 
+react-dom@^19.0.0:
+  version "19.0.0"
+  resolved "https://registry.yarnpkg.com/react-dom/-/react-dom-19.0.0.tgz#43446f1f01c65a4cd7f7588083e686a6726cfb57"
+  integrity sha512-4GV5sHFG0e/0AD4X+ySy6UJd3jVl1iNsNHdpad0qhABJ11twS3TTBnseqsKurKcsNqCEFeGL3uLpVChpIO3QfQ==
+  dependencies:
+    scheduler "^0.25.0"
+
 react-is@^18.0.0:
   version "18.3.1"
   resolved "https://registry.yarnpkg.com/react-is/-/react-is-18.3.1.tgz#e83557dc12eae63a99e003a46388b1dcbb44db7e"
   integrity sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==
 
-react@^18.3.1:
-  version "18.3.1"
-  resolved "https://registry.yarnpkg.com/react/-/react-18.3.1.tgz#49ab892009c53933625bd16b2533fc754cab2891"
-  integrity sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==
-  dependencies:
-    loose-envify "^1.1.0"
+react@^19.0.0:
+  version "19.0.0"
+  resolved "https://registry.yarnpkg.com/react/-/react-19.0.0.tgz#6e1969251b9f108870aa4bff37a0ce9ddfaaabdd"
+  integrity sha512-V8AVnmPIICiWpGfm6GLzCR/W5FXLchHop40W4nXBmdlEceh16rCN8O8LNWm5bh5XUX91fh7KpA+W0TgMKmgTpQ==
 
 read-pkg-up@^7.0.1:
   version "7.0.1"
@@ -3840,6 +3837,11 @@ safe-regex-test@^1.0.3:
     es-errors "^1.3.0"
     is-regex "^1.1.4"
 
+scheduler@^0.25.0:
+  version "0.25.0"
+  resolved "https://registry.yarnpkg.com/scheduler/-/scheduler-0.25.0.tgz#336cd9768e8cceebf52d3c80e3dcf5de23e7e015"
+  integrity sha512-xFVuu11jh+xcO7JOAGJNOXld8/TcEHK/4CituBUeUb5hqxJLj9YuemAEuvm9gQ/+pgXYfbQuqAkiYu+u7YEsNA==
+
 "semver@2 || 3 || 4 || 5":
   version "5.7.2"
   resolved "https://registry.yarnpkg.com/semver/-/semver-5.7.2.tgz#48d55db737c3287cd4835e17fa13feace1c41ef8"

libs/sdk-py/langgraph_sdk/client.py

@@ -388,7 +388,9 @@ class AssistantsClient:
                 'created_at': '2024-06-25T17:10:33.109781+00:00',
                 'updated_at': '2024-06-25T17:10:33.109781+00:00',
                 'config': {},
-                'metadata': {'created_by': 'system'}
+                'metadata': {'created_by': 'system'},
+                'version': 1,
+                'name': 'my_assistant'
             }
 
         """  # noqa: E501
@@ -742,7 +744,7 @@ class AssistantsClient:
             offset: The number of versions to skip.
 
         Returns:
-            list[Assistant]: A list of assistants.
+            list[AssistantVersion]: A list of assistant versions.
 
         Example Usage:
 
@@ -2127,6 +2129,7 @@ class StoreClient:
         key: str,
         value: dict[str, Any],
         index: Optional[Union[Literal[False], list[str]]] = None,
+        ttl: Optional[int] = None,
     ) -> None:
         """Store or update an item.
 
@@ -2135,6 +2138,7 @@ class StoreClient:
             key: The unique identifier for the item within the namespace.
             value: A dictionary containing the item's data.
             index: Controls search indexing - None (use defaults), False (disable), or list of field paths to index.
+            ttl: Optional time-to-live in minutes for the item, or None for no expiration.
 
         Returns:
             None
@@ -2152,15 +2156,29 @@ class StoreClient:
                 raise ValueError(
                     f"Invalid namespace label '{label}'. Namespace labels cannot contain periods ('.')."
                 )
-        payload = {"namespace": namespace, "key": key, "value": value, "index": index}
-        await self.http.put("/store/items", json=payload)
+        payload = {
+            "namespace": namespace,
+            "key": key,
+            "value": value,
+            "index": index,
+            "ttl": ttl,
+        }
+        await self.http.put("/store/items", json=_provided_vals(payload))
 
-    async def get_item(self, namespace: Sequence[str], /, key: str) -> Item:
+    async def get_item(
+        self,
+        namespace: Sequence[str],
+        /,
+        key: str,
+        *,
+        refresh_ttl: Optional[bool] = None,
+    ) -> Item:
         """Retrieve a single item.
 
         Args:
             key: The unique identifier for the item.
             namespace: Optional list of strings representing the namespace path.
+            refresh_ttl: Whether to refresh the TTL on this read operation. If None, uses the store's default behavior.
 
         Returns:
             Item: The retrieved item.
@@ -2188,9 +2206,10 @@ class StoreClient:
                 raise ValueError(
                     f"Invalid namespace label '{label}'. Namespace labels cannot contain periods ('.')."
                 )
-        return await self.http.get(
-            "/store/items", params={"namespace": ".".join(namespace), "key": key}
-        )
+        params = {"namespace": ".".join(namespace), "key": key}
+        if refresh_ttl is not None:
+            params["refresh_ttl"] = refresh_ttl
+        return await self.http.get("/store/items", params=params)
 
     async def delete_item(self, namespace: Sequence[str], /, key: str) -> None:
         """Delete an item.
@@ -2221,6 +2240,7 @@ class StoreClient:
         limit: int = 10,
         offset: int = 0,
         query: Optional[str] = None,
+        refresh_ttl: Optional[bool] = None,
     ) -> SearchItemsResponse:
         """Search for items within a namespace prefix.
 
@@ -2230,6 +2250,7 @@ class StoreClient:
             limit: Maximum number of items to return (default is 10).
             offset: Number of items to skip before returning results (default is 0).
             query: Optional query for natural language search.
+            refresh_ttl: Whether to refresh the TTL on items returned by this search. If None, uses the store's default behavior.
 
         Returns:
             List[Item]: A list of items matching the search criteria.
@@ -2268,6 +2289,7 @@ class StoreClient:
             "limit": limit,
             "offset": offset,
             "query": query,
+            "refresh_ttl": refresh_ttl,
         }
 
         return await self.http.post("/store/items/search", json=_provided_vals(payload))
@@ -2517,7 +2539,7 @@ def encode_json(json: Any) -> tuple[dict[str, str], bytes]:
 
 def decode_json(r: httpx.Response) -> Any:
     body = r.read()
-    return orjson.loads(body if body else None)
+    return orjson.loads(body) if body else None
 
 
 class SyncAssistantsClient:
@@ -4252,6 +4274,7 @@ class SyncStoreClient:
         key: str,
         value: dict[str, Any],
         index: Optional[Union[Literal[False], list[str]]] = None,
+        ttl: Optional[int] = None,
     ) -> None:
         """Store or update an item.
 
@@ -4260,7 +4283,7 @@ class SyncStoreClient:
             key: The unique identifier for the item within the namespace.
             value: A dictionary containing the item's data.
             index: Controls search indexing - None (use defaults), False (disable), or list of field paths to index.
-
+            ttl: Optional time-to-live in minutes for the item, or None for no expiration.
         Returns:
             None
 
@@ -4282,15 +4305,24 @@ class SyncStoreClient:
             "key": key,
             "value": value,
             "index": index,
+            "ttl": ttl,
         }
-        self.http.put("/store/items", json=payload)
+        self.http.put("/store/items", json=_provided_vals(payload))
 
-    def get_item(self, namespace: Sequence[str], /, key: str) -> Item:
+    def get_item(
+        self,
+        namespace: Sequence[str],
+        /,
+        key: str,
+        *,
+        refresh_ttl: Optional[bool] = None,
+    ) -> Item:
         """Retrieve a single item.
 
         Args:
             key: The unique identifier for the item.
             namespace: Optional list of strings representing the namespace path.
+            refresh_ttl: Whether to refresh the TTL on this read operation. If None, uses the store's default behavior.
 
         Returns:
             Item: The retrieved item.
@@ -4319,9 +4351,10 @@ class SyncStoreClient:
                     f"Invalid namespace label '{label}'. Namespace labels cannot contain periods ('.')."
                 )
 
-        return self.http.get(
-            "/store/items", params={"key": key, "namespace": ".".join(namespace)}
-        )
+        params = {"key": key, "namespace": ".".join(namespace)}
+        if refresh_ttl is not None:
+            params["refresh_ttl"] = refresh_ttl
+        return self.http.get("/store/items", params=params)
 
     def delete_item(self, namespace: Sequence[str], /, key: str) -> None:
         """Delete an item.
@@ -4350,6 +4383,7 @@ class SyncStoreClient:
         limit: int = 10,
         offset: int = 0,
         query: Optional[str] = None,
+        refresh_ttl: Optional[bool] = None,
     ) -> SearchItemsResponse:
         """Search for items within a namespace prefix.
 
@@ -4359,6 +4393,7 @@ class SyncStoreClient:
             limit: Maximum number of items to return (default is 10).
             offset: Number of items to skip before returning results (default is 0).
             query: Optional query for natural language search.
+            refresh_ttl: Whether to refresh the TTL on items returned by this search. If None, uses the store's default behavior.
 
         Returns:
             List[Item]: A list of items matching the search criteria.
@@ -4397,6 +4432,7 @@ class SyncStoreClient:
             "limit": limit,
             "offset": offset,
             "query": query,
+            "refresh_ttl": refresh_ttl,
         }
         return self.http.post("/store/items/search", json=_provided_vals(payload))
 

libs/sdk-py/langgraph_sdk/schema.py

@@ -169,6 +169,8 @@ class AssistantBase(TypedDict):
     """The assistant metadata."""
     version: int
     """The version of the assistant"""
+    name: str
+    """The name of the assistant"""
 
 
 class AssistantVersion(AssistantBase):
@@ -182,8 +184,6 @@ class Assistant(AssistantBase):
 
     updated_at: datetime
     """The last time the assistant was updated."""
-    name: str
-    """The name of the assistant"""
 
 
 class Interrupt(TypedDict, total=False):

libs/sdk-py/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-sdk"
-version = "0.1.53"
+version = "0.1.56"
 description = "SDK for interacting with LangGraph API"
 authors = []
 license = "MIT"