From f289e64320eab8d1f4df351f7e50088e273593e1 Mon Sep 17 00:00:00 2001
From: Eric Zhu <ekzhu@users.noreply.github.com>
Date: Fri, 17 Jan 2025 01:13:14 -0800
Subject: [PATCH] docs: enhance agents.ipynb with parallel tool calls section
 (#5088)

* docs: enhance agents.ipynb with parallel tool calls section

* type ignore
---
 .../tutorial/agents.ipynb                     | 47 +++++++++++++++++--
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb
index 95b6834d99a6..cb846ee20b41 100644
--- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb
+++ b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb
@@ -27,7 +27,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -220,8 +220,13 @@
     "it will return the tool's output as a string in {py:class}`~autogen_agentchat.messages.ToolCallSummaryMessage` in its response.\n",
     "If your tool does not return a well-formed string in natural language, you\n",
     "can add a reflection step to have the model summarize the tool's output,\n",
-    "by setting the `reflect_on_tool_use=True` parameter in the {py:class}`~autogen_agentchat.agents.AssistantAgent` constructor.\n",
-    "\n",
+    "by setting the `reflect_on_tool_use=True` parameter in the {py:class}`~autogen_agentchat.agents.AssistantAgent` constructor."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "### Langchain Tools\n",
     "\n",
     "In addition to custom tools, you can also use tools from the Langchain library\n",
@@ -280,6 +285,42 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Parallel Tool Calls\n",
+    "\n",
+    "Some models support parallel tool calls, which can be useful for tasks that require multiple tools to be called simultaneously.\n",
+    "By default, if the model client produces multiple tool calls, {py:class}`~autogen_agentchat.agents.AssistantAgent`\n",
+    "will call the tools in parallel.\n",
+    "\n",
+    "You may want to disable parallel tool calls when the tools have side effects that may interfere with each other, or,\n",
+    "when agent behavior needs to be consistent across different models.\n",
+    "This should be done at the model client level.\n",
+    "\n",
+    "For {py:class}`~autogen_ext.models.openai.OpenAIChatCompletionClient` and {py:class}`~autogen_ext.models.openai.AzureOpenAIChatCompletionClient`,\n",
+    "set `parallel_tool_calls=False` to disable parallel tool calls."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_client_no_parallel_tool_call = OpenAIChatCompletionClient(\n",
+    "    model=\"gpt-4o\",\n",
+    "    parallel_tool_calls=False,  # type: ignore\n",
+    ")\n",
+    "agent_no_parallel_tool_call = AssistantAgent(\n",
+    "    name=\"assistant\",\n",
+    "    model_client=model_client_no_parallel_tool_call,\n",
+    "    tools=[web_search],\n",
+    "    system_message=\"Use tools to solve tasks.\",\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},