[Docs] Improve create_react_agent docstring (#899)

- Cleanup parameter formatting
- Add diagrams
- Walk through example execution

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:
 

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(

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