Swarms are a versatile pattern that provide flows between agents that are determined at the swarm or agent-level. The control of the flow is managed through various mechanisms, including hand-offs, post-tool transitions, post-work transitions, or an internal group chat manager, all of which determine the next agent (or end the swarm).

The simplest swarm comprises of a group of agents and utilizes the swarm’s internal manager (a GroupChatManager) to decide, based on the conversation messages and the agent’s descriptions, who should be the next agent.

Here’s an example.

from autogen import ConversableAgent, AfterWorkOption, initiate_swarm_chat

llm_config = {"api_type": "openai", "model": "gpt-4o-mini"}

# 1. Create our agents
planner_message = """You are a classroom lesson planner.
Given a topic, write a lesson plan for a fourth grade class.
If you are given revision feedback, update your lesson plan and record it.
Use the following format:
<title>Lesson plan title</title>
<learning_objectives>Key learning objectives</learning_objectives>
<script>How to introduce the topic to the kids</script>
"""

lesson_planner = ConversableAgent(
    name="planner_agent", llm_config=llm_config, system_message=planner_message
)

reviewer_message = """You are a classroom lesson reviewer.
You compare the lesson plan to the fourth grade curriculum
and provide a maximum of 3 recommended changes for each review.
Make sure you provide recommendations each time the plan is updated.
"""

lesson_reviewer = ConversableAgent(
    name="reviewer_agent", llm_config=llm_config, system_message=reviewer_message
)

teacher_message = """You are a classroom teacher.
You decide topics for lessons and work with a lesson planner.
and reviewer to create and finalise lesson plans.
"""

teacher = ConversableAgent(
    name="teacher_agent",
    llm_config=llm_config,
    system_message=teacher_message,
)

# 2. Initiate the swarm chat using a swarm manager who will
# select agents automatically
result, _, _ = initiate_swarm_chat(
    initial_agent=teacher,
    agents=[lesson_planner, lesson_reviewer, teacher],
    messages="Today, let's introduce our kids to the solar system.",
    max_rounds=10,
    swarm_manager_args={"llm_config": llm_config},
    after_work=AfterWorkOption.SWARM_MANAGER
)

In this case, we create three agents, each with a detailed system message that will aid our swarm manager in working out the next best agent. There will also be a user agent (you) that may be transitioned to if the swarm manager thinks it needs further information or has finished.

Let’s examine the code:

  1. Create our three agents

  2. Initiate the chat

    • All our agents are passed in to agents
    • Our starting message is set in messages
    • As we’re using our swarm manager to select agents, we need to give them an LLM configuration, so we pass it in swarm_manager_args
    • When each agent has spoken it will utilise the swarm’s AfterWork setting, in this case AfterWorkOption.SWARM_MANAGER set with the after_work parameter, indicating that the swarm manager is responsible for selecting the next agent.

In this example, the swarm manager’s LLM is solely responsible for deciding the next agent at each turn.

​
Controlling swarm transitions

To gain more control over the transitions between agents, utilise hand-offs and after work transitions.

When designing your swarm, think about your agents in a diagram with the lines between agents being your hand-offs. Each line will have a condition statement which an LLM will evaluate. Control stays with an agent while they execute their tools and once they’ve finished with their tools the conditions to transition will be evaluated.

One of the unique aspects of a swarm is a shared context. ConversableAgents have a context dictionary but in a swarm that context is made common across all agents, allowing a state of the workflow to be maintained and viewed by all agents. This context can also be used within the hand off condition statements, providing more control of transitions.

AG2’s swarm has a number of unique capabilities, find out more in our Swarm deep-dive.

Here’s our lesson planner workflow using AG2’s Swarm.

from autogen import (
    AFTER_WORK,
    ON_CONDITION,
    AfterWorkOption,
    SwarmAgent,
    SwarmResult,
    initiate_swarm_chat,
    register_hand_off,
)

llm_config = {"api_type": "openai", "model": "gpt-4o-mini", "cache_seed": None}

# 1. Context
shared_context = {
    "lesson_plans": [],
    "lesson_reviews": [],
    # Will be decremented, resulting in 0 (aka False) when no reviews are left
    "reviews_left": 2,
}


# 2. Functions
def record_plan(lesson_plan: str, context_variables: dict) -> SwarmResult:
    """Record the lesson plan"""
    context_variables["lesson_plans"].append(lesson_plan)

    # Returning the updated context so the shared context can be updated
    return SwarmResult(context_variables=context_variables)


