run-llama/llama_index · error · ValueError

All agents must have a name in a multi-agent workflow

Error message

All agents must have a name in a multi-agent workflow

What it means

AgentWorkflow validates its agent list at construction time. When more than one agent is passed, every agent must have an explicit name; the check compares agent.name against the sentinel default DEFAULT_AGENT_NAME ("Agent") set in base_agent.py. Any agent still carrying that default name makes routing between agents impossible, so the constructor raises immediately.

Source

Thrown at llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:127

        state_prompt: Optional[Union[str, BasePromptTemplate]] = None,
        timeout: Optional[float] = None,
        output_cls: Optional[Type[BaseModel]] = None,
        structured_output_fn: Optional[
            Callable[[List[ChatMessage]], Dict[str, Any]]
        ] = None,
        early_stopping_method: Literal["force", "generate"] = "force",
        **workflow_kwargs: Any,
    ):
        super().__init__(timeout=timeout, **workflow_kwargs)
        self.early_stopping_method = early_stopping_method
        if not agents:
            raise ValueError("At least one agent must be provided")

        # Raise an error if any agent has no name or no description
        if len(agents) > 1 and any(
            agent.name == DEFAULT_AGENT_NAME for agent in agents
        ):
            raise ValueError("All agents must have a name in a multi-agent workflow")

        if len(agents) > 1 and any(
            agent.description == DEFAULT_AGENT_DESCRIPTION for agent in agents
        ):
            raise ValueError(
                "All agents must have a description in a multi-agent workflow"
            )

        if any(agent.initial_state for agent in agents):
            raise ValueError(
                "Initial state is not supported per-agent in AgentWorkflow"
            )

        self.agents = {cfg.name: cfg for cfg in agents}
        if len(agents) == 1:
            root_agent = agents[0].name
        elif root_agent is None:
            raise ValueError("Exactly one root agent must be provided")

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass a unique name= to every agent in the list, e.g. FunctionAgent(name="researcher", ...), FunctionAgent(name="writer", ...).
2. Ensure each agent's name is distinct — self.agents is built as {cfg.name: cfg}, so duplicate names silently overwrite each other even though the error is about the default.
3. If you truly want one agent, pass a single-element list so the len(agents) > 1 guard is skipped.

Example fix

# before
agent1 = FunctionAgent(tools=[search_tool], llm=llm)
agent2 = FunctionAgent(tools=[write_tool], llm=llm)
wf = AgentWorkflow(agents=[agent1, agent2])  # ValueError

# after
agent1 = FunctionAgent(name="researcher", tools=[search_tool], llm=llm)
agent2 = FunctionAgent(name="writer", tools=[write_tool], llm=llm)
wf = AgentWorkflow(agents=[agent1, agent2], root_agent="researcher")

from llama_index.core.agent.workflow.base_agent import DEFAULT_AGENT_NAME

def validate_agents(agents):
    if len(agents) > 1 and any(a.name == DEFAULT_AGENT_NAME for a in agents):
        raise ValueError(f"Unnamed agent(s): {[a for a in agents if a.name == DEFAULT_AGENT_NAME]}")
    if len({a.name for a in agents}) != len(agents):
        raise ValueError("Duplicate agent names")
    return agents

def all_agents_named(agents: list) -> bool:
    return all(a.name and a.name != "Agent" for a in agents)

When it happens

Trigger: Calling AgentWorkflow(workflow=[agent_a, agent_b]) (or agents=[...]) with 2+ agents where at least one was built without name=..., e.g. FunctionAgent(tools=[...], llm=llm) — its name defaults to "Agent". Single-agent workflows never trigger this.

Common situations: Starting from a working single-agent AgentWorkflow and adding a second agent without retrofitting names; copying agent construction code from a single-agent example; upgrading from versions where unnamed multi-agent setups were tolerated.

Related errors

• All agents must have a description in a multi-agent workflow
• Exactly one root agent must be provided
• Initial state is not supported per-agent in AgentWorkflow
• Root agent {root_agent} not found in provided agents
• Handoff prompt must contain {agent_info}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/adbe114d220bc751. Report an issue: GitHub.