From 0b4638269b6565e6e0ef055ff4f87c9eb04a8417 Mon Sep 17 00:00:00 2001 From: Isaac Francisco <78627776+isahers1@users.noreply.github.com> Date: Wed, 27 Aug 2025 12:21:25 -0700 Subject: [PATCH] feat(sdk-py): add durability flag (#5963) --- libs/sdk-py/langgraph_sdk/client.py | 100 ++++++++++++++++++++++++---- libs/sdk-py/langgraph_sdk/schema.py | 6 ++ 2 files changed, 94 insertions(+), 12 deletions(-) diff --git a/libs/sdk-py/langgraph_sdk/client.py b/libs/sdk-py/langgraph_sdk/client.py index cf6d9f510..904e78e01 100644 --- a/libs/sdk-py/langgraph_sdk/client.py +++ b/libs/sdk-py/langgraph_sdk/client.py @@ -15,6 +15,7 @@ import logging import os import re import sys +import warnings from collections.abc import AsyncIterator, Iterator, Mapping, Sequence from types import TracebackType from typing import ( @@ -45,6 +46,7 @@ from langgraph_sdk.schema import ( CronSelectField, CronSortBy, DisconnectMode, + Durability, GraphSchema, IfNotExists, Item, @@ -1772,7 +1774,7 @@ class RunsClient: context: Context | None = None, checkpoint: Checkpoint | None = None, checkpoint_id: str | None = None, - checkpoint_during: bool | None = None, + checkpoint_during: bool | None = None, # deprecated interrupt_before: All | Sequence[str] | None = None, interrupt_after: All | Sequence[str] | None = None, feedback_keys: Sequence[str] | None = None, @@ -1785,6 +1787,7 @@ class RunsClient: headers: Mapping[str, str] | None = None, params: QueryParamTypes | None = None, on_run_created: Callable[[RunCreateMetadata], None] | None = None, + durability: Durability | None = None, ) -> AsyncIterator[StreamPart]: """Create a run and stream the results. @@ -1804,7 +1807,7 @@ class RunsClient: context: Static context to add to the assistant. !!! version-added "Supported with langgraph>=0.6.0" checkpoint: The checkpoint to resume from. - checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption). + checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption). interrupt_before: Nodes to interrupt immediately before they get executed. interrupt_after: Nodes to Nodes to interrupt immediately after they get executed. feedback_keys: Feedback keys to assign to run. @@ -1822,6 +1825,10 @@ class RunsClient: headers: Optional custom headers to include with the request. params: Optional query parameters to include with the request. on_run_created: Callback when a run is created. + durability: The durability to use for the run. Values are "sync", "async", or "exit". + "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True + "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False + "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps Returns: AsyncIterator[StreamPart]: Asynchronous iterator of stream results. @@ -1857,6 +1864,13 @@ class RunsClient: ``` """ # noqa: E501 + if checkpoint_during is not None: + warnings.warn( + "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.", + DeprecationWarning, + stacklevel=2, + ) + payload = { "input": input, "command": ( @@ -1881,6 +1895,7 @@ class RunsClient: "on_disconnect": on_disconnect, "on_completion": on_completion, "after_seconds": after_seconds, + "durability": durability, } endpoint = ( f"/threads/{thread_id}/runs/stream" @@ -1971,7 +1986,7 @@ class RunsClient: context: Context | None = None, checkpoint: Checkpoint | None = None, checkpoint_id: str | None = None, - checkpoint_during: bool | None = None, + checkpoint_during: bool | None = None, # deprecated interrupt_before: All | Sequence[str] | None = None, interrupt_after: All | Sequence[str] | None = None, webhook: str | None = None, @@ -1982,6 +1997,7 @@ class RunsClient: headers: Mapping[str, str] | None = None, params: QueryParamTypes | None = None, on_run_created: Callable[[RunCreateMetadata], None] | None = None, + durability: Durability | None = None, ) -> Run: """Create a background run. @@ -2001,7 +2017,7 @@ class RunsClient: context: Static context to add to the assistant. !!! version-added "Supported with langgraph>=0.6.0" checkpoint: The checkpoint to resume from. - checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption). + checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption). interrupt_before: Nodes to interrupt immediately before they get executed. interrupt_after: Nodes to Nodes to interrupt immediately after they get executed. webhook: Webhook to call after LangGraph API call is done. @@ -2015,6 +2031,10 @@ class RunsClient: Use to schedule future runs. headers: Optional custom headers to include with the request. on_run_created: Optional callback to call when a run is created. + durability: The durability to use for the run. Values are "sync", "async", or "exit". + "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True + "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False + "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps Returns: Run: The created background run. @@ -2090,6 +2110,12 @@ class RunsClient: } ``` """ # noqa: E501 + if checkpoint_during is not None: + warnings.warn( + "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.", + DeprecationWarning, + stacklevel=2, + ) payload = { "input": input, "command": ( @@ -2112,6 +2138,7 @@ class RunsClient: "if_not_exists": if_not_exists, "on_completion": on_completion, "after_seconds": after_seconds, + "durability": durability, } payload = {k: v for k, v in payload.items() if v is not None} @@ -2209,7 +2236,7 @@ class RunsClient: context: Context | None = None, checkpoint: Checkpoint | None = None, checkpoint_id: str | None = None, - checkpoint_during: bool | None = None, + checkpoint_during: bool | None = None, # deprecated interrupt_before: All | Sequence[str] | None = None, interrupt_after: All | Sequence[str] | None = None, webhook: str | None = None, @@ -2222,6 +2249,7 @@ class RunsClient: headers: Mapping[str, str] | None = None, params: QueryParamTypes | None = None, on_run_created: Callable[[RunCreateMetadata], None] | None = None, + durability: Durability | None = None, ) -> list[dict] | dict[str, Any]: """Create a run, wait until it finishes and return the final state. @@ -2237,7 +2265,7 @@ class RunsClient: context: Static context to add to the assistant. !!! version-added "Supported with langgraph>=0.6.0" checkpoint: The checkpoint to resume from. - checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption). + checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption). interrupt_before: Nodes to interrupt immediately before they get executed. interrupt_after: Nodes to Nodes to interrupt immediately after they get executed. webhook: Webhook to call after LangGraph API call is done. @@ -2253,6 +2281,10 @@ class RunsClient: Use to schedule future runs. headers: Optional custom headers to include with the request. on_run_created: Optional callback to call when a run is created. + durability: The durability to use for the run. Values are "sync", "async", or "exit". + "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True + "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False + "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps Returns: Union[list[dict], dict[str, Any]]: The output of the run. @@ -2306,6 +2338,12 @@ class RunsClient: ``` """ # noqa: E501 + if checkpoint_during is not None: + warnings.warn( + "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.", + DeprecationWarning, + stacklevel=2, + ) payload = { "input": input, "command": ( @@ -2326,6 +2364,7 @@ class RunsClient: "on_disconnect": on_disconnect, "on_completion": on_completion, "after_seconds": after_seconds, + "durability": durability, } endpoint = ( f"/threads/{thread_id}/runs/wait" if thread_id is not None else "/runs/wait" @@ -4823,7 +4862,7 @@ class SyncRunsClient: context: Context | None = None, checkpoint: Checkpoint | None = None, checkpoint_id: str | None = None, - checkpoint_during: bool | None = None, + checkpoint_during: bool | None = None, # deprecated interrupt_before: All | Sequence[str] | None = None, interrupt_after: All | Sequence[str] | None = None, feedback_keys: Sequence[str] | None = None, @@ -4836,6 +4875,7 @@ class SyncRunsClient: headers: Mapping[str, str] | None = None, params: QueryParamTypes | None = None, on_run_created: Callable[[RunCreateMetadata], None] | None = None, + durability: Durability | None = None, ) -> Iterator[StreamPart]: """Create a run and stream the results. @@ -4855,7 +4895,7 @@ class SyncRunsClient: context: Static context to add to the assistant. !!! version-added "Supported with langgraph>=0.6.0" checkpoint: The checkpoint to resume from. - checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption). + checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption). interrupt_before: Nodes to interrupt immediately before they get executed. interrupt_after: Nodes to Nodes to interrupt immediately after they get executed. feedback_keys: Feedback keys to assign to run. @@ -4872,6 +4912,11 @@ class SyncRunsClient: Use to schedule future runs. headers: Optional custom headers to include with the request. on_run_created: Optional callback to call when a run is created. + durability: The durability to use for the run. Values are "sync", "async", or "exit". + "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True + "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False + "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps + Returns: Iterator[StreamPart]: Iterator of stream results. @@ -4904,6 +4949,12 @@ class SyncRunsClient: StreamPart(event='end', data=None) ``` """ # noqa: E501 + if checkpoint_during is not None: + warnings.warn( + "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.", + DeprecationWarning, + stacklevel=2, + ) payload = { "input": input, "command": ( @@ -4928,6 +4979,7 @@ class SyncRunsClient: "on_disconnect": on_disconnect, "on_completion": on_completion, "after_seconds": after_seconds, + "durability": durability, } endpoint = ( f"/threads/{thread_id}/runs/stream" @@ -5018,7 +5070,7 @@ class SyncRunsClient: context: Context | None = None, checkpoint: Checkpoint | None = None, checkpoint_id: str | None = None, - checkpoint_during: bool | None = None, + checkpoint_during: bool | None = None, # deprecated interrupt_before: All | Sequence[str] | None = None, interrupt_after: All | Sequence[str] | None = None, webhook: str | None = None, @@ -5029,6 +5081,7 @@ class SyncRunsClient: headers: Mapping[str, str] | None = None, params: QueryParamTypes | None = None, on_run_created: Callable[[RunCreateMetadata], None] | None = None, + durability: Durability | None = None, ) -> Run: """Create a background run. @@ -5048,7 +5101,7 @@ class SyncRunsClient: context: Static context to add to the assistant. !!! version-added "Supported with langgraph>=0.6.0" checkpoint: The checkpoint to resume from. - checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption). + checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption). interrupt_before: Nodes to interrupt immediately before they get executed. interrupt_after: Nodes to Nodes to interrupt immediately after they get executed. webhook: Webhook to call after LangGraph API call is done. @@ -5062,6 +5115,10 @@ class SyncRunsClient: Use to schedule future runs. headers: Optional custom headers to include with the request. on_run_created: Optional callback to call when a run is created. + durability: The durability to use for the run. Values are "sync", "async", or "exit". + "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True + "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False + "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps Returns: Run: The created background run. @@ -5137,6 +5194,12 @@ class SyncRunsClient: } ``` """ # noqa: E501 + if checkpoint_during is not None: + warnings.warn( + "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.", + DeprecationWarning, + stacklevel=2, + ) payload = { "input": input, "command": ( @@ -5159,6 +5222,7 @@ class SyncRunsClient: "if_not_exists": if_not_exists, "on_completion": on_completion, "after_seconds": after_seconds, + "durability": durability, } payload = {k: v for k, v in payload.items() if v is not None} @@ -5254,7 +5318,7 @@ class SyncRunsClient: metadata: Mapping[str, Any] | None = None, config: Config | None = None, context: Context | None = None, - checkpoint_during: bool | None = None, + checkpoint_during: bool | None = None, # deprecated checkpoint: Checkpoint | None = None, checkpoint_id: str | None = None, interrupt_before: All | Sequence[str] | None = None, @@ -5269,6 +5333,7 @@ class SyncRunsClient: headers: Mapping[str, str] | None = None, params: QueryParamTypes | None = None, on_run_created: Callable[[RunCreateMetadata], None] | None = None, + durability: Durability | None = None, ) -> list[dict] | dict[str, Any]: """Create a run, wait until it finishes and return the final state. @@ -5284,7 +5349,7 @@ class SyncRunsClient: context: Static context to add to the assistant. !!! version-added "Supported with langgraph>=0.6.0" checkpoint: The checkpoint to resume from. - checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption). + checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption). interrupt_before: Nodes to interrupt immediately before they get executed. interrupt_after: Nodes to Nodes to interrupt immediately after they get executed. webhook: Webhook to call after LangGraph API call is done. @@ -5301,6 +5366,10 @@ class SyncRunsClient: raise_error: Whether to raise an error if the run fails. headers: Optional custom headers to include with the request. on_run_created: Optional callback to call when a run is created. + durability: The durability to use for the run. Values are "sync", "async", or "exit". + "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True + "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False + "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps Returns: Union[list[dict], dict[str, Any]]: The output of the run. @@ -5355,6 +5424,12 @@ class SyncRunsClient: ``` """ # noqa: E501 + if checkpoint_during is not None: + warnings.warn( + "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.", + DeprecationWarning, + stacklevel=2, + ) payload = { "input": input, "command": ( @@ -5376,6 +5451,7 @@ class SyncRunsClient: "on_completion": on_completion, "after_seconds": after_seconds, "raise_error": raise_error, + "durability": durability, } def on_response(res: httpx.Response): diff --git a/libs/sdk-py/langgraph_sdk/schema.py b/libs/sdk-py/langgraph_sdk/schema.py index ccc8133dc..a1a8f4f9c 100644 --- a/libs/sdk-py/langgraph_sdk/schema.py +++ b/libs/sdk-py/langgraph_sdk/schema.py @@ -91,6 +91,12 @@ Defines action after completion: - "keep": Retain resources after completion. """ +Durability = Literal["sync", "async", "exit"] +"""Durability mode for the graph execution. +- `"sync"`: Changes are persisted synchronously before the next step starts. +- `"async"`: Changes are persisted asynchronously while the next step executes. +- `"exit"`: Changes are persisted only when the graph exits.""" + All = Literal["*"] """Represents a wildcard or 'all' selector."""