{ "cells": [ { "cell_type": "markdown", "id": "7388763d", "metadata": {}, "source": [ "# Human-in-the-loop\n", "\n", "When creating LangGraph agents, it is often nice to add a human in the loop\n", "component. This can be helpful when giving them access to tools. Often in these\n", "situations you may want to manually approve an action before taking.\n", "\n", "This can be in several ways, but the primary supported way is to add an\n", "\"interrupt\" before a node is executed. This interrupts execution at that node.\n", "You can then resume from that spot to continue.\n", "\n", "
\n", "

Note

\n", "

\n", " In this how-to, we will create our agent from scratch to be transparent (but verbose). You can accomplish similar functionality using either `interruptBefore` or `interruptAfter` in the createReactAgent(model, tools=tool, interruptBefore=[\"tools\" | \"agent\"], interruptAfter=[\"tools\" | \"agent\"]) API doc constructor. This may be more appropriate if you are used to LangChain's AgentExecutor class.\n", "

\n", "
\n", "\n", "## Setup\n", "\n", "First we need to install the packages required\n", "\n", "```bash\n", "yarn add @langchain/langgraph\n", "```\n", "\n", "Next, we need to set API keys for OpenAI (the LLM we will use). Optionally, we\n", "can set API key for [LangSmith tracing](https://smith.langchain.com/), which\n", "will give us best-in-class observability." ] }, { "cell_type": "code", "execution_count": 1, "id": "74b6bfe1", "metadata": { "lines_to_next_cell": 2 }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Human-in-the-loop: LangGraphJS\n" ] } ], "source": [ "// process.env.OPENAI_API_KEY = \"sk_...\";\n", "\n", "// Optional, add tracing in LangSmith\n", "// process.env.LANGCHAIN_API_KEY = \"ls__...\";\n", "// process.env.LANGCHAIN_CALLBACKS_BACKGROUND = \"true\";\n", "process.env.LANGCHAIN_TRACING_V2 = \"true\";\n", "process.env.LANGCHAIN_PROJECT = \"Human-in-the-loop: LangGraphJS\";" ] }, { "cell_type": "markdown", "id": "a7b247cf", "metadata": {}, "source": [ "## Set up the State\n", "\n", "The state is the interface for all the nodes.\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "50c5189d", "metadata": { "lines_to_next_cell": 2 }, "outputs": [], "source": [ "import { BaseMessage } from \"@langchain/core/messages\";\n", "import { StateGraphArgs } from \"@langchain/langgraph\";\n", "\n", "interface IState {\n", " messages: BaseMessage[];\n", "}\n", "\n", "// This defines the agent state\n", "const graphState: StateGraphArgs[\"channels\"] = {\n", " messages: {\n", " value: (x: BaseMessage[], y: BaseMessage[]) => x.concat(y),\n", " default: () => [],\n", " },\n", "};" ] }, { "cell_type": "markdown", "id": "b1607663", "metadata": {}, "source": [ "## Set up the tools\n", "\n", "We will first define the tools we want to use. For this simple example, we will\n", "create a placeholder \"search engine\". However, it is really easy to create your\n", "own tools - see the\n", "[LangChain documentation](https://js.langchain.com/docs/modules/agents/tools/)\n", "on how to do that." ] }, { "cell_type": "code", "execution_count": 3, "id": "b24f1e9e", "metadata": { "lines_to_next_cell": 2 }, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "[WARN]: You have enabled LangSmith tracing without backgrounding callbacks.\n", "[WARN]: If you are not using a serverless environment where you must wait for tracing calls to finish,\n", "[WARN]: we suggest setting \"process.env.LANGCHAIN_CALLBACKS_BACKGROUND=true\" to avoid additional latency.\n" ] } ], "source": [ "import { DynamicStructuredTool } from \"@langchain/core/tools\";\n", "import { z } from \"zod\";\n", "\n", "const searchTool = new DynamicStructuredTool({\n", " name: \"search\",\n", " description: \"Call to surf the web.\",\n", " schema: z.object({\n", " query: z.string().describe(\"The query to use in your search.\"),\n", " }),\n", " func: async ({}: { query: string }) => {\n", " // This is a placeholder for the actual implementation\n", " // Don't let the LLM know this though 😊\n", " return \"It's sunny in San Francisco, but you better look out if you're a Gemini 😈.\";\n", " },\n", "});\n", "\n", "const tools = [searchTool];" ] }, { "cell_type": "markdown", "id": "1cfcf345", "metadata": {}, "source": [ "We can now wrap these tools in a simple\n", "[ToolNode](https://langchain-ai.github.io/langgraphjs/reference/classes/prebuilt.ToolNode.html).\n", "\n", "This is a simple class that takes in a list of messages containing an\n", "[AIMessage with tool_calls](https://v02.api.js.langchain.com/classes/langchain_core_messages.AIMessage.html),\n", "runs the tools, and returns the output as\\\n", "[ToolMessage](https://v02.api.js.langchain.com/classes/langchain_core_messages_tool.ToolMessage.html)s." ] }, { "cell_type": "code", "execution_count": 4, "id": "528a8e10", "metadata": { "lines_to_next_cell": 2 }, "outputs": [], "source": [ "import { ToolNode } from \"@langchain/langgraph/prebuilt\";\n", "\n", "const toolNode = new ToolNode<{ messages: BaseMessage[] }>(tools);" ] }, { "cell_type": "markdown", "id": "b3bed0ce", "metadata": {}, "source": [ "## Set up the model\n", "\n", "Now we need to load the chat model we want to use. Since we are creating a\n", "tool-using ReAct agent, we want to make sure the model supports\n", "[Tool Calling](https://js.langchain.com/docs/modules/model_io/models/chat/function-calling/)\n", "and works with chat messages.\n", "\n", "Note: these model requirements are not requirements for using LangGraph - they\n", "are just requirements for this one example." ] }, { "cell_type": "code", "execution_count": 5, "id": "b12434ff", "metadata": { "lines_to_next_cell": 2 }, "outputs": [], "source": [ "import { ChatOpenAI } from \"@langchain/openai\";\n", "\n", "const model = new ChatOpenAI({ temperature: 0 });\n", "\n", "// After we've done this, we should make sure the model knows that it has these tools available to call.\n", "// We can do this by binding the tools to the model class.\n", "const boundModel = model.bindTools(tools);" ] }, { "cell_type": "markdown", "id": "97312191", "metadata": {}, "source": [ "## Define the nodes\n", "\n", "We now need to define a few different nodes in our graph. In `langgraph`, a node\n", "can be either a function or a\\\n", "[runnable](https://js.langchain.com/docs/modules/runnables/). There are two main\n", "nodes we need for this:\n", "\n", "1. The agent: responsible for deciding what (if any) actions to take.\n", "2. A function to invoke tools: if the agent decides to take an action, this\n", " node\\\n", " will then execute that action.\n", "\n", "We will also need to define some edges. Some of these edges may be conditional.\n", "The reason they are conditional is that based on the output of a node, one of\n", "several paths may be taken. The path that is taken is not known until that node\n", "is run (the LLM decides).\n", "\n", "1. Conditional Edge: after the agent is called, we should either: a. If the\n", " agent said to take an action, then the function to invoke tools should be\n", " called\\\n", " b. If the agent said that it was finished, then it should finish\n", "2. Normal Edge: after the tools are invoked, it should always go back to the\n", " agent to decide what to do next\n", "\n", "Let's define the nodes, as well as a function to decide how what conditional\n", "edge to take." ] }, { "cell_type": "code", "execution_count": 6, "id": "b52bef4a", "metadata": {}, "outputs": [], "source": [ "import { RunnableConfig } from \"@langchain/core/runnables\";\n", "import { AIMessage } from \"@langchain/core/messages\";\n", "import { END } from \"@langchain/langgraph\";\n", "\n", "const routeMessage = (state: IState) => {\n", " const { messages } = state;\n", " const lastMessage = messages[messages.length - 1] as AIMessage;\n", " // If no tools are called, we can finish (respond to the user)\n", " if (!lastMessage?.tool_calls?.length) {\n", " return END;\n", " }\n", " // Otherwise if there is, we continue and call the tools\n", " return \"tools\";\n", "};\n", "\n", "const callModel = async (\n", " state: IState,\n", " config?: RunnableConfig,\n", ") => {\n", " const { messages } = state;\n", " const response = await boundModel.invoke(messages, config);\n", " return { messages: [response] };\n", "};" ] }, { "cell_type": "markdown", "id": "22360833", "metadata": {}, "source": [ "## Define the graph\n", "\n", "We can now put it all together and define the graph!\n" ] }, { "cell_type": "code", "execution_count": 7, "id": "a8b8dace", "metadata": {}, "outputs": [], "source": [ "import { START, StateGraph } from \"@langchain/langgraph\";\n", "import { MemorySaver } from \"@langchain/langgraph\";\n", "\n", "const workflow = new StateGraph({\n", " channels: graphState,\n", "})\n", " .addNode(\"agent\", callModel)\n", " .addNode(\"tools\", toolNode)\n", " .addEdge(START, \"agent\")\n", " .addConditionalEdges(\"agent\", routeMessage)\n", " .addEdge(\"tools\", \"agent\");\n", "\n", "// **Persistence**\n", "// Human-in-the-loop workflows require a checkpointer to ensure\n", "// nothing is lost between interactions\n", "const checkpointer = new MemorySaver();\n", "\n", "// **Interrupt**\n", "// To always interrupt before a particular node, pass the name of the node to `interruptBefore` when compiling.\n", "const graph = workflow.compile({ checkpointer, interruptBefore: [\"tools\"] });" ] }, { "cell_type": "markdown", "id": "325d45c5", "metadata": {}, "source": [ "## Interacting with the Agent\n", "\n", "We can now interact with the agent and see that it stops before calling a tool.\n" ] }, { "cell_type": "code", "execution_count": 8, "id": "17d79c6b", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[human]: hi! I'm bob\n", "[ai]: Hello Bob! How can I assist you today?\n" ] } ], "source": [ "import { HumanMessage, isAIMessage } from \"@langchain/core/messages\";\n", "\n", "const prettyPrint = (message: BaseMessage) => {\n", " let txt = `[${message._getType()}]: ${message.content}`;\n", " if (\n", " isAIMessage(message) && (message as AIMessage)?.tool_calls?.length || 0 > 0\n", " ) {\n", " const tool_calls = (message as AIMessage)?.tool_calls\n", " ?.map((tc) => `- ${tc.name}(${JSON.stringify(tc.args)})`)\n", " .join(\"\\n\");\n", " txt += ` \\nTools: \\n${tool_calls}`;\n", " }\n", " console.log(txt);\n", "};\n", "\n", "const config = { configurable: { thread_id: \"example-thread-1\" } };\n", "\n", "let inputs = { messages: [new HumanMessage(\"hi! I'm bob\")] };\n", "for await (\n", " const { messages } of await graph.stream(inputs, {\n", " ...config,\n", " streamMode: \"values\",\n", " })\n", ") {\n", " prettyPrint(messages[messages.length - 1]);\n", "}" ] }, { "cell_type": "code", "execution_count": 9, "id": "2166619d", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[human]: What did I tell you my name was?\n", "[ai]: You mentioned that your name is Bob. How can I help you, Bob?\n" ] } ], "source": [ "inputs = { messages: [new HumanMessage(\"What did I tell you my name was?\")] };\n", "for await (\n", " const { messages } of await graph.stream(inputs, {\n", " ...config,\n", " streamMode: \"values\",\n", " })\n", ") {\n", " prettyPrint(messages[messages.length - 1]);\n", "}" ] }, { "cell_type": "code", "execution_count": 10, "id": "f523a658", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[human]: what's the weather in sf now?\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "[ai]: \n", "Tools: \n", "- search({\"query\":\"weather in San Francisco\"})\n" ] } ], "source": [ "inputs = { messages: [new HumanMessage(\"what's the weather in sf now?\")] };\n", "for await (\n", " const { messages } of await graph.stream(inputs, {\n", " ...config,\n", " streamMode: \"values\",\n", " })\n", ") {\n", " prettyPrint(messages[messages.length - 1]);\n", "}" ] }, { "cell_type": "markdown", "id": "13d79e78", "metadata": {}, "source": [ "**Resume**\n", "\n", "We can now call the agent again with no inputs to continue, ie. run the tool as\n", "requested.\n", "\n", "Running an interrupted graph with `null` as the input means to \"proceed as if\n", "the interruption didn't occur.\"" ] }, { "cell_type": "code", "execution_count": 11, "id": "a0dc047e", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[tool]: It's sunny in San Francisco, but you better look out if you're a Gemini 😈.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "[ai]: It seems like it's sunny in San Francisco at the moment. If you need more detailed weather information, feel free to ask!\n" ] } ], "source": [ "for await (\n", " const { messages } of await graph.stream(null, {\n", " ...config,\n", " streamMode: \"values\",\n", " })\n", ") {\n", " prettyPrint(messages[messages.length - 1]);\n", "}" ] }, { "cell_type": "code", "execution_count": null, "id": "8185b577-064b-4b5c-8198-4c4d4b6d6cee", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "jupytext": { "encoding": "# -*- coding: utf-8 -*-" }, "kernelspec": { "display_name": "TypeScript", "language": "typescript", "name": "tslab" }, "language_info": { "codemirror_mode": { "mode": "typescript", "name": "javascript", "typescript": true }, "file_extension": ".ts", "mimetype": "text/typescript", "name": "typescript", "version": "3.7.2" } }, "nbformat": 4, "nbformat_minor": 5 }