Swarm Documentation

website/blog/2024-11-17-Swarm/index.mdx

@@ -0,0 +1,21 @@
+title: Building Swarm-based agents with AutoGen
+authors:
+  - yiranwu
+  - marklysze
+tags: [groupchat, swarm]
+---
+
+AutoGen Groupchat now supports a new speaker selection method, `swarm`, which allows quick implementation of the swarm orchestration from OpenAI's [Swarm](https://github.com/openai/swarm) framework.
+
+Here are two key features of the `swarm` speaker selection method:
+- **Headoffs**: Agents can transfer control to another agent via function calls, enabling smooth transitions within workflows.
+- **Context Variables**: Agents can dynamically update shared variables through function calls, maintaining context and adaptability throughout the process.
+
+
+## Getting Started
+
+The `swarm` speaker selection method needs to be used in conjunction with `SwarmAgent` and `SwarmResult` classes. Use the `initialize_swarm_chat` to get a swarm reply.
+
+```python
+from autogen.agentchat.swarm.swarm_agent import SwarmAgent, SwarmResult, initialize_swarm_chat
+```

website/docs/topics/groupchat/using_swarm.ipynb

@@ -0,0 +1,178 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Using Swarm Ochestration\n",
+    "\n",
+    "You can set the speaker selection method to `swarm` to use the swarm-like orchestration.\n",
+    "\n",
+    "- **Headoffs**: Agents can transfer control to another agent via function calls, enabling smooth transitions within workflows.\n",
+    "- **Context Variables**: Agents can dynamically update shared variables through function calls, maintaining context and adaptability throughout the process.\n",
+    "\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## SwarmAgent and SwarmResult\n",
+    "\n",
+    "To allow easier setup of the swarm, a `SwarmAgent` class is provided. When passing functions to this agent, the agent will execute any tool calls from LLMs directly. \n",
+    "\n",
+    "```python\n",
+    "agent = SwarmAgent(\n",
+    "    ..., # same arguments as AssistantAgent\n",
+    "    functions=[func_1, func_2, ...] # a new parameter that allows passing a list of functions\n",
+    ")\n",
+    "```\n",
+    "\n",
+    "We also create a `SwarmResult` class, where you can return a value, the next agent to call and update context variables at the same time.\n",
+    "\n",
+    "```python\n",
+    "def func_name() -> SwarmResult:\n",
+    "    return SwarmResult(value=\"value\", agent=<swarmagent object>, context_variables={\"key\": \"value\"})\n",
+    "```\n",
+    "\n",
+    "To only define transitions between agents, we provide an quick way to define the handoffs:\n",
+    "\n",
+    "```python\n",
+    "swarm_agent.handoff(agent, condition=\"when should transition happen\")\n",
+    "```\n",
+    "We will register a transfer function to llm config:\n",
+    "```\n",
+    "def transfer_to_agent_name():\n",
+    "    \"\"\"<Condition string>\"\"\"\n",
+    "    return agent_name\n",
+    "```\n",
+    "\n",
+    "When defining function calls, you can return one of the following types:\n",
+    "- `str`\n",
+    "- `SwarmAgent`: if a `SwarmAgent` object is returned, it will be called next.\n",
+    "- `SwarmResult`: if a `SwarmResult` object is returned, we will use it to update the context variables, return a value and call the next agent.\n",
+    "\n",
+    "\n",
+    "**Notes for creating the function calls**\n",
+    "- For input arguments, you must define the type of the argument, otherwise the registration will fail (e.g. `arg_name: str`). \n",
+    "- The docstring of the function will be used as the prompt. So make sure to write a clear description.\n",
+    "- The function name will be used as the tool name.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from autogen.agentchat.contrib.swarm_agent import SwarmAgent, SwarmResult\n",
+    "\n",
+    "llm_config = \"Setup your config here\"\n",
+    "\n",
+    "\n",
+    "def update_context_1(context_variables: dict) -> str:\n",
+    "    context_variables[\"1\"] = True\n",
+    "    return SwarmResult(\n",
+    "        value=\"success\", context_variables=context_variables\n",
+    "    )  # Update context variables and return success\n",
+    "\n",
+    "\n",
+    "def update_context_2_and_transfer_to_3(context_variables: dict) -> str:\n",
+    "    context_variables[\"2\"] = True\n",
+    "    return SwarmResult(\n",
+    "        value=\"success\", context_variables=context_variables, agent=agent_3\n",
+    "    )  # Update context variables, return success, and transfer to agent_3\n",
+    "\n",
+    "\n",
+    "def update_context_3(context_variables: dict) -> str:\n",
+    "    context_variables[\"3\"] = True\n",
+    "    return SwarmResult(\n",
+    "        value=\"success\", context_variables=context_variables\n",
+    "    )  # Update context variables and return success\n",
+    "\n",
+    "\n",
+    "agent_1 = SwarmAgent(\n",
+    "    name=\"Agent_1\",\n",
+    "    system_message=\"You are Agent 1, first, call the function to update context 1, and transfer to Agent 2\",\n",
+    "    llm_config=llm_config,\n",
+    "    functions=[update_context_1],\n",
+    ")\n",
+    "\n",
+    "agent_2 = SwarmAgent(\n",
+    "    name=\"Agent_2\",\n",
+    "    system_message=\"You are Agent 2, call the function that updates context 2 and transfer to Agent 3\",\n",
+    "    llm_config=llm_config,\n",
+    "    functions=[update_context_2_and_transfer_to_3],\n",
+    ")\n",
+    "\n",
+    "agent_3 = SwarmAgent(\n",
+    "    name=\"Agent_3\",\n",
+    "    system_message=\"You are Agent 3, first, call the function to update context 3, and then reply TERMINATE\",\n",
+    "    llm_config=llm_config,\n",
+    "    functions=[update_context_3],\n",
+    ")\n",
+    "\n",
+    "agent_1.hand_off(agent_2, condition=\"handoff to agent 2\")  # register handoff using hand_off method."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Use initialize_swarm_chat\n",
+    "\n",
+    "To get response from the swarm agent, you can use the `initialize_swarm_chat` function. This function will return the response from the agent and the updated context variables.\n",
+    "\n",
+    "```python\n",
+    "chat_history, context_variables, last_agent = initialize_swarm_chat(\n",
+    "    init_agent, # which agent to start with\n",
+    "    messages, # list of messages\n",
+    "    agents, # pass in all the swarm agents\n",
+    "    max_rounds, # maximum number of rounds\n",
+    "    context_variables, # initial context variables\n",
+    ")\n",
+    "```\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from autogen.agentchat.contrib.swarm_agent import initialize_swarm_chat\n",
+    "\n",
+    "context_variables = {\"1\": False, \"2\": False, \"3\": False}\n",
+    "chat_result, context_variables, last_agent = initialize_swarm_chat(\n",
+    "    init_agent=agent_1,\n",
+    "    agents=[agent_1, agent_2, agent_3],\n",
+    "    messages=\"start\",\n",
+    "    context_variables=context_variables,\n",
+    ")\n",
+    "print(context_variables)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "autodev",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.19"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}