From 17785375b8a23d57cfc028645233658678453e58 Mon Sep 17 00:00:00 2001 From: Isaac Francisco <78627776+isahers1@users.noreply.github.com> Date: Tue, 9 Jul 2024 18:22:11 -0700 Subject: [PATCH] [docs]: adding LangGraph up documentation (#975) * first draft * harrison comments --- docs/docs/cloud/concepts/index.md | 6 +- docs/docs/cloud/deployment/test_locally.md | 91 +++++++++++++++++++ .../how-tos/human_in_the_loop_breakpoint.md | 2 +- .../how-tos/human_in_the_loop_time_travel.md | 2 +- docs/docs/cloud/quick_start.md | 8 +- docs/docs/cloud/reference/cli.md | 25 +++++ docs/mkdocs.yml | 1 + examples/cloud_examples/webhooks.ipynb | 2 +- examples/introduction.ipynb | 14 +-- 9 files changed, 136 insertions(+), 15 deletions(-) create mode 100644 docs/docs/cloud/deployment/test_locally.md diff --git a/docs/docs/cloud/concepts/index.md b/docs/docs/cloud/concepts/index.md index 4d0794328..071f5bdbb 100644 --- a/docs/docs/cloud/concepts/index.md +++ b/docs/docs/cloud/concepts/index.md @@ -63,7 +63,7 @@ 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/index.md#double-texting). These options are: +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/index.md#double-texting). These options are: - `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/reject_concurrent.md) 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/enqueue_concurrent.md) for configuring the enqueue double text option. @@ -101,3 +101,7 @@ The LangGraph Cloud offers several features to support secure and robost deploym ### 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. + +### Local Testing + +Before deploying your app in production to LangGraph Cloud, you may wish to test out your graph locally in order to ensure that everything is running as expected. Luckily, LangGraph makes this easy for you through use of the LangGraph CLI. Read more in this [how-to guide](../deployment/test_locally.md) or look at the [CLI reference](../reference/cli.md) to learn more. \ No newline at end of file diff --git a/docs/docs/cloud/deployment/test_locally.md b/docs/docs/cloud/deployment/test_locally.md new file mode 100644 index 000000000..99c1bbcdb --- /dev/null +++ b/docs/docs/cloud/deployment/test_locally.md @@ -0,0 +1,91 @@ +# How to test a LangGraph app locally + +This guide assumes you have a LangGraph app correctly set up with a proper configuration file and a corresponding compiled graph, and that you have a proper LangChain API key. + +## Setup + +Install the proper packages: + +```shell +pip install langgraph-cli +``` + +## Start the API server + +Once you have downloaded the CLI, you can run the following command to start the API server for local testing: + +```shell +langgraph up +``` + +This will start up the LangGraph API server locally. If this runs successfully, you should see something like: + +```shell +Ready! +- API: http://localhost:8123 +2024-06-26 19:20:41,056:INFO:uvicorn.access 127.0.0.1:44138 - "GET /ok HTTP/1.1" 200 +``` + +### Interact with the server + +We can now interact with the API server using the LangGraph SDK. First, we need to start our client, select our assistant (in this case a graph we called "agent", make sure to select the proper assistant you wish to test). + +=== "Python" + + ```python + from langgraph_sdk import get_client + + # only pass the url argument to get_client() if you changed the default port when calling langgraph up + client = get_client() + assistant_id = "agent" + thread = await client.threads.create() + ``` + +=== "Javascript" + + ```js + import { Client } from "@langchain/langgraph-sdk"; + + // only set the apiUrl if you changed the default port when calling langgraph up + const client = new Client(); + const assistantId = "agent" + const thread = await client.threads.create(); + ``` + +Now we can invoke our graph to ensure it is working. Make sure to change the input to match the proper schema for your graph. + +=== "Python" + + ```python + input = {"messages": [{"role": "human", "content": "what's the weather in sf"}]} + async for chunk in client.runs.stream( + thread["thread_id"], + assistant_id, + input=input, + stream_mode="updates", + ): + print(f"Receiving new event of type: {chunk.event}...") + print(chunk.data) + print("\n\n") + ``` +=== "Javascript" + + ```js + const input = { "messages": [{ "role": "human", "content": "what's the weather in sf"}] } + + const streamResponse = client.runs.stream( + thread["thread_id"], + assistantId, + { + input: input, + streamMode: "updates", + } + ); + for await (const chunk of streamResponse) { + console.log(`Receiving new event of type: ${chunk.event}...`); + console.log(chunk.data); + console.log("\n\n"); + } + ``` + +If your graph works correctly, you should see your graph output displayed in the console. Of course, there are many more ways you might need to test your graph, for a full list of commands you can send with the SDK, see the [Python](https://langchain-ai.github.io/langgraph/cloud/reference/sdk/python_sdk_ref/) and [JS/TS](https://langchain-ai.github.io/langgraph/cloud/reference/sdk/js_ts_sdk_ref/) references. \ No newline at end of file diff --git a/docs/docs/cloud/how-tos/human_in_the_loop_breakpoint.md b/docs/docs/cloud/how-tos/human_in_the_loop_breakpoint.md index d06388e59..908d9fa9e 100644 --- a/docs/docs/cloud/how-tos/human_in_the_loop_breakpoint.md +++ b/docs/docs/cloud/how-tos/human_in_the_loop_breakpoint.md @@ -43,7 +43,7 @@ We can do this by adding `interrupt_before=["action"]`, which tells us to interr We can do this either when compiling the graph or when kicking off a run. Here we will do it when kicking of a run, if you would like to to do it at compile time you need to edit the python file where your graph is defined and add the `interrupt_before` parameter when you call `.compile`. -First let's access our hosted Langgraph instance through the SDK: +First let's access our hosted LangGraph instance through the SDK: And, now let's compile it with a breakpoint before the tool node: diff --git a/docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md b/docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md index 9999899ba..0c6df0910 100644 --- a/docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md +++ b/docs/docs/cloud/how-tos/human_in_the_loop_time_travel.md @@ -1,6 +1,6 @@ # How to Replay and Branch from Prior States -With Langgraph Cloud you have the ability to return to any of your prior states and either re-run the graph to reproduce issues noticed during testing, or branch out in a different way from what was originally done in the prior states. In this guide we will show a quick example of how to rerun past states and how to branch off from previous states as well. +With LangGraph Cloud you have the ability to return to any of your prior states and either re-run the graph to reproduce issues noticed during testing, or branch out in a different way from what was originally done in the prior states. In this guide we will show a quick example of how to rerun past states and how to branch off from previous states as well. ## Setup diff --git a/docs/docs/cloud/quick_start.md b/docs/docs/cloud/quick_start.md index 17536e4f3..65e51b26d 100644 --- a/docs/docs/cloud/quick_start.md +++ b/docs/docs/cloud/quick_start.md @@ -74,13 +74,13 @@ In order to do this we can first install the LangGraph CLI pip install langgraph-cli ``` -We can then stand up a simple test server. The server this stands up is INCREDIBLY simple - it is just a single endpoint and has no persistence. **This should not be used for hosting your application, only for testing the build and basic functionality.** +We can then test our API server locally. This requires access to LangGraph closed beta. In order to run the server locally, you will need to add your `LANGCHAIN_API_KEY` to the .env file so we can validate you have access to LangGraph closed beta. ```shell -langgraph test +langgraph up ``` -This will test building of the agent server. If this runs successfully, you should see something like: +This will start up the LangGraph API server locally. If this runs successfully, you should see something like: ```shell Ready! @@ -88,7 +88,7 @@ Ready! 2024-06-26 19:20:41,056:INFO:uvicorn.access 127.0.0.1:44138 - "GET /ok HTTP/1.1" 200 ``` -You can now test this out! Again, we only expose a single simple endpoint (for streaming stateless runs). This is intended to allow you to test that the agent is properly set up, but should **NOT** but used for production purposes. To test it out, you can go to another terminal window and run: +You can now test this out! **Note: this local server is intended SOLELY for local testing purposes and is not performant enough for production applications, so please do not use it as such.** To test it out, you can go to another terminal window and run: ```shell curl --request POST \ diff --git a/docs/docs/cloud/reference/cli.md b/docs/docs/cloud/reference/cli.md index 815294040..5e77ad113 100644 --- a/docs/docs/cloud/reference/cli.md +++ b/docs/docs/cloud/reference/cli.md @@ -83,6 +83,31 @@ langgraph build [OPTIONS] | `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | | `--help` | | Display command documentation. | +### `up` +Start langgraph API server. For local testing, requires a LangSmith API key with access to LangGraph Cloud closed beta. Requires a license key for production use. + +**Usage** +``` +langgraph up [OPTIONS] +``` + +**Options** + +| Option | Default | Description | +| ------ | ------- | ----------- | +| `--wait` | | Wait for services to start before returning. Implies --detach | +| `--postgres-uri TEXT` | Local database | Postgres URI to use for the database. | +| `--watch` | | Restart on file changes | +| `--debugger-base-url TEXT` | `http://127.0.0.1:[PORT]` | URL used by the debugger to access LangGraph API. | +| `--debugger-port INTEGER` | | Pull the debugger image locally and serve the UI on specified port | +| `--verbose` | | Show more output from the server logs. | +| `-c, --config FILE` | `langgraph.json` | Path to configuration file declaring dependencies, graphs and environment variables. | +| `-d, --docker-compose FILE` | | Path to docker-compose.yml file with additional services to launch. | +| `-p, --port INTEGER` | `8123` | Port to expose. Example: `langgraph test --port 8000` | +| `--pull / --no-pull` | `pull` | Pull latest images. Use --no-pull for running the server with locally-built images. Example: `langgraph up --no-pull` | +| `--recreate / --no-recreate` | `no-recreate` | Recreate containers even if their configuration and image haven't changed | +| `--help` | | Display command documentation. | + ### `test` Test your LangGraph in the cloud. The only function you can call from the SDK after testing your graph is `client.runs.stream(thread_id=None, ...)` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 12d2461a2..def0227b2 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -183,6 +183,7 @@ nav: - Deployment: - Setup App: "cloud/deployment/setup.md" - Setup App (pyproject.toml): "cloud/deployment/setup_pyproject.md" + - Test App Locally: "cloud/deployment/test_locally.md" - Deploy to Cloud: "cloud/deployment/cloud.md" - Self-Host: "cloud/deployment/self_hosted.md" - Streaming: diff --git a/examples/cloud_examples/webhooks.ipynb b/examples/cloud_examples/webhooks.ipynb index 60d40f4ed..682bcd8aa 100644 --- a/examples/cloud_examples/webhooks.ipynb +++ b/examples/cloud_examples/webhooks.ipynb @@ -6,7 +6,7 @@ "source": [ "# Use Webhooks\n", "\n", - "You may wish to use webhooks in your client, especially when using async streams in case you want to update something in your service once the API call to Langgraph Cloud has finished running. To do so, you will need to expose an endpoint that can accept POST requests, and then pass it to your API request in the \"webhook\" parameter.\n", + "You may wish to use webhooks in your client, especially when using async streams in case you want to update something in your service once the API call to LangGraph Cloud has finished running. To do so, you will need to expose an endpoint that can accept POST requests, and then pass it to your API request in the \"webhook\" parameter.\n", "\n", "Currently, the SDK has not exposed this endpoint but you can access it through curl commands as follows.\n", "\n", diff --git a/examples/introduction.ipynb b/examples/introduction.ipynb index 343c9e014..ec7468091 100644 --- a/examples/introduction.ipynb +++ b/examples/introduction.ipynb @@ -277,21 +277,21 @@ "name": "stdout", "output_type": "stream", "text": [ - "Assistant: Langgraph is a new open-source deep learning framework that focuses on enabling efficient training and deployment of large language models. Some key things to know about Langgraph:\n", + "Assistant: LangGraph is a new open-source deep learning framework that focuses on enabling efficient training and deployment of large language models. Some key things to know about LangGraph:\n", "\n", - "1. Efficient Training: Langgraph is designed to accelerate the training of large language models by leveraging advanced optimization techniques and parallelization strategies.\n", + "1. Efficient Training: LangGraph is designed to accelerate the training of large language models by leveraging advanced optimization techniques and parallelization strategies.\n", "\n", - "2. Modular Architecture: Langgraph has a modular architecture that allows for easy customization and extension of language models, making it flexible for a variety of NLP tasks.\n", + "2. Modular Architecture: LangGraph has a modular architecture that allows for easy customization and extension of language models, making it flexible for a variety of NLP tasks.\n", "\n", "3. Hardware Acceleration: The framework is optimized for both CPU and GPU hardware, allowing for efficient model deployment on a wide range of devices.\n", "\n", - "4. Scalability: Langgraph is designed to handle large-scale language models with billions of parameters, enabling the development of state-of-the-art NLP applications.\n", + "4. Scalability: LangGraph is designed to handle large-scale language models with billions of parameters, enabling the development of state-of-the-art NLP applications.\n", "\n", - "5. Open-Source: Langgraph is an open-source project, allowing developers and researchers to collaborate, contribute, and build upon the framework.\n", + "5. Open-Source: LangGraph is an open-source project, allowing developers and researchers to collaborate, contribute, and build upon the framework.\n", "\n", - "6. Performance: The goal of Langgraph is to provide superior performance and efficiency compared to existing deep learning frameworks, particularly for training and deploying large language models.\n", + "6. Performance: The goal of LangGraph is to provide superior performance and efficiency compared to existing deep learning frameworks, particularly for training and deploying large language models.\n", "\n", - "Overall, Langgraph is a promising new deep learning framework that aims to address the challenges of building and deploying advanced natural language processing models at scale. It is an active area of research and development, with the potential to drive further advancements in the field of language AI.\n" + "Overall, LangGraph is a promising new deep learning framework that aims to address the challenges of building and deploying advanced natural language processing models at scale. It is an active area of research and development, with the potential to drive further advancements in the field of language AI.\n" ] }, {