From 575de221fe98d19939ec4c50fa1154e530d76a07 Mon Sep 17 00:00:00 2001 From: Andrew Nguonly Date: Fri, 28 Mar 2025 14:21:24 -0700 Subject: [PATCH] docs: Update Cloud SaaS and CLI documentation pages (#4077) ### Summary 1. Update API spec. 2. Clarify how to specify `requirements.txt` in `dependencies` list. 3. Clarify deletion policy for database. 4. Clarify resource allocation for `Production` type deployments. 5. Update supported Python versions. --- docs/docs/cloud/reference/api/openapi.json | 305 ++++++++++++++++++++- docs/docs/cloud/reference/cli.md | 4 +- docs/docs/concepts/langgraph_cloud.md | 8 +- 3 files changed, 303 insertions(+), 14 deletions(-) diff --git a/docs/docs/cloud/reference/api/openapi.json b/docs/docs/cloud/reference/api/openapi.json index 3f2c20c9b..6c4b8ab34 100644 --- a/docs/docs/cloud/reference/api/openapi.json +++ b/docs/docs/cloud/reference/api/openapi.json @@ -22,7 +22,7 @@ "description": "A run is an invocation of a graph / assistant, with no state or memory persistence." }, { - "name": "Crons (Enterprise-only)", + "name": "Crons (Plus tier)", "description": "A cron is a periodic run that recurs on a given schedule. The repeats can be isolated, or share state in a thread" }, { @@ -805,6 +805,58 @@ } } }, + "/threads/state/bulk": { + "post": { + "tags": [ + "Threads" + ], + "summary": "Bulk Update Thread State", + "description": "Create a new thread from a batch of state updates.", + "operationId": "bulk_update_thread_state_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ThreadStateBulkUpdate" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Thread" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, "/threads/{thread_id}/state": { "get": { "tags": [ @@ -1342,6 +1394,21 @@ }, "name": "offset", "in": "query" + }, + { + "required": false, + "schema": { + "type": "string", + "enum": [ + "pending", + "error", + "success", + "timeout", + "interrupted" + ] + }, + "name": "status", + "in": "query" } ], "responses": { @@ -1458,7 +1525,7 @@ "/threads/{thread_id}/runs/crons": { "post": { "tags": [ - "Crons (Enterprise-only)" + "Crons (Plus tier)" ], "summary": "Create Thread Cron", "description": "Create a cron to schedule runs on a thread.", @@ -1836,6 +1903,17 @@ }, "name": "run_id", "in": "path" + }, + { + "required": false, + "schema": { + "type": "boolean", + "title": "Cancel on Disconnect", + "description": "If true, the run will be cancelled if the client disconnects.", + "default": false + }, + "name": "cancel_on_disconnect", + "in": "query" } ], "responses": { @@ -2032,7 +2110,7 @@ "/runs/crons": { "post": { "tags": [ - "Crons (Enterprise-only)" + "Crons (Plus tier)" ], "summary": "Create Cron", "description": "Create a cron to schedule runs on new threads.", @@ -2084,7 +2162,7 @@ "/runs/crons/search": { "post": { "tags": [ - "Crons (Enterprise-only)" + "Crons (Plus tier)" ], "summary": "Search Crons", "description": "Search all active crons", @@ -2190,6 +2268,68 @@ } } }, + "/runs/cancel": { + "post": { + "tags": [ + "Thread Runs" + ], + "summary": "Cancel Runs", + "description": "Cancel one or more runs. Can cancel runs by thread ID and run IDs, or by status filter.", + "operationId": "cancel_runs_post", + "parameters": [ + { + "description": "Action to take when cancelling the run. Possible values are `interrupt` or `rollback`. `interrupt` will simply cancel the run. `rollback` will cancel the run and delete the run and associated checkpoints afterwards.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "interrupt", + "rollback" + ], + "title": "Action", + "default": "interrupt" + }, + "name": "action", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RunsCancel" + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "Success - Runs cancelled" + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, "/runs/wait": { "post": { "tags": [ @@ -2373,7 +2513,7 @@ "/runs/crons/{cron_id}": { "delete": { "tags": [ - "Crons (Enterprise-only)" + "Crons (Plus tier)" ], "summary": "Delete Cron", "description": "Delete a cron by ID.", @@ -2936,7 +3076,7 @@ "type": "string", "maxLength": 65536, "minLength": 1, - "format": "uri", + "format": "uri-reference", "title": "Webhook", "description": "Webhook to call after LangGraph API call is done." }, @@ -3216,7 +3356,11 @@ "description": "The command to run.", "properties": { "update": { - "type": "object", + "type": [ + "object", + "array", + "null" + ], "title": "Update", "description": "An update to the state." }, @@ -3226,12 +3370,13 @@ "array", "number", "string", + "boolean", "null" ], "title": "Resume", "description": "A value to pass to an interrupted node." }, - "send": { + "goto": { "anyOf": [ { "$ref": "#/components/schemas/Send" @@ -3242,10 +3387,21 @@ "$ref": "#/components/schemas/Send" } }, + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + }, { "type": "null" } - ] + ], + "title": "Goto", + "description": "Name of the node(s) to navigate to next or node(s) to be executed with a provided input." } } }, @@ -3276,6 +3432,18 @@ { "type": "object" }, + { + "type": "array" + }, + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, { "type": "null" } @@ -3326,7 +3494,7 @@ "type": "string", "maxLength": 65536, "minLength": 1, - "format": "uri", + "format": "uri-reference", "title": "Webhook", "description": "Webhook to call after LangGraph API call is done." }, @@ -3491,6 +3659,18 @@ { "type": "object" }, + { + "type": "array" + }, + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, { "type": "null" } @@ -3541,7 +3721,7 @@ "type": "string", "maxLength": 65536, "minLength": 1, - "format": "uri", + "format": "uri-reference", "title": "Webhook", "description": "Webhook to call after LangGraph API call is done." }, @@ -3840,6 +4020,36 @@ "title": "If Exists", "description": "How to handle duplicate creation. Must be either 'raise' (raise error if duplicate), or 'do_nothing' (return existing thread).", "default": "raise" + }, + "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." + } + } + }, + "supersteps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "updates": { + "type": "array", + "items": { "$ref": "#/components/schemas/ThreadSuperstepUpdate" } + } + }, + "required": ["updates"] + } } }, "type": "object", @@ -4028,6 +4238,43 @@ "title": "ThreadStateUpdate", "description": "Payload for updating the state of a thread." }, + "ThreadSuperstepUpdate": { + "properties": { + "values": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "object" + } + }, + { + "type": "object" + }, + { + "type": "null" + } + ] + }, + "command": { + "anyOf": [ + { + "$ref": "#/components/schemas/Command" + }, + { + "type": "null" + } + ], + "description": "The command associated with the update." + }, + "as_node": { + "type": "string", + "description": "Update the state as if this node had just executed." + } + }, + "required": ["as_node"], + "type": "object" + }, "ThreadStateUpdateResponse": { "properties": { "checkpoint": { @@ -4230,6 +4477,42 @@ }, "description": "Represents a single document or data entry in the graph's Store. Items are used to store cross-thread memories." }, + "RunsCancel": { + "type": "object", + "title": "RunsCancel", + "description": "Payload for cancelling runs.", + "properties": { + "status": { + "type": "string", + "enum": ["pending", "running", "all"], + "title": "Status", + "description": "Filter runs by status to cancel. Must be one of 'pending', 'running', or 'all'." + }, + "thread_id": { + "type": "string", + "format": "uuid", + "title": "Thread Id", + "description": "The ID of the thread containing runs to cancel." + }, + "run_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "title": "Run Ids", + "description": "List of run IDs to cancel." + } + }, + "oneOf": [ + { + "required": ["status"] + }, + { + "required": ["thread_id", "run_ids"] + } + ] + }, "SearchItemsResponse": { "type": "object", "required": [ diff --git a/docs/docs/cloud/reference/cli.md b/docs/docs/cloud/reference/cli.md index d087793de..aa4c3fd43 100644 --- a/docs/docs/cloud/reference/cli.md +++ b/docs/docs/cloud/reference/cli.md @@ -42,12 +42,12 @@ The LangGraph CLI requires a JSON configuration file with the following keys: | Key | Description | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `dependencies` | **Required**. Array of dependencies for LangGraph Cloud API server. Dependencies can be one of the following: (1) `"."`, which will look for local Python packages, (2) `pyproject.toml`, `setup.py` or `requirements.txt` in the app directory `"./local_package"`, or (3) a package name. | + | `dependencies` | **Required**. Array of dependencies for LangGraph Cloud API server. Dependencies can be one of the following: | | `graphs` | **Required**. Mapping from graph ID to path where the compiled graph or a function that makes a graph is defined. Example: | | `auth` | _(Added in v0.0.11)_ Auth configuration containing the path to your authentication handler. Example: `./your_package/auth.py:auth`, where `auth` is an instance of `langgraph_sdk.Auth`. See [authentication guide](../../concepts/auth.md) for details. | | `env` | Path to `.env` file or a mapping from environment variable to its value. | | `store` | Configuration for adding semantic search to the BaseStore. Contains the following fields: | - | `python_version` | `3.11` or `3.12`. Defaults to `3.11`. | + | `python_version` | `3.11`, `3.12`, or `3.13`. Defaults to `3.11`. | | `node_version` | Specify `node_version: 20` to use LangGraph.js. | | `pip_config_file` | Path to `pip` config file. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | diff --git a/docs/docs/concepts/langgraph_cloud.md b/docs/docs/concepts/langgraph_cloud.md index b30f4a1ad..4ca3df20a 100644 --- a/docs/docs/concepts/langgraph_cloud.md +++ b/docs/docs/concepts/langgraph_cloud.md @@ -19,6 +19,10 @@ Resource Allocation: | Development | 1 CPU | 1 GB | Up to 1 container | | Production | 2 CPU | 2 GB | Up to 10 containers | +CPU and memory resources are per container. + +For **Production type** deployments, resources can be manually increased on a case-by-case basis depending on use case and capacity constraints. Contact support@langchain.dev to request an increase in resources. + See the [how-to guide](../cloud/deployment/cloud.md#create-new-deployment) for creating a new deployment. ## Revision @@ -35,6 +39,8 @@ When defining a graph to be deployed to LangGraph Cloud SaaS, a [checkpointer](. There is no direct access to the database. All access to the database occurs through the LangGraph Server APIs. +The database is never deleted until the deployment itself is deleted. See [Automatic Deletion](#automatic-deletion) for additional details. + ## Autoscaling `Production` type deployments automatically scale up to 10 containers. Scaling is based on the current request load for a single container. Specifically, the autoscaling implementation scales the deployment so that each container is processing about 10 concurrent requests. For example... @@ -57,7 +63,7 @@ Infrastructure for [deployments](#deployment) and [revisions](#revision) are pro ## LangSmith Integration -A [LangSmith](https://docs.smith.langchain.com/) tracing project is automatically created for each deployemnt. The tracing project has the same name as the deployment. When creating a deployment, the `LANGCHAIN_TRACING_V2` and `LANGCHAIN_API_KEY` environment variables do not need to be specified; they are set internally, automatically. Traces are created for each run and are emitted to the tracing project automatically. +A [LangSmith](https://docs.smith.langchain.com/) tracing project is automatically created for each deployemnt. The tracing project has the same name as the deployment. When creating a deployment, the `LANGCHAIN_TRACING` and `LANGSMITH_API_KEY`/`LANGCHAIN_API_KEY` environment variables do not need to be specified; they are set internally, automatically. Traces are created for each run and are emitted to the tracing project automatically. When a deployment is deleted, the traces and the tracing project are not deleted.