{"record":{"id":"adbe114d220bc751","repo":"run-llama/llama_index","slug":"all-agents-must-have-a-name-in-a-multi-agent-workf","errorCode":null,"errorMessage":"All agents must have a name in a multi-agent workflow","messagePattern":"All agents must have a name in a multi-agent workflow","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py","lineNumber":127,"sourceCode":"        state_prompt: Optional[Union[str, BasePromptTemplate]] = None,\n        timeout: Optional[float] = None,\n        output_cls: Optional[Type[BaseModel]] = None,\n        structured_output_fn: Optional[\n            Callable[[List[ChatMessage]], Dict[str, Any]]\n        ] = None,\n        early_stopping_method: Literal[\"force\", \"generate\"] = \"force\",\n        **workflow_kwargs: Any,\n    ):\n        super().__init__(timeout=timeout, **workflow_kwargs)\n        self.early_stopping_method = early_stopping_method\n        if not agents:\n            raise ValueError(\"At least one agent must be provided\")\n\n        # Raise an error if any agent has no name or no description\n        if len(agents) > 1 and any(\n            agent.name == DEFAULT_AGENT_NAME for agent in agents\n        ):\n            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\")","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L109-L145","documentation":"AgentWorkflow validates its agent list at construction time. When more than one agent is passed, every agent must have an explicit name; the check compares agent.name against the sentinel default DEFAULT_AGENT_NAME (\"Agent\") set in base_agent.py. Any agent still carrying that default name makes routing between agents impossible, so the constructor raises immediately.","triggerScenarios":"Calling AgentWorkflow(workflow=[agent_a, agent_b]) (or agents=[...]) with 2+ agents where at least one was built without name=..., e.g. FunctionAgent(tools=[...], llm=llm) — its name defaults to \"Agent\". Single-agent workflows never trigger this.","commonSituations":"Starting from a working single-agent AgentWorkflow and adding a second agent without retrofitting names; copying agent construction code from a single-agent example; upgrading from versions where unnamed multi-agent setups were tolerated.","solutions":["Pass a unique name= to every agent in the list, e.g. FunctionAgent(name=\"researcher\", ...), FunctionAgent(name=\"writer\", ...).","Ensure each agent's name is distinct — self.agents is built as {cfg.name: cfg}, so duplicate names silently overwrite each other even though the error is about the default.","If you truly want one agent, pass a single-element list so the len(agents) > 1 guard is skipped."],"exampleFix":"# before\nagent1 = FunctionAgent(tools=[search_tool], llm=llm)\nagent2 = FunctionAgent(tools=[write_tool], llm=llm)\nwf = AgentWorkflow(agents=[agent1, agent2])  # ValueError\n\n# after\nagent1 = FunctionAgent(name=\"researcher\", tools=[search_tool], llm=llm)\nagent2 = FunctionAgent(name=\"writer\", tools=[write_tool], llm=llm)\nwf = AgentWorkflow(agents=[agent1, agent2], root_agent=\"researcher\")","handlingStrategy":"validation","validationCode":"from llama_index.core.agent.workflow.base_agent import DEFAULT_AGENT_NAME\n\ndef validate_agents(agents):\n    if len(agents) > 1 and any(a.name == DEFAULT_AGENT_NAME for a in agents):\n        raise ValueError(f\"Unnamed agent(s): {[a for a in agents if a.name == DEFAULT_AGENT_NAME]}\")\n    if len({a.name for a in agents}) != len(agents):\n        raise ValueError(\"Duplicate agent names\")\n    return agents","typeGuard":"def all_agents_named(agents: list) -> bool:\n    return all(a.name and a.name != \"Agent\" for a in agents)","tryCatchPattern":null,"preventionTips":["Always pass an explicit name= when constructing agents destined for a multi-agent workflow.","Centralize agent construction in a factory that requires name and description arguments.","Validate the agent list (names unique, none default) in a unit test for your workflow setup code."],"tags":["agent-workflow","validation","constructor","multi-agent"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}