What causes "Root agent {root_agent} not found in provided agents" in run-llama/llama_index?

Make root_agent exactly equal to one agent's name= (case-sensitive).

run-llama/llama_index · error · ValueError

Root agent {root_agent} not found in provided agents

Error message

Root agent {root_agent} not found in provided agents

What it means

After resolving root_agent, AgentWorkflow verifies it is a key in the self.agents dict built from {cfg.name: cfg}. A root_agent string that does not exactly match any agent name (typo, casing, whitespace, stale name) fails this membership check.

Source

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

            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):
            handoff_output_prompt = PromptTemplate(handoff_output_prompt)
            if (
                "{to_agent}" not in handoff_output_prompt.get_template()
                or "{reason}" not in handoff_output_prompt.get_template()
            ):

View on GitHub (pinned to afd0fef371)

Solutions

Make root_agent exactly equal to one agent's name= (case-sensitive).
Derive it programmatically to avoid drift: root_agent=agents[0].name.
Print/review {a.name for a in agents} when unsure of the exact names.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

def validate_root(agents, root_agent):
    names = {a.name for a in agents}
    if root_agent not in names:
        raise ValueError(f"root_agent {root_agent!r} not in {sorted(names)}")
    return root_agent

Type guard

def is_valid_root(agents: list, root_agent: str) -> bool:
    return root_agent in {a.name for a in agents}

Prevention

Reference agent.name programmatically instead of retyping the string.
Keep agent names in one constant/enum used by both agent construction and root_agent.
Fail fast with your own membership check that lists valid names in the error message.

When it happens

Trigger: AgentWorkflow(agents=[...], root_agent="Reseacher") when the agent's name is "researcher"; renaming an agent but not the root_agent argument; passing an agent object instead of its name string.

Common situations: Typos or case mismatches between name= and root_agent=; refactors that rename agents; passing agent.name of a different variable than the one in the list.

Related errors

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