prebuilt: add filter_orphaned_reasoning_messages pre_model_hook

[Alan Andrade (alan-andrade)]

Why

When a client aborts a streaming response mid-flight, LangGraph may persist an AIMessage whose content consists exclusively of type="reasoning" blocks with no accompanying text or tool-call output. On the next conversation turn, replaying that orphaned message causes a provider error:

BadRequestError: Item 'rs_...' of type 'reasoning' was provided without its required following item.

This is a gap in the existing _validate_chat_history logic, which only checks for orphaned tool calls, not orphaned reasoning blocks.

What

Adds a public filter_orphaned_reasoning_messages function to langgraph.prebuilt that is designed to be passed directly as a pre_model_hook to create_react_agent:

from langgraph.prebuilt import create_react_agent, filter_orphaned_reasoning_messages

agent = create_react_agent(
    model,
    tools,
    pre_model_hook=filter_orphaned_reasoning_messages,
)

The function:

• Scans state["messages"] for AIMessages whose content is a non-empty list of only type="reasoning" blocks and that carry no tool_calls
• Returns {"messages": [RemoveMessage(id=...), ...]} to strip them before the model call
• Returns None (no-op) when no orphaned messages are present
• Skips messages without an id rather than raising

15 unit tests cover the full edge-case surface: empty content, mixed reasoning+text (complete turns, not orphaned), messages with tool_calls, multiple orphans, idempotency, and the no-id edge case.

Notes

This pattern was first implemented in production at dbt Labs to handle stream-abort scenarios with the OpenAI Responses API (o3, o4-mini). It sits alongside the existing _validate_chat_history orphaned-tool-call check and is non-overlapping with it by construction — _is_reasoning_only returns False for any message carrying tool_calls.

Drafted by Claude Sonnet 4.6 under the direction of Alan Andrade (@alan-andrade)

[github-actions]

This PR has been automatically closed because it does not link to an approved issue.

All external contributions must reference an approved issue or discussion. Please:

1. Find or open an issue describing the change
2. Wait for a maintainer to approve and assign you
3. Add Fixes #<issue_number>, Closes #<issue_number>, or Resolves #<issue_number> to your PR description and the PR will be reopened automatically

Maintainers: reopen this PR or remove the missing-issue-link label to bypass this check.