Skip to content

Overview

So far we have only seen conversation patterns that involve two agents or a sequence of two-agent chats. AutoGen provides a more general conversation pattern called group chat, which involves more than two agents.

The core idea of group chat is that all agents contribute to a single conversation thread and share the same context.

This is useful for tasks that require collaboration among multiple agents.

The figure below illustrates how group chat works.

group_chat

A group chat is orchestrated by a special agent type GroupChatManager. In the first step of the group chat, the Group Chat Manager selects an agent to speak. Then, the selected agent speaks and the message is sent back to the Group Chat Manager, who broadcasts the message to all other agents in the group.

This process repeats until the conversation stops.

The Group Chat Manager can use several strategies to select the next agent.

Currently, the following strategies are supported:

  1. round_robin: The Group Chat Manager selects agents in a round-robin fashion based on the order of the agents provided.
  2. random: The Group Chat Manager selects agents randomly.
  3. manual: The Group Chat Manager selects agents by asking for human input.
  4. auto: The default strategy, which selects agents using the Group Chat Manager's LLM.

To illustrate this pattern, let's consider a simple example of a group chat among the same arithmetic operator agents as in the previous example, with the objective of turning a number into a specific target number using a sequence of arithmetic operations powered by the agents.

In this example, we use the auto strategy to select the next agent.

To help the Group Chat Manager select the next agent, we also set the description of the agents. Without the description, the Group Chat Manager will use the agents' system_message, which may be not be the best choice.

# The `description` attribute is a string that describes the agent.
# It can also be set in `ConversableAgent` constructor.
adder_agent.description = "Add 1 to each input number."
multiplier_agent.description = "Multiply each input number by 2."
subtracter_agent.description = "Subtract 1 from each input number."
divider_agent.description = "Divide each input number by 2."
number_agent.description = "Return the numbers given."

We first create a GroupChat object and provide the list of agents. If we were to use the round_robin strategy, this list would specify the order of the agents to be selected.

We also initialize the group chat with an empty message list and a maximum round of 6, which means there will be at most 6 iteratiosn of selecting speaker, agent speaks and broadcasting message.

from autogen import GroupChat

group_chat = GroupChat(
    agents=[adder_agent, multiplier_agent, subtracter_agent, divider_agent, number_agent],
    messages=[],
    max_round=6,
)

Now we create a GroupChatManager object and provide the GroupChat object as input. We also need to specify the llm_config of the Group Chat Manager so it can use the LLM to select the next agent (the auto strategy).

from autogen import GroupChatManager

group_chat_manager = GroupChatManager(
    groupchat=group_chat,
    llm_config=llm_config,
)

Finally, we have the Number Agent from before to start a two-agent chat with the Group Chat Manager, which runs the group chat internally and terminates the two-agent chat when the internal group chat is done. Because the Number Agent is selected to speak by us, it counts as the first round of the group chat.

chat_result = number_agent.initiate_chat(
    group_chat_manager,
    message="My number is 3, I want to turn it into 13.",
    summary_method="reflection_with_llm",
)

print(chat_result.summary)

You will see that the Number Agent is selected to speak first, then the Group Chat Manager selects the Multiplier Agent to speak, then the Adder Agent, and so on. The number is operated upon by each agent in the group chat, and the final result is 13.

Send Introductions#

In the previous example, we set the description of the agents to help the Group Chat Manager select the next agent. This only helps the Group Chat Manager, however, does not help the participating agents to know about each other.

Sometimes it is useful have each agent introduce themselves to other agents in the group chat. This can be done by setting the send_introductions=True.

group_chat_with_introductions = GroupChat(
    agents=[adder_agent, multiplier_agent, subtracter_agent, divider_agent, number_agent],
    messages=[],
    max_round=6,
    send_introductions=True,
)

Under the hood, the Group Chat Manager sends a message containing the agents' names and descriptions to all agents in the group chat before the group chat starts.

