{"record":{"id":"4abb75821c03302e","repo":"run-llama/llama_index","slug":"root-agent-root-agent-not-found-in-provided-agen","errorCode":null,"errorMessage":"Root agent {root_agent} not found in provided agents","messagePattern":"Root agent (.+?) not found in provided agents","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py","lineNumber":150,"sourceCode":"            raise ValueError(\n                \"All agents must have a description in a multi-agent workflow\"\n            )\n\n        if any(agent.initial_state for agent in agents):\n            raise ValueError(\n                \"Initial state is not supported per-agent in AgentWorkflow\"\n            )\n\n        self.agents = {cfg.name: cfg for cfg in agents}\n        if len(agents) == 1:\n            root_agent = agents[0].name\n        elif root_agent is None:\n            raise ValueError(\"Exactly one root agent must be provided\")\n        else:\n            root_agent = root_agent\n\n        if root_agent not in self.agents:\n            raise ValueError(f\"Root agent {root_agent} not found in provided agents\")\n\n        self.root_agent = root_agent\n        self.initial_state = initial_state or {}\n\n        handoff_prompt = handoff_prompt or DEFAULT_HANDOFF_PROMPT\n        if isinstance(handoff_prompt, str):\n            handoff_prompt = PromptTemplate(handoff_prompt)\n            if \"{agent_info}\" not in handoff_prompt.get_template():\n                raise ValueError(\"Handoff prompt must contain {agent_info}\")\n        self.handoff_prompt = handoff_prompt\n\n        handoff_output_prompt = handoff_output_prompt or DEFAULT_HANDOFF_OUTPUT_PROMPT\n        if isinstance(handoff_output_prompt, str):\n            handoff_output_prompt = PromptTemplate(handoff_output_prompt)\n            if (\n                \"{to_agent}\" not in handoff_output_prompt.get_template()\n                or \"{reason}\" not in handoff_output_prompt.get_template()\n            ):","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L132-L168","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nwf = AgentWorkflow(agents=[researcher, writer], root_agent=\"Researcher\")  # ValueError\n\n# after\nwf = AgentWorkflow(agents=[researcher, writer], root_agent=researcher.name)","handlingStrategy":"validation","validationCode":"def validate_root(agents, root_agent):\n    names = {a.name for a in agents}\n    if root_agent not in names:\n        raise ValueError(f\"root_agent {root_agent!r} not in {sorted(names)}\")\n    return root_agent","typeGuard":"def is_valid_root(agents: list, root_agent: str) -> bool:\n    return root_agent in {a.name for a in agents}","tryCatchPattern":null,"preventionTips":["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."],"tags":["agent-workflow","validation","constructor","typo"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}