{"record":{"id":"94fab9154768607d","repo":"run-llama/llama_index","slug":"handoff-output-prompt-must-contain-to-agent-and","errorCode":null,"errorMessage":"Handoff output prompt must contain {to_agent} and {reason}","messagePattern":"Handoff output prompt must contain (.+?) and (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py","lineNumber":169,"sourceCode":"\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 (\n                \"{state}\" not in state_prompt.get_template()\n                or \"{msg}\" not in state_prompt.get_template()\n            ):\n                raise ValueError(\"State prompt must contain {state} and {msg}\")\n        self.state_prompt = state_prompt\n\n        self.output_cls = output_cls\n        self.structured_output_fn = structured_output_fn\n        if output_cls is not None and structured_output_fn is not None:\n            self.structured_output_fn = None","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L151-L187","documentation":"handoff_output_prompt defines the exact string format the LLM must emit to perform a handoff (containing {to_agent} and {reason}). When passed as a string, AgentWorkflow validates both placeholders exist before wrapping it in a PromptTemplate, because _initialize_agent handoff parsing depends on this exact output shape.","triggerScenarios":"AgentWorkflow(..., handoff_output_prompt=...) with a string template lacking either '{to_agent}' or '{reason}'. Both must be present; missing either one triggers the error.","commonSituations":"Reformatting the handoff output template (e.g. renaming {to_agent} to {target}) which breaks the parser; translating/localizing the prompt and losing a placeholder; copying examples from incompatible versions.","solutions":["Include both tokens verbatim, e.g. handoff_output_prompt='Handoff to <{to_agent}> because {reason}'.","Or leave handoff_output_prompt unset to use DEFAULT_HANDOFF_OUTPUT_PROMPT.","If you need a different format, keep the placeholders and only change surrounding text."],"exampleFix":"# before\nwf = AgentWorkflow(\n    agents=[...], root_agent=\"researcher\",\n    handoff_output_prompt=\"Transfer to {target} since {reason}\",  # ValueError\n)\n\n# after\nwf = AgentWorkflow(\n    agents=[...], root_agent=\"researcher\",\n    handoff_output_prompt=\"Transfer to {to_agent} because {reason}\",\n)","handlingStrategy":"validation","validationCode":"def check_handoff_output_prompt(tpl: str):\n    for token in (\"{to_agent}\", \"{reason}\"):\n        if token not in tpl:\n            raise ValueError(f\"handoff_output_prompt must contain {token}\")\n    return tpl","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never rename the {to_agent}/{reason} tokens — the handoff parser matches them.","Change only literal wording around placeholders when customizing.","Unit-test custom templates for placeholder presence."],"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"}