@before_model: Reference Guide

What is @before_model?

@before_model is a middleware decorator that registers a function to run before each language model call inside a LangChain agent. The hook receives the full agent state dict, can mutate it freely, and must return the (modified) state. This makes it the central extension point for controlling what the model sees — trimming conversation history to control token cost, injecting retrieved context from a vector store, adding system instructions dynamically, or blocking requests that violate access control rules.

The most common production use is message history trimming. Long agent conversations accumulate messages and eventually exceed the model's context window or inflate token costs. A @before_model hook that keeps only the last N messages solves this at the middleware layer without changing the agent's core logic. A subtler version uses a summarization approach: when the history exceeds a threshold, summarize the oldest messages into a single summary message and keep only that plus the recent messages.

RAG injection is another powerful use. You can extract the user's latest message from state["messages"][-1].content, run a retrieval query against a vector store, and prepend the retrieved context as a SystemMessage or HumanMessage before the model call. This pattern decouples retrieval from the main agent graph — the agent's nodes never need to know about the retrieval step. Like @after_model, each hook must return the state dict; multiple hooks compose in registration order.

Use Cases

• • Trim history
• • Inject RAG
• • Validate input
• • Optimize tokens
• • Cost control
• • Access control

Key Features

• ✓ Pre-model hook
• ✓ State access
• ✓ Preprocessing
• ✓ Token counting
• ✓ RAG support
• ✓ Composable

When NOT to Use

Notes

Import

from langchain.agents import before_model

How to Apply

@before_model
def trim(state):
    state['messages'] = state['messages'][-10:]
    return state

What It Enables

• ✓ Message trimming
• ✓ Context injection
• ✓ Validation
• ✓ Token optimization

Code Examples

from langchain.agents import before_model
@before_model
def trim(state):
    state['messages'] = state['messages'][-10:]
    return state

from langchain.agents import before_model
from langchain_core.messages import SystemMessage
@before_model
def inject_rag(state):
    query = state['messages'][-1].content
    docs = retriever.invoke(query)
    context = "\n".join(d.page_content for d in docs)
    state['messages'].insert(0, SystemMessage(content=f'Context:\n{context}'))
    return state

from langchain.agents import before_model
import tiktoken
enc = tiktoken.encoding_for_model("gpt-4o-mini")
def token_count(msgs):
    return sum(len(enc.encode(m.content)) for m in msgs)
@before_model
def budget_guard(state):
    while token_count(state['messages']) > 3000:
        state['messages'].pop(1)  # Remove oldest non-system
    return state

Integration Patterns

Common Mistakes

Related LangChain References

Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with @before_model and the wider framework.

@before_model FAQ