From d7a04663dae461cb983b0b547e916ecf8bb9fb5e Mon Sep 17 00:00:00 2001
From: William FH <13333726+hinthornw@users.noreply.github.com>
Date: Mon, 1 Jul 2024 10:20:20 -0700
Subject: [PATCH] [Docs]  Improve create_react_agent docstring (#899)

- Cleanup parameter formatting
- Add diagrams
- Walk through example execution
---
 .../langgraph/prebuilt/chat_agent_executor.py | 43 +++++++++++++++++++
 .../langgraph/prebuilt/tool_executor.py       | 14 +++---
 .../langgraph/langgraph/prebuilt/tool_node.py |  1 +
 3 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/libs/langgraph/langgraph/prebuilt/chat_agent_executor.py b/libs/langgraph/langgraph/prebuilt/chat_agent_executor.py
index 2a8057f32..b5dba5d52 100644
--- a/libs/langgraph/langgraph/prebuilt/chat_agent_executor.py
+++ b/libs/langgraph/langgraph/prebuilt/chat_agent_executor.py
@@ -180,7 +180,9 @@ def create_react_agent(
         tools: A list of tools or a ToolExecutor instance.
         messages_modifier: An optional
             messages modifier. This applies to messages BEFORE they are passed into the LLM.
+
             Can take a few different forms:
+
             - SystemMessage: this is added to the beginning of the list of messages.
             - str: This is converted to a SystemMessage and added to the beginning of the list of messages.
             - Callable: This function should take in a list of messages and the output is then passed to the language model.
@@ -198,6 +200,47 @@ def create_react_agent(
     Returns:
         A compiled LangChain runnable that can be used for chat interactions.
 
+    The resulting graph looks like this:
+
+    ``` mermaid
+    stateDiagram-v2
+        [*] --> Start
+        Start --> Agent
+        Agent --> Tools : continue
+        Tools --> Agent
+        Agent --> End : end
+        End --> [*]
+
+        classDef startClass fill:#ffdfba;
+        classDef endClass fill:#baffc9;
+        classDef otherClass fill:#fad7de;
+
+        class Start startClass
+        class End endClass
+        class Agent,Tools otherClass
+    ```
+
+    The "agent" node calls the language model with the messages list (after applying the messages modifier).
+    If the resulting AIMessage contains `tool_calls`, the graph will then call the ["tools"][toolnode].
+    The "tools" node executes the tools (1 tool per `tool_call`) and adds the responses to the messages list
+    as `ToolMessage` objects. The agent node then calls the language model again.
+    The process repeats until no more `tool_calls` are present in the response.
+    The agent then returns the full list of messages as a dictionary containing the key "messages".
+
+    ``` mermaid
+        sequenceDiagram
+            participant U as User
+            participant A as Agent (LLM)
+            participant T as Tools
+            U->>A: Initial input
+            Note over A: Messages modifier + LLM
+            loop while tool_calls present
+                A->>T: Execute tools
+                T-->>A: ToolMessage for each tool_calls
+            end
+            A->>U: Return final state
+    ```
+
     Examples:
         Use with a simple tool:
 
diff --git a/libs/langgraph/langgraph/prebuilt/tool_executor.py b/libs/langgraph/langgraph/prebuilt/tool_executor.py
index cf3140e72..cfd217044 100644
--- a/libs/langgraph/langgraph/prebuilt/tool_executor.py
+++ b/libs/langgraph/langgraph/prebuilt/tool_executor.py
@@ -34,11 +34,13 @@ class ToolInvocation(Serializable):
         tool_input (Union[str, dict]): The input to pass in to the Tool.
 
     Examples:
-
-            invocation = ToolInvocation(
-                tool="search",
-                tool_input="What is the capital of France?"
-            )
+        Basic usage:
+        ```pycon
+        >>> invocation = ToolInvocation(
+        ...    tool="search",
+        ...     tool_input="What is the capital of France?"
+        ... )
+        ```
     """
 
     tool: str
@@ -54,6 +56,7 @@ class ToolExecutor(RunnableCallable):
             when an invalid tool is requested. Defaults to INVALID_TOOL_MSG_TEMPLATE.
 
     Examples:
+        Basic usage:
 
         ```pycon
         >>> from langchain_core.tools import tool
@@ -74,6 +77,7 @@ class ToolExecutor(RunnableCallable):
         >>> print(result)
         "Searching for: What is the capital of France?"
         ```
+        Handling invalid tool:
 
         ```pycon
         >>> invocation = ToolInvocation(
diff --git a/libs/langgraph/langgraph/prebuilt/tool_node.py b/libs/langgraph/langgraph/prebuilt/tool_node.py
index ecb051581..0dddaf584 100644
--- a/libs/langgraph/langgraph/prebuilt/tool_node.py
+++ b/libs/langgraph/langgraph/prebuilt/tool_node.py
@@ -136,6 +136,7 @@ def tools_condition(
 
     Examples:
         Create a custom ReAct-style agent with tools.
+
         ```pycon
         >>> from langchain_anthropic import ChatAnthropic
         >>> from langchain_core.tools import tool