From b3907b33b2bbedb0f59e99c25617eab8f156814e Mon Sep 17 00:00:00 2001 From: Andrew Nguonly Date: Mon, 24 Jun 2024 13:27:36 -0700 Subject: [PATCH] Add JS SDK how-to page. (#787) --- docs/mkdocs.yml | 6 +- examples/sdk/js_sdk.ipynb | 782 +++++++++++++++++++++++++++++++++- examples/sdk/python_sdk.ipynb | 113 ++++- 3 files changed, 894 insertions(+), 7 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 577c2aa82..3796bba08 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -171,9 +171,6 @@ nav: - 'cloud/index.md' - Tutorials: - Quick Start: 'cloud/quick_start.md' - - SDK: - - Python: 'cloud/sdk/python_sdk.ipynb' - - JS/TS: 'cloud/sdk/js_sdk.ipynb' - Deployment: - Self-Hosted: 'cloud/deployment/self_hosted.md' - Managed: 'cloud/deployment/managed.md' @@ -194,6 +191,9 @@ nav: - Human in the loop: 'cloud/how-tos/cloud_examples/human-in-the-loop_cloud.ipynb' - Create Agents with Configuration: 'cloud/how-tos/cloud_examples/configuration_cloud.ipynb' - Convert LangGraph calls to LangGraph Cloud calls: 'cloud/how-tos/cloud_examples/langgraph_to_langgraph_cloud.ipynb' + - SDK: + - Python: 'cloud/sdk/python_sdk.ipynb' + - JS/TS: 'cloud/sdk/js_sdk.ipynb' - Conceptual Guides: 'cloud/concepts/index.md' - Reference: diff --git a/examples/sdk/js_sdk.ipynb b/examples/sdk/js_sdk.ipynb index 4110ebb1b..9331b89a6 100644 --- a/examples/sdk/js_sdk.ipynb +++ b/examples/sdk/js_sdk.ipynb @@ -4,14 +4,790 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## JS SDK\n", - "Coming soon" + "This how-to takes you through the steps of using the JS/TS SDK for interacting with deployed Langgraph Cloud APIs." ] }, { "cell_type": "markdown", "metadata": {}, - "source": [] + "source": [ + "## Initialization\n", + "\n", + "### Initializing client\n", + "\n", + "To get started we need to initialize our client. The process for initializing our client is almost identical for both the local deployment and cloud deployment using Langsmith." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "import { Client } from \"@langchain/langgraph-sdk\";\n", + "\n", + "\n", + "\n", + "// If you deployed using Langsmith use this option\n", + "// Find this url on your Langsmith deployment page\n", + "const example_deployed_url = \"https://ht-unhealthy-buffalo25-39d00f953458585aa9f7b5a4fa-g3ps4aazkq-uc.a.run.app\";\n", + "\n", + "// If you deployed locally using langgraph up -c langgraph.json use this option\n", + "// This is the default URL, and you can just call get_client() to use it\n", + "const example_local_url = \"http://localhost:8123\";\n", + "\n", + "const client = new Client({apiUrl:\"whatever-your-url-is\"});" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Selecting an Assistant\n", + "\n", + "To select an assistant we can search the assistants that are hosted on our client, and then select the one we want:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "// List all assistants\n", + "const assistants = await client.assistants.search({\n", + " metadata: null,\n", + " offset: 0,\n", + " limit: 10,\n", + "});\n", + "\n", + "// We auto-create an assistant for each graph you register in config.\n", + "const agent = assistants[0];" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In our example we are only hosting a single assistant, but you have the option to host many, in which case you will most likely want to do more filtering than just selecting the first one. Each assistant is a JSON object with the following format, allowing you to select based on a variety of parameters." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "console.log(agent);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "{\n", + " assistant_id: 'fe096781-5601-53d2-b2f6-0d3403f7e9ca',\n", + " graph_id: 'agent',\n", + " created_at: '2024-06-11T20:12:45.862108+00:00',\n", + " updated_at: '2024-06-11T20:12:45.862108+00:00',\n", + " config: {},\n", + " metadata: { created_by: 'system' }\n", + "}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Configuring an assistant\n", + "\n", + "One important thing to know is that graph can be defined to be configurable, meaning that not every instance of the graph needs to be the same (read up on [this guide](https://langchain-ai.github.io/langgraph/how-tos/configuration/) to learn more about how to create your own configurable graphs). Let's briefly show how we can configure an assistant. The first step to do is find the assistant we want to configure. In our simple example we are only hosting a single graph, so we must choose it as the graph to configure." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "const base_assistant = assistants[0];" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This assistant has one configurable argument called `model`, which can take on two values: `openai` or `anthropic`. In this case, I want to create a graph that originates from this assistant that uses the `openai` option, which we can do as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "const config_graph = await client.assistants.create({graphId: base_assistant['graph_id'],config: {'configurable':{'model':'openai'}}});\n", + "console.log(config_graph);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "{\n", + " assistant_id: '414a1ddd-4453-4500-ab0b-7bc4f5bb41b1',\n", + " graph_id: 'agent',\n", + " created_at: '2024-06-21T23:42:16.388341+00:00',\n", + " updated_at: '2024-06-21T23:42:16.388341+00:00',\n", + " config: { configurable: { model: 'openai' } },\n", + " metadata: {}\n", + "}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Being able to create configurable assistants allows you to create different graphs all based on the same underlying structure. This can be very powerful for testing different configurations of a graph or allowing users to customize their graph." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Creating a thread\n", + "\n", + "Threads are what we will actually use to run our graphs (assistants). Each thread will update the same state for the graph, meaning we can run the graph multiple times while the state will persist. We can also look back at our thread history, add meta data to different steps of our thread, and update the thread state manually if we wish. We will dive into all of those topics later in this article, but for now let’s just see how to start a thread:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "// Start a new thread\n", + "const thread = await client.threads.create();" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can examine the structure of our thread, which similar to the assistants object provides us with some information about the thread itself, including its id, timestamps, and metadata:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "console.log(thread);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "{\n", + " thread_id: '12a112dc-d175-42ce-8b06-85697733cccc',\n", + " created_at: '2024-06-20T22:01:18.715497+00:00',\n", + " updated_at: '2024-06-20T22:01:18.715497+00:00',\n", + " metadata: {}\n", + "}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now we are ready to actually use our graph!\n", + "\n", + "## Invoking the graph\n", + "\n", + "The graph used in this example is a simple example of a StateGraph, but it allows us to show most of the API functionality. The state of our graph is defined as follows (Langgraph Cloud is coming in the future for JS!):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from typing import Annotated, TypedDict\n", + "\n", + "from langchain_core.messages import AnyMessage\n", + "\n", + "from langgraph.graph import add_messages\n", + "\n", + "\n", + "def update_user_info(old_info, new_info):\n", + " if \"name\" not in new_info or new_info[\"age\"] == -1:\n", + " return old_info\n", + " return new_info\n", + "\n", + "\n", + "class UserInformation(TypedDict):\n", + " age: int\n", + " name: str\n", + "\n", + "\n", + "class AgentState(TypedDict):\n", + " messages: Annotated[list[AnyMessage], add_messages]\n", + " user_info: Annotated[UserInformation, update_user_info]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "It is important to note that our member variables can be updated by using the `Annotated` class. This is especially important when we make API calls that will update our variables. This is also a good example that your graph can hold much more information than just messages. In our example we use a very simple `UserInformation` class, but you can imagine holding much richer information in your state.\n", + "\n", + "Our graph looks like follows:\n", + "\n", + "
\n", + " \n", + "
\n", + "\n", + "The workflow is as follows: first the user inputs some message, our llm decides how to configure the call to our tool `get_user_info` , and after getting the results of the tool call we respond to our user using another LLM.\n", + "\n", + "### Simple Invocation\n", + "\n", + "Ok, now that we have set up our client, assistant, and thread we can actually invoke the graph above. Let’s first define the function we will use to invoke the graph, since we don’t want to have to rewrite this code every single run." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "async function processStreamedMessages(client, thread, agent, messages, metadata = {}) {\n", + " var answer = [];\n", + " try {\n", + " const streamResponse = client.runs.stream(\n", + " thread[\"thread_id\"],\n", + " agent[\"assistant_id\"],\n", + " {\n", + " input: { messages },\n", + " config: {\"configurable\": metadata}\n", + " }\n", + " );\n", + "\n", + " for await (const chunk of streamResponse) {\n", + " answer.concat(chunk);\n", + " // Process each chunk of streamed data here\n", + " }\n", + " return answer;\n", + " } catch (error) {\n", + " console.error('Error processing streamed messages:', error);\n", + " }\n", + "}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let’s now see what happens to our graph when we run it with a simple sentence:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var messages = [{ role: \"human\", content: \"My name is Bagatur and I am 26 years old.\" }];\n", + "\n", + "await processStreamedMessages(client, thread, agent, messages);" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In order to see what happened to our graph, let's examine the state which was updated after the run we just sent through." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var state = await client.threads.getState(thread['thread_id']);\n", + "console.log(state);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "{\n", + " values: {\n", + " messages: [ [Object], [Object], [Object] ],\n", + " user_info: { age: 26, name: 'Bagatur' }\n", + " },\n", + " next: [],\n", + " config: {\n", + " configurable: {\n", + " thread_id: '15292d98-6aca-4df8-b2a1-f4508e11abb1',\n", + " thread_ts: '1ef2f516-ebd2-68f4-8003-2a1251f89da5'\n", + " }\n", + " },\n", + " metadata: {\n", + " step: 3,\n", + " run_id: '1ef2f516-e211-6e60-8d19-6a1309008ece',\n", + " source: 'loop',\n", + " writes: { respond_to_user: [Object] },\n", + " user_id: '',\n", + " graph_id: 'agent',\n", + " thread_id: '15292d98-6aca-4df8-b2a1-f4508e11abb1',\n", + " created_by: 'system',\n", + " assistant_id: 'fe096781-5601-53d2-b2f6-0d3403f7e9ca'\n", + " },\n", + " created_at: '2024-06-20T22:07:06.852149+00:00',\n", + " parent_config: {\n", + " configurable: {\n", + " thread_id: '15292d98-6aca-4df8-b2a1-f4508e11abb1',\n", + " thread_ts: '1ef2f516-e6c7-6698-8002-80a6bedfa731'\n", + " }\n", + " }\n", + " }" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Our state variable contains a variety of important information. Here is a quick summary of the keys and what they represent:\n", + "\n", + "- `values` contains the actual state values, so in our case you could call `state['values']['messages']` or `state['values']['user_info']` and get the actual values of each of the state variables.\n", + "- `next` tells us what action in the graph is next at the current state. Since we just finished running our graph and reached the end node, it is currently empty because there is no next action to take. However, if you go through the state at each point of the run you will see that the `next` value goes from `__start__` → `llm` → `get_user_info` →`respond_to_user` .\n", + "- `config` tells us what the configuration of the state is. This is important for when we want to run a query starting at a previous state instead of the one we are at. An example of this is shown in the Invoking from a previous checkpoint section\n", + "- `metadata` stores the metadata associated with our state. This is data that is outside of the agent state, but is important to keep track of across multiple runs. An example of this is shown in the next section.\n", + "- `created_at` is information on the date and time the state was created at.\n", + "- `parent_config` is config for the previous step of the graph. Note that the previous step is not the previous run, but rather the previous node that the graph was at.\n", + "\n", + "\n", + "### Invoking with Metadata\n", + "\n", + "Let’s create a new thread to reset our state and start fresh." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "const thread_2 = await client.threads.create();" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now let’s add some metadata to our request. In this example we are going to treat each run of our assistant as a separate “node”. For each run, we will pass in a “node_id” as well as a “parent_node” in the metadata. This way we can easily go “back in time” and rerun our graph from a previous checkpoint. \n", + "\n", + "> NOTE: The reason we add this metadata instead of using the `parent_config` attribute is because `parent_config` tracks every individual step of a run, not the entire run itself.\n", + ">" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var messages = [{ role: \"human\", content: \"My name is Bagatur and I am 26 years old.\" }];\n", + "\n", + "await processStreamedMessages(client, thread_2, agent, messages, {\"node_id\": 1, \"parent_node\": null});" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Using our `run_input` function makes it easy to pass in metadata and you can inspect the function as well as the API docs to see exactly how metadata gets passed.\n", + "\n", + "We can continue our thread by creating a second node as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "messages = [{ role: \"human\", content: \"What is my name?\" }];\n", + "\n", + "await processStreamedMessages(client, thread_2, agent, messages, {\"node_id\": 2, \"parent_node\": 1});" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's check our state to make sure the graph remembered our name on the second run:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var state = await client.threads.getState(thread_2['thread_id']);\n", + "var graph_messages = state.values['messages'].map((message) => message.content);\n", + "console.log(graph_messages);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "[\n", + " 'My name is Bagatur and I am 26 years old.',\n", + " '',\n", + " 'Hello Bagatur! How can I assist you today?',\n", + " 'What is my name?',\n", + " '',\n", + " 'Your name is Bagatur. How can I assist you today, Bagatur?'\n", + "]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Perfect! The state persisted across separate runs, and the LLM remembers the name of our user. In a future we will explore non-sequential runs, i.e. not having each run just follow the last one but choosing which checkpoint we start our run from.\n", + "\n", + "## Querying and Updating the thread\n", + "\n", + "### Getting checkpoints by metadata\n", + "\n", + "Let’s say we want to start a new run from a previous state (not the current state). This state lives somewhere in our history, so we can utilize the `get_history` function to try and find it." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var all_history = await client.threads.getHistory(thread_2[\"thread_id\"])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This is helpful for inspecting the specifics of our current thread, but remember that the history contains all the intermediate steps a graph takes. In our case, where the graph has 5 nodes (remember that Start and End both count as nodes), our history array grows quickly. Luckily, there is a way to query by using metadata. For example if we wanted to start a run from Node 1(from the example from above) we need to find the state from the end of run with metadata node_id:1 , which we can do like so:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var node_1_history = await client.threads.getHistory(thread_2[\"thread_id\"],{metadata: {'node_id':1}})\n", + "\n", + "var node_1_end_of_run = history.filter(node => node.next.length === 0)[0];" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now let’s explore how we could use this information to create a new branch in our thread.\n", + "\n", + "### Invoking from a previous checkpoint\n", + "\n", + "The following diagram describes what we would like to happen:\n", + "\n", + "
\n", + " \n", + "
\n", + "Basically, we want to have 3 runs of our graph, but instead of having them sequentially - we want both the second and third run to originate from the same state. We can do this by utilizing the code we used above, and passing additional metadata to our run." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "messages = [{ role: \"human\", content: \"What is my age?\" }];\n", + "\n", + "await processStreamedMessages(client, thread_2, agent, messages, {\"node_id\": 3, \"parent_node\": 1, \"thread_ts\":node_1_end_of_run.checkpoint_id});" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To check that everything actually worked as planned, let’s check our current state and check that message history to ensure that the message we passed to Node 2 is nowhere to be found." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var state = await client.threads.getState(thread_2['thread_id']);\n", + "var graph_messages = state.values['messages'].map((message) => message.content);\n", + "console.log(graph_messages);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "[\n", + " 'My name is Bagatur and I am 26 years old.',\n", + " '',\n", + " 'Hello Bagatur! How can I assist you today?',\n", + " 'What is my age?',\n", + " '',\n", + " 'You are 26 years old, Bagatur. How can I assist you today?'\n", + "]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Great! This has worked as expected. Being able to go back to previous states and execute new graph runs from those checkpoints is a great way to develop flexible applications that don’t require reloading or restarting everything when an error is detected or a user changes their mind.\n", + "\n", + "### Updating/Patching the thread state\n", + "\n", + "Lastly, let’s discuss the ability to manually change both the thread state as well as the metadata for a given state. Let’s say we incorrectly inputted data to the LLM and we want to rectify it. \n", + "\n", + "Continuing our previous example, let’s say the user mistyped their age and we want to let the graph know that without actually running it. In this case we can rectify this by using `update_state`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "await client.threads.updateState(thread_2['thread_id'], { values: { \"user_info\": { \"name\": \"Bagatur\", \"age\": 35 } } });" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let’s make sure that the state did in fact update by checking the current state:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var state = await client.threads.getState(thread_2['thread_id']);\n", + "console.log(state.values['user_info']);\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "{ name: 'Bagatur', age: 35 }" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Voila! The LLM knows our users age updated without us having to prompt it at all.\n", + "\n", + "The last thing we will talk about is patching the thread, which is used when we want to update the metadata of a state. For example, say we actually wanted to update our last state to have `node_id:4` instead of `node_id:3`. To do this, we can call:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "await client.threads.patchState(thread_2['thread_id'],{\"node_id\": 4});" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can check that this worked by checking the metadata of our state" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "var state = await client.threads.getState(thread_2['thread_id']);\n", + "console.log(state.metadata['node_id']);" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "vscode": { + "languageId": "javascript" + } + }, + "outputs": [], + "source": [ + "4" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Perfect! The patch worked as expected." + ] } ], "metadata": { diff --git a/examples/sdk/python_sdk.ipynb b/examples/sdk/python_sdk.ipynb index 98e0fc283..e778aa7e8 100644 --- a/examples/sdk/python_sdk.ipynb +++ b/examples/sdk/python_sdk.ipynb @@ -4,6 +4,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "\n", + "This how-to takes you through the steps of using the Python SDK for interacting with deployed Langgraph Cloud APIs.\n", + "\n", "## Initialization\n", "\n", "### Initializing client\n", @@ -38,7 +41,7 @@ "source": [ "### Selecting an Assistant\n", "\n", - "To select an assistant we can search the assistants that are hosted on our client, and then select the one we want," + "To select an assistant we can search the assistants that are hosted on our client, and then select the one we want:" ] }, { @@ -84,6 +87,79 @@ "assistant" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Configuring an assistant\n", + "\n", + "One important thing to know is that graph can be defined to be configurable, meaning that not every instance of the graph needs to be the same (read up on [this guide](https://langchain-ai.github.io/langgraph/how-tos/configuration/) to learn more about how to create your own configurable graphs). Let's briefly show how we can configure an assistant. The first step to do is find the assistant we want to configure. In our simple example we are only hosting a single graph, so we must choose it as the graph to configure." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "base_assistant = assistants[0]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This assistant has one configurable argument called `model`, which can take on two values: `openai` or `anthropic`. In this case, I want to create a graph that originates from this assistant that uses the `openai` option, which we can do as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [], + "source": [ + "config_graph = await client.assistants.create(base_assistant['graph_id'],config = {'configurable':{'model':'openai'}})" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now if we inspect our new graph, we can see that it has been configured and whenever we run it, it will select the `openai` model." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'assistant_id': '4d91047c-585c-4d1b-9ade-5b0f4d292528',\n", + " 'graph_id': 'agent',\n", + " 'created_at': '2024-06-21T23:06:08.203776+00:00',\n", + " 'updated_at': '2024-06-21T23:06:08.203776+00:00',\n", + " 'config': {'configurable': {'model': 'openai'}},\n", + " 'metadata': {}}" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "config_graph" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Being able to create configurable assistants allows you to create different graphs all based on the same underlying structure. This can be very powerful for testing different configurations of a graph or allowing users to customize their graph." + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -369,6 +445,41 @@ "source": [ "Perfect! The state persisted across separate runs, and the LLM remembers the name of our user. In a future we will explore non-sequential runs, i.e. not having each run just follow the last one but choosing which checkpoint we start our run from.\n", "\n", + "### Invoking on a schedule\n", + "\n", + "Running your graph on a schedule can be valuable in situations where you want to run tasks periodically. The Langgraph Cloud API allows you to do this through the `CronAssistant` class. To schedule a graph job, you need to pass a [cron expression](https://crontab.cronhub.io/) to inform the client when you want to run the graph. `Cron` jobs are run in the background and do not interfere with normal invocations of the graph." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# This schedules a job to run at 15:27 (3:27PM) every day\n", + "cron_1 = await client.crons.create(assistant['assistant_id'],schedule=\"27 15 * * *\",input={'messages':[{\"role\":\"user\",\"content\":\"What time is it?\"}]})" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note that it is **very** important to delete `Cron` jobs that are no longer useful. Otherwise you could rack up unwanted API charges to the LLM! You can delete a `Cron` job using the following code:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await client.crons.delete(cron_1['cron_id'])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ "## Querying and Updating the thread\n", "\n", "### Getting checkpoints by metadata\n",