run-llama/llama_index · error · ValueError

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

Error message

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

What it means

In a multi-agent AgentWorkflow, each agent's description is injected into the other agents' prompts via the handoff prompt ({agent_info}) so the LLM can decide when to hand off. The constructor rejects any of the 2+ agents whose description still equals the sentinel DEFAULT_AGENT_DESCRIPTION ("An agent that can perform a task"), because identical boilerplate descriptions make handoff decisions meaningless.

Source

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

        ] = 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")
        else:
            root_agent = root_agent

        if root_agent not in self.agents:
            raise ValueError(f"Root agent {root_agent} not found in provided agents")

View on GitHub (pinned to afd0fef371)

Solutions

1. Give every agent a distinct, task-specific description=... describing when it should be used, e.g. FunctionAgent(name="writer", description="Writes polished prose from research notes", ...).
2. Double-check agents created by helper functions/loops — the description must not literally equal the default string 'An agent that can perform a task'.
3. Keep descriptions differentiated; identical handoff targets degrade routing quality even when they pass validation.

Example fix

# before
agent2 = FunctionAgent(name="writer", tools=[write_tool], llm=llm)
wf = AgentWorkflow(agents=[researcher, agent2])  # ValueError

# after
agent2 = FunctionAgent(
    name="writer",
    description="Writes final reports from research notes",
    tools=[write_tool],
    llm=llm,
)
wf = AgentWorkflow(agents=[researcher, agent2], root_agent="researcher")

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

def validate_agent_descriptions(agents):
    if len(agents) > 1 and any(a.description == DEFAULT_AGENT_DESCRIPTION for a in agents):
        missing = [a.name for a in agents if a.description == DEFAULT_AGENT_DESCRIPTION]
        raise ValueError(f"Agents missing description: {missing}")
    return agents

def all_agents_described(agents: list) -> bool:
    return all(a.description and a.description != "An agent that can perform a task" for a in agents)

When it happens

Trigger: AgentWorkflow(agents=[a, b]) with len > 1 where any agent was created without description=... and thus kept the default from base_agent.py. Runs right after the name check, so names must already be set before you hit it.

Common situations: Adding agents to an existing workflow and setting only name=; porting from ReActAgent-style code where descriptions were optional; agents built from a factory function that hardcodes or omits descriptions.

Related errors

• All agents must have a name 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/86a7c3556311b12b. Report an issue: GitHub.