microsoft/autogen · error · ValueError

The participant topic types must be unique.

Error message

The participant topic types must be unique.

What it means

Thrown by the BaseGroupChatManager constructor when two or more participants in a group chat team resolve to the same topic type. Topic types are derived from participant names, so this almost always means two agents (or nested teams) in the team share the same name; each participant must map to a unique runtime topic for message routing to be deterministic.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat_manager.py:66

        message_factory: MessageFactory,
        emit_team_events: bool = False,
    ):
        super().__init__(
            description="Group chat manager",
            sequential_message_types=[
                GroupChatStart,
                GroupChatAgentResponse,
                GroupChatTeamResponse,
                GroupChatMessage,
                GroupChatReset,
            ],
        )
        if max_turns is not None and max_turns <= 0:
            raise ValueError("The maximum number of turns must be greater than 0.")
        if len(participant_topic_types) != len(participant_descriptions):
            raise ValueError("The number of participant topic types, agent types, and descriptions must be the same.")
        if len(set(participant_topic_types)) != len(participant_topic_types):
            raise ValueError("The participant topic types must be unique.")
        if group_topic_type in participant_topic_types:
            raise ValueError("The group topic type must not be in the participant topic types.")
        self._name = name
        self._group_topic_type = group_topic_type
        self._output_topic_type = output_topic_type
        self._participant_names = participant_names
        self._participant_name_to_topic_type = {
            name: topic_type for name, topic_type in zip(participant_names, participant_topic_types, strict=True)
        }
        self._participant_descriptions = participant_descriptions
        self._message_thread: List[BaseAgentEvent | BaseChatMessage] = []
        self._output_message_queue = output_message_queue
        self._termination_condition = termination_condition
        self._max_turns = max_turns
        self._current_turn = 0
        self._message_factory = message_factory
        self._emit_team_events = emit_team_events
        self._active_speakers: List[str] = []

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Give every agent/team in the participants list a unique name= argument when constructing them.
2. If participants are built dynamically, assert uniqueness before team construction (see validation code) and append an index or hash on collision.
3. Check nested teams: a Team used as a participant carries its own name and must not collide with sibling names.

Example fix

// before
agents = [AssistantAgent(name="writer", model_client=client), CodeExecutorAgent(name="writer")]  # both 'writer'
team = RoundRobinGroupChat(participants=agents)

// after
agents = [AssistantAgent(name="writer", model_client=client), CodeExecutorAgent(name="reviewer")]
team = RoundRobinGroupChat(participants=agents)

names = [a.name for a in participants]
if len(set(names)) != len(names):
    dupes = sorted({n for n in names if names.count(n) > 1})
    raise ValueError(f"Duplicate participant names: {dupes}")
team = RoundRobinGroupChat(participants)

def has_unique_participant_names(participants: Sequence[ChatAgent | Team]) -> bool:
    names = [p.name for p in participants]
    return len(set(names)) == len(names)

When it happens

Trigger: Creating RoundRobinGroupChat, SelectorGroupChat, Swarm, or GraphFlow with a participants list containing two agents with identical .name values; or passing participant_topic_types with duplicates when constructing the manager directly. Note names are compared case-sensitively ('Agent1' vs 'agent1' are distinct).

Common situations: Agents instantiated from the same class/config in a loop without assigning unique names; dynamically generated participant lists where names come from data; refactoring a config file where an agent was duplicated; copy-pasting an agent definition.

Related errors

• The participant names must be unique.
• The group topic type must not be in the participant topic ty
• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.
• All agents must have a name.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/3a4a28781ac66d5f. Report an issue: GitHub.