def record_review(lesson_review: str, context_variables: dict) -> SwarmResult:
    """After a review has been made, increment the count of reviews"""
    context_variables["lesson_reviews"].append(lesson_review)
    context_variables["reviews_left"] -= 1

    # Controlling the flow to the next agent from a tool call
    return SwarmResult(
        agent=teacher if context_variables["reviews_left"] < 0 else lesson_planner, context_variables=context_variables
    )


planner_message = """You are a classroom lesson planner.
Given a topic, write a lesson plan for a fourth grade class.
If you are given revision feedback, update your lesson plan and record it.
Use the following format:
<title>Lesson plan title</title>
<learning_objectives>Key learning objectives</learning_objectives>
<script>How to introduce the topic to the kids</script>
"""

# 3. Our agents now have tools to use (functions above)
lesson_planner = ConversableAgent(
    name="planner_agent", llm_config=llm_config, system_message=planner_message, functions=[record_plan]
)

reviewer_message = """You are a classroom lesson reviewer.
You compare the lesson plan to the fourth grade curriculum
and provide a maximum of 3 recommended changes for each review.
Make sure you provide recommendations each time the plan is updated.
"""

lesson_reviewer = ConversableAgent(
    name="reviewer_agent", llm_config=llm_config, system_message=reviewer_message, functions=[record_review]
)

teacher_message = """You are a classroom teacher.
You decide topics for lessons and work with a lesson planner.
and reviewer to create and finalise lesson plans.
"""

teacher = ConversableAgent(
    name="teacher_agent",
    llm_config=llm_config,
    system_message=teacher_message,
)

# 4. Transitions using hand-offs

# Lesson planner will create a plan and hand off to the reviewer if we're still
# allowing reviews. After that's done, transition to the teacher.
register_hand_off(lesson_planner,
    [
        ON_CONDITION(
            target=lesson_reviewer,
            condition="After creating/updating and recording the plan, it must be reviewed.",
            available="reviews_left",
        ),
        AFTER_WORK(agent=teacher),
    ]
)

# Lesson reviewer will review the plan and return control to the planner if there's
# no plan to review, otherwise it will provide a review and
register_hand_off(lesson_reviewer,
    [
        ON_CONDITION(
            target=lesson_planner, condition="After new feedback has been made and recorded, the plan must be updated."
        ),
        AFTER_WORK(agent=teacher),
    ]
)

# Teacher works with the lesson planner to create a plan. When control returns to them and
# a plan exists, they'll end the swarm.
register_hand_off(teacher,
    [
        ON_CONDITION(target=lesson_planner, condition="Create a lesson plan.", available="reviews_left"),
        AFTER_WORK(AfterWorkOption.TERMINATE),
    ]
)

# 5. Run the Swarm which returns the chat and updated context variables
chat_result, context_variables, last_agent = initiate_swarm_chat(
    initial_agent=teacher,
    agents=[lesson_planner, lesson_reviewer, teacher],
    messages="Today, let's introduce our kids to the solar system.",
    context_variables=shared_context,
)

print(f"Number of reviews: {len(context_variables['lesson_reviews'])}")
print(f"Reviews remaining: {context_variables['reviews_left']}")
print(f"Final Lesson Plan:\n{context_variables['lesson_plans'][-1]}")

  1. Our shared context, available in function calls and on agents.

  2. Functions that represent the work the agents carry out, these the update shared context and, optionally, managed transitions.

  3. Agents setup with their tools, functions, and a system message and LLM configuration.

  4. The important hand-offs, defining the conditions for which to transfer to other agents and what to do after their work is finished (equivalent to no longer calling tools). Transfer conditions can be turned on/off using the available parameter.

  5. Kick off the swarm with our agents and shared context. Similar to initiate_chat, initiate_swarm_chat returns the chat result (messages and summary) and the final shared context.

    Number of reviews: 2
Reviews remaining: 0
Final Lesson Plan:
<title>Exploring the Solar System</title>
<learning_objectives>Students will be able to identify and describe the planets in the Solar System, understand the concept of orbits, and recognize the sun as the center of our Solar System.</learning_objectives>
<script>Using a large poster of the Solar System, I will introduce the planets one by one, discussing key characteristics such as size, color, and distance from the sun. I will engage the students by asking questions about their favorite planets and what they know about them. We will do a quick demo using a simple model to show how planets orbit around the sun. Students will create their own solar system models in small groups with various materials to understand the scale and distance better, fostering teamwork. We will incorporate a multimedia presentation to visualize the orbits and relative sizes of the planets. Finally, a short assessment will be conducted at the end of the lesson to gauge students' understanding, using quizzes or presentations of their models.</script>
Edit this page
Nested chatEnding a chat