{"record":{"id":"86a7c3556311b12b","repo":"run-llama/llama_index","slug":"all-agents-must-have-a-description-in-a-multi-agen","errorCode":null,"errorMessage":"All agents must have a description in a multi-agent workflow","messagePattern":"All agents must have a description 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":132,"sourceCode":"        ] = 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\")\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\")","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L114-L150","documentation":"In a multi-agent AgentWorkflow, each agent's description is injected into the other agents' prompts via the handoff prompt ({agent_info}) so the LLM can decide when to hand off. The constructor rejects any of the 2+ agents whose description still equals the sentinel DEFAULT_AGENT_DESCRIPTION (\"An agent that can perform a task\"), because identical boilerplate descriptions make handoff decisions meaningless.","triggerScenarios":"AgentWorkflow(agents=[a, b]) with len > 1 where any agent was created without description=... and thus kept the default from base_agent.py. Runs right after the name check, so names must already be set before you hit it.","commonSituations":"Adding agents to an existing workflow and setting only name=; porting from ReActAgent-style code where descriptions were optional; agents built from a factory function that hardcodes or omits descriptions.","solutions":["Give every agent a distinct, task-specific description=... describing when it should be used, e.g. FunctionAgent(name=\"writer\", description=\"Writes polished prose from research notes\", ...).","Double-check agents created by helper functions/loops — the description must not literally equal the default string 'An agent that can perform a task'.","Keep descriptions differentiated; identical handoff targets degrade routing quality even when they pass validation."],"exampleFix":"# before\nagent2 = FunctionAgent(name=\"writer\", tools=[write_tool], llm=llm)\nwf = AgentWorkflow(agents=[researcher, agent2])  # ValueError\n\n# after\nagent2 = FunctionAgent(\n    name=\"writer\",\n    description=\"Writes final reports from research notes\",\n    tools=[write_tool],\n    llm=llm,\n)\nwf = AgentWorkflow(agents=[researcher, agent2], root_agent=\"researcher\")","handlingStrategy":"validation","validationCode":"from llama_index.core.agent.workflow.base_agent import DEFAULT_AGENT_DESCRIPTION\n\ndef validate_agent_descriptions(agents):\n    if len(agents) > 1 and any(a.description == DEFAULT_AGENT_DESCRIPTION for a in agents):\n        missing = [a.name for a in agents if a.description == DEFAULT_AGENT_DESCRIPTION]\n        raise ValueError(f\"Agents missing description: {missing}\")\n    return agents","typeGuard":"def all_agents_described(agents: list) -> bool:\n    return all(a.description and a.description != \"An agent that can perform a task\" for a in agents)","tryCatchPattern":null,"preventionTips":["Treat name and description as required fields in your agent factory/builder functions.","Write descriptions that state WHEN the agent should be used — they drive handoff routing.","Assert in tests that every agent in a multi-agent workflow has a non-default description."],"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"}