docs: move async guide into graph-api (#4676)

docs/_scripts/notebook_hooks.py

@@ -39,6 +39,7 @@ REDIRECT_MAP = {
     "how-tos/configuration.ipynb": "how-tos/graph-api/#add-runtime-configuration",
     "how-tos/node-retries.ipynb": "how-tos/graph-api/#add-retry-policies",
     "how-tos/return-when-recursion-limit-hits.ipynb": "how-tos/graph-api/#impose-a-recursion-limit",
+    "how-tos/async.ipynb": "how-tos/graph-api/#async",
     # memory how-tos
     "how-tos/memory/manage-conversation-history.ipynb": "how-tos/memory.ipynb",
     "how-tos/memory/delete-messages.ipynb": "how-tos/memory.ipynb#delete-messages",

docs/docs/how-tos/graph-api.ipynb

@@ -2677,6 +2677,55 @@
     "</details>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "5a2d23ae-ea3f-478b-8db6-791cd29cfb6c",
+   "metadata": {},
+   "source": [
+    "## Async\n",
+    "\n",
+    "Using the [async](https://docs.python.org/3/library/asyncio.html) programming paradigm can produce significant performance improvements when running [IO-bound](https://en.wikipedia.org/wiki/I/O_bound) code concurrently (e.g., making concurrent API requests to a chat model provider).\n",
+    "\n",
+    "To convert a `sync` implementation of the graph to an `async` implementation, you will need to:\n",
+    "\n",
+    "1. Update `nodes` use `async def` instead of `def`.\n",
+    "2. Update the code inside to use `await` appropriately.\n",
+    "3. Invoke the graph with `.ainvoke` or `.astream` as desired.\n",
+    "\n",
+    "Because many LangChain objects implement the [Runnable Protocol](https://python.langchain.com/docs/expression_language/interface/) which has `async` variants of all the `sync` methods it's typically fairly quick to upgrade a `sync` graph to an `async` graph.\n",
+    "\n",
+    "See example below. To demonstrate async invocations of underlying LLMs, we will include a chat model:\n",
+    "\n",
+    "{!snippets/chat_model_tabs.md!}\n",
+    "\n",
+    "```python\n",
+    "from langchain.chat_models import init_chat_model\n",
+    "from langgraph.graph import MessagesState, StateGraph\n",
+    "\n",
+    "\n",
+    "# highlight-next-line\n",
+    "async def node(state: MessagesState): # (1)!\n",
+    "    # highlight-next-line\n",
+    "    new_message = await llm.ainvoke(state[\"messages\"]) # (2)!\n",
+    "    return {\"messages\": [new_message]}\n",
+    "\n",
+    "\n",
+    "builder = StateGraph(MessagesState).add_node(node).set_entry_point(\"node\")\n",
+    "graph = builder.compile()\n",
+    "\n",
+    "input_message = {\"role\": \"user\", \"content\": \"Hello\"}\n",
+    "# highlight-next-line\n",
+    "result = await graph.ainvoke({\"messages\": [input_message]}) # (3)!\n",
+    "```\n",
+    "\n",
+    "1. Declare nodes to be async functions.\n",
+    "2. Use async invocations when available within the node.\n",
+    "3. Use async invocations on the graph object itself.\n",
+    "\n",
+    "!!! tip \"Async streaming\"\n",
+    "    See the [streaming guide](../../how-tos/streaming) for examples of streaming with async."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "d33ecddc-6818-41a3-9d0d-b1b1cbcd286d",

docs/mkdocs.yml

@@ -277,9 +277,6 @@ nav:
     - Agentic RAG: tutorials/rag/langgraph_agentic_rag.ipynb
     - Agent Supervisor: tutorials/multi_agent/agent_supervisor.ipynb
     - SQL agent: tutorials/sql-agent.ipynb
-    - Run a graph asynchronously: how-tos/async.ipynb
-        # We want to push async higher (need to check the content inside it)
-        # and convert it into a concept rather than a how-to page.
     - Graph runs in LangSmith: how-tos/run-id-langsmith.ipynb
     - LangGraph Platform:
       - Authentication: