run-llama/llama_index · error · ValueError

Initial state is not supported per-agent in AgentWorkflow

Error message

Initial state is not supported per-agent in AgentWorkflow

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:137

        self.early_stopping_method = early_stopping_method
        if not agents:
            raise ValueError("At least one agent must be provided")

        # Raise an error if any agent has no name or no description
        if len(agents) > 1 and any(
            agent.name == DEFAULT_AGENT_NAME for agent in agents
        ):
            raise ValueError("All agents must have a name in a multi-agent workflow")

        if len(agents) > 1 and any(
            agent.description == DEFAULT_AGENT_DESCRIPTION for agent in agents
        ):
            raise ValueError(
                "All agents must have a description in a multi-agent workflow"
            )

        if any(agent.initial_state for agent in agents):
            raise ValueError(
                "Initial state is not supported per-agent in AgentWorkflow"
            )

        self.agents = {cfg.name: cfg for cfg in agents}
        if len(agents) == 1:
            root_agent = agents[0].name
        elif root_agent is None:
            raise ValueError("Exactly one root agent must be provided")
        else:
            root_agent = root_agent

        if root_agent not in self.agents:
            raise ValueError(f"Root agent {root_agent} not found in provided agents")

        self.root_agent = root_agent
        self.initial_state = initial_state or {}

        handoff_prompt = handoff_prompt or DEFAULT_HANDOFF_PROMPT

View on GitHub (pinned to afd0fef371)

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.

Example fix

# before
agent = FunctionAgent(name="writer", initial_state={"draft": ""}, ...)
wf = AgentWorkflow(agents=[agent])  # ValueError

# after
agent = FunctionAgent(name="writer", ...)
wf = AgentWorkflow(agents=[agent], initial_state={"draft": ""})

Defensive patterns

Strategy: validation

Validate before calling

def ensure_no_per_agent_state(agents):
    offenders = [a.name for a in agents if getattr(a, "initial_state", None)]
    if offenders:
        raise ValueError(f"Move initial_state to AgentWorkflow for agents: {offenders}")
    return agents

Prevention

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.

When it happens

Trigger: Constructing AgentWorkflow(agents=[...]) where any agent was built with initial_state={...} (e.g. FunctionAgent(initial_state={"foo": "bar"})). Applies even to single-agent lists.

Common situations: 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.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/5ad8b7b492048250. Report an issue: GitHub.