Swarm Tutorial

[gziz]

Why are these changes needed?

Provide a tutorial for the Swarm pattern

Related issue number

#4113

Checks

• I've included any doc changes needed for https://microsoft.github.io/autogen/. See https://microsoft.github.io/autogen/docs/Contribute#documentation to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

[ekzhu]

Thanks!

We can have two examples:

One chatbot scenario, such as the flight example but with more realistic user experience, with more options such as flight search, cancellation, rebooking, status, etc. Use relevant tools with preset outputs. For the chat bot scenario, it is important to constantly engage the user, so you want to set max_turn=1 in Swarm to make sure it is returning the control back to the user each time an agent responds. You don't need to include handoff to the user because max_turn=1. Also, we can show that a handoff can be customized with a autogen_agentchat.agents.HandOff class.

For max_turn let's wait for this one: #4143

The second example is more autonomous. I would go with content generation such as investment/market research. No need to be super fancy just use tools with preset outputs. E.g., a planner agent, a financial analysis agent with a stock data query tool, a news agent with a news retrieval tool, a data visualization agent with plotting tool, and a writer agent. The planner agent hands off to all other agents, while all other agents hand off back to the planner agent.

I use draw.io to create SVGs for visualizations. I think we should have a visualization for both scenarios. You can save the drawio source in the python/packages/autogen-core/docs/drawio folder. Then I produce SVG by exporting and choose selection only and auto light mode. Don't set transparent background because it is going to mess up the dark mode. Don't select any thing like include a copy or fonts etc., just the raw SVG.

[gziz]

Hi @ekzhu
For the first example, after testing Swarm with max_turns=1 as suggested, I don’t think this would work as expected.

travel_team = Swarm(
    participants=[travel_agent, flights_refunder],
    termination_condition=TextMentionTermination("TERMINATE"),
    max_turns=1,
)

user_input = "Help me refund my flight."

while True:
    result = await travel_team.run(task=user_input)
    last_message = result.messages[-1]
    print(f"{last_message.source}: {last_message.content}")
    
    if isinstance(last_message, TaskResult) and last_message.stop_reason == "TERMINATE":
        break

    user_input = input("\nUser: ")

With something like the above, every time we stop the travel_team because of max_turns, the user inputs something. This user message would be message_thread[-1], the SwarmGroupChatManager selects the next speaker if the last message in message_thread is a handoff message. Hence if the last message is a handoff between travel_agent to flights_refunder, this handoff message would be lost and the next speaker would be travel_agent again.

Am I missing something?

[ekzhu]

I believe you just identified a bug in Swarm. Rather than using the last message to identify the handoff target, we should be using the last handoff message and check if the handoff has happened already. The currently implementation didn't consider this scenario.

[ekzhu]

Just opened an issue #4180

[gziz]

😮 That makes sense!

[ekzhu]

@gziz #4198

[gziz]

Thanks