From 725d573d5b01efe430e51b6d9a7e7f901b895de3 Mon Sep 17 00:00:00 2001 From: Eric Zhu Date: Tue, 7 Jan 2025 09:57:23 -0800 Subject: [PATCH] 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 --- python/packages/autogen-core/docs/src/conf.py | 6 +++ .../user-guide/agentchat-user-guide/index.md | 37 ++++++++++---- .../agentchat-user-guide/migration-guide.md | 7 ++- .../{tutorial => }/selector-group-chat.ipynb | 4 +- .../{tutorial => }/selector-group-chat.svg | 0 .../{tutorial => }/swarm.ipynb | 2 +- .../{tutorial => }/swarm_customer_support.svg | 0 .../{tutorial => }/swarm_stock_research.svg | 0 .../tutorial/agents.ipynb | 50 ++++--------------- .../agentchat-user-guide/tutorial/teams.ipynb | 12 ++++- python/packages/autogen-core/pyproject.toml | 1 + python/uv.lock | 14 ++++++ 12 files changed, 75 insertions(+), 58 deletions(-) rename python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/{tutorial => }/selector-group-chat.ipynb (99%) rename python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/{tutorial => }/selector-group-chat.svg (100%) rename python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/{tutorial => }/swarm.ipynb (99%) rename python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/{tutorial => }/swarm_customer_support.svg (100%) rename python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/{tutorial => }/swarm_stock_research.svg (100%) diff --git a/python/packages/autogen-core/docs/src/conf.py b/python/packages/autogen-core/docs/src/conf.py index ce18be3fe..691a528e8 100644 --- a/python/packages/autogen-core/docs/src/conf.py +++ b/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 diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md index 0bab2460a..46f526c6c 100644 --- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/index.md +++ b/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: diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/migration-guide.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/migration-guide.md index 9360daaff..a0beff3e2 100644 --- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/migration-guide.md +++ b/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) diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/selector-group-chat.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/selector-group-chat.ipynb similarity index 99% rename from python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/selector-group-chat.ipynb rename to python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/selector-group-chat.ipynb index 7fbe5b131..efb7c2419 100644 --- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/selector-group-chat.ipynb +++ b/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", diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/selector-group-chat.svg b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/selector-group-chat.svg similarity index 100% rename from python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/selector-group-chat.svg rename to python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/selector-group-chat.svg diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/swarm.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/swarm.ipynb similarity index 99% rename from python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/swarm.ipynb rename to python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/swarm.ipynb index 6dd051108..99bb02710 100644 --- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/swarm.ipynb +++ b/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", diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/swarm_customer_support.svg b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/swarm_customer_support.svg similarity index 100% rename from python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/swarm_customer_support.svg rename to python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/swarm_customer_support.svg diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/swarm_stock_research.svg b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/swarm_stock_research.svg similarity index 100% rename from python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/swarm_stock_research.svg rename to python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/swarm_stock_research.svg 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 dc4076f61..95b6834d9 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 @@ -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", diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb index a4a43d980..8781b7985 100644 --- a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/teams.ipynb +++ b/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", + "```" ] }, { diff --git a/python/packages/autogen-core/pyproject.toml b/python/packages/autogen-core/pyproject.toml index 0c06a7934..41f36ef59 100644 --- a/python/packages/autogen-core/pyproject.toml +++ b/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", diff --git a/python/uv.lock b/python/uv.lock index 1e4c1c576..6aa63d6ee 100644 --- a/python/uv.lock +++ b/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"