What causes "Exactly one root agent must be provided" in run-llama/llama_index?

Pass root_agent= matching one agent's name: AgentWorkflow(agents=[...], root_agent="researcher").

run-llama/llama_index · error · ValueError

Exactly one root agent must be provided

Error message

Exactly one root agent must be provided

What it means

With multiple agents, AgentWorkflow needs to know which agent receives the first message. Unlike single-agent mode (where the lone agent is auto-selected as root), the constructor cannot guess a root, so root_agent=None with len(agents) > 1 raises ValueError.

Source

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

            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")

        self.root_agent = root_agent
        self.initial_state = initial_state or {}

        handoff_prompt = handoff_prompt or DEFAULT_HANDOFF_PROMPT
        if isinstance(handoff_prompt, str):
            handoff_prompt = PromptTemplate(handoff_prompt)
            if "{agent_info}" not in handoff_prompt.get_template():
                raise ValueError("Handoff prompt must contain {agent_info}")
        self.handoff_prompt = handoff_prompt

        handoff_output_prompt = handoff_output_prompt or DEFAULT_HANDOFF_OUTPUT_PROMPT
        if isinstance(handoff_output_prompt, str):

View on GitHub (pinned to afd0fef371)

Solutions

Pass root_agent=<name> matching one agent's name: AgentWorkflow(agents=[...], root_agent="researcher").
Verify the value equals an agent's name= exactly (it is checked against the {name: agent} dict next).
If only one agent is intended, pass just that agent so auto-selection applies.

Example fix

# before
wf = AgentWorkflow(agents=[researcher, writer])  # ValueError

# after
wf = AgentWorkflow(agents=[researcher, writer], root_agent="researcher")

Defensive patterns

Strategy: validation

Validate before calling

def build_workflow(agents, root_agent=None):
    if len(agents) > 1 and root_agent is None:
        raise ValueError("Multi-agent AgentWorkflow requires root_agent")
    return AgentWorkflow(agents=agents, root_agent=root_agent)

Prevention

Always specify root_agent when passing more than one agent.
Derive it from the agent object (root_agent=agents[0].name) to avoid name drift.
Wrap workflow construction in a helper that enforces the root_agent rule.

When it happens

Trigger: AgentWorkflow(agents=[a, b, c]) with the root_agent parameter omitted or explicitly None while more than one agent is supplied.

Common situations: Growing a single-agent workflow (where root_agent was never needed) into a multi-agent one; building agents dynamically and forgetting to designate an entry point; copying constructor calls from single-agent examples.

Related errors

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