langchain-turn-window

A small, model-agnostic LangChain agent middleware that keeps only the last N conversational turns before each model call — without ever splitting an AIMessage tool call from its ToolMessage response.

Why

Every provider (OpenAI, Anthropic, Gemini, ...) rejects a request where a tool_calls entry has no matching tool result message. Naive history trimming — slicing by raw message count or token count — can easily cut the window in the middle of a tool-call/tool-result pair and break the request.

TurnWindowMiddleware anchors the window on HumanMessage boundaries instead: it always starts the kept slice at the Nth-most-recent HumanMessage, which guarantees every AIMessage tool call inside the window still has its ToolMessage response attached.

This is a lightweight alternative to LangChain's built-in SummarizationMiddleware (which needs an extra LLM call) or context_editing (which selectively clears old tool outputs) for the common case of "just bound the context to the last few turns."

Install

pip install langchain-turn-window

Usage

from langchain.agents import create_agent

from langchain_turn_window import TurnWindowMiddleware

agent = create_agent(
    model="openai:gpt-4o",
    tools=[...],
    middleware=[
        TurnWindowMiddleware(keep_last_turns=3),
    ],
)

keep_last_turns is the number of most-recent HumanMessage turns to retain. If the conversation has fewer turns than that, the full history passes through unchanged.

How it works

TurnWindowMiddleware implements wrap_model_call / awrap_model_call. On every model call it:

1. Finds the indexes of all HumanMessages in request.messages.
2. If there are fewer than keep_last_turns human turns, passes the messages through unchanged.
3. Otherwise, slices the message list starting at the keep_last_turns-th-most-recent HumanMessage and forwards only that suffix to the model.

The underlying pure function is also exported directly if you want to use it outside of middleware (e.g. in a custom node):

from langchain_turn_window import window_by_human_turns

windowed = window_by_human_turns(messages, n=3)

window_by_human_turns never mutates its input and returns the original list object unchanged when no trimming is needed (positive-n guard, empty list, or fewer human turns than n).

Configuration

Limitations

• Assumes a single-user conversational shape (one HumanMessage per turn). For multi-agent handoff patterns where turns aren't anchored on HumanMessage, this middleware is not the right fit as-is.
• This is a hard trim, not a summary — content outside the window is dropped, not condensed. Combine with SummarizationMiddleware if you need older context preserved in compressed form.

Development

pip install -e ".[dev]"
pytest

License

MIT