microsoft/autogen · error · TypeError

Participant {participant} must be a ChatAgent.

Error message

Participant {participant} must be a ChatAgent.

What it means

Raised by GraphFlow.__init__ (TypeError) when a participant is not a ChatAgent instance. Graph flow nodes must be individual chat agents — a nested Team, a runtime agent, or any other object is rejected, unlike Selector/Swarm teams which can nest teams inside a container.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py:800

    def __init__(
        self,
        participants: List[ChatAgent],
        graph: DiGraph,
        *,
        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,
    ) -> None:
        self._input_participants = participants
        self._input_termination_condition = termination_condition

        for participant in participants:
            if not isinstance(participant, ChatAgent):
                raise TypeError(f"Participant {participant} must be a ChatAgent.")

        # No longer add _StopAgent or StopMessageTermination
        # Termination is now handled directly in GraphFlowManager._apply_termination_condition
        super().__init__(
            name=name or self.DEFAULT_NAME,
            description=description or self.DEFAULT_DESCRIPTION,
            participants=list(participants),
            group_chat_manager_name="GraphManager",
            group_chat_manager_class=GraphFlowManager,
            termination_condition=termination_condition,
            max_turns=max_turns,
            runtime=runtime,
            custom_message_types=custom_message_types,
        )
        self._graph = graph

    def _create_group_chat_manager_factory(
        self,

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Flatten the nested team: register its member agents directly as graph participants and express the inner team's sequencing as graph edges.
2. Or use SelectorGroupChat/Swarm if nesting teams inside participants is a hard requirement.
3. Type-check participants before construction (see validation code) for config-driven setups.

Example fix

// before
inner = RoundRobinGroupChat([a, b])
flow = GraphFlow([inner, c])  # TypeError

// after
flow = GraphFlow([a, b, c])  # model the inner team's order as edges
builder.add_edge(a, b); builder.add_edge(b, c)

from autogen_agentchat.base import ChatAgent
bad = [p for p in participants if not isinstance(p, ChatAgent)]
if bad:
    raise TypeError(f"GraphFlow participants must be ChatAgent, got: {[type(b).__name__ for b in bad]}")

from autogen_agentchat.base import ChatAgent, Team
def is_flat_chat_agents(participants: Sequence[object]) -> bool:
    return all(isinstance(p, ChatAgent) and not isinstance(p, Team) for p in participants)

try:
    flow = GraphFlow(participants, graph_builder=builder)
except TypeError as e:
    if "must be a ChatAgent" in str(e):
        # flatten nested teams into their member agents and re-model as graph edges
        ...

When it happens

Trigger: Passing a RoundRobinGroupChat/SelectorGroupChat/other Team in the participants list of GraphFlow; passing an autogen_core agent (not agentchat ChatAgent); passing None or a plain object from a misbuilt config.

Common situations: Trying to compose hierarchical multi-team workflows with GraphFlow; migrating from another team type where nesting was allowed; dynamically loading 'agents' from config where one entry resolves to a Team.

Related errors

• Participant {participant} must be a ChatAgent.
• Participant {participant} must be a ChatAgent.
• Failed to sync gallery from ${url}
• Message must have a receiver to be sent.
• Agent state for {name} not found in the saved state.

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