{"record":{"id":"8c49cc50297197d3","repo":"run-llama/llama_index","slug":"exactly-one-root-agent-must-be-provided","errorCode":null,"errorMessage":"Exactly one root agent must be provided","messagePattern":"Exactly one root agent must be provided","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py","lineNumber":145,"sourceCode":"            raise ValueError(\"All agents must have a name in a multi-agent workflow\")\n\n        if len(agents) > 1 and any(\n            agent.description == DEFAULT_AGENT_DESCRIPTION for agent in agents\n        ):\n            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):","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L127-L163","documentation":"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.","triggerScenarios":"AgentWorkflow(agents=[a, b, c]) with the root_agent parameter omitted or explicitly None while more than one agent is supplied.","commonSituations":"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.","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."],"exampleFix":"# before\nwf = AgentWorkflow(agents=[researcher, writer])  # ValueError\n\n# after\nwf = AgentWorkflow(agents=[researcher, writer], root_agent=\"researcher\")","handlingStrategy":"validation","validationCode":"def build_workflow(agents, root_agent=None):\n    if len(agents) > 1 and root_agent is None:\n        raise ValueError(\"Multi-agent AgentWorkflow requires root_agent\")\n    return AgentWorkflow(agents=agents, root_agent=root_agent)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["agent-workflow","validation","constructor","multi-agent"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}