{"record":{"id":"5ad8b7b492048250","repo":"run-llama/llama_index","slug":"initial-state-is-not-supported-per-agent-in-agentw","errorCode":null,"errorMessage":"Initial state is not supported per-agent in AgentWorkflow","messagePattern":"Initial state is not supported per-agent in AgentWorkflow","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py","lineNumber":137,"sourceCode":"        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\")\n\n        self.root_agent = root_agent\n        self.initial_state = initial_state or {}\n\n        handoff_prompt = handoff_prompt or DEFAULT_HANDOFF_PROMPT","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py#L119-L155","documentation":"AgentWorkflow owns a single shared workflow state (initial_state passed to AgentWorkflow itself). BaseWorkflowAgent accepts an initial_state field, but per-agent states are not supported because all agents run in the same Workflow Context. The constructor raises if any provided agent carries a non-empty initial_state.","triggerScenarios":"Constructing AgentWorkflow(agents=[...]) where any agent was built with initial_state={...} (e.g. FunctionAgent(initial_state={\"foo\": \"bar\"})). Applies even to single-agent lists.","commonSituations":"Migrating code from custom Workflow subclasses where each @step had its own state; assuming BaseWorkflowAgent's initial_state parameter is wired up because the constructor exposes it; setting state per agent when splitting one workflow into several agents.","solutions":["Remove initial_state from each agent and pass it once to the workflow: AgentWorkflow(agents=[...], initial_state={\"foo\": \"bar\"}).","If agents need distinct data, namespace keys in the shared state (e.g. {\"writer_draft\": ..., \"reviewer_notes\": ...}).","For truly isolated per-agent state, build a custom Workflow instead of AgentWorkflow."],"exampleFix":"# before\nagent = FunctionAgent(name=\"writer\", initial_state={\"draft\": \"\"}, ...)\nwf = AgentWorkflow(agents=[agent])  # ValueError\n\n# after\nagent = FunctionAgent(name=\"writer\", ...)\nwf = AgentWorkflow(agents=[agent], initial_state={\"draft\": \"\"})","handlingStrategy":"validation","validationCode":"def ensure_no_per_agent_state(agents):\n    offenders = [a.name for a in agents if getattr(a, \"initial_state\", None)]\n    if offenders:\n        raise ValueError(f\"Move initial_state to AgentWorkflow for agents: {offenders}\")\n    return agents","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass initial_state only to AgentWorkflow(...), never to individual agents.","Namespace per-agent data inside the shared state dict instead.","Document in your codebase that AgentWorkflow state is global to the run."],"tags":["agent-workflow","validation","state","constructor"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}