{"record":{"id":"343f841246f33eda","repo":"run-llama/llama_index","slug":"state-prompt-must-contain-state-and-msg","errorCode":null,"errorMessage":"State prompt must contain {state} and {msg}","messagePattern":"State 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":181,"sourceCode":"        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\n\n    def _get_prompts(self) -> PromptDictType:\n        \"\"\"Get prompts.\"\"\"\n        return {\n            \"handoff_prompt\": self.handoff_prompt,\n            \"handoff_output_prompt\": self.handoff_output_prompt,\n            \"state_prompt\": self.state_prompt,\n        }\n\n    def _get_prompt_modules(self) -> PromptMixinType:\n        \"\"\"Get prompt sub-modules.\"\"\"\n        return {agent.name: agent for agent in self.agents.values()}","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L163-L199","documentation":"state_prompt controls how the current workflow state and the incoming user message are rendered into the agent's system context. When given as a string, it must contain both '{state}' and '{msg}' placeholders or AgentWorkflow raises, since the runtime substitutes both values on every run.","triggerScenarios":"AgentWorkflow(..., state_prompt=...) with a string template missing '{state}' or '{msg}'. Note the object stored is a PromptTemplate; only string inputs pass through this validation.","commonSituations":"Customizing state prompts to hide state from the LLM; adapting examples where only one placeholder was used; version changes that added the {msg} requirement.","solutions":["Include both tokens, e.g. state_prompt=\"Current state:\\n{state}\\nUser message: {msg}\".","Or omit state_prompt to use DEFAULT_STATE_PROMPT.","If you want to exclude state content, keep the placeholders and supply an empty/filtered state rather than deleting tokens."],"exampleFix":"# before\nwf = AgentWorkflow(agents=[...], root_agent=\"researcher\", state_prompt=\"State: {state}\")  # ValueError\n\n# after\nwf = AgentWorkflow(\n    agents=[...], root_agent=\"researcher\",\n    state_prompt=\"State: {state}\\nMessage: {msg}\",\n)","handlingStrategy":"validation","validationCode":"def check_state_prompt(tpl: str):\n    for token in (\"{state}\", \"{msg}\"):\n        if token not in tpl:\n            raise ValueError(f\"state_prompt must contain {token}\")\n    return tpl","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Include both {state} and {msg} in any custom state prompt.","Omit state_prompt entirely unless you truly need to change it.","Re-run your workflow-construction test after editing prompt templates."],"tags":["agent-workflow","prompt-template","validation","state"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}