run-llama/llama_index · error · ValueError

Expected ActionReasoningStep, got {reasoning_step}

Error message

Expected ActionReasoningStep, got {reasoning_step}

What it means

ReActAgent parses each LLM response into a reasoning step via structured output. If the parsed output reports is_done=False it must be an ActionReasoningStep (thought + action + action_input) so a tool call can be built. Any other pydantic subclass — e.g. a ResponseReasoningStep or ObservationReasoningStep sneaking through with is_done=False — triggers this ValueError.

Source

Thrown at llama-index-core/llama_index/core/agent/workflow/react_agent.py:246

        current_reasoning.append(reasoning_step)
        await ctx.store.set(self.reasoning_key, current_reasoning)

        # If response step, we're done
        raw = (
            last_chat_response.raw.model_dump()
            if isinstance(last_chat_response.raw, BaseModel)
            else last_chat_response.raw
        )
        if reasoning_step.is_done:
            return AgentOutput(
                response=last_chat_response.message,
                raw=raw,
                current_agent_name=self.name,
            )

        reasoning_step = cast(ActionReasoningStep, reasoning_step)
        if not isinstance(reasoning_step, ActionReasoningStep):
            raise ValueError(f"Expected ActionReasoningStep, got {reasoning_step}")

        # Create tool call
        tool_calls = [
            ToolSelection(
                tool_id=str(uuid.uuid4()),
                tool_name=reasoning_step.action,
                tool_kwargs=reasoning_step.action_input,
            )
        ]

        return AgentOutput(
            response=last_chat_response.message,
            tool_calls=tool_calls,
            raw=raw,
            current_agent_name=self.name,
        )

    async def handle_tool_call_results(

View on GitHub (pinned to afd0fef371)

Solutions

1. Use a model with reliable structured/JSON output (OpenAI gpt-4o-class, Claude, etc.) with ReActAgent.
2. Avoid overriding the ReAct system prompt or output_cls; use FunctionAgent for plain function-calling models instead.
3. Upgrade llama-index-core — the structured ReAct path has had fixes for edge cases.
4. If it happens sporadically, retry the run; borderline model outputs can parse differently per attempt.

Example fix

# before
agent = ReActAgent(tools=[tool], llm=weak_local_llm)  # parses into wrong step type

# after
agent = FunctionAgent(tools=[tool], llm=weak_local_llm)  # uses native tool calling

for attempt in range(2):
    try:
        result = await agent.run(user_msg=q)
        break
    except ValueError as e:
        if "Expected ActionReasoningStep" not in str(e) or attempt == 1:
            raise

When it happens

Trigger: Using ReActAgent with an LLM whose structured-output parsing returns an unexpected ReasoningStep subtype with is_done=False; swapping output_cls or customizing react_agent_system_prompt so the model emits the wrong schema; weak models that produce malformed ReAct output under structured output modes.

Common situations: Using ReActAgent with llm.structured output on models that follow the wrong branch of the ReAct prompt; upgrading llama-index versions where the ReAct agent moved from text parsing to structured output; overriding agent reasoning step classes.

Related errors

• structured_predict expected a {output_cls.__name__} instance
• astructured_predict expected a {output_cls.__name__} instanc
• Malformed partial JSON encountered.
• Got empty streaming response
• LLM only supports text inputs

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