From a64f9f80c0ad50b164adff2b0d22a98f63a8fc99 Mon Sep 17 00:00:00 2001 From: Vadym Barda Date: Mon, 9 Dec 2024 20:18:29 -0500 Subject: [PATCH 1/5] docs: add a how to for multi-agent network (#2675) --- docs/docs/how-tos/index.md | 6 + docs/docs/how-tos/multi-agent-network.ipynb | 566 ++++++++++++++++++++ docs/mkdocs.yml | 2 + 3 files changed, 574 insertions(+) create mode 100644 docs/docs/how-tos/multi-agent-network.ipynb diff --git a/docs/docs/how-tos/index.md b/docs/docs/how-tos/index.md index 8256a9adb..b26656117 100644 --- a/docs/docs/how-tos/index.md +++ b/docs/docs/how-tos/index.md @@ -91,6 +91,12 @@ These how-to guides show common patterns for tool calling with LangGraph: - [How to view and update state in subgraphs](subgraphs-manage-state.ipynb) - [How to transform inputs and outputs of a subgraph](subgraph-transform-state.ipynb) +### Multi-agent + +- [How to build a multi-agent network](multi-agent-network.ipynb) + +See the [multi-agent tutorials](../tutorials/index.md#multi-agent-systems) for implementations of other multi-agent architectures. + ### State Management - [How to use Pydantic model as state](state-model.ipynb) diff --git a/docs/docs/how-tos/multi-agent-network.ipynb b/docs/docs/how-tos/multi-agent-network.ipynb new file mode 100644 index 000000000..4dde1ac79 --- /dev/null +++ b/docs/docs/how-tos/multi-agent-network.ipynb @@ -0,0 +1,566 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "87684b48-150e-4e15-b0a5-a9dd7851f8fb", + "metadata": {}, + "source": [ + "# How to build a multi-agent network" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "2c65639c-9705-49f1-840a-370718852e98", + "metadata": {}, + "source": [ + "!!! info \"Prerequisites\"\n", + " This guide assumes familiarity with the following:\n", + "\n", + " - [Node](../../concepts/low_level/#nodes)\n", + " - [Command](../../concepts/low_level/#command)\n", + " - [Multi-agent systems](../../concepts/multi_agent)\n", + "\n", + "\n", + "In this how-to guide we will demonstrate how to implement a [multi-agent network](../../concepts/multi_agent#network) architecture.\n", + "\n", + "Each agent can be represented as a node in the graph that executes agent step(s) and decides what to do next - finish execution or route to another agent (including routing to itself, e.g. running in a loop). A common pattern for routing in multi-agent architectures is handoffs. Handoffs allow you to specify:\n", + "\n", + "1. which agent to navigate to next and (e.g. name of the node to go to)\n", + "2. what information to pass to that agent (e.g. state update)\n", + "\n", + "To implement handoffs, agent nodes can return `Command` object that allows you to [combine both control flow and state updates](../command):\n", + "\n", + "```python\n", + "def agent(state) -> Command[Literal[\"agent\", \"another_agent\"]]:\n", + " # the condition for routing/halting can be anything, e.g. LLM tool call / structured output, etc.\n", + " goto = get_next_agent(...) # 'agent' / 'another_agent'\n", + " if goto:\n", + " return Command(goto=goto, update={\"my_state_key\": \"my_state_value\"})\n", + " \n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "faaa4444-cd06-4813-b9ca-c9700fe12cb7", + "metadata": {}, + "source": [ + "## Setup\n", + "\n", + "First, let's install the required packages" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "05038da0-31df-4066-a1a4-c4ccb5db4d3a", + "metadata": {}, + "outputs": [], + "source": [ + "%%capture --no-stderr\n", + "%pip install -U langgraph langchain-openai" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "0bcff5d4-130e-426d-9285-40d0f72c7cd3", + "metadata": {}, + "outputs": [ + { + "name": "stdin", + "output_type": "stream", + "text": [ + "OPENAI_API_KEY: ········\n" + ] + } + ], + "source": [ + "import getpass\n", + "import os\n", + "\n", + "\n", + "def _set_env(var: str):\n", + " if not os.environ.get(var):\n", + " os.environ[var] = getpass.getpass(f\"{var}: \")\n", + "\n", + "\n", + "_set_env(\"OPENAI_API_KEY\")" + ] + }, + { + "cell_type": "markdown", + "id": "c3ec6e48-85dc-4905-ba50-985e5d4788e6", + "metadata": {}, + "source": [ + "
\n", + "

Set up LangSmith for LangGraph development

\n", + "

\n", + " Sign up for LangSmith to quickly spot issues and improve the performance of your LangGraph projects. LangSmith lets you use trace data to debug, test, and monitor your LLM apps built with LangGraph — read more about how to get started here. \n", + "

\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "4a53f304-3709-4df7-8714-1ca61e615743", + "metadata": {}, + "source": [ + "## Travel Recommendations Example" + ] + }, + { + "cell_type": "markdown", + "id": "34cd131b-f0c2-4b69-887f-2cbd5afb14a7", + "metadata": {}, + "source": [ + "In this example we will build a team of travel assistant agents that can communicate with each other via handoffs.\n", + "\n", + "We will create 3 agents:\n", + "\n", + "* `travel_advisor`: can help with general travel destination recommendations. Can ask `sightseeing_advisor` and `hotel_advisor` for help.\n", + "* `sightseeing_advisor`: can help with sightseeing recommendations. Can ask `travel_advisor` and `hotel_advisor` for help.\n", + "* `hotel_advisor`: can help with hotel recommendations. Can ask `sightseeing_advisor` and `hotel_advisor` for help.\n", + "\n", + "This is a fully-connected network - every agent can talk to any other agent. \n", + "\n", + "To implement the handoffs between the agents we'll be using LLMs with structured output. Each agent's LLM will return an output with both its text response (`response`) as well as which agent to route to next (`goto`). If the agent has enough information to respond to the user, `goto` will contain `finish`.\n", + "\n", + "Now, let's define our agent nodes and graph!" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "aa4bdbff-9461-46cc-aee9-8a22d3c3d9ec", + "metadata": {}, + "outputs": [], + "source": [ + "from typing_extensions import TypedDict, Literal\n", + "\n", + "from langchain_openai import ChatOpenAI\n", + "from langgraph.graph import MessagesState, StateGraph, START, END\n", + "from langgraph.types import Command\n", + "\n", + "model = ChatOpenAI(model=\"gpt-4o\")\n", + "\n", + "\n", + "def make_agent_node(*, name: str, destinations: list[str], system_prompt: str):\n", + " def agent_node(state: MessagesState) -> Command[Literal[*destinations, END]]:\n", + " # define schema for the structured output:\n", + " # - model's text response (`response`)\n", + " # - name of the node to go to next (or 'finish')\n", + " class Response(TypedDict):\n", + " response: str\n", + " goto: Literal[*destinations, \"finish\"]\n", + "\n", + " messages = [{\"role\": \"system\", \"content\": system_prompt}] + state[\"messages\"]\n", + " response = model.with_structured_output(Response).invoke(messages)\n", + " goto = response[\"goto\"]\n", + " if goto == \"finish\":\n", + " goto = END\n", + "\n", + " # handoff to another agent or halt\n", + " ai_msg = {\"role\": \"ai\", \"content\": response[\"response\"], \"name\": name}\n", + " return Command(goto=goto, update={\"messages\": ai_msg})\n", + "\n", + " return agent_node\n", + "\n", + "\n", + "travel_advisor = make_agent_node(\n", + " name=\"travel_advisor\",\n", + " destinations=[\"sightseeing_advisor\", \"hotel_advisor\"],\n", + " system_prompt=(\n", + " \"You are a general travel expert that can recommend travel destinations (e.g. countries, cities, etc). \"\n", + " \"If you need specific sightseeing recommendations, ask 'sightseeing_advisor' for help. \"\n", + " \"If you need hotel recommendations, ask 'hotel_advisor' for help. \"\n", + " \"If you have enough information to respond to the user, return 'finish'. \"\n", + " \"Never mention other agents by name.\"\n", + " ),\n", + ")\n", + "sightseeing_advisor = make_agent_node(\n", + " name=\"sightseeing_advisor\",\n", + " destinations=[\"travel_advisor\", \"hotel_advisor\"],\n", + " system_prompt=(\n", + " \"You are a travel expert that can provide specific sightseeing recommendations for a given destination. \"\n", + " \"If you need general travel help, go to 'travel_advisor' for help. \"\n", + " \"If you need hotel recommendations, go to 'hotel_advisor' for help. \"\n", + " \"If you have enough information to respond to the user, return 'finish'. \"\n", + " \"Never mention other agents by name.\"\n", + " ),\n", + ")\n", + "hotel_advisor = make_agent_node(\n", + " name=\"hotel_advisor\",\n", + " destinations=[\"travel_advisor\", \"sightseeing_advisor\"],\n", + " system_prompt=(\n", + " \"You are a travel expert that can provide hotel recommendations for a given destination. \"\n", + " \"If you need general travel help, ask 'travel_advisor' for help. \"\n", + " \"If you need specific sightseeing recommendations, ask 'sightseeing_advisor' for help. \"\n", + " \"If you have enough information to respond to the user, return 'finish'. \"\n", + " \"Never mention other agents by name.\"\n", + " ),\n", + ")\n", + "\n", + "\n", + "builder = StateGraph(MessagesState)\n", + "builder.add_node(\"travel_advisor\", travel_advisor)\n", + "builder.add_node(\"sightseeing_advisor\", sightseeing_advisor)\n", + "builder.add_node(\"hotel_advisor\", hotel_advisor)\n", + "# we'll always start with a general travel advisor\n", + "builder.add_edge(START, \"travel_advisor\")\n", + "\n", + "graph = builder.compile()" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "d77921f6-599d-443f-8b15-56b1adafd3a8", + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from IPython.display import display, Image\n", + "\n", + "display(Image(graph.get_graph().draw_mermaid_png()))" + ] + }, + { + "cell_type": "markdown", + "id": "af856e1b-41fc-4041-8cbf-3818a60088e0", + "metadata": {}, + "source": [ + "First, let's invoke it with a generic input:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "26a0d4df-ff99-40f0-92a8-0b3f2c591040", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{'travel_advisor': {'messages': {'role': 'ai', 'content': 'The Caribbean is a fantastic choice for warm, sunny weather and beautiful beaches. Here are a few destinations you might consider:\\n\\n1. **Jamaica**: Known for its vibrant culture, reggae music, and stunning beaches like Negril and Montego Bay.\\n\\n2. **Bahamas**: With over 700 islands, the Bahamas offers clear turquoise waters and beautiful sandy beaches, perfect for relaxation and water sports.\\n\\n3. **Dominican Republic**: Known for its resorts, beaches, and golfing. Punta Cana and Puerto Plata are popular destinations.\\n\\n4. **Barbados**: Offers beautiful beaches and a rich history, with plenty of activities and festivals.\\n\\n5. **Puerto Rico**: A mix of Spanish heritage and modern resorts, with opportunities for hiking in El Yunque National Forest and enjoying the vibrant nightlife in San Juan.\\n\\n6. **Aruba**: Known for its dry climate and sunny days, with beautiful beaches and activities like snorkeling and diving.\\n\\nEach of these destinations has its own unique charm and appeal. If you need specific sightseeing or hotel recommendations, let me know!', 'name': 'travel_advisor'}}}\n", + "\n", + "\n" + ] + } + ], + "source": [ + "for chunk in graph.stream(\n", + " {\"messages\": [(\"user\", \"i wanna go somewhere warm in the caribbean\")]}\n", + "):\n", + " print(chunk)\n", + " print(\"\\n\")" + ] + }, + { + "cell_type": "markdown", + "id": "997ea9aa-36ee-40a1-a5fc-b44a079786a9", + "metadata": {}, + "source": [ + "You can see that in this case only the first agent (`travel_advisor`) ran. Let's now ask for more recommendations:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "68a547d4-0a15-43bd-aeed-c9ba1dfe388f", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{'travel_advisor': {'messages': {'role': 'ai', 'content': \"I recommend visiting Barbados for a warm Caribbean getaway. It's known for its beautiful beaches, vibrant culture, and friendly locals. Let me gather some sightseeing and hotel recommendations for you.\", 'name': 'travel_advisor'}}}\n", + "\n", + "\n", + "{'sightseeing_advisor': {'messages': {'role': 'ai', 'content': \"Barbados is a fantastic destination to experience the warmth of the Caribbean. Here are some things to do and places to stay:\\n\\n### Sightseeing Recommendations:\\n1. **Harrison's Cave**: Explore this stunning limestone cave with its impressive stalactites and stalagmites. \\n2. **Bathsheba Beach**: Known for its unique rock formations and surf-friendly waves, it's perfect for a day of relaxation and exploration.\\n3. **St. Nicholas Abbey**: Visit this historic plantation house, distillery, and museum for a glimpse into the island's colonial past.\\n4. **Animal Flower Cave**: Located at the northern tip of Barbados, this sea cave offers incredible views and natural rock pools.\\n5. **Oistins Fish Fry**: Experience local culture and cuisine with fresh seafood, music, and dancing every Friday night.\\n\\n### Hotel Recommendations:\\n1. **Sandy Lane**: A luxurious resort offering world-class amenities, golf courses, and a private beach.\\n2. **The Crane Resort**: Known for its historic charm and stunning ocean views, it provides a unique blend of luxury and culture.\\n3. **Sea Breeze Beach House**: Offers an all-inclusive experience with multiple dining options and beachfront access.\\n4. **The House by Elegant Hotels**: A boutique, adults-only hotel perfect for a romantic getaway with personalized service and beachfront location.\\n\\nEnjoy your trip to Barbados!\", 'name': 'sightseeing_advisor'}}}\n", + "\n", + "\n" + ] + } + ], + "source": [ + "for chunk in graph.stream(\n", + " {\n", + " \"messages\": [\n", + " (\n", + " \"user\",\n", + " \"i wanna go somewhere warm in the caribbean. pick one destination, give me some things to do and hotel recommendations\",\n", + " )\n", + " ]\n", + " }\n", + "):\n", + " print(chunk)\n", + " print(\"\\n\")" + ] + }, + { + "cell_type": "markdown", + "id": "c1c66f91-39b0-4ed2-91e8-6daf6d124f47", + "metadata": {}, + "source": [ + "Voila - `travel_advisor` makes a decision to first get some sightseeing recommendations from `sightseeing_advisor`, and then `sightseeing_advisor` in turn calls `hotel_advisor` for more info. Notice that we never explicitly defined the order in which the agents should be executed!" + ] + }, + { + "cell_type": "markdown", + "id": "3f9930b9-16b4-4179-9990-7ddf48cb3ed7", + "metadata": {}, + "source": [ + "## Game NPCs Example" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "3f7b49c5-070e-4289-88aa-afbfae44cc98", + "metadata": {}, + "source": [ + "In this example we will create a team of [non-player characters (NPCs)](https://en.wikipedia.org/wiki/Non-player_character) that all run at the same time and share game state (resources). At each step, each NPC will inspect the state and decide whether to halt or continue acting at the next step. If it continues, it will update the shared game state (produce or consume resources).\n", + "\n", + "We will create 4 NPC agents:\n", + "\n", + "- `villager`: produces wood and food until there is enough, then halts\n", + "- `guard`: protects gold and consumes food. When there is not enough food, leaves duty and halts\n", + "- `merchant`: trades wood for gold. When there is not enough wood, halts\n", + "- `thief`: checks if the guard is on duty and steals all of the gold when the guard leaves, then halts\n", + "\n", + "Our NPC agents will be simple node functions (`villager`, `guard`, etc.). At each step of the graph execution, the agent function will inspect the resource values in the state and decide whether it should halt or continue. If it decides to continue, it will update the resource values in the state and loop back to itself to run at the next step.\n", + "\n", + "Now, let's define our agent nodes and graph!" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "f15c38c0-c88a-404b-9687-a9ef9ff20ffc", + "metadata": {}, + "outputs": [], + "source": [ + "from typing_extensions import Annotated, TypedDict, Literal\n", + "\n", + "from langchain_core.runnables import RunnableConfig\n", + "from langgraph.graph import StateGraph, START, END\n", + "from langgraph.types import Command\n", + "\n", + "import operator\n", + "\n", + "\n", + "class GameState(TypedDict):\n", + " # note that we're defining a reducer (operator.add) here.\n", + " # This will allow all agents to write their updates for resources concurrently.\n", + " wood: Annotated[int, operator.add]\n", + " food: Annotated[int, operator.add]\n", + " gold: Annotated[int, operator.add]\n", + " guard_on_duty: bool\n", + "\n", + "\n", + "def villager(state: GameState) -> Command[Literal[\"villager\", END]]:\n", + " \"\"\"Villager NPC that gathers wood and food.\"\"\"\n", + " current_resources = state[\"wood\"] + state[\"food\"]\n", + " if current_resources < 15: # Continue gathering until we have enough resources\n", + " print(\"Villager gathering resources.\")\n", + " # Loop back to the 'villager' agent\n", + " return Command(goto=\"villager\", update={\"wood\": 3, \"food\": 1})\n", + " # NOTE: Returning Command(goto=END) is not necessary for the graph to run correctly\n", + " # but it's useful for visualization, to show that the agent actually halts\n", + " else:\n", + " return Command(goto=END)\n", + "\n", + "\n", + "def guard(state: GameState) -> Command[Literal[\"guard\", END]]:\n", + " \"\"\"Guard NPC that protects gold and consumes food.\"\"\"\n", + " if not state[\"guard_on_duty\"]:\n", + " return Command(goto=END)\n", + "\n", + " if state[\"food\"] > 0: # Guard needs food to keep patrolling\n", + " print(\"Guard patrolling.\")\n", + " # Loop back to the 'guard' agent\n", + " return Command(\n", + " goto=\"guard\",\n", + " update={\"food\": -1}, # Consume food while patrolling\n", + " )\n", + " else:\n", + " print(\"Guard leaving to get food.\")\n", + " return Command(goto=END, update={\"guard_on_duty\": False}) # Leave to get food\n", + "\n", + "\n", + "def merchant(state: GameState) -> Command[Literal[\"merchant\", END]]:\n", + " \"\"\"Merchant NPC that trades wood for gold.\"\"\"\n", + " if state[\"wood\"] >= 5: # Trade wood for gold when available\n", + " print(\"Merchant trading wood for gold.\")\n", + " return Command(goto=\"merchant\", update={\"wood\": -5, \"gold\": 1})\n", + " else:\n", + " return Command(goto=END)\n", + "\n", + "\n", + "def thief(state: GameState) -> Command[Literal[\"thief\", END]]:\n", + " \"\"\"Thief NPC that steals gold if the guard leaves to get food.\"\"\"\n", + " if not state[\"guard_on_duty\"]:\n", + " print(\"Thief stealing gold.\")\n", + " return Command(goto=END, update={\"gold\": -state[\"gold\"]})\n", + " else:\n", + " # keep thief on standby (loop back to the 'thief' agent)\n", + " return Command(goto=\"thief\")\n", + "\n", + "\n", + "builder = StateGraph(GameState)\n", + "\n", + "# Add NPC nodes\n", + "builder.add_node(villager)\n", + "builder.add_node(guard)\n", + "builder.add_node(merchant)\n", + "builder.add_node(thief)\n", + "\n", + "# All NPCs start running in parallel\n", + "builder.add_edge(START, \"villager\")\n", + "builder.add_edge(START, \"guard\")\n", + "builder.add_edge(START, \"merchant\")\n", + "builder.add_edge(START, \"thief\")\n", + "graph = builder.compile()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "ab4cc03e-4e25-44ac-88b1-e415fcbce151", + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "display(Image(graph.get_graph().draw_mermaid_png()))" + ] + }, + { + "cell_type": "markdown", + "id": "5a3ea167-c302-41f7-906e-60fd0e5cd004", + "metadata": {}, + "source": [ + "Let's run it with some initial state!" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "83f50671-9371-46dd-847d-5db824c1141e", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Game state {'wood': 10, 'food': 3, 'gold': 10, 'guard_on_duty': True}\n", + "\n", + "\n", + "Villager gathering resources.\n", + "Guard patrolling.\n", + "Merchant trading wood for gold.\n", + "Game state {'wood': 8, 'food': 3, 'gold': 11, 'guard_on_duty': True}\n", + "\n", + "\n", + "Villager gathering resources.\n", + "Guard patrolling.\n", + "Merchant trading wood for gold.\n", + "Game state {'wood': 6, 'food': 3, 'gold': 12, 'guard_on_duty': True}\n", + "\n", + "\n", + "Villager gathering resources.\n", + "Guard patrolling.\n", + "Merchant trading wood for gold.\n", + "Game state {'wood': 4, 'food': 3, 'gold': 13, 'guard_on_duty': True}\n", + "\n", + "\n", + "Villager gathering resources.\n", + "Guard patrolling.\n", + "Game state {'wood': 7, 'food': 3, 'gold': 13, 'guard_on_duty': True}\n", + "\n", + "\n", + "Villager gathering resources.\n", + "Guard patrolling.\n", + "Game state {'wood': 10, 'food': 3, 'gold': 13, 'guard_on_duty': True}\n", + "\n", + "\n", + "Villager gathering resources.\n", + "Guard patrolling.\n", + "Game state {'wood': 13, 'food': 3, 'gold': 13, 'guard_on_duty': True}\n", + "\n", + "\n", + "Guard patrolling.\n", + "Game state {'wood': 13, 'food': 2, 'gold': 13, 'guard_on_duty': True}\n", + "\n", + "\n", + "Guard patrolling.\n", + "Game state {'wood': 13, 'food': 1, 'gold': 13, 'guard_on_duty': True}\n", + "\n", + "\n", + "Guard patrolling.\n", + "Game state {'wood': 13, 'food': 0, 'gold': 13, 'guard_on_duty': True}\n", + "\n", + "\n", + "Guard leaving to get food.\n", + "Game state {'wood': 13, 'food': 0, 'gold': 13, 'guard_on_duty': False}\n", + "\n", + "\n", + "Thief stealing gold.\n", + "Game state {'wood': 13, 'food': 0, 'gold': 0, 'guard_on_duty': False}\n", + "\n", + "\n" + ] + } + ], + "source": [ + "initial_state = {\"wood\": 10, \"food\": 3, \"gold\": 10, \"guard_on_duty\": True}\n", + "for state in graph.stream(initial_state, stream_mode=\"values\"):\n", + " print(\"Game state\", state)\n", + " print(\"\\n\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index bc1ff59ea..d83eec8cf 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -199,6 +199,8 @@ nav: - how-tos/subgraph.ipynb - how-tos/subgraphs-manage-state.ipynb - how-tos/subgraph-transform-state.ipynb + - Multi-agent: + - how-tos/multi-agent-network.ipynb - State Management: - State Management: how-tos#state-management - how-tos/state-model.ipynb From e1d8c6b11314c587ccb28bb416d5bf5478fb9951 Mon Sep 17 00:00:00 2001 From: Vadym Barda Date: Mon, 9 Dec 2024 21:01:14 -0500 Subject: [PATCH 2/5] docs: update multi-agent concept doc (#2684) --- docs/docs/concepts/multi_agent.md | 200 ++++++++++++++++++++++-------- 1 file changed, 151 insertions(+), 49 deletions(-) diff --git a/docs/docs/concepts/multi_agent.md b/docs/docs/concepts/multi_agent.md index d8ef0a73b..61bed3fd7 100644 --- a/docs/docs/concepts/multi_agent.md +++ b/docs/docs/concepts/multi_agent.md @@ -26,10 +26,131 @@ There are several ways to connect agents in a multi-agent system: - **Hierarchical**: you can define a multi-agent system with [a supervisor of supervisors](https://langchain-ai.github.io/langgraph/tutorials/multi_agent/hierarchical_agent_teams/). This is a generalization of the supervisor architecture and allows for more complex control flows. - **Custom multi-agent workflow**: each agent communicates with only a subset of agents. Parts of the flow are deterministic, and only some agents can decide which other agents to call next. +### Handoffs + +In multi-agent architectures, agents can be represented as graph nodes. Each agent node executes its step(s) and decides whether to finish execution or route to another agent, including potentially routing to itself (e.g., running in a loop). A common pattern in multi-agent interactions is handoffs, where one agent hands off control to another. Handoffs allow you to specify: + +- __destination__: target agent to navigate to (e.g., name of the node to go to) +- __payload__: [information to pass to that agent](#communication-between-agents) (e.g., state update) + +To implement handoffs in LangGraph, agent nodes can return [`Command`](./low_level.md#command) object that allows you to combine both control flow and state updates: + +```python +def agent(state) -> Command[Literal["agent", "another_agent"]]: + # the condition for routing/halting can be anything, e.g. LLM tool call / structured output, etc. + goto = get_next_agent(...) # 'agent' / 'another_agent' + return Command( + # Specify which agent to call next + goto=goto, + # Update the graph state + update={"my_state_key": "my_state_value"} + ) +``` + +In a more complex scenario where each agent node is itself a graph (i.e., a [subgraph](./low_level.md#subgraphs)), a node in one of the agent subgraphs might want to navigate to a different agent. For example, if you have two agents, `alice` and `bob` (subgraph nodes in a parent graph), and `alice` needs to navigate to `bob`, you can set `graph=Command.PARENT` in the `Command` object: + +```python +def some_node_inside_alice(state) + return Command( + goto="bob", + update={"my_state_key": "my_state_value"}, + # specify which graph to navigate to (defaults to the current graph) + graph=Command.PARENT, + ) +``` + +!!! note + If you need to support visualization for subgraphs communicating using `Command(graph=Command.PARENT)` you would need to wrap them in a node function with `Command` annotation, e.g. instead of this: + + ```python + builder.add_node(alice) + ``` + + you would need to do this: + + ```python + def call_alice(state) -> Command[Literal["bob"]]: + return alice.invoke(state) + + builder.add_node("alice", call_alice) + ``` + +#### Handoffs as tools + +One of the most common agent types is a ReAct-style tool-calling agents. For those types of agents, a common pattern is wrapping a handoff in a tool call, e.g.: + +```python +def transfer_to_bob(state): + """Transfer to bob.""" + return Command( + goto="bob", + update={"my_state_key": "my_state_value"}, + graph=Command.PARENT, + ) +``` + +This is a special case of [updating the graph state from tools](../how-tos/update-state-from-tools.ipynb) where in addition the state update, the control flow is included as well. + +!!! important + +If you want to use tools that return `Command`, you can either use prebuilt [`create_react_agent`][langgraph.prebuilt.chat_agent_executor.create_react_agent] / [`ToolNode`][langgraph.prebuilt.tool_node.ToolNode] components, or implement your own tool-executing node that collects `Command` objects returned by the tools and returns a list of them, e.g.: + +```python +def call_tools(state): + ... + commands = [tools_by_name[call["name"].invoke(call, config={"coerce_tool_content": False}) for tool_call in tool_calls] + return commands +``` + +Let's now take a closer look at the different multi-agent architectures. + ### Network In this architecture, agents are defined as graph nodes. Each agent can communicate with every other agent (many-to-many connections) and can decide which agent to call next. This architecture is good for problems that do not have a clear hierarchy of agents or a specific sequence in which agents should be called. + +```python +from typing import Literal +from langchain_openai import ChatOpenAI +from langgraph.graph import StateGraph, MessagesState, START + +model = ChatOpenAI() + +def agent_1(state: MessagesState) -> Command[Literal["agent_2", "agent_3", END]]: + # you can pass relevant parts of the state to the LLM (e.g., state["messages"]) + # to determine which agent to call next. a common pattern is to call the model + # with a structured output (e.g. force it to return an output with a "next_agent" field) + response = model.invoke(...) + # route to one of the agents or exit based on the LLM's decision + # if the LLM returns "__end__", the graph will finish execution + return Command( + goto=response["next_agent"], + update={"messages": [response["content"]]}, + ) + +def agent_2(state: MessagesState) -> Command[Literal["agent_1", "agent_3", END]]: + response = model.invoke(...) + return Command( + goto=response["next_agent"], + update={"messages": [response["content"]]}, + ) + +def agent_3(state: MessagesState) -> Command[Literal["agent_1", "agent_2", END]]: + ... + return Command( + goto=response["next_agent"], + update={"messages": [response["content"]]}, + ) + +builder = StateGraph(MessagesState) +builder.add_node(agent_1) +builder.add_node(agent_2) +builder.add_node(agent_3) + +builder.add_edge(START, "agent_1") +network = builder.compile() +``` + ### Supervisor In this architecture, we define agents as nodes and add a supervisor node (LLM) that decides which agent nodes should be called next. We use [conditional edges](./low_level.md#conditional-edges) to route execution to the appropriate agent node based on supervisor's decision. This architecture also lends itself well to running multiple agents in parallel or using [map-reduce](../how-tos/map-reduce.ipynb) pattern. @@ -37,43 +158,41 @@ In this architecture, we define agents as nodes and add a supervisor node (LLM) ```python from typing import Literal from langchain_openai import ChatOpenAI -from langgraph.graph import StateGraph, MessagesState, START +from langgraph.graph import StateGraph, MessagesState, START, END model = ChatOpenAI() -class AgentState(MessagesState): - next: Literal["agent_1", "agent_2", "__end__"] - -def supervisor(state: AgentState): +def supervisor(state: MessagesState) -> Command[Literal["agent_1", "agent_2", END]]: # you can pass relevant parts of the state to the LLM (e.g., state["messages"]) # to determine which agent to call next. a common pattern is to call the model # with a structured output (e.g. force it to return an output with a "next_agent" field) response = model.invoke(...) - # the "next" key will be used by the conditional edges to route execution - # to the appropriate agent - return {"next": response["next_agent"]} + # route to one of the agents or exit based on the supervisor's decision + # if the supervisor returns "__end__", the graph will finish execution + return Command(goto=response["next_agent"]) -def agent_1(state: AgentState): +def agent_1(state: MessagesState) -> Command[Literal["supervisor"]]: # you can pass relevant parts of the state to the LLM (e.g., state["messages"]) # and add any additional logic (different models, custom prompts, structured output, etc.) response = model.invoke(...) - return {"messages": [response]} + return Command( + goto="supervisor", + update={"messages": [response]}, + ) -def agent_2(state: AgentState): +def agent_2(state: MessagesState) -> Command[Literal["supervisor"]]: response = model.invoke(...) - return {"messages": [response]} + return Command( + goto="supervisor", + update={"messages": [response]}, + ) -builder = StateGraph(AgentState) +builder = StateGraph(MessagesState) builder.add_node(supervisor) builder.add_node(agent_1) builder.add_node(agent_2) builder.add_edge(START, "supervisor") -# route to one of the agents or exit based on the supervisor's decisiion -# if the supervisor returns "__end__", the graph will finish execution -builder.add_conditional_edges("supervisor", lambda state: state["next"]) -builder.add_edge("agent_1", "supervisor") -builder.add_edge("agent_2", "supervisor") supervisor = builder.compile() ``` @@ -121,37 +240,29 @@ To address this, you can design your system _hierarchically_. For example, you c ```python from typing import Literal from langchain_openai import ChatOpenAI -from langgraph.graph import StateGraph, MessagesState, START +from langgraph.graph import StateGraph, MessagesState, START, END model = ChatOpenAI() # define team 1 (same as the single supervisor example above) -class Team1State(MessagesState): - next: Literal["team_1_agent_1", "team_1_agent_2", "__end__"] -def team_1_supervisor(state: Team1State): +def team_1_supervisor(state: MessagesState) -> Command[Literal["team_1_agent_1", "team_1_agent_2", END]]: response = model.invoke(...) - return {"next": response["next_agent"]} + return Command(goto=response["next_agent"]) -def team_1_agent_1(state: Team1State): +def team_1_agent_1(state: MessagesState) -> Command[Literal["team_1_supervisor"]]: response = model.invoke(...) - return {"messages": [response]} + return Command(goto="team_1_supervisor", update={"messages": [response]}) -def team_1_agent_2(state: Team1State): +def team_1_agent_2(state: MessagesState) -> Command[Literal["team_1_supervisor"]]: response = model.invoke(...) - return {"messages": [response]} + return Command(goto="team_1_supervisor", update={"messages": [response]}) team_1_builder = StateGraph(Team1State) team_1_builder.add_node(team_1_supervisor) team_1_builder.add_node(team_1_agent_1) team_1_builder.add_node(team_1_agent_2) team_1_builder.add_edge(START, "team_1_supervisor") -# route to one of the agents or exit based on the supervisor's decisiion -# if the supervisor returns "__end__", the graph will finish execution -team_1_builder.add_conditional_edges("team_1_supervisor", lambda state: state["next"]) -team_1_builder.add_edge("team_1_agent_1", "team_1_supervisor") -team_1_builder.add_edge("team_1_agent_2", "team_1_supervisor") - team_1_graph = team_1_builder.compile() # define team 2 (same as the single supervisor example above) @@ -174,31 +285,22 @@ team_2_graph = team_2_builder.compile() # define top-level supervisor -class TopLevelState(MessagesState): - next: Literal["team_1", "team_2", "__end__"] - -builder = StateGraph(TopLevelState) -def top_level_supervisor(state: TopLevelState): +builder = StateGraph(MessagesState) +def top_level_supervisor(state: MessagesState): # you can pass relevant parts of the state to the LLM (e.g., state["messages"]) # to determine which team to call next. a common pattern is to call the model # with a structured output (e.g. force it to return an output with a "next_team" field) response = model.invoke(...) - # the "next" key will be used by the conditional edges to route execution - # to the appropriate team - return {"next": response["next_team"]} + # route to one of the teams or exit based on the supervisor's decision + # if the supervisor returns "__end__", the graph will finish execution + return Command(goto=response["next_team"]) -builder = StateGraph(TopLevelState) +builder = StateGraph(MessagesState) builder.add_node(top_level_supervisor) builder.add_node(team_1_graph) builder.add_node(team_2_graph) builder.add_edge(START, "top_level_supervisor") -# route to one of the teams or exit based on the supervisor's decision -# if the top-level supervisor returns "__end__", the graph will finish execution -builder.add_conditional_edges("top_level_supervisor", lambda state: state["next"]) -builder.add_edge("team_1_graph", "top_level_supervisor") -builder.add_edge("team_2_graph", "top_level_supervisor") - graph = builder.compile() ``` @@ -208,7 +310,7 @@ In this architecture we add individual agents as graph nodes and define the orde - **Explicit control flow (normal edges)**: LangGraph allows you to explicitly define the control flow of your application (i.e. the sequence of how agents communicate) explicitly, via [normal graph edges](./low_level.md#normal-edges). This is the most deterministic variant of this architecture above — we always know which agent will be called next ahead of time. -- **Dynamic control flow (conditional edges)**: in LangGraph you can allow LLMs to decide parts of your application control flow. This can be achieved by using [conditional edges](./low_level.md#conditional-edges). A special case of this is a [supervisor tool-calling](#supervisor-tool-calling) architecture. In that case, the tool-calling LLM powering the supervisor agent will make decisions about the order in which the tools (agents) are being called. +- **Dynamic control flow (Command)**: in LangGraph you can allow LLMs to decide parts of your application control flow. This can be achieved by using [`Command`](./low_level.md#command). A special case of this is a [supervisor tool-calling](#supervisor-tool-calling) architecture. In that case, the tool-calling LLM powering the supervisor agent will make decisions about the order in which the tools (agents) are being called. ```python from langchain_openai import ChatOpenAI From d81dec653d0760fdbc80b01000a4dcbb9b1aeac7 Mon Sep 17 00:00:00 2001 From: Vadym Barda Date: Mon, 9 Dec 2024 21:09:32 -0500 Subject: [PATCH 3/5] docs: temporarily fix link (#2685) --- docs/docs/concepts/multi_agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/multi_agent.md b/docs/docs/concepts/multi_agent.md index 61bed3fd7..c9bdd5d89 100644 --- a/docs/docs/concepts/multi_agent.md +++ b/docs/docs/concepts/multi_agent.md @@ -89,7 +89,7 @@ def transfer_to_bob(state): ) ``` -This is a special case of [updating the graph state from tools](../how-tos/update-state-from-tools.ipynb) where in addition the state update, the control flow is included as well. +This is a special case of updating the graph state from tools where in addition the state update, the control flow is included as well. !!! important From 43b6c06f5c0fc055db1320ac8fa9f8436c393ed7 Mon Sep 17 00:00:00 2001 From: Vadym Barda Date: Mon, 9 Dec 2024 21:19:16 -0500 Subject: [PATCH 4/5] docs: update Command concept doc (#2686) --- docs/docs/concepts/low_level.md | 33 +-------------------------------- 1 file changed, 1 insertion(+), 32 deletions(-) diff --git a/docs/docs/concepts/low_level.md b/docs/docs/concepts/low_level.md index 1d059568b..297f97ec9 100644 --- a/docs/docs/concepts/low_level.md +++ b/docs/docs/concepts/low_level.md @@ -339,37 +339,6 @@ def my_node(state: State) -> Command[Literal["my_other_node"]]: ) ``` -`Command` has the following properties: - -| Property | Description | -| --- | --- | -| `graph` | Graph to send the command to. Supported values:
- `None`: the current graph (default)
- `Command.PARENT`: closest parent graph | -| `update` | Update to apply to the graph's state. | -| `resume` | Value to resume execution with. To be used together with [`interrupt()`][langgraph.types.interrupt]. | -| `goto` | Can be one of the following:
- name of the node to navigate to next (any node that belongs to the specified `graph`)
- sequence of node names to navigate to next
- `Send` object (to execute a node with the input provided)
- sequence of `Send` objects
If `goto` is not specified and there are no other tasks left in the graph, the graph will halt after executing the current superstep. | - -```python -from langgraph.graph import StateGraph, START -from langgraph.types import Command -from typing_extensions import Literal, TypedDict - -class State(TypedDict): - foo: str - -def my_node(state: State) -> Command[Literal["my_other_node"]]: - return Command(update={"foo": "bar"}, goto="my_other_node") - -def my_other_node(state: State): - return {"foo": state["foo"] + "baz"} - -builder = StateGraph(State) -builder.add_edge(START, "my_node") -builder.add_node("my_node", my_node) -builder.add_node("my_other_node", my_other_node) - -graph = builder.compile() -``` - With `Command` you can also achieve dynamic control flow behavior (identical to [conditional edges](#conditional-edges)): ```python @@ -380,7 +349,7 @@ def my_node(state: State) -> Command[Literal["my_other_node"]]: !!! important - When returning `Command` in your node functions, you must add return type annotations with the list of node names the node is routing to, e.g. `Command[Literal["node_b", "node_c"]]`. This is necessary for the graph compilation and rendering, and tells LangGraph that `node_a` can navigate to `node_b` and `node_c`. + When returning `Command` in your node functions, you must add return type annotations with the list of node names the node is routing to, e.g. `Command[Literal["my_other_node"]]`. This is necessary for the graph rendering and tells LangGraph that `my_node` can navigate to `my_other_node`. Check out this [how-to guide](../how-tos/command.ipynb) for an end-to-end example of how to use `Command`. From 33fe467d1f32d080beb607c1241766ba72824708 Mon Sep 17 00:00:00 2001 From: Nuno Campos Date: Mon, 9 Dec 2024 18:22:53 -0800 Subject: [PATCH 5/5] lib: Treat Command as "resuming" signal (#2682) - so it works w interrupt_before/after --------- Co-authored-by: Eugene Yurtsev --- libs/langgraph/langgraph/pregel/loop.py | 27 +++++++++-------- libs/langgraph/tests/test_pregel.py | 40 +++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 12 deletions(-) diff --git a/libs/langgraph/langgraph/pregel/loop.py b/libs/langgraph/langgraph/pregel/loop.py index 678e355ab..e96276259 100644 --- a/libs/langgraph/langgraph/pregel/loop.py +++ b/libs/langgraph/langgraph/pregel/loop.py @@ -535,9 +535,23 @@ def _first(self, *, input_keys: Union[str, Sequence[str]]) -> None: # - receiving None input (outer graph) or RESUMING flag (subgraph) configurable = self.config.get(CONF, {}) is_resuming = bool(self.checkpoint["channel_versions"]) and bool( - configurable.get(CONFIG_KEY_RESUMING, self.input is None) + configurable.get( + CONFIG_KEY_RESUMING, + self.input is None or isinstance(self.input, Command), + ) ) + # map command to writes + if isinstance(self.input, Command): + writes: defaultdict[str, list[tuple[str, Any]]] = defaultdict(list) + # group writes by task ID + for tid, c, v in map_command(self.input, self.checkpoint_pending_writes): + writes[tid].append((c, v)) + if not writes: + raise EmptyInputError("Received empty Command input") + # save writes + for tid, ws in writes.items(): + self.put_writes(tid, ws) # proceed past previous checkpoint if is_resuming: self.checkpoint["versions_seen"].setdefault(INTERRUPT, {}) @@ -549,17 +563,6 @@ def _first(self, *, input_keys: Union[str, Sequence[str]]) -> None: self._emit( "values", map_output_values, self.output_keys, True, self.channels ) - # map command to writes - elif isinstance(self.input, Command): - writes: defaultdict[str, list[tuple[str, Any]]] = defaultdict(list) - # group writes by task ID - for tid, c, v in map_command(self.input, self.checkpoint_pending_writes): - writes[tid].append((c, v)) - if not writes: - raise EmptyInputError("Received empty Command input") - # save writes - for tid, ws in writes.items(): - self.put_writes(tid, ws) # map inputs to channel updates elif input_writes := deque(map_input(input_keys, self.input)): # TODO shouldn't these writes be passed to put_writes too? diff --git a/libs/langgraph/tests/test_pregel.py b/libs/langgraph/tests/test_pregel.py index 1cbadf099..91d7907d0 100644 --- a/libs/langgraph/tests/test_pregel.py +++ b/libs/langgraph/tests/test_pregel.py @@ -14904,3 +14904,43 @@ def my_node(state: State): graph = graph.compile() assert graph.invoke({"foo": ""}) == {"foo": "ab"} + + +def test_command_with_static_breakpoints() -> None: + """Test that we can use Command to resume and update with static breakpoints.""" + + class State(TypedDict): + """The graph state.""" + + foo: str + + def node1(state: State): + return { + "foo": state["foo"] + "|node-1", + } + + def node2(state: State): + return { + "foo": state["foo"] + "|node-2", + } + + builder = StateGraph(State) + builder.add_node("node1", node1) + builder.add_node("node2", node2) + builder.add_edge(START, "node1") + builder.add_edge("node1", "node2") + + # A checkpointer must be enabled for interrupts to work! + checkpointer = MemorySaver() + graph = builder.compile(checkpointer=checkpointer, interrupt_before=["node1"]) + + config = { + "configurable": { + "thread_id": uuid.uuid4(), + } + } + + # Start the graph and interrupt at the first node + graph.invoke({"foo": "abc"}, config) + result = graph.invoke(Command(resume="node1"), config) + assert result == {"foo": "abc|node-1|node-2"}