{"record":{"id":"d5c31840caa87481","repo":"run-llama/llama_index","slug":"handoff-prompt-must-contain-agent-info","errorCode":null,"errorMessage":"Handoff prompt must contain {agent_info}","messagePattern":"Handoff prompt must contain (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py","lineNumber":159,"sourceCode":"        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            ):\n                raise ValueError(\n                    \"Handoff output prompt must contain {to_agent} and {reason}\"\n                )\n        self.handoff_output_prompt = handoff_output_prompt\n\n        state_prompt = state_prompt or DEFAULT_STATE_PROMPT\n        if isinstance(state_prompt, str):\n            state_prompt = PromptTemplate(state_prompt)\n            if (","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L141-L177","documentation":"When handoff_prompt is supplied as a plain string, AgentWorkflow wraps it in a PromptTemplate and validates that it contains the {agent_info} placeholder. That placeholder is where the list of available agents (name + description) is rendered so the LLM knows its handoff targets; without it the prompt cannot inform routing.","triggerScenarios":"AgentWorkflow(agents=[...], handoff_prompt=\"Hand off to another agent if needed.\") — any string template missing the literal {agent_info} token. Only string prompts are validated; pre-built PromptTemplate objects are accepted as-is.","commonSituations":"Customizing the handoff prompt for tone/language and dropping the placeholder; copying a prompt from an older version with different placeholders; escaping braces so the template no longer matches.","solutions":["Add {agent_info} to your custom string, e.g. handoff_prompt=\"You have access to these agents:\\n{agent_info}\\nHand off when appropriate.\"","Or omit handoff_prompt entirely to use DEFAULT_HANDOFF_PROMPT.","Check handoff_prompt.get_template() contains the exact token '{agent_info}' — double braces or renamed placeholders fail."],"exampleFix":"# before\nwf = AgentWorkflow(\n    agents=[...], root_agent=\"researcher\",\n    handoff_prompt=\"Pass the task to a better agent.\",  # ValueError\n)\n\n# after\nwf = AgentWorkflow(\n    agents=[...], root_agent=\"researcher\",\n    handoff_prompt=(\n        \"You can hand off to these agents:\\n{agent_info}\\n\"\n        \"Use handoff when another agent is better suited.\"\n    ),\n)","handlingStrategy":"validation","validationCode":"def check_handoff_prompt(tpl: str):\n    if \"{agent_info}\" not in tpl:\n        raise ValueError(\"handoff_prompt must contain {agent_info}\")\n    return tpl","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep required placeholders ({agent_info}) in a checklist when localizing prompts.","Prefer overriding prompts with PromptTemplate objects only after checking get_template() output.","Write a smoke test that constructs AgentWorkflow with your custom prompts."],"tags":["agent-workflow","prompt-template","validation","handoff"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}