Group Chat in a Sequential Chat#

Group chat can also be used as a part of a sequential chat.

In this case, the Group Chat Manager is treated as a regular agent in the sequence of two-agent chats.

# Let's use the group chat with introduction messages created above.
group_chat_manager_with_intros = GroupChatManager(
    groupchat=group_chat_with_introductions,
    llm_config=llm_config,
)

# Start a sequence of two-agent chats between the number agent and
# the group chat manager.
chat_result = number_agent.initiate_chats(
    [
        {
            "recipient": group_chat_manager_with_intros,
            "message": "My number is 3, I want to turn it into 13.",
        },
        {
            "recipient": group_chat_manager_with_intros,
            "message": "Turn this number to 32.",
        },
    ]
)

In the above example, the Group Chat Manager runs the group chat two times. In the first time the number 3 becomes 13, and the last message of this group chat is being used as the carryover for the next group chat, which starts from 13.

You will also see from the warning message that the Group Chat Manager's history is being cleared after the first group chat, which is the default.

To keep the history of the Group Chat Manager, you can set the clear_history=False for the first chat.

Constrained Speaker Selection#

Group chat is a powerful conversation pattern, but it can be hard to control if the number of participating agents is large.

AG2 provides a way to constrain the selection of the next speaker by using the allowed_or_disallowed_speaker_transitions argument of the GroupChat class.

The allowed_or_disallowed_speaker_transitions argument is a dictionary that maps a given agent to a list of agents that can (or cannot) be selected to speak next. The speaker_transitions_type argument specifies whether the transitions are allowed or disallowed.

Here is an example:

allowed_transitions = {
    number_agent: [adder_agent, number_agent],
    adder_agent: [multiplier_agent, number_agent],
    subtracter_agent: [divider_agent, number_agent],
    multiplier_agent: [subtracter_agent, number_agent],
    divider_agent: [adder_agent, number_agent],
}

In this example, the allowed transitions are specified for each agent.

The Number Agent can be followed by the Adder Agent and the Number Agent, the Adder Agent can be followed by the Multiplier Agent and the Number Agent, and so on.

Let's put this into the group chat and see how it works.

The speaker_transitions_type is set to allowed so the transitions are positive constraints.

constrained_graph_chat = GroupChat(
    agents=[adder_agent, multiplier_agent, subtracter_agent, divider_agent, number_agent],
    allowed_or_disallowed_speaker_transitions=allowed_transitions,
    speaker_transitions_type="allowed",
    messages=[],
    max_round=12,
    send_introductions=True,
)

constrained_group_chat_manager = GroupChatManager(
    groupchat=constrained_graph_chat,
    llm_config=llm_config,
)

chat_result = number_agent.initiate_chat(
    constrained_group_chat_manager,
    message="My number is 3, I want to turn it into 10. Once I get to 10, keep it there.",
    summary_method="reflection_with_llm",
)

When this is run, the agents are selected following the constraints we have specified.

Changing the select speaker role name#

As part of the Group chat process, when the select_speaker_method is set to 'auto' (the default value), a select speaker message is sent to the LLM to determine the next speaker.

Each message in the chat sequence has a role attribute that is typically user, assistant, or system. The select speaker message is the last in the chat sequence when used and, by default, has a role of system.

When using some models, such as Mistral through Mistral.AI's API, the role on the last message in the chat sequence has to be user.

To change the default behaviour, Autogen provides a way to set the value of the select speaker message's role to any string value by setting the role_for_select_speaker_messages parameter in the GroupChat's constructor. The default value is system and by setting it to user you can accommodate the last message role requirement of Mistral.AI's API.

Conversation Patterns#

GroupChat has four built-in conversation patterns:

Method Agent selection
auto (default) Automatic, chosen by the GroupChatManager using an LLM
round_robin Sequentially in their added order
random Randomly
manual Selected by you at each turn
Callable Create your own flow

Coordinating the GroupChat is the GroupChatManager, an agent that provides a way to start and resume multi-agent chats.

Let's continue our lesson planner example to include a lesson reviewer and a teacher agent.

Before jumping into the code, here's a quick run down of what you need to do: - If using auto speaker selection, add specific descriptions to agents for GroupChatManager to use - Create a GroupChat and a GroupChatManager - Start the chat with the GroupChatManager

Tip

You can start any multi-agent chats using the initiate_chat method

from autogen import ConversableAgent, GroupChat, GroupChatManager, LLMConfig

# Put your key in the OPENAI_API_KEY environment variable
llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")

planner_message = """You are a classroom lesson agent.
Given a topic, write a lesson plan for a fourth grade class.
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>
"""

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.
Provide only one round of reviews to a lesson plan.
"""

# 1. Add a separate 'description' for our planner and reviewer agents
planner_description = "Creates or revises lesson plans."

reviewer_description = """Provides one round of reviews to a lesson plan
for the lesson_planner to revise."""

with llm_config:
    lesson_planner = ConversableAgent(
        name="planner_agent",
        system_message=planner_message,
        description=planner_description,
    )

    lesson_reviewer = ConversableAgent(
        name="reviewer_agent",
        system_message=reviewer_message,
        description=reviewer_description,
    )

# 2. The teacher's system message can also be used as a description, so we don't define it
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.
When you are happy with a lesson plan, output "DONE!".
"""

with llm_config:
    teacher = ConversableAgent(
        name="teacher_agent",
        system_message=teacher_message,
        # 3. Our teacher can end the conversation by saying DONE!
        is_termination_msg=lambda x: "DONE!" in (x.get("content", "") or "").upper(),
    )

# 4. Create the GroupChat with agents and selection method
groupchat = GroupChat(
    agents=[teacher, lesson_planner, lesson_reviewer],
    speaker_selection_method="auto",
    messages=[],
)

# 5. Our GroupChatManager will manage the conversation and uses an LLM to select the next agent
manager = GroupChatManager(
    name="group_manager",
    groupchat=groupchat,
    llm_config=llm_config,
)

# 6. Initiate the chat with the GroupChatManager as the recipient
teacher.initiate_chat(
    recipient=manager,
    message="Today, let's introduce our kids to the solar system."
)

  1. Separate to system_message, we add a description for our planner and reviewer agents and this is used exclusively for the purposes of determining the next agent by the GroupChatManager when using automatic speaker selection.

  2. The teacher's system_message is suitable as a description so, by not setting it, the GroupChatManager will use the system_message for the teacher when determining the next agent.

  3. The workflow is ended when the teacher's message contains the phrase "DONE!".

  4. Construct the GroupChat with our agents and selection method as automatic (which is the default).

  5. GroupChat requires a GroupChatManager to manage the chat and an LLM configuration is needed because they'll use an LLM to decide the next agent.

  6. Starting a chat with the GroupChatManager as the recipient kicks off the group chat.

    teacher_agent (to group_manager):

Today, let's introduce our kids to the solar system.

--------------------------------------------------------------------------------

Next speaker: planner_agent

>>>>>>>> USING AUTO REPLY...
planner_agent (to group_manager):

<title>Exploring the Solar System</title>
<learning_objectives>
1. Identify and name the planets in the solar system.
2. Describe key characteristics of each planet.
3. Understand the concept of orbit and how planets revolve around the sun.
4. Develop an appreciation for the scale and structure of our solar system.
</learning_objectives>
<script>
"Good morning, class! Today, we are going to embark on an exciting journey through our solar system. Have any of you ever looked up at the night sky and wondered what those bright dots are? Well, those dots are often stars, but some of them are planets in our own solar system!

To start our adventure, I want you to close your eyes and imagine standing on a giant spaceship, ready to zoom past the sun. Does anyone know what the sun is? (Pause for responses.) Right! The sun is a star at the center of our solar system.

Today, we are going to learn about the planets that travel around the sun - but not just their names, we're going to explore what makes each of them special! We will create a model of the solar system together, and by the end of the lesson, you will be able to name all the planets and tell me something interesting about each one.

So, are you ready to blast off and discover the wonders of space? Let's begin!"
</script>

--------------------------------------------------------------------------------

Next speaker: reviewer_agent

>>>>>>>> USING AUTO REPLY...
reviewer_agent (to group_manager):

**Review of the Lesson Plan: Exploring the Solar System**

1. **Alignment with Curriculum Standards**: Ensure that the lesson includes specific references to the fourth grade science standards for the solar system. This could include discussing gravity, the differences between inner and outer planets, and the role of the sun as a stable center of our solar system. Adding this information will support a deeper understanding of the topic and ensure compliance with state educational standards.

2. **Interactive Activities**: While creating a model of the solar system is a great hands-on activity, consider including additional interactive elements such as a group discussion or a game that reinforces the learning objectives. For instance, incorporating a "planet facts" game where students can share interesting facts about each planet would further engage the students and foster collaborative learning.

3. **Assessment of Learning**: It would be beneficial to include a formative assessment to gauge students' understanding at the end of the lesson. This could be a quick quiz, a group presentation about one planet, or a drawing activity where students depict their favorite planet and share one fact about it. This will help reinforce the learning objectives and provide students with an opportunity to demonstrate their knowledge.

Making these adjustments will enhance the educational experience and align it more closely with fourth-grade learning goals.

--------------------------------------------------------------------------------

Next speaker: planner_agent

>>>>>>>> USING AUTO REPLY...
planner_agent (to group_manager):

**Revised Lesson Plan: Exploring the Solar System**

<title>Exploring the Solar System</title>
<learning_objectives>
1. Identify and name the planets in the solar system according to grade-level science standards.
2. Describe key characteristics of each planet, including differences between inner and outer planets.
3. Understand the concept of orbit and how gravity keeps planets revolving around the sun.
4. Develop an appreciation for the scale and structure of our solar system and the sun's role as the center.
</learning_objectives>
<script>
"Good morning, class! Today, we are going to embark on an exciting journey through our solar system. Have any of you ever looked up at the night sky and wondered what those bright dots are? Well, those dots are often stars, but some of them are planets in our own solar system!

To start our adventure, I want you to close your eyes and imagine standing on a giant spaceship, ready to zoom past the sun. Does anyone know what the sun is? (Pause for responses.) That's right! The sun is a star at the center of our solar system.

Now, today's goal is not only to learn the names of the planets but also to explore what makes each of them unique. We'll create a model of the solar system together, and through this process, we will also talk about the differences between the inner and outer planets.

As part of our exploration, we'll play a fun "planet facts" game. After learning about the planets, I will divide you into small groups, and each group will get a planet to research. You’ll find interesting facts about the planet, and we will come together to share what you discovered!

At the end of our lesson, I'll give you a quick quiz to see how much you've learned about the planets, or you can draw your favorite planet and share one cool fact you found with the class.

So, are you ready to blast off and discover the wonders of space? Let's begin!"
</script>

**Interactive Activities**:
- **Planet Facts Game**: After discussing each planet, students will work in groups to find and share a unique fact about their assigned planet.

**Assessment of Learning**:
- **Individual Reflection Drawing**: Students draw their favorite planet and write one fact about it.
- **Quick Quiz**: A short quiz at the end to assess understanding of the planets and their characteristics.

This revised plan incorporates additional interactive elements and assessments that align with educational standards and enhance the overall learning experience.

--------------------------------------------------------------------------------

Next speaker: teacher_agent

>>>>>>>> USING AUTO REPLY...
teacher_agent (to group_manager):

DONE!

--------------------------------------------------------------------------------

Now, let's look at how this is done in a Swarm.