microsoft/autogen · error · TypeError

Participant {participant} must be a ChatAgent.

Error message

Participant {participant} must be a ChatAgent.

What it means

Swarm.__init__ raises TypeError when any participant is not an instance of ChatAgent. Swarm handoff mechanics rely on per-agent HandoffMessage production and tool-based handoffs, which only ChatAgent (e.g. AssistantAgent) provides.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_swarm_group_chat.py:247

    DEFAULT_NAME = "Swarm"
    DEFAULT_DESCRIPTION = "A team of agents."

    def __init__(
        self,
        participants: List[ChatAgent],
        *,
        name: str | None = None,
        description: str | None = None,
        termination_condition: TerminationCondition | None = None,
        max_turns: int | None = None,
        runtime: AgentRuntime | None = None,
        custom_message_types: List[type[BaseAgentEvent | BaseChatMessage]] | None = None,
        emit_team_events: bool = False,
    ) -> None:
        for participant in participants:
            if not isinstance(participant, ChatAgent):
                raise TypeError(f"Participant {participant} must be a ChatAgent.")
        super().__init__(
            name=name or self.DEFAULT_NAME,
            description=description or self.DEFAULT_DESCRIPTION,
            participants=[participant for participant in participants],
            group_chat_manager_name="SwarmGroupChatManager",
            group_chat_manager_class=SwarmGroupChatManager,
            termination_condition=termination_condition,
            max_turns=max_turns,
            runtime=runtime,
            custom_message_types=custom_message_types,
            emit_team_events=emit_team_events,
        )
        # The first participant must be able to produce handoff messages.
        first_participant = self._participants[0]
        assert isinstance(first_participant, ChatAgent)
        if HandoffMessage not in first_participant.produced_message_types:
            raise ValueError("The first participant must be able to produce a handoff messages.")

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Use only AssistantAgent/ChatAgent instances as Swarm participants.
2. To include a team's behavior, either flatten its agents into the swarm or use GraphFlow which supports Team nodes.
3. For a custom agent, subclass autogen_agentchat.agents.ChatAgent and implement its abstract methods, including handoff support.

Example fix

# before
swarm = Swarm(participants=[researcher, RoundRobinGroupChat([coder, reviewer])])  # TypeError

# after
swarm = Swarm(participants=[researcher, coder, reviewer])

from autogen_agentchat.agents import ChatAgent
assert all(isinstance(p, ChatAgent) for p in participants), "Swarm requires ChatAgent participants"

from autogen_agentchat.agents import ChatAgent

def all_chat_agents(participants: Sequence[object]) -> bool:
    return all(isinstance(p, ChatAgent) for p in participants)

When it happens

Trigger: Passing a Team, an autogen_core BaseAgent, or any non-ChatAgent object in participants to Swarm(); wrapping a team and passing the wrapper if it is not a ChatAgent subclass.

Common situations: Trying to nest a RoundRobinGroupChat or GraphFlow inside Swarm; passing raw autogen_core agents from a custom runtime.

Related errors

• Participant {participant} must be a ChatAgent.
• The first participant must be able to produce a handoff mess
• Agent state for {name} not found in the saved state.
• Participant {participant} must be a ChatAgent.
• At least one participant is required for MagenticOneGroupCha

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