Heuristic:Microsoft Autogen Name Uniqueness Constraints

Knowledge Sources	Microsoft AutoGen AssistantAgent validation BaseGroupChat validation
Domains	Multi_Agent_Systems, Debugging
Last Updated	2026-02-11 18:00 GMT

Overview

All names must be unique within their scope: tool names, handoff names, and participant names cannot overlap. Violations raise `ValueError` at construction time.

Description

AutoGen enforces strict uniqueness constraints on names at multiple levels. Within an agent, tool names must be unique, handoff names must be unique, and handoff names must not overlap with tool names. Within a team (group chat), participant agent names must be unique. The `SelectorGroupChat` further requires at least two participants. These constraints are validated eagerly at construction time, not at runtime, so errors are caught early.

Usage

Use this heuristic when:

Constructing agents with multiple tools or handoffs
Building teams with multiple participants
Debugging `ValueError` exceptions about duplicate names
Dynamically generating agent configurations where name collisions are possible

The Insight (Rule of Thumb)

Rule 1: Tool names within an agent must be unique.
Rule 2: Handoff names (target agent names) within an agent must be unique.
Rule 3: Handoff names must not collide with tool names on the same agent.
Rule 4: Participant names in a group chat must be unique.
Rule 5: SelectorGroupChat requires at least 2 participants (not just 1).
Rule 6: Tools and workbenches are mutually exclusive — an agent cannot have both.

Reasoning

Agent-level validation from `_assistant_agent.py:786-825`:

# Check if tool names are unique.
tool_names = [tool.name for tool in self._tools]
if len(tool_names) != len(set(tool_names)):
    raise ValueError(f"Tool names must be unique: {tool_names}")

# Check if handoff tool names are unique.
handoff_tool_names = [tool.name for tool in self._handoff_tools]
if len(handoff_tool_names) != len(set(handoff_tool_names)):
    raise ValueError(f"Handoff names must be unique: {handoff_tool_names}")

# Check if there's any overlap between handoff tool names and tool names
overlap = tool_names_set.intersection(handoff_tool_names_set)
if overlap:
    raise ValueError("Handoff names must be unique from tool names")

Team-level validation from `_base_group_chat.py:81-84`:

if len(participants) == 0:
    raise ValueError("At least one participant is required.")
if len(participants) != len(set(participant.name for participant in participants)):
    raise ValueError("The participant names must be unique.")

SelectorGroupChat from `_selector_group_chat.py:638`:

# SelectorGroupChat requires at least TWO participants

Mutual exclusivity from `_assistant_agent.py:827-829`:

if workbench is not None:
    if self._tools:
        raise ValueError("Tools cannot be used with a workbench.")

These constraints exist because the LLM uses tool/handoff names to select actions, and the group chat manager uses participant names for speaker selection. Duplicate names would create ambiguity in routing. The early validation prevents subtle runtime bugs where the wrong tool or agent is selected.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment