Update tutorial content; move selector group chat and swarm outside of tutorial. (#4915)

* Update tutorial content; move selector group chat and swarm outside of tutorial.

* Add redirect

---------

Co-authored-by: Jack Gerrits <jackgerrits@users.noreply.github.com>

python/packages/autogen-core/docs/src/conf.py

@@ -33,6 +33,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.graphviz",
+    "sphinxext.rediraffe",
     "sphinx_design",
     "sphinx_copybutton",
     "_extension.gallery_directive",
@@ -165,6 +166,11 @@ nb_mime_priority_overrides = [
   ('code_lint', 'text/plain', 100)
 ]
 
+rediraffe_redirects = {
+    "user-guide/agentchat-user-guide/tutorial/selector-group-chat.ipynb": "user-guide/agentchat-user-guide/selector-group-chat.ipynb",
+    "user-guide/agentchat-user-guide/tutorial/swarm.ipynb": "user-guide/agentchat-user-guide/swarm.ipynb",
+}
+
 
 def setup_to_main(
     app: Sphinx, pagename: str, templatename: str, context, doctree

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md

@@ -31,18 +31,30 @@ How to install AgentChat
 Build your first agent
 :::
 
+:::{grid-item-card} {fas}`graduation-cap;pst-color-primary` Tutorial
+:link: ./tutorial/models.html
+
+Step-by-step guide to using AgentChat, learn about agents, teams, and more
+:::
+
+:::{grid-item-card} {fas}`book;pst-color-primary` Selector Group Chat
+:link: ./selector-group-chat.html
+
+Multi-agent coordination through a shared context and centralized, customizable selector
+:::
+
+:::{grid-item-card} {fas}`book;pst-color-primary` Swarm
+:link: ./swarm.html
+
+Multi-agent coordination through a shared context and localized, tool-based selector
+:::
+
 :::{grid-item-card} {fas}`book;pst-color-primary` Magentic-One
 :link: ./magentic-one.html
 
 Get started with Magentic-One
 :::
 
-:::{grid-item-card} {fas}`graduation-cap;pst-color-primary` Tutorial
-:link: ./tutorial/models.html
-
-Step-by-step guide to using AgentChat
-:::
-
 :::{grid-item-card} {fas}`code;pst-color-primary` Examples
 :link: ./examples/index.html
 
@@ -62,7 +74,6 @@ How to migrate from AutoGen 0.2.x to 0.4.x.
 
 installation
 quickstart
-magentic-one
 migration-guide
 ```
 
@@ -76,13 +87,21 @@ tutorial/messages
 tutorial/agents
 tutorial/teams
 tutorial/human-in-the-loop
-tutorial/selector-group-chat
-tutorial/swarm
 tutorial/termination
 tutorial/custom-agents
 tutorial/state
 ```
 
+```{toctree}
+:maxdepth: 1
+:hidden:
+:caption: Advanced
+
+selector-group-chat
+swarm
+magentic-one
+```
+
 ```{toctree}
 :maxdepth: 1
 :hidden:

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/migration-guide.md

@@ -600,7 +600,7 @@ for more details.
 In `v0.4`, you get a {py:class}`~autogen_agentchat.base.TaskResult` object from a `run` or `run_stream` method.
 The {py:class}`~autogen_agentchat.base.TaskResult` object contains the `messages` which is the message history
 of the chat, including both agents' private (tool calls, etc.) and public messages.
- 
+
 There are some notable differences between {py:class}`~autogen_agentchat.base.TaskResult` and `ChatResult`:
 
 - The `messages` list in {py:class}`~autogen_agentchat.base.TaskResult` uses different message format than the `ChatResult.chat_history` list.
@@ -610,7 +610,6 @@ There are some notable differences between {py:class}`~autogen_agentchat.base.Ta
 
 ## Conversion between v0.2 and v0.4 Messages
 
-
 You can use the following conversion functions to convert between a v0.4 message in
 {py:attr}`autogen_agentchat.base.TaskResult.messages` and a v0.2 message in `ChatResult.chat_history`.
 
@@ -809,7 +808,7 @@ asyncio.run(main())
 ```
 
 For LLM-based speaker selection, you can use the {py:class}`~autogen_agentchat.teams.SelectorGroupChat` instead.
-See [Selector Group Chat Tutorial](./tutorial/selector-group-chat.ipynb)
+See [Selector Group Chat Tutorial](./selector-group-chat.ipynb)
 and {py:class}`~autogen_agentchat.teams.SelectorGroupChat` for more details.
 
 > **Note**: In `v0.4`, you do not need to register functions on a user proxy to use tools
@@ -912,7 +911,7 @@ as the tools are directly executed within the {py:class}`~autogen_agentchat.agen
 which publishes the response from the tool to the group chat.
 So the group chat manager does not need to be involved in routing tool calls.
 
-See [Selector Group Chat Tutorial](./tutorial/selector-group-chat.ipynb) for an example
+See [Selector Group Chat Tutorial](./selector-group-chat.ipynb) for an example
 of using tools in a group chat.
 
 ## Group Chat with Custom Selector (Stateflow)

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/selector-group-chat.ipynb

@@ -22,7 +22,7 @@
                 "- Customizable selection function to override the default model-based selection\n",
                 "\n",
                 "```{note}\n",
-                "{py:class}`~autogen_agentchat.teams.SelectorGroupChat` is a high-level API. For more control and customization, refer to the [Group Chat Pattern](../../core-user-guide/design-patterns/group-chat.ipynb) in the Core API documentation to implement your own group chat logic.\n",
+                "{py:class}`~autogen_agentchat.teams.SelectorGroupChat` is a high-level API. For more control and customization, refer to the [Group Chat Pattern](../core-user-guide/design-patterns/group-chat.ipynb) in the Core API documentation to implement your own group chat logic.\n",
                 "```\n",
                 "\n",
                 "## How Does it Work?\n",
@@ -32,7 +32,7 @@
                 "When the team receives a task through {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run` or {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run_stream`,\n",
                 "the following steps are executed:\n",
                 "\n",
-                "1. The team analyzes the current conversation context, including the conversation history and participants' {py:attr}`~autogen_agentchat.base.ChatAgent.name` and {py:attr}`~autogen_agentchat.base.ChatAgent.description` attributes, to determine the next speaker using a model. You can override the model by providing a custom selection function.\n",
+                "1. The team analyzes the current conversation context, including the conversation history and participants' {py:attr}`~autogen_agentchat.base.ChatAgent.name` and {py:attr}`~autogen_agentchat.base.ChatAgent.description` attributes, to determine the next speaker using a model. By default, the team will not select the same speak consecutively unless it is the only agent available. This can be changed by setting `allow_repeated_speaker=True`. You can also override the model by providing a custom selection function.\n",
                 "2. The team prompts the selected speaker agent to provide a response, which is then **broadcasted** to all other participants.\n",
                 "3. The termination condition is checked to determine if the conversation should end, if not, the process repeats from step 1.\n",
                 "4. When the conversation ends, the team returns the {py:class}`~autogen_agentchat.base.TaskResult` containing the conversation history from this task.\n",

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/swarm.ipynb

@@ -18,7 +18,7 @@
                 "```{note}\n",
                 "{py:class}`~autogen_agentchat.teams.Swarm` is a high-level API. If you need more\n",
                 "control and customization that is not supported by this API, you can take a look\n",
-                "at the [Handoff Pattern](../../core-user-guide/design-patterns/handoffs.ipynb)\n",
+                "at the [Handoff Pattern](../core-user-guide/design-patterns/handoffs.ipynb)\n",
                 "in the Core API documentation and implement your own version of the Swarm pattern.\n",
                 "```\n",
                 "\n",

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/agents.ipynb

@@ -14,6 +14,7 @@
     "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages`: Send the agent a sequence of {py:class}`~autogen_agentchat.messages.ChatMessage` get a {py:class}`~autogen_agentchat.base.Response`. **It is important to note that agents are expected to be stateful and this method is expected to be called with new messages, not the complete history**.\n",
     "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream`: Same as {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages` but returns an iterator of {py:class}`~autogen_agentchat.messages.AgentEvent` or {py:class}`~autogen_agentchat.messages.ChatMessage` followed by a {py:class}`~autogen_agentchat.base.Response` as the last item.\n",
     "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_reset`: Reset the agent to its initial state.\n",
+    "- {py:meth}`~autogen_agentchat.agents.BaseChatAgent.run` and {py:meth}`~autogen_agentchat.agents.BaseChatAgent.run_stream`: convenience methods that call {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages` and {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream` respectively but offer the same interface as [Teams](./teams.ipynb).\n",
     "\n",
     "See {py:mod}`autogen_agentchat.messages` for more information on AgentChat message types.\n",
     "\n",
@@ -115,7 +116,10 @@
     "Unlike in v0.2 AgentChat, the tools are executed by the same agent directly within\n",
     "the same call to {py:meth}`~autogen_agentchat.agents.AssistantAgent.on_messages`.\n",
     "By default, the agent will return the result of the tool call as the final response.\n",
-    "```"
+    "```\n",
+    "\n",
+    "You can also call the {py:meth}`~autogen_agentchat.agents.BaseChatAgent.run` method, which is a convenience method that calls {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages`. \n",
+    "It follows the same interface as [Teams](./teams.ipynb) and returns a {py:class}`~autogen_agentchat.base.TaskResult` object."
    ]
   },
   {
@@ -186,7 +190,9 @@
     "with the final item being the response message in the {py:attr}`~autogen_agentchat.base.Response.chat_message` attribute.\n",
     "\n",
     "From the messages, you can observe that the assistant agent utilized the `web_search` tool to\n",
-    "gather information and responded based on the search results."
+    "gather information and responded based on the search results.\n",
+    "\n",
+    "You can also use {py:meth}`~autogen_agentchat.agents.BaseChatAgent.run_stream` to get the same streaming behavior as {py:meth}`~autogen_agentchat.agents.BaseChatAgent.on_messages_stream`. It follows the same interface as [Teams](./teams.ipynb)."
    ]
   },
   {
@@ -310,45 +316,6 @@
     ")"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## User Proxy Agent\n",
-    "\n",
-    "{py:class}`~autogen_agentchat.agents.UserProxyAgent` is a built-in agent that\n",
-    "provides one way for a user to intervene in the process. This agent will put the team in a temporary blocking state, and thus any exceptions or runtime failures while in the blocked state will result in a deadlock. It is strongly advised that this agent be coupled with a timeout mechanic and that all errors and exceptions emanating from it are handled."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from autogen_agentchat.agents import UserProxyAgent\n",
-    "\n",
-    "\n",
-    "async def user_proxy_run() -> None:\n",
-    "    user_proxy_agent = UserProxyAgent(\"user_proxy\")\n",
-    "    response = await user_proxy_agent.on_messages(\n",
-    "        [TextMessage(content=\"What is your name? \", source=\"user\")], cancellation_token=CancellationToken()\n",
-    "    )\n",
-    "    print(f\"Your name is {response.chat_message.content}\")\n",
-    "\n",
-    "\n",
-    "# Use asyncio.run(user_proxy_run()) when running in a script.\n",
-    "await user_proxy_run()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The User Proxy agent is ideally used for on-demand human-in-the-loop interactions for scenarios such as Just In Time approvals, human feedback, alerts, etc. For slower user interactions, consider terminating a team using a termination condition and start another one from\n",
-    "{py:meth}`~autogen_agentchat.base.TaskRunner.run` or {py:meth}`~autogen_agentchat.base.TaskRunner.run_stream` with another message."
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -357,6 +324,7 @@
     "\n",
     "The following preset agents are available:\n",
     "\n",
+    "- {py:class}`~autogen_agentchat.agents.UserProxyAgent`: An agent that takes user input returns it as responses.\n",
     "- {py:class}`~autogen_agentchat.agents.CodeExecutorAgent`: An agent that can execute code.\n",
     "- {py:class}`~autogen_ext.agents.openai.OpenAIAssistantAgent`: An agent that is backed by an OpenAI Assistant, with ability to use custom tools.\n",
     "- {py:class}`~autogen_ext.agents.web_surfer.MultimodalWebSurfer`: A multi-modal agent that can search the web and visit web pages for information.\n",

python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb

@@ -8,7 +8,17 @@
                 "\n",
                 "In this section you'll learn how to create a _multi-agent team_ (or simply team) using AutoGen. A team is a group of agents that work together to achieve a common goal.\n",
                 "\n",
-                "We'll first show you how to create and run a team. We'll then explain how to observe the team's behavior, which is crucial for debugging and understanding the team's performance, and common operations to control the team's behavior."
+                "We'll first show you how to create and run a team. We'll then explain how to observe the team's behavior, which is crucial for debugging and understanding the team's performance, and common operations to control the team's behavior.\n",
+                "\n",
+                "```{note}\n",
+                "When to use a team? \n",
+                "Teams can solve more complex tasks but they also need more scaffolding to steer than single agents.\n",
+                "While AgentChat has made it easier for you to work with teams,\n",
+                "you should first try to solve your problem with a single agent, and use a team\n",
+                "when a single agent becomes insufficient.\n",
+                "Make sure you have tried giving your single agent the right tools and instructions before\n",
+                "moving to a team.\n",
+                "```"
             ]
         },
         {

python/packages/autogen-core/pyproject.toml

@@ -71,6 +71,7 @@ dev = [
     "sphinxcontrib-apidoc",
     "autodoc_pydantic~=2.2",
     "pygments",
+    "sphinxext-rediraffe",
 
     "autogen_ext==0.4.0.dev13",
 

python/uv.lock

@@ -392,6 +392,7 @@ dev = [
     { name = "sphinx-copybutton" },
     { name = "sphinx-design" },
     { name = "sphinxcontrib-apidoc" },
+    { name = "sphinxext-rediraffe" },
     { name = "tavily-python" },
     { name = "textual" },
     { name = "textual-dev" },
@@ -451,6 +452,7 @@ dev = [
     { name = "sphinx-copybutton" },
     { name = "sphinx-design" },
     { name = "sphinxcontrib-apidoc" },
+    { name = "sphinxext-rediraffe" },
     { name = "tavily-python" },
     { name = "textual" },
     { name = "textual-dev" },
@@ -4486,6 +4488,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/52/a7/d2782e4e3f77c8450f727ba74a8f12756d5ba823d81b941f1b04da9d033a/sphinxcontrib_serializinghtml-2.0.0-py3-none-any.whl", hash = "sha256:6e2cb0eef194e10c27ec0023bfeb25badbbb5868244cf5bc5bdc04e4464bf331", size = 92072 },
 ]
 
+[[package]]
+name = "sphinxext-rediraffe"
+version = "0.2.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "sphinx" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1f/b4/e5fbb493f796430230189a1ce5f9beff1ac1b98619fc71ed35deca6059a5/sphinxext-rediraffe-0.2.7.tar.gz", hash = "sha256:651dcbfae5ffda9ffd534dfb8025f36120e5efb6ea1a33f5420023862b9f725d", size = 8735 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/76/4f/c8797e796199e55cf6c8979ecdf5f4b09b81e93f87b3193c759faea63263/sphinxext_rediraffe-0.2.7-py3-none-any.whl", hash = "sha256:9e430a52d4403847f4ffb3a8dd6dfc34a9fe43525305131f52ed899743a5fd8c", size = 8267 },
+]
+
 [[package]]
 name = "spider-client"
 version = "0.0.27"