update

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

@@ -8,60 +8,60 @@ tags: [groupchat, swarm]
 
 AG2 now provides an implementation of the swarm orchestration from OpenAI's [Swarm](https://github.com/openai/swarm) framework, with some additional features!
 
-*Background*: the swarm orchestration is a multi-agent collaboration where agents execute tasks and are responsible for handing-off to other agents.
+*Background*: the swarm orchestration is a multi-agent collaboration where agents execute tasks and are responsible for handing them off to other agents.
 
 Here are the key features of the swarm orchestration:
-- **Hand offs**: Agents can transfer control to another agent, enabling smooth and direct transitions within workflows.
+- **Hand-offs**: Agents can transfer control to another agent, enabling smooth and direct transitions within workflows.
 - **Context variables**: Agents can dynamically update a shared memory through function calls, maintaining context and adaptability throughout the process.
 
-Beside these core features, AG2 provides:
-- **Simple Interface for Tool Call/Handoff Registeration**: When creating a swarm agent, you can pass in a list of functions to be registered directly. We also provide a simple method to register handoffs.
-- **Transition Beyond Tool Calls**: We enable the ability to automatically transfer to a nominated swarm agent when an agent has completed their task. In a future release, we may extend this to allo passing in a callable function to determine the next agent to hand off to.
+Besides these core features, AG2 provides:
+- **Simple Interface for Tool Call/Handoff Registration**: When creating a swarm agent, you can pass in a list of functions to be registered directly. We also provide a simple method to register handoffs.
+- **Transition Beyond Tool Calls**: We enable the ability to automatically transfer to a nominated swarm agent when an agent has completed their task. We will extend this to allow other transitions in the future (e.g., use a function to determine the next agent ).
 - **Built-in human-in-the-loop**: Adding a user agent (UserProxyAgent) to your swarm will allow swarm agents to transition back to the user. Provides a means to clarify and confirm with the user without breaking out of the swarm.
 
-## Hand offs
+## Handoffs
 
-Before we dive into a swarm example, an important concept in the swarm orchestration is when and how an agent hands off to another agent.
+Before we dive into a swarm example, an important concept in swarm orchestration is when and how an agent hands off to another agent.
 
-Providing additional flexibility, we introduce the capability to define an after work hand off. Think of *after work* as the agent's next action after completing their task. It can be to hand off to another agent, revert to the user, stay with the agent for another iteration, or terminate the conversation.
+Providing additional flexibility, we introduce the capability to define an after-work handoff. Think of it as the agent's next action after completing their task. It can be to hand off to another agent, revert to the user, stay with the agent for another iteration, or terminate the conversation.
 
-The following are the prioritised hand offs for each iteration of the swarm.
+The following are the prioritized handoffs for each iteration of the swarm.
 
 1. **Agent-level: Calls a tool that returns a swarm agent**: A swarm agent's tool call returns the next agent to hand off to.
-2. **Agent-level: Calls a pre-defined conditional hand off**: A swarm agent has an `ON_CONDITION` hand off that is chosen by the LLM (behaves like a tool call).
-3. **Agent-level: After work hand off**: When no tool calls are made it can use an, optional, `AFTER_WORK` hand off that is a preset option or a nominated swarm agent.
-4. **Swarm-level: After work hand off**: If the agent does not have an `AFTER_WORK` hand off, the swarm's `AFTER_WORK` hand off will be used.
+2. **Agent-level: Calls a pre-defined conditional handoff**: A swarm agent has an `ON_CONDITION` handoff that is chosen by the LLM (behaves like a tool call).
+3. **Agent-level: After work hand off**: When no tool calls are made it can use an, optional, `AFTER_WORK` handoff that is a preset option or a nominated swarm agent.
+4. **Swarm-level: After work handoff**: If the agent does not have an `AFTER_WORK` handoff, the swarm's `AFTER_WORK` handoff will be used.
 
 In the following code sample a `SwarmAgent` named `responder` has:
-- Two conditional hand offs registered (`ON_CONDITION`), specifying the agent to hand off to and the condition to trigger the hand off.
-- An after work hand off (`AFTER_WORK`) nominated using one of the preset options (`TERMINATE`, `REVERT_TO_USER`, `STAY`). This could also be a swarm agent.
+- Two conditional handoffs registered (`ON_CONDITION`), specifying the agent to hand off to and the condition to trigger the handoff.
+- An after-work handoff (`AFTER_WORK`) nominated using one of the preset options (`TERMINATE`, `REVERT_TO_USER`, `STAY`). This could also be a swarm agent.
 
 ```python
 responder.register_hand_off(
     hand_to=[
-        ON_CONDITION(weather, "If you need weather data, hand off to the Weather_Agent"),
-        ON_CONDITION(travel_advisor, "If you have weather data but need formatted recommendations, hand off to the Travel_Advisor_Agent"),
-        AFTER_WORK(REVERT_TO_USER),
-    ]
+ ON_CONDITION(weather, "If you need weather data, hand off to the Weather_Agent"),
+ ON_CONDITION(travel_advisor, "If you have weather data but need formatted recommendations, hand off to the Travel_Advisor_Agent"),
+ AFTER_WORK(AfterWorkOption.REVERT_TO_USER),
+ ]
 )
 ```
 
-You can specify the swarm-level after work hand off when initiating the swarm (here we nominate to terminate):
+You can specify the swarm-level after work handoff when initiating the swarm (here we nominate to terminate):
 ```python
 history, context, last_agent = initiate_swarm_chat(
     init_agent=responder,
     agents=my_list_of_swarm_agents,
     max_rounds=30,
     messages=messages,
-    after_work=AFTER_WORK(TERMINATE)
+    after_work=AFTER_WORK(AfterWorkOption.TERMINATE)
 )
 ```
 
 ## Creating a swarm
 
 1. Define the functions that can be used by your `SwarmAgent`s.
 2. Create your `SwarmAgent`s (which derives from `ConversableAgent`).
-3. For each swarm agent, specify the hand offs (transitions to another agent) and what to do when they have finished their work (termed *After Work*).
+3. For each swarm agent, specify the handoffs (transitions to another agent) and what to do when they have finished their work (termed *After Work*).
 4. Optionally, create your context dictionary.
 5. Call `initiate_swarm_chat`.
 
@@ -70,8 +70,7 @@ history, context, last_agent = initiate_swarm_chat(
 This example of managing refunds demonstrates the context handling, swarm and agent-level conditional and after work hand offs, and the human-in-the-loop feature.
 
 ```python
-from autogen.agentchat.contrib.swarm_agent import initiate_swarm_chat, SwarmAgent, SwarmResult
-from autogen.agentchat.contrib.swarm_agent import ON_CONDITION, AFTER_WORK, REVERT_TO_USER, TERMINATE
+from autogen.agentchat.contrib.swarm_agent import initiate_swarm_chat, SwarmAgent, SwarmResult, ON_CONDITION, AFTER_WORK, AfterWorkOption
 from autogen import UserProxyAgent
 import os
 
@@ -88,8 +87,7 @@ context_variables = {
 
 # Functions that our swarm agents will be assigned
 # They can return a SwarmResult, a SwarmAgent, or a string
-# SwarmResult allows you to update context_variables
-# and/or hand off to another agent
+# SwarmResult allows you to update context_variables and/or hand off to another agent
 def verify_customer_identity(passport_number: str, context_variables: dict) -> str:
     context_variables["passport_number"] = passport_number
     context_variables["customer_verified"] = True
@@ -103,9 +101,7 @@ def process_refund_payment(context_variables: dict) -> str:
     context_variables["payment_processed"] = True
     return SwarmResult(values="Payment processed successfully", context_variables=context_variables)
 
-# Swarm Agents, similar to ConversableAgent,
-# but with functions and hand offs (specified later)
-
+# Swarm Agents, similar to ConversableAgent, but with functions and hand offs (specified later)
 customer_service = SwarmAgent(
     name="CustomerServiceRep",
     system_message="""You are a customer service representative.
@@ -144,7 +140,7 @@ satisfaction_surveyor = SwarmAgent(
 customer_service.register_hand_off(
     hand_to=[
         ON_CONDITION(refund_specialist, "After customer verification, transfer to refund specialist"),
-        AFTER_WORK(REVERT_TO_USER)
+        AFTER_WORK(AfterWorkOption.REVERT_TO_USER)
     ]
 )
 
@@ -155,12 +151,7 @@ payment_processor.register_hand_off(
 )
 
 # Our human, you, allowing swarm agents to revert back for more information
-user = UserProxyAgent(
-    name="User",
-    system_message="The customer, always answers questions when agents require more information.",
-    human_input_mode="ALWAYS",
-    code_execution_config=False,
-)
+user = UserProxyAgent(name="User", code_execution_config=False)
 
 # Initiate the swarm
 # Returns the ChatResult, final context, and last speaker
@@ -171,7 +162,7 @@ chat_result, context_variables, last_speaker = initiate_swarm_chat(
     user_agent=user, # Human user
     messages="Customer requesting refund for order #12345",
     context_variables=context_variables, # Context
-    after_work=AFTER_WORK(TERMINATE) # Swarm-level after work hand off
+    after_work=AFTER_WORK(AfterWorkOption.TERMINATE) # Swarm-level after work hand off
 )