diff --git a/README.md b/README.md index b49d56d35..0ef2a2765 100644 --- a/README.md +++ b/README.md @@ -215,4 +215,5 @@ final_state["messages"][-1].content * [Tutorials](https://langchain-ai.github.io/langgraph/tutorials/): Learn to build with LangGraph through guided examples. * [How-to Guides](https://langchain-ai.github.io/langgraph/how-tos/): Accomplish specific things within LangGraph, from streaming, to adding memory & persistence, to common design patterns (branching, subgraphs, etc.), these are the place to go if you want to copy and run a specific code snippet. * [Conceptual Guides](https://langchain-ai.github.io/langgraph/concepts/): In-depth explanations of the key concepts and principles behind LangGraph, such as nodes, edges, state and more. -* [API Reference](https://langchain-ai.github.io/langgraph/reference/graphs/): Review important classes and methods, simple examples of how to use the graph and checkpointing APIs, higher-level prebuilt components and more. \ No newline at end of file +* [API Reference](https://langchain-ai.github.io/langgraph/reference/graphs/): Review important classes and methods, simple examples of how to use the graph and checkpointing APIs, higher-level prebuilt components and more. +* [Cloud (alpha)](https://langchain-ai.github.io/langgraph/cloud/): With one click, deploy LangGraph applications to LangGraph Cloud. diff --git a/docs/docs/cloud/concepts/index.md b/docs/docs/cloud/concepts/index.md index 5185cdcbf..267970061 100644 --- a/docs/docs/cloud/concepts/index.md +++ b/docs/docs/cloud/concepts/index.md @@ -52,10 +52,10 @@ There are many occasions where the graph cannot run completely autonomously. For ### Double Texting Many times users might interact with your graph in unintended ways. For instance, a user may send one message and before the graph has finished running send a second message. To solve this issue of "double-texting" (i.e. prompting the graph a second time before the first run has finished), Langgraph has provided four different solutions, all of which are covered in the [Double Texting how-tos](../how-tos/cloud_examples/interrupt_concurrent/). These options are: -- `reject`: This is the simplest option, this just rejects any follow up runs and does not allow double texting. -- `enqueue`: This is a relatively simple option which continues the first run until it completes the whole run, then sends the new input as a separate run. -- `interrupt`: This option interrupts the current execution but saves all the work done up until that point. It then inserts the user input and continues from there. If you enable this option, your graph should be able to handle weird edge cases that may arise. -- `rollback`: This option rolls back all work done up until that point. It then sends the user input in, basically as if it just followed the original run input. +- `reject`: This is the simplest option, this just rejects any follow up runs and does not allow double texting. See the [How-to Guide](../how-tos/cloud_examples/reject_concurrent/) for configuring the reject double text option. +- `enqueue`: This is a relatively simple option which continues the first run until it completes the whole run, then sends the new input as a separate run. See the [How-to Guide](../how-tos/cloud_examples/enqueue_concurrent/) for configuring the enqueue double text option. +- `interrupt`: This option interrupts the current execution but saves all the work done up until that point. It then inserts the user input and continues from there. If you enable this option, your graph should be able to handle weird edge cases that may arise. See the [How-to Guide](../how-tos/cloud_examples/interrupt_concurrent/) for configuring the interrupt double text option. +- `rollback`: This option rolls back all work done up until that point. It then sends the user input in, basically as if it just followed the original run input. See the [How-to Guide](../how-tos/cloud_examples/rollback_concurrent/) for configuring the rollback double text option. ### Stateless Runs @@ -72,4 +72,12 @@ The only difference is in stateless background runs, if the task worker dies hal - whereas a stateful background run would retry from the last successful checkpoint - a stateless background run would retry from the beginning -See the [How-to Guide](../how-tos/cloud_examples/stateless_runs/) for creating stateless runs. \ No newline at end of file +See the [How-to Guide](../how-tos/cloud_examples/stateless_runs/) for creating stateless runs. + +## Deployment + +The LangGraph Cloud offers several features to support secure and robost deployments. + +### Authentication + +LangGraph applications deployed to LangGraph Cloud are automatically configured with LangSmith authentication. In order to call the API, a valid LangSmith API key is required. diff --git a/docs/docs/cloud/deployment/cloud.md b/docs/docs/cloud/deployment/cloud.md index 238f0d167..0d136d04b 100644 --- a/docs/docs/cloud/deployment/cloud.md +++ b/docs/docs/cloud/deployment/cloud.md @@ -21,7 +21,7 @@ Starting from the LangSmi 1. Select the desired `Deployment Type`. 1. `Development` deployments are meant for non-production use cases and are provisioned with minimal resources. 1. `Production` deployments can serve up to 500 requests/second and are provisioned with highly available storage with automatic backups. - 1. Specify `Environment Variables` and secrets. + 1. Specify `Environment Variables` and secrets. See the [Environment Variables reference](../reference/env_var.md) to configure additional variables for the deployment. 1. Sensitive values such as API keys (e.g. `OPENAI_API_KEY`) should be specified as secrets. 1. Additional non-secret environment variables can be specified as well. 1. A new LangSmith `Tracing Project` is automatically created with the same name as the deployment. @@ -39,7 +39,7 @@ Starting from the LangSmi 1. In the `New Revision` modal, fill out the required fields. 1. Specify the full path to the [LangGraph API config file](../reference/cli.md#configuration-file) including the file name. For example, if the file `langgraph.json` is in the root of the repository, simply specify `langgraph.json`. 1. Specify the desired `git` reference (e.g. branch name). For example, different branches of the repository can be deployed. - 1. Specify `Environment Variables` and secrets. Existing secrets and environment variables are prepopulated. + 1. Specify `Environment Variables` and secrets. Existing secrets and environment variables are prepopulated. See the [Environment Variables reference](../reference/env_var.md) to configure additional variables for the revision. 1. Add new secrets or environment variables. 1. Remove existing secrets or environment variables. 1. Update the value of existing secrets or environment variables. diff --git a/docs/docs/cloud/deployment/managed.md b/docs/docs/cloud/deployment/managed.md deleted file mode 100644 index 4134d0fb9..000000000 --- a/docs/docs/cloud/deployment/managed.md +++ /dev/null @@ -1,157 +0,0 @@ -# Deploy custom LangGraph code with LangGraph Cloud (Python) - -## Set up your application code - -### Create a new application - -To create a new app called create a directory with the following structure - -``` -/ -|-- agent.py # code for your LangGraph agent -|-- requirements.txt # python packages required for your graph -|-- langgraph.json # configuration file for langgraph -|-- .env # environment files with API keys -``` - -### Agent File - -In your agent file, you can define as many graphs (agents) as you would like. For our example we are going to create the simplest graph possible: a one node graph. You can read about adding more complexity to your graphs in the [docs](https://langchain-ai.github.io/langgraph/tutorials/introduction/). - -Here is what our `agent.py` file looks like for this example: - -```python -from langchain_openai import ChatOpenAI -from langgraph.graph import END, MessageGraph - -model = ChatOpenAI(temperature=0) - -graph_workflow = MessageGraph() - -graph_workflow.add_node("oracle", model) -graph_workflow.add_edge("oracle", END) - -graph_workflow.set_entry_point("oracle") -graph = graph_workflow.compile() -``` - -### Configuration file - -- `langgraph.json` is a configuration file with three parts: - - `graphs` - - Pass in the graphs you want to host on your deployment, using the graph_id as the key and the path to the agent (a CompiledGraph) as the value. In our example we only use one graph, so the json looks like so: - - ```json - "graphs": { - "agent": "./agent.py:graph" - }, - ``` - - - `dependencies` - - Pass in a list of the dependencies you would like to be installed in order to host your app. In our case, we don’t need any additional dependencies besides our `requirements.txt` file, but if we did we could append them to the dependencies list using the names of the additional packages we want installed. - - ```json - "dependencies": ["."], - ``` - - - `env` - - This is simply a path to our environment file containing all variables/files to load. - - ```json - "env": ".env" - ``` - - -Putting it all together, our `langgraph.json` file should look like this: - -```json -{ - "dependencies": ["."], - "graphs": { - "agent": "./agent.py:agent" - }, - "env": ".env" -} -``` - -### Environment and Package Requirement files - -- The `.env` contains any environment variables that are needed to run your code. In our example the file looks like follows: - -```python -OPENAI_API_KEY= ... -LANGCHAIN_API_KEY= ... -LANGCHAIN_TRACING_V2=true -``` - -- The `requirements.txt` file lists python package dependencies for your project (along with the associated versions if necessary). In our example the file looks like this: - - ``` - langgraph - langchain_openai - ``` - -### Push your code to GitHub - -Create a git repo in the `` directory, and verify it’s existence. You can use the GitHub CLI if you like, or just create a repo manually. - -## Host your code on LangGraph Cloud - -### Deploy from GitHub with LangGraph Cloud - -Head to LangSmith and click on the 🚀 icon on the left navbar to create a new deployment. Click the `+ New Deployment` button. - -***If you have not deployed to LangGraph Cloud before:*** there will be a button that shows up saying Import from GitHub. You’ll need to follow that flow to connect LangGraph Cloud to GitHub. - -***Once you have set up your GitHub connection:*** the new deployment page will look as follows - -![Screenshot 2024-06-11 at 1.17.03 PM.png](./img/deployment_page.png) - -To deploy your application, you should do the following: - -1. Select your GitHub username or organization from the selector -2. Search for your repo to deploy in the search bar and select it -3. Choose any name -4. In the `LangGraph API config file` field, enter the path to your `langgraph.json` file (if left blank langsmith will automatically search for it on deployment) -5. For Git Reference, you can select either the git branch for the code you want to deploy, or the exact commit SHA. -6. If your chain relies on environment variables (for example, an OPENAI_API_KEY), add those in. They will be propagated to the underlying server so your code can access them. - -Putting this all together, you should have something as follows for your deployment details: - -![Screenshot 2024-06-11 at 1.21.52 PM.png](./img/deploy_filled_out.png) - -Hit `Submit` and your application will start deploying! - -## Inspect Traces + Monitor Service - -### Deployments View - -After your deployment is complete, your deployments page should look as follows: - -![Screenshot 2024-06-11 at 2.03.34 PM.png](./img/deployed_page.png) - -You can see that by default, you get access to the `Trace Count` monitoring chart and `Recent Traces` run view. These are powered by LangSmith. - -You can click on `All Charts` to view all monitoring info for your server, or click on `See tracing project` to get more information on an individual trace. - -### Access the Docs - -You can access the docs by clicking on the API DOCS link, which should send you to a page that looks like this: - -![Screenshot 2024-06-19 at 2.27.24 PM.png](./img/api_page.png) - -You won’t actually be able to test any of the API endpoints without authorizing first. To do so, click on the Authorize button in the top right corner, input your `LANGCHAIN_API_KEY` in the `API Key` box, and then click `Authorize` to finish the process. You should now be able to select any of the API endpoints, click `Try it out` , enter the parameters you would like to pass, and then click `Execute` to view the results of the API call. - -## Interact with your deployment via LangGraph Studio - -### Access Studio - -If you click on your deployment you should see a blue button in the top right that says `LangGraph Studio`. Clicking on this button will take you to a page that looks like this: - -![Screenshot 2024-06-11 at 2.51.51 PM.png](./img/graph_visualiztion) - -On this page you can test out your graph by passing in starting states and clicking `Start Run` (this should behave identically to calling `.invoke`). You will then be able to look into the execution thread for each run and explore the steps your graph is taking to produce its output. - -## Deploy new code - -To deploy new code that you push to GitHub, simply navigate to the deployments page, and hit `+ New Revision`. LangGraph Cloud releases what it calls a new “revision” every time you deploy code. Therefore, your first deployment automatically showed revisions. A Revision always corresponds to a new piece of code being deployed. A modal will pop up to enter new revision info. This can be thought of as a partial update on the last revision, so you do not need to enter any fields that didn’t change (*note: environment variables are not saved between revisions, you must re-enter them for each new revision)*. \ No newline at end of file diff --git a/docs/docs/cloud/deployment/setup.md b/docs/docs/cloud/deployment/setup.md index f1d486f03..c76a5e3d9 100644 --- a/docs/docs/cloud/deployment/setup.md +++ b/docs/docs/cloud/deployment/setup.md @@ -22,7 +22,7 @@ my-app/ ## Specify Environment Variables -Environment variables can optionally be specified in a file (e.g. `.env`). +Environment variables can optionally be specified in a file (e.g. `.env`). See the [Environment Variables reference](../reference/env_var.md) to configure additional variables for a deployment. Example `.env` file: ``` @@ -57,6 +57,9 @@ graph_workflow.set_entry_point("agent") agent = graph_workflow.compile() ``` +!!! warning "Assign `CompiledGraph` to Variable" + The build process for LangGraph Cloud requires that the `CompiledGraph` object be assigned to a variable at the top-level of a Python module. + Example file directory: ``` my-app/ @@ -84,6 +87,8 @@ Example `langgraph.json` file: } ``` +Note that the variable name of the `CompiledGraph` appears at the end of the value of each subkey in the top-level `graphs` key (i.e. `:`). + Example file directory: ``` my-app/ diff --git a/docs/docs/cloud/index.md b/docs/docs/cloud/index.md index 66f9c9810..6b7276420 100644 --- a/docs/docs/cloud/index.md +++ b/docs/docs/cloud/index.md @@ -28,6 +28,6 @@ The LangGraph Cloud API supports key LangGraph features in addition to new funct ## Documentation - [Tutorials](./quick_start.md): Learn to build and deploy applications for LangGraph Cloud. -- [How-to Guides](./how-tos/cloud_examples/stream_values/): Implement specific features of the LangGraph Cloud API such as streaming tokens, configuring double texting, and creating cron jobs. Go here if you want to copy and run a specific code snippet. +- [How-to Guides](./deployment/setup/): Learn how to set up a LangGraph application for deployment and implement features of the LangGraph Cloud API such as streaming tokens, configuring double texting, and creating cron jobs. Go here if you want to copy and run a specific code snippet. - [Conceptual Guides](./concepts/): In-depth explanations of the core data models (e.g. assistants) and key features (e.g. double texting) of the LangGraph Cloud API. -- [Reference](./reference/api/api_ref.md): References for the LangGraph Cloud API, the corresponding Python and JS/TS SDKs, and the LangGraph CLI. +- [Reference](./reference/api/api_ref.md): References for the LangGraph Cloud API, the corresponding Python and JS/TS SDKs, the LangGraph CLI, and deployment environment variables. diff --git a/docs/docs/cloud/reference/cli.md b/docs/docs/cloud/reference/cli.md index 52c2551d4..a01e949a6 100644 --- a/docs/docs/cloud/reference/cli.md +++ b/docs/docs/cloud/reference/cli.md @@ -1,5 +1,5 @@ # LangGraph CLI -The LangGraph CLI includes commands to build and run a LangGraph Cloud server locally in [Docker](https://www.docker.com/). For development and testing, use the CLI to deploy a local API server. +The LangGraph CLI includes commands to build and run a LangGraph Cloud API server locally in [Docker](https://www.docker.com/). For development and testing, use the CLI to deploy a local API server. ## Installation 1. Ensure that Docker is installed (e.g. `docker --version`). @@ -11,7 +11,7 @@ The LangGraph CLI requires a JSON configuration file with the following keys: | Key | Description | | --- | ----------- | -| `dependencies` | **Required**. Array of dependencies for LangGraph Deploy 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: (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. | | `graphs` | **Required**. Mapping from graph ID to path where the compiled graph is defined. Example: `./your_package/your_file.py:variable`, where `variable` is an instance of `langgraph.graph.graph.CompiledGraph`. | | `env` | Path to `.env` file or a mapping from environment variable to its value. | | `python_version` | `3.11` or `3.12`. Defaults to `3.11`. | @@ -65,7 +65,7 @@ langgraph [OPTIONS] COMMAND [ARGS] ``` ### `build` -Build LangGraph Deploy API server Docker image. +Build LangGraph Cloud API server Docker image. **Usage** ``` @@ -78,12 +78,12 @@ langgraph build [OPTIONS] | ------ | ------- | ----------- | | `--platform TEXT` | | Target platform(s) to build the Docker image for. Example: `langgraph build --platform linux/amd64,linux/arm64` | | `-t, --tag TEXT` | | **Required**. Tag for the Docker image. Example: `langgraph build -t my-image` | -| `--pull / --no-pull` | `--pull` | Build with latest remote Docker image. Use `--no-pull` for running the LangGraph Deploy API server with locally built images. | +| `--pull / --no-pull` | `--pull` | Build with latest remote Docker image. Use `--no-pull` for running the LangGraph Cloud API server with locally built images. | | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | | `--help` | | Display command documentation. | ### `down` -Stop LangGraph Deploy API server. +Stop LangGraph Cloud API server. **Usage** ``` @@ -102,7 +102,7 @@ langgraph down [OPTIONS] | `--help` | | Display command documentation. | ### `logs` -Show LangGraph Deploy API server logs. +Show LangGraph Cloud API server logs. **Usage** ``` @@ -119,7 +119,7 @@ langgraph logs [OPTIONS] | `--help` | | Display command documentation. | ### `up` -Start LangGraph Deploy API server. +Start LangGraph Cloud API server. **Usage** ``` @@ -137,6 +137,6 @@ langgraph up [OPTIONS] | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | | `-d, --docker-compose FILE` | | Advanced. Path to `docker-compose.yml` file with additional services to launch. | | `-p, --port INTEGER` | `8123` | Port to expose. Example: `langgraph up --port 8000` | -| `--pull / --no-pull` | `--pull` | Build with latest remote Docker image. Use `--no-pull` for running the LangGraph Deploy API server with locally built images. | +| `--pull / --no-pull` | `--pull` | Build with latest remote Docker image. Use `--no-pull` for running the LangGraph Cloud API server with locally built images. | | `--recreate / --no-recreate` | `--no-recreate` | Recreate containers even if their configuration and image haven't changed. | | `--help` | | Display command documentation. | diff --git a/docs/docs/cloud/reference/env_var.md b/docs/docs/cloud/reference/env_var.md new file mode 100644 index 000000000..820af41ec --- /dev/null +++ b/docs/docs/cloud/reference/env_var.md @@ -0,0 +1,13 @@ +# Environment Variables + +The LangGraph Cloud API supports specific environment variables for configuring a deployment. + +## `LANGGRAPH_AUTH_TYPE` + +Type of authentication for the LangGraph Cloud API deployment. Valid values: `langsmith`, `noop`. + +For deployments to LangGraph Cloud, this environment variable is set automatically. For local development or deployments where authentication is handled externally (e.g. self-hosted), set this environment variable to `noop`. + +## `N_JOBS_PER_WORKER` + +Number of jobs per worker for the LangGraph Cloud task queue. Defaults to `10`. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f0bdefc30..0280eee6e 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -214,6 +214,7 @@ nav: - Python: 'cloud/reference/sdk/python_sdk_ref.md' - JS/TS: 'cloud/reference/sdk/js_ts_sdk_ref.md' - CLI: 'cloud/reference/cli.md' + - Environment Variables: 'cloud/reference/env_var.md' markdown_extensions: diff --git a/examples/cloud_examples/enqueue_concurrent.ipynb b/examples/cloud_examples/enqueue_concurrent.ipynb index 61c76e6f8..c12b7b4d4 100644 --- a/examples/cloud_examples/enqueue_concurrent.ipynb +++ b/examples/cloud_examples/enqueue_concurrent.ipynb @@ -6,7 +6,9 @@ "source": [ "## Enqueue\n", "\n", - "There are several strategies for handling concurrent runs in your graph. This notebook covers how to use the `enqueue` option - please see the other how-to guides in the \"Double Texting\" directory to learn about the other methods.\n", + "This notebook assumes knowledge of what double-texting is, which you can learn about in the [double-texting conceptual guide](https://langchain-ai.github.io/langgraph/cloud/concepts/#double-texting).\n", + "\n", + "The guide covers the `enqueue` option for double texting, which adds the interruptions to a queue and executes them in the order they are received by the client. Below is a quick example of using the `enqueue` option.\n", "\n", "First, let's import our required packages and instantiate our client, assistant, and thread." ] diff --git a/examples/cloud_examples/interrupt_concurrent.ipynb b/examples/cloud_examples/interrupt_concurrent.ipynb index c142bcd17..fe589816b 100644 --- a/examples/cloud_examples/interrupt_concurrent.ipynb +++ b/examples/cloud_examples/interrupt_concurrent.ipynb @@ -6,7 +6,9 @@ "source": [ "## Interrupt\n", "\n", - "There are several strategies for handling concurrent runs in your graph. This notebook covers how to use the `interrupt` option - please see the other how-to guides in the \"Double Texting\" directory to learn about the other methods.\n", + "This notebook assumes knowledge of what double-texting is, which you can learn about in the [double-texting conceptual guide](https://langchain-ai.github.io/langgraph/cloud/concepts/#double-texting).\n", + "\n", + "The guide covers the `interrupt` option for double texting, which interrupts the prior run of the graph and starts a new one with the double-text. This option does not delete the first run, but rather keeps it in the database but sets its status to `interrupted`. Below is a quick example of using the `interrupt` option.\n", "\n", "First, let's import our required packages and instantiate our client, assistant, and thread." ] diff --git a/examples/cloud_examples/reject_concurrent.ipynb b/examples/cloud_examples/reject_concurrent.ipynb index 4f8f1d97d..ed362b561 100644 --- a/examples/cloud_examples/reject_concurrent.ipynb +++ b/examples/cloud_examples/reject_concurrent.ipynb @@ -6,7 +6,9 @@ "source": [ "## Reject\n", "\n", - "There are several strategies for handling concurrent runs in your graph. This notebook covers how to use the `reject` option - please see the other how-to guides in the \"Double Texting\" directory to learn about the other methods.\n", + "This notebook assumes knowledge of what double-texting is, which you can learn about in the [double-texting conceptual guide](https://langchain-ai.github.io/langgraph/cloud/concepts/#double-texting).\n", + "\n", + "The guide covers the `reject` option for double texting, which rejects the new run of the graph by throwing an error and continues with the original run until completion. Below is a quick example of using the `reject` option.\n", "\n", "First, let's import our required packages and instantiate our client, assistant, and thread." ] diff --git a/examples/cloud_examples/rollback_concurrent.ipynb b/examples/cloud_examples/rollback_concurrent.ipynb index 3c24fb273..da5f95876 100644 --- a/examples/cloud_examples/rollback_concurrent.ipynb +++ b/examples/cloud_examples/rollback_concurrent.ipynb @@ -6,7 +6,9 @@ "source": [ "## Rollback\n", "\n", - "There are several strategies for handling concurrent runs in your graph. This notebook covers how to use the `rollback` option - please see the other how-to guides in the \"Double Texting\" directory to learn about the other methods.\n", + "This notebook assumes knowledge of what double-texting is, which you can learn about in the [double-texting conceptual guide](https://langchain-ai.github.io/langgraph/cloud/concepts/#double-texting).\n", + "\n", + "The guide covers the `rollback` option for double texting, which interrupts the prior run of the graph and starts a new one with the double-text. This option is very similar to the `interrupt` option, but in this case the first run is completely deleted from the database and cannot be restarted. Below is a quick example of using the `rollback` option.\n", "\n", "First, let's import our required packages and instantiate our client, assistant, and thread." ]