feat(sdk-py): Specify ttl on thread creation and update (#6075)

This PR updates the OpenAPI specification with changes detected from the
LangGraph API server.

**Changes detected as of LangGraph API version 0.4.11**

This update was automatically generated by the sync workflow in the
langgraph-api repository.

Co-authored-by: hinthornw <hinthornw@users.noreply.github.com>

docs/docs/cloud/reference/api/openapi.json

@@ -29,6 +29,10 @@
       "name": "Store",
       "description": "Store is an API for managing persistent key-value store (long-term memory) that is available from any thread."
     },
+    {
+      "name": "A2A",
+      "description": "Agent-to-Agent Protocol related endpoints for exposing assistants as A2A-compliant agents."
+    },
     {
       "name": "MCP",
       "description": "Model Context Protocol related endpoints for exposing an agent as an MCP server."
@@ -3182,6 +3186,195 @@
         }
       }
     },
+    "/a2a/{assistant_id}": {
+      "post": {
+        "operationId": "post_a2a",
+        "summary": "A2A Post",
+        "description": "Communicate with an assistant using the Agent-to-Agent Protocol.\nSends a JSON-RPC 2.0 message to the assistant.\n\n- **Request**: Provide an object with `jsonrpc`, `id`, `method`, and optional `params`.\n- **Response**: Returns a JSON-RPC response with task information or error.\n\n**Supported Methods:**\n- `message/send`: Send a message to the assistant\n- `tasks/get`: Get the status and result of a task\n\n**Notes:**\n- Supports threaded conversations via thread context\n- Messages can contain text and data parts\n- Tasks run asynchronously and return completion status\n",
+        "parameters": [
+          {
+            "name": "assistant_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "description": "The ID of the assistant to communicate with"
+          },
+          {
+            "name": "Accept",
+            "in": "header",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": ["application/json"]
+            },
+            "description": "Must be application/json"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "jsonrpc": {
+                    "type": "string",
+                    "enum": ["2.0"],
+                    "description": "JSON-RPC version"
+                  },
+                  "id": {
+                    "type": "string",
+                    "description": "Request identifier"
+                  },
+                  "method": {
+                    "type": "string",
+                    "enum": ["message/send", "tasks/get"],
+                    "description": "The method to invoke"
+                  },
+                  "params": {
+                    "type": "object",
+                    "description": "Method parameters",
+                    "oneOf": [
+                      {
+                        "title": "Message Send Parameters",
+                        "properties": {
+                          "message": {
+                            "type": "object",
+                            "properties": {
+                              "role": {
+                                "type": "string",
+                                "enum": ["user", "assistant"],
+                                "description": "Message role"
+                              },
+                              "parts": {
+                                "type": "array",
+                                "items": {
+                                  "oneOf": [
+                                    {
+                                      "title": "Text Part",
+                                      "type": "object",
+                                      "properties": {
+                                        "kind": {
+                                          "type": "string",
+                                          "enum": ["text"]
+                                        },
+                                        "text": {
+                                          "type": "string"
+                                        }
+                                      },
+                                      "required": ["kind", "text"]
+                                    },
+                                    {
+                                      "title": "Data Part", 
+                                      "type": "object",
+                                      "properties": {
+                                        "kind": {
+                                          "type": "string",
+                                          "enum": ["data"]
+                                        },
+                                        "data": {
+                                          "type": "object"
+                                        }
+                                      },
+                                      "required": ["kind", "data"]
+                                    }
+                                  ]
+                                },
+                                "description": "Message parts"
+                              },
+                              "messageId": {
+                                "type": "string",
+                                "description": "Unique message identifier"
+                              }
+                            },
+                            "required": ["role", "parts", "messageId"]
+                          },
+                          "thread": {
+                            "type": "object",
+                            "properties": {
+                              "threadId": {
+                                "type": "string",
+                                "description": "Thread identifier for conversation context"
+                              }
+                            },
+                            "description": "Optional thread context"
+                          }
+                        },
+                        "required": ["message"]
+                      },
+                      {
+                        "title": "Task Get Parameters",
+                        "properties": {
+                          "taskId": {
+                            "type": "string",
+                            "description": "Task identifier to retrieve"
+                          }
+                        },
+                        "required": ["taskId"]
+                      }
+                    ]
+                  }
+                },
+                "required": ["jsonrpc", "id", "method"]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "JSON-RPC response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "jsonrpc": {
+                      "type": "string",
+                      "enum": ["2.0"]
+                    },
+                    "id": {
+                      "type": "string"
+                    },
+                    "result": {
+                      "type": "object",
+                      "description": "Success result containing task information or task details"
+                    },
+                    "error": {
+                      "type": "object",
+                      "properties": {
+                        "code": {
+                          "type": "integer"
+                        },
+                        "message": {
+                          "type": "string"
+                        }
+                      },
+                      "description": "Error information if request failed"
+                    }
+                  },
+                  "required": ["jsonrpc", "id"]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - invalid JSON-RPC or missing Accept header"
+          },
+          "404": {
+            "description": "Assistant not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        },
+        "tags": [
+          "A2A"
+        ]
+      }
+    },
     "/mcp/": {
       "post": {
         "operationId": "post_mcp",
@@ -4822,6 +5015,12 @@
       },
       "ThreadSearchRequest": {
         "properties": {
+          "ids": {
+            "type": "array",
+            "items": {"type": "string", "format": "uuid"},
+            "title": "Ids",
+            "description": "List of thread IDs to include. Others are excluded."
+          },
           "metadata": {
             "type": "object",
             "title": "Metadata",
@@ -5062,11 +5261,30 @@
             "type": "object",
             "title": "Metadata",
             "description": "Metadata to merge with existing thread metadata."
+          },
+          "ttl": {
+            "type": "object",
+            "title": "TTL",
+            "description": "The time-to-live for the thread.",
+            "properties": {
+              "strategy": {
+                "type": "string",
+                "enum": [
+                  "delete"
+                ],
+                "description": "The TTL strategy. 'delete' removes the entire thread.",
+                "default": "delete"
+              },
+              "ttl": {
+                "type": "number",
+                "description": "The time-to-live in minutes from now until thread should be swept."
+              }
+            }
           }
         },
         "type": "object",
         "title": "ThreadPatch",
-        "description": "Payload for creating a thread."
+        "description": "Payload for updating a thread."
       },
       "ThreadStateCheckpointRequest": {
         "properties": {

docs/docs/concepts/low_level.md

@@ -1040,7 +1040,7 @@ def node_a(state: State, runtime: Runtime[ContextSchema]):
     ...
 ```
 
-See [this guide](../how-tos/graph-api.ipynb#add-runtime-configuration) for a full breakdown on configuration.
+See [this guide](../how-tos/graph-api.md#add-runtime-configuration) for a full breakdown on configuration.
 :::
 
 :::js

libs/sdk-py/langgraph_sdk/__init__.py

@@ -1,6 +1,6 @@
 from langgraph_sdk.auth import Auth
 from langgraph_sdk.client import get_client, get_sync_client
 
-__version__ = "0.2.3"
+__version__ = "0.2.6"
 
 __all__ = ["Auth", "get_client", "get_sync_client"]

libs/sdk-py/langgraph_sdk/auth/types.py

@@ -400,6 +400,20 @@ class AuthContext(BaseAuthContext):
     """
 
 
+class ThreadTTL(typing.TypedDict, total=False):
+    """Time-to-live configuration for a thread.
+
+    Matches the OpenAPI schema where TTL is represented as an object with
+    an optional strategy and a time value in minutes.
+    """
+
+    strategy: typing.Literal["delete"]
+    """TTL strategy. Currently only 'delete' is supported."""
+
+    ttl: int
+    """Time-to-live in minutes from now until the thread should be swept."""
+
+
 class ThreadsCreate(typing.TypedDict, total=False):
     """Parameters for creating a new thread.
 
@@ -422,6 +436,9 @@ class ThreadsCreate(typing.TypedDict, total=False):
     if_exists: OnConflictBehavior
     """Behavior when a thread with the same ID already exists."""
 
+    ttl: ThreadTTL
+    """Optional TTL configuration for the thread."""
+
 
 class ThreadsRead(typing.TypedDict, total=False):
     """Parameters for reading thread state or run information.
@@ -489,6 +506,9 @@ class ThreadsSearch(typing.TypedDict, total=False):
     offset: int
     """Offset for pagination."""
 
+    ids: Sequence[UUID] | None
+    """typing.Optional list of thread IDs to filter by."""
+
     thread_id: UUID | None
     """typing.Optional thread ID to filter by."""
 

libs/sdk-py/langgraph_sdk/client.py

@@ -71,6 +71,7 @@ from langgraph_sdk.schema import (
     ThreadSortBy,
     ThreadState,
     ThreadStatus,
+    ThreadStreamMode,
     ThreadUpdateStateResponse,
 )
 from langgraph_sdk.sse import SSEDecoder, aiter_lines_raw, iter_lines_raw
@@ -1178,6 +1179,7 @@ class ThreadsClient:
         if_exists: OnConflictBehavior | None = None,
         supersteps: Sequence[dict[str, Sequence[dict[str, Any]]]] | None = None,
         graph_id: str | None = None,
+        ttl: int | Mapping[str, Any] | None = None,
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> Thread:
@@ -1192,6 +1194,9 @@ class ThreadsClient:
             supersteps: Apply a list of supersteps when creating a thread, each containing a sequence of updates.
                 Each update has `values` or `command` and `as_node`. Used for copying a thread between deployments.
             graph_id: Optional graph ID to associate with the thread.
+            ttl: Optional time-to-live in minutes for the thread. You can pass an
+                integer (minutes) or a mapping with keys `ttl` and optional
+                `strategy` (defaults to "delete").
             headers: Optional custom headers to include with the request.
             params: Optional query parameters to include with the request.
 
@@ -1233,6 +1238,11 @@ class ThreadsClient:
                 }
                 for s in supersteps
             ]
+        if ttl is not None:
+            if isinstance(ttl, (int, float)):
+                payload["ttl"] = {"ttl": ttl, "strategy": "delete"}
+            else:
+                payload["ttl"] = ttl
 
         return await self.http.post(
             "/threads", json=payload, headers=headers, params=params
@@ -1243,6 +1253,7 @@ class ThreadsClient:
         thread_id: str,
         *,
         metadata: Mapping[str, Any],
+        ttl: int | Mapping[str, Any] | None = None,
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> Thread:
@@ -1251,6 +1262,9 @@ class ThreadsClient:
         Args:
             thread_id: ID of thread to update.
             metadata: Metadata to merge with existing thread metadata.
+            ttl: Optional time-to-live in minutes for the thread. You can pass an
+                integer (minutes) or a mapping with keys `ttl` and optional
+                `strategy` (defaults to "delete").
             headers: Optional custom headers to include with the request.
             params: Optional query parameters to include with the request.
 
@@ -1264,12 +1278,19 @@ class ThreadsClient:
             thread = await client.threads.update(
                 thread_id="my-thread-id",
                 metadata={"number":1},
+                ttl=43_200,
             )
             ```
         """  # noqa: E501
+        payload: dict[str, Any] = {"metadata": metadata}
+        if ttl is not None:
+            if isinstance(ttl, (int, float)):
+                payload["ttl"] = {"ttl": ttl, "strategy": "delete"}
+            else:
+                payload["ttl"] = ttl
         return await self.http.patch(
             f"/threads/{thread_id}",
-            json={"metadata": metadata},
+            json=payload,
             headers=headers,
             params=params,
         )
@@ -1308,6 +1329,7 @@ class ThreadsClient:
         *,
         metadata: Json = None,
         values: Json = None,
+        ids: Sequence[str] | None = None,
         status: ThreadStatus | None = None,
         limit: int = 10,
         offset: int = 0,
@@ -1322,6 +1344,7 @@ class ThreadsClient:
         Args:
             metadata: Thread metadata to filter on.
             values: State values to filter on.
+            ids: List of thread IDs to filter by.
             status: Thread status to filter on.
                 Must be one of 'idle', 'busy', 'interrupted' or 'error'.
             limit: Limit on number of threads to return.
@@ -1355,6 +1378,8 @@ class ThreadsClient:
             payload["metadata"] = metadata
         if values:
             payload["values"] = values
+        if ids:
+            payload["ids"] = ids
         if status:
             payload["status"] = status
         if sort_by:
@@ -1684,6 +1709,53 @@ class ThreadsClient:
             params=params,
         )
 
+    async def join_stream(
+        self,
+        thread_id: str,
+        *,
+        last_event_id: str | None = None,
+        stream_mode: ThreadStreamMode | Sequence[ThreadStreamMode] = "run_modes",
+        headers: Mapping[str, str] | None = None,
+        params: QueryParamTypes | None = None,
+    ) -> AsyncIterator[StreamPart]:
+        """Get a stream of events for a thread.
+
+        Args:
+            thread_id: The ID of the thread to get the stream for.
+            last_event_id: The ID of the last event to get.
+            headers: Optional custom headers to include with the request.
+            params: Optional query parameters to include with the request.
+
+        Returns:
+            Iterator[StreamPart]: An iterator of stream parts.
+
+        ???+ example "Example Usage"
+
+            ```python
+
+            for chunk in client.threads.join_stream(
+                thread_id="my_thread_id",
+                last_event_id="my_event_id",
+            ):
+                print(chunk)
+            ```
+
+        """  # noqa: E501
+        query_params = {
+            "stream_mode": stream_mode,
+        }
+        if params:
+            query_params.update(params)
+        return self.http.stream(
+            f"/threads/{thread_id}/stream",
+            "GET",
+            headers={
+                **({"Last-Event-ID": last_event_id} if last_event_id else {}),
+                **(headers or {}),
+            },
+            params=query_params,
+        )
+
 
 class RunsClient:
     """Client for managing runs in LangGraph.
@@ -4280,6 +4352,7 @@ class SyncThreadsClient:
         if_exists: OnConflictBehavior | None = None,
         supersteps: Sequence[dict[str, Sequence[dict[str, Any]]]] | None = None,
         graph_id: str | None = None,
+        ttl: int | Mapping[str, Any] | None = None,
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> Thread:
@@ -4294,6 +4367,9 @@ class SyncThreadsClient:
             supersteps: Apply a list of supersteps when creating a thread, each containing a sequence of updates.
                 Each update has `values` or `command` and `as_node`. Used for copying a thread between deployments.
             graph_id: Optional graph ID to associate with the thread.
+            ttl: Optional time-to-live in minutes for the thread. You can pass an
+                integer (minutes) or a mapping with keys `ttl` and optional
+                `strategy` (defaults to "delete").
             headers: Optional custom headers to include with the request.
 
         Returns:
@@ -4335,6 +4411,11 @@ class SyncThreadsClient:
                 }
                 for s in supersteps
             ]
+        if ttl is not None:
+            if isinstance(ttl, (int, float)):
+                payload["ttl"] = {"ttl": ttl, "strategy": "delete"}
+            else:
+                payload["ttl"] = ttl
 
         return self.http.post("/threads", json=payload, headers=headers, params=params)
 
@@ -4343,6 +4424,7 @@ class SyncThreadsClient:
         thread_id: str,
         *,
         metadata: Mapping[str, Any],
+        ttl: int | Mapping[str, Any] | None = None,
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
     ) -> Thread:
@@ -4351,7 +4433,11 @@ class SyncThreadsClient:
         Args:
             thread_id: ID of thread to update.
             metadata: Metadata to merge with existing thread metadata.
+            ttl: Optional time-to-live in minutes for the thread. You can pass an
+                integer (minutes) or a mapping with keys `ttl` and optional
+                `strategy` (defaults to "delete").
             headers: Optional custom headers to include with the request.
+            params: Optional query parameters to include with the request.
 
         Returns:
             Thread: The created thread.
@@ -4363,12 +4449,19 @@ class SyncThreadsClient:
             thread = client.threads.update(
                 thread_id="my-thread-id",
                 metadata={"number":1},
+                ttl=43_200,
             )
             ```
         """  # noqa: E501
+        payload: dict[str, Any] = {"metadata": metadata}
+        if ttl is not None:
+            if isinstance(ttl, (int, float)):
+                payload["ttl"] = {"ttl": ttl, "strategy": "delete"}
+            else:
+                payload["ttl"] = ttl
         return self.http.patch(
             f"/threads/{thread_id}",
-            json={"metadata": metadata},
+            json=payload,
             headers=headers,
             params=params,
         )
@@ -4406,6 +4499,7 @@ class SyncThreadsClient:
         *,
         metadata: Json = None,
         values: Json = None,
+        ids: Sequence[str] | None = None,
         status: ThreadStatus | None = None,
         limit: int = 10,
         offset: int = 0,
@@ -4420,6 +4514,7 @@ class SyncThreadsClient:
         Args:
             metadata: Thread metadata to filter on.
             values: State values to filter on.
+            ids: List of thread IDs to filter by.
             status: Thread status to filter on.
                 Must be one of 'idle', 'busy', 'interrupted' or 'error'.
             limit: Limit on number of threads to return.
@@ -4449,6 +4544,8 @@ class SyncThreadsClient:
             payload["metadata"] = metadata
         if values:
             payload["values"] = values
+        if ids:
+            payload["ids"] = ids
         if status:
             payload["status"] = status
         if sort_by:
@@ -4772,6 +4869,54 @@ class SyncThreadsClient:
             params=params,
         )
 
+    def join_stream(
+        self,
+        thread_id: str,
+        *,
+        stream_mode: ThreadStreamMode | Sequence[ThreadStreamMode] = "run_modes",
+        last_event_id: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        params: QueryParamTypes | None = None,
+    ) -> Iterator[StreamPart]:
+        """Get a stream of events for a thread.
+
+        Args:
+            thread_id: The ID of the thread to get the stream for.
+            last_event_id: The ID of the last event to get.
+            headers: Optional custom headers to include with the request.
+            params: Optional query parameters to include with the request.
+
+        Returns:
+            Iterator[StreamPart]: An iterator of stream parts.
+
+        ???+ example "Example Usage"
+
+            ```python
+
+            for chunk in client.threads.join_stream(
+                thread_id="my_thread_id",
+                last_event_id="my_event_id",
+                stream_mode="run_modes",
+            ):
+                print(chunk)
+            ```
+
+        """  # noqa: E501
+        query_params = {
+            "stream_mode": stream_mode,
+        }
+        if params:
+            query_params.update(params)
+        return self.http.stream(
+            f"/threads/{thread_id}/stream",
+            "GET",
+            headers={
+                **({"Last-Event-ID": last_event_id} if last_event_id else {}),
+                **(headers or {}),
+            },
+            params=query_params,
+        )
+
 
 class SyncRunsClient:
     """Synchronous client for managing runs in LangGraph.

libs/sdk-py/langgraph_sdk/schema.py

@@ -38,6 +38,14 @@ Represents the status of a thread:
 - "error": An exception occurred during task processing.
 """
 
+ThreadStreamMode = Literal["run_modes", "lifecycle", "state_update"]
+"""
+Defines the mode of streaming:
+- "run_modes": Stream the same events as the runs on thread, as well as run_done events.
+- "lifecycle": Stream only run start/end events.
+- "state_update": Stream state updates on the thread.
+"""
+
 StreamMode = Literal[
     "values",
     "messages",