langchain — User Guide

LangChain is a Python framework for building agents and LLM-powered applications. It gives you one interface for talking to dozens of model providers, a production-ready agent loop (create_agent) built on LangGraph, a composable middleware system for retries, guardrails, human approval and context management, and the component library (messages, tools, prompts, output parsers, embeddings, vector stores, text splitters) that everything else is built from.

This guide covers the Python monorepo langchain-ai/langchain at commit a9780cd. It is organized by what you want to do: get a first result, install the right packages, build agents, add tools and memory, and fix things when they break. Architecture, internals, security and the complete configuration reference live in the companion Admin Guide.

Note

Every package requires Python 3.10 or newer (requires-python = ">=3.10.0,<4.0.0"). LangChain has no server, no daemon and no configuration file of its own — it is a library you import. "Configuration" means constructor arguments, environment variables for provider credentials, and the per-call config dictionary.

1. Quick Start

The shortest path from zero to a working agent with a tool.

Step 1 — install the framework plus one provider package:

pip install -U langchain langchain-openai

Successfully installed langchain-1.4.3 langchain-core-1.6.6 langchain-openai-1.6.6 langgraph-1.2.x openai-2.x ...

Step 2 — set your provider key in the environment:

export OPENAI_API_KEY="sk-..."

Step 3 — talk to a model. init_chat_model takes a provider:model string and returns a ready chat model:

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.5")
reply = model.invoke("Say hello in five words.")
print(reply.text)

Hello there, nice to meet!

Step 4 — build an agent. Any typed Python function with a docstring can be a tool:

from langchain.agents import create_agent


def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"It's always sunny in {city}!"


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "What's the weather in Paris?"}]})
print(result["messages"][-1].text)

It's always sunny in Paris!

Tip

result["messages"] holds the whole conversation: your HumanMessage, the model's AIMessage with a tool call, the ToolMessage your function produced, and the model's final AIMessage. Print them all to see the agent loop at work.

Important

Model reply text varies from run to run. Outputs shown in this guide are representative, not exact.

• [x] Installed langchain and a provider package
• [x] Set the provider's API key
• [x] Got a model reply
• [x] Ran an agent that called a tool

2. Installation

2.1 Requirements

2.2 Choose what to install

LangChain is split into a small core plus one package per provider. Install the framework, then add only the providers you use.

uv (recommended by the project)

uv add langchain
uv add langchain-openai        # or langchain-anthropic, langchain-ollama, ...

pip

pip install -U langchain
pip install -U langchain-openai

pip with extras

# The langchain package declares an extra per provider
pip install -U "langchain[openai,anthropic]"

MCP support

# langchain.mcp needs FastMCP 4.x
pip install -U "langchain[mcp]"

The langchain package declares these optional-dependency extras (each simply installs the named integration):

Note

Only 16 provider packages live in this repository (Anthropic, Chroma, DeepSeek, Exa, Fireworks, Groq, Hugging Face, Mistral AI, Nomic, Ollama, OpenAI, OpenRouter, Perplexity, Qdrant, TypeSafe, xAI). Google, AWS, Azure AI, Cohere and many others are maintained in their own repositories but are still reachable through init_chat_model once installed.

2.3 Provider packages in this repository

2.4 Text splitters and optional helpers

pip install -U langchain-text-splitters
# Optional back ends are NOT declared as extras; install what you use:
pip install tiktoken            # TokenTextSplitter, from_tiktoken_encoder
pip install beautifulsoup4 lxml # HTML splitters
pip install nltk spacy          # sentence splitters

2.5 Verify the installation

langchain-core ships a system report you can paste into bug reports:

python -m langchain_core.sys_info

System Information
------------------
> OS:  Linux
> OS Version:  ...
> Python Version:  3.12.x

Package Information
-------------------
> langchain_core: 1.6.6
> langchain: 1.4.3
> langsmith: 0.x
> langchain_openai: 1.6.6
> langgraph: 1.2.x
...

Tip

print_sys_info(additional_pkgs=[...]) is also importable from langchain_core.sys_info if you want to include extra packages in the report.

2.6 Upgrading from LangChain 0.x

LangChain 1.0 moved legacy functionality into langchain-classic. If an old import stops working, it has usually moved:

pip install -U langchain-classic

Warning

langchain-classic receives no new features. Its README says: "In most cases, you should be using the main langchain package."

3. Configuration Basics

LangChain reads no config file. You configure it in three places: environment variables (mostly credentials), constructor arguments on models and middleware, and the per-call config dict. The exhaustive reference is in the Admin Guide, Section 4.

3.1 Environment Variables

Provider packages read their credentials from the environment when you do not pass api_key=...:

Framework-level variables:

Caution

Setting LANGCHAIN_TRACING or LANGCHAIN_HANDLER (the old v1 tracer variables) now raises RuntimeError: Tracing using LangChainTracerV1 is no longer supported.... Unset them and use LANGSMITH_TRACING.

Warning

ChatOllama does not read OLLAMA_HOST. Pass base_url="http://host:11434" explicitly if your Ollama server is not at the SDK's default address.

3.2 Choosing a model with a string

Everything that accepts a model (create_agent, ModelFallbackMiddleware, SummarizationMiddleware, …) accepts either a chat model object or a "provider:model" string. Strings are resolved by init_chat_model:

from langchain.chat_models import init_chat_model

gpt = init_chat_model("openai:gpt-5.5", temperature=0)
claude = init_chat_model("anthropic:claude-sonnet-4-5-20250929", max_tokens=1024)
local = init_chat_model("ollama:llama3.1", base_url="http://localhost:11434")

Any extra keyword argument is passed to the provider class constructor, so temperature, max_tokens, timeout, max_retries, base_url and rate_limiter all work.

Tip

Prefer the prefixed form ("anthropic:..."). A bare name such as "claude-opus-4-7" also works because the provider is inferred from the prefix, but inference is best-effort (see Section 10.2 for the exact rules), and names like o4-mini are not inferred.

3.3 Per-call configuration

Every invoke, stream and batch call accepts a config dict (RunnableConfig):

config = {"configurable": {"thread_id": "session-1"}, "tags": ["prod"], "metadata": {"user": "u-17"}}
agent.invoke({"messages": [{"role": "user", "content": "hi"}]}, config)

Note

RunnableConfig has no timeout key. Unknown top-level keys are silently moved into configurable. Set timeouts on the model (timeout= / request_timeout=).

4. Everyday Usage

4.1 Talking to a chat model

Every chat model implements the same Runnable interface: invoke, stream, batch and their async versions ainvoke, astream, abatch.

Inputs can be a string, a list of messages, or message-like dicts and tuples:

from langchain.messages import HumanMessage, SystemMessage

model.invoke("What is 2 + 2?")
model.invoke([SystemMessage("Answer tersely."), HumanMessage("What is 2 + 2?")])
model.invoke([{"role": "system", "content": "Answer tersely."}, {"role": "user", "content": "What is 2 + 2?"}])
model.invoke([("system", "Answer tersely."), ("human", "What is 2 + 2?")])

Accepted role strings: human/user, ai/assistant, system, developer (becomes a SystemMessage flagged for OpenAI's developer role), tool, function and remove.

Outputs are AIMessage objects:

msg = model.invoke("Name one planet.")
print(msg.text)             # plain text of the reply
print(msg.content_blocks)   # standardized content blocks
print(msg.usage_metadata)   # token usage
print(msg.response_metadata.get("model_name"))

Mars.
[{'type': 'text', 'text': 'Mars.'}]
{'input_tokens': 11, 'output_tokens': 3, 'total_tokens': 14}
gpt-5.5

Note

Use .text as a property. Calling .text() as a method is deprecated since 1.0.0 and will be removed in 2.0.0.

Streaming yields AIMessageChunk objects that you can add together:

full = None
for chunk in model.stream("Write a haiku about rivers."):
    print(chunk.text, end="", flush=True)
    full = chunk if full is None else full + chunk
print()
print(full.usage_metadata)

Silver threads descend
carving patience into stone
the sea waits below
{'input_tokens': 14, 'output_tokens': 18, 'total_tokens': 32}

Batching runs many inputs in a thread pool:

answers = model.batch(["Capital of France?", "Capital of Japan?"], config={"max_concurrency": 4})
print([a.text for a in answers])

['Paris.', 'Tokyo.']

Tip

Use return_exceptions=True in batch to get exceptions back in place of results instead of failing the whole batch. It catches Exception subclasses only.

Note

If a provider class does not implement token streaming, stream() still works — it falls back to invoke() and yields one chunk.

4.2 Building an agent

create_agent returns a compiled LangGraph graph that calls the model, runs any tool calls, feeds results back and repeats until the model answers without tool calls.

from langchain.agents import create_agent

agent = create_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    tools=[get_weather],
    system_prompt="You are a concise travel assistant.",
    name="travel_agent",
)

The key parameters (full list in Section 10.3):

Invoking. The input is a dict with a messages list; the output is the final state:

state = agent.invoke({"messages": [{"role": "user", "content": "Weather in Rome?"}]})
for m in state["messages"]:
    print(type(m).__name__, "->", m.text or m.tool_calls)

HumanMessage -> Weather in Rome?
AIMessage -> [{'name': 'get_weather', 'args': {'city': 'Rome'}, 'id': 'toolu_01...', 'type': 'tool_call'}]
ToolMessage -> It's always sunny in Rome!
AIMessage -> It's sunny in Rome right now.

Streaming an agent. The compiled graph supports LangGraph stream modes. The two most useful:

# Node-by-node progress
for update in agent.stream({"messages": [{"role": "user", "content": "Weather in Oslo?"}]}, stream_mode="updates"):
    print(update)

# Token-by-token model output
for token, metadata in agent.stream({"messages": [{"role": "user", "content": "Weather in Oslo?"}]}, stream_mode="messages"):
    print(token.text, end="")

{'model': {'messages': [AIMessage(content='', tool_calls=[{'name': 'get_weather', ...}])]}}
{'tools': {'messages': [ToolMessage(content="It's always sunny in Oslo!", ...)]}}
{'model': {'messages': [AIMessage(content="It's sunny in Oslo.")]}}

Tip

Middleware can emit your own progress events with runtime.stream_writer({...}); receive them with stream_mode="custom".

Note

The agent graph's recursion_limit is set to 9,999 by create_agent, so long tool loops are not cut off at LangGraph's usual limit. Use ModelCallLimitMiddleware or ToolCallLimitMiddleware to cap loops deliberately.

4.3 Defining tools

Plain functions work directly — the name comes from the function, the description from the docstring, the schema from type hints. For more control use the @tool decorator:

from typing import Annotated
from langchain.tools import tool


@tool(parse_docstring=True)
def search_orders(customer_id: str, limit: int = 5) -> str:
    """Look up recent orders for a customer.

    Args:
        customer_id: The customer's ID, e.g. "C-1001".
        limit: Maximum number of orders to return.
    """
    return f"{limit} orders for {customer_id}"


print(search_orders.name, search_orders.args)

search_orders {'customer_id': {'description': 'The customer\'s ID, e.g. "C-1001".', 'title': 'Customer Id', 'type': 'string'}, 'limit': {'default': 5, 'description': 'Maximum number of orders to return.', 'title': 'Limit', 'type': 'integer'}}

@tool options:

Warning

Do not name tool arguments config, run_manager or callbacks. config is shadowed by the injected RunnableConfig, and run_manager/callbacks are silently removed from the schema.

Injected arguments are supplied by the framework and hidden from the model:

from typing import Annotated
from langchain.tools import tool, ToolRuntime, InjectedToolCallId


@tool
def whoami(runtime: ToolRuntime) -> str:
    """Report who the current user is."""
    return f"user={runtime.context['user_id']}, messages so far={len(runtime.state['messages'])}"


@tool
def echo_id(text: str, tool_call_id: Annotated[str, InjectedToolCallId]) -> str:
    """Echo text with the calling tool-call ID."""
    return f"{text} ({tool_call_id})"

ToolRuntime (re-exported by langchain.tools from LangGraph) gives a tool access to state, context, config, store, stream_writer and tool_call_id.

Errors inside tools. Raise ToolException to report a failure the model can react to, and set handle_tool_error on the tool:

from langchain.tools import ToolException, tool


@tool
def divide(a: float, b: float) -> float:
    """Divide a by b."""
    if b == 0:
        raise ToolException("Cannot divide by zero; ask the user for a non-zero divisor.")
    return a / b


divide.handle_tool_error = True  # the exception message becomes the ToolMessage content

Tip

For agent-wide policies (retry flaky tools, convert only certain exceptions to messages) use ToolRetryMiddleware and ToolErrorMiddleware instead of per-tool settings — see Section 6.1.

Provider-native tools (web search, code execution, etc.) are passed as dicts and executed by the provider, not locally:

agent = create_agent("openai:gpt-5.5", tools=[{"type": "web_search"}, get_weather])

4.4 Getting structured output

From a model — with_structured_output returns a runnable that produces your schema:

from pydantic import BaseModel, Field


class Movie(BaseModel):
    """A movie recommendation."""
    title: str
    year: int = Field(description="Release year")


structured = init_chat_model("openai:gpt-5.5").with_structured_output(Movie)
print(structured.invoke("Recommend one classic sci-fi film."))

title='Blade Runner' year=1982

Pass include_raw=True to get {"raw": AIMessage, "parsed": Movie | None, "parsing_error": Exception | None} instead of raising on parse failures.

From an agent — pass response_format to create_agent; the parsed object appears in result["structured_response"]:

agent = create_agent("openai:gpt-5.5", tools=[get_weather], response_format=Movie)
result = agent.invoke({"messages": [{"role": "user", "content": "Recommend a film set in Paris."}]})
print(result["structured_response"])

title='Midnight in Paris' year=2011

How the strategy is chosen:

from langchain.agents.structured_output import ToolStrategy, ProviderStrategy

agent = create_agent("openai:gpt-5.5", tools=[], response_format=ToolStrategy(Movie, handle_errors=True))

Tip

ToolStrategy accepts a union of schemas (ToolStrategy(Movie | Book)); the model picks one. If it calls two at once you get MultipleStructuredOutputsError, which handle_errors=True turns into a retry.

4.5 Conversation memory

An agent remembers a conversation only when it has a checkpointer and you reuse the same thread_id:

from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent("openai:gpt-5.5", tools=[get_weather], checkpointer=InMemorySaver())
cfg = {"configurable": {"thread_id": "alice"}}

agent.invoke({"messages": [{"role": "user", "content": "My name is Alice."}]}, cfg)
reply = agent.invoke({"messages": [{"role": "user", "content": "What's my name?"}]}, cfg)
print(reply["messages"][-1].text)

Your name is Alice.

Important

InMemorySaver loses everything when the process exits. For durable memory use a persistent LangGraph checkpointer (for example a Postgres or SQLite saver from the LangGraph ecosystem).

Keeping the context window under control:

from langchain.agents.middleware import SummarizationMiddleware

agent = create_agent(
    "openai:gpt-5.5",
    tools=[get_weather],
    checkpointer=InMemorySaver(),
    middleware=[SummarizationMiddleware("openai:gpt-5.4-mini", trigger=("tokens", 4000), keep=("messages", 20))],
)

Warning

SummarizationMiddleware has no default trigger. If you omit trigger, it never summarizes. Always set one, e.g. trigger=("tokens", 4000) or trigger=[("fraction", 0.8), ("messages", 100)].

4.6 Prompts, chains and parsers

For deterministic pipelines that do not need an agent loop, compose components with the | operator (LangChain Expression Language):

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "You translate English to {language}."),
    ("human", "{text}"),
])
chain = prompt | init_chat_model("openai:gpt-5.5") | StrOutputParser()
print(chain.invoke({"language": "French", "text": "Good morning"}))

Bonjour

Caution

Never accept jinja2 templates from untrusted users. The docs in the source state that jinja2 sandboxing "should be treated as a best-effort approach rather than a guarantee of security". Prefer f-string or mustache.

4.7 Embeddings, text splitting and retrieval

from langchain.embeddings import init_embeddings
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter

embeddings = init_embeddings("openai:text-embedding-3-small")

splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
chunks = splitter.split_documents([Document(page_content=open("handbook.txt").read(), metadata={"source": "handbook"})])

store = InMemoryVectorStore(embeddings)
store.add_documents(chunks)
for doc in store.similarity_search("vacation policy", k=2):
    print(doc.metadata["source"], doc.page_content[:60])

handbook Employees accrue 1.5 days of paid vacation per month...
handbook Vacation requests must be submitted two weeks in advance...

init_embeddings requires the provider:model form (or provider=) and supports these providers: openai, azure_openai, azure_ai, bedrock, cohere, google_genai, google_vertexai, huggingface, mistralai, ollama.

Turn the store into a retriever and then into a tool an agent can call:

from langchain_core.tools import create_retriever_tool

retriever = store.as_retriever(search_type="mmr", search_kwargs={"k": 4, "fetch_k": 20})
handbook_tool = create_retriever_tool(retriever, "search_handbook", "Search the employee handbook.")
agent = create_agent("openai:gpt-5.5", tools=[handbook_tool])

Note

InMemoryVectorStore filters are Python callables (filter=lambda doc: doc.metadata["source"] == "handbook"), not metadata dicts. It needs numpy for similarity math, and can be saved with store.dump(path) and reloaded with InMemoryVectorStore.load(path, embeddings).

5. Common Workflows

Each recipe is complete and runnable once the named provider package is installed and its API key is set.

5.1 A support agent with memory and per-user context

from dataclasses import dataclass

from langchain.agents import create_agent
from langchain.agents.middleware import dynamic_prompt, ModelRequest
from langchain.tools import tool, ToolRuntime
from langgraph.checkpoint.memory import InMemorySaver


@dataclass
class UserContext:
    user_id: str
    plan: str


@tool
def account_status(runtime: ToolRuntime) -> str:
    """Return the caller's account status."""
    ctx = runtime.context
    return f"User {ctx.user_id} is on the {ctx.plan} plan and in good standing."


@dynamic_prompt
def plan_aware_prompt(request: ModelRequest) -> str:
    return f"You are a support agent. The customer is on the {request.runtime.context.plan} plan."


agent = create_agent(
    "openai:gpt-5.5",
    tools=[account_status],
    middleware=[plan_aware_prompt],
    context_schema=UserContext,
    checkpointer=InMemorySaver(),
)

cfg = {"configurable": {"thread_id": "ticket-881"}}
ctx = UserContext(user_id="u-17", plan="Pro")
out = agent.invoke({"messages": [{"role": "user", "content": "Is my account OK?"}]}, cfg, context=ctx)
print(out["messages"][-1].text)

Yes — your account (u-17) is on the Pro plan and in good standing.

Tip

Context is per-run, read-only information you supply (context=). State is the conversation data the graph accumulates and the checkpointer saves. Keep secrets and user identity in context, not in the prompt.

5.2 Human approval before risky tool calls

HumanInTheLoopMiddleware pauses the run with a LangGraph interrupt whenever the model calls a gated tool. Resuming requires a checkpointer.

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langchain.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command


@tool
def delete_file(path: str) -> str:
    """Delete a file."""
    return f"Deleted {path}"


@tool
def read_file(path: str) -> str:
    """Read a file."""
    return f"Contents of {path}"


agent = create_agent(
    "openai:gpt-5.5",
    tools=[delete_file, read_file],
    middleware=[HumanInTheLoopMiddleware(interrupt_on={
        "delete_file": {"allowed_decisions": ["approve", "edit", "reject"]},
        "read_file": False,  # auto-approved
    })],
    checkpointer=InMemorySaver(),
)
cfg = {"configurable": {"thread_id": "cleanup-1"}}

paused = agent.invoke({"messages": [{"role": "user", "content": "Delete report.md"}]}, cfg)
[interrupt] = paused["__interrupt__"]
print(interrupt.value["action_requests"][0]["description"])

final = agent.invoke(Command(resume={"decisions": [{"type": "approve"}]}), cfg)
print(final["messages"][-1].text)

Tool execution requires approval

Tool: delete_file
Args: {'path': 'report.md'}
I've deleted report.md.

Decision types you can send back, one per interrupted tool call and in the same order:

Important

The number of decisions must equal the number of interrupted tool calls, or you get ValueError: Number of human decisions (...) does not match number of hanging tool calls (...).

Tip

Use InterruptOnConfig(allowed_decisions=[...], description=callable, when=predicate) to build custom approval prompts and to interrupt only some calls (for example only when args["amount"] > 1000). The description callable receives (tool_call, state, runtime).

5.3 Giving an agent tools from MCP servers

import asyncio

from langchain.agents import create_agent
from langchain.mcp import MCPAdapter


async def main() -> None:
    async with MCPAdapter("https://example.com/mcp") as adapter:
        tools = await adapter.list_tools()
    agent = create_agent("anthropic:claude-sonnet-4-5-20250929", tools)
    result = await agent.ainvoke({"messages": [{"role": "user", "content": "What can you do?"}]})
    print(result["messages"][-1].text)


asyncio.run(main())

Several servers behind one adapter, mixing transports:

import sys

config = {
    "mcpServers": {
        "weather": {"command": sys.executable, "args": ["weather_server.py"]},
        "docs": {"url": "https://docs.example.com/mcp"},
    }
}
async with MCPAdapter(config) as adapter:
    tools = await adapter.list_tools()   # names are prefixed per server

Warning

langchain.mcp is beta. Importing it emits LangChainBetaWarning: langchain.mcp is in beta.... Silence it with warnings.filterwarnings("ignore", category=LangChainBetaWarning). MCP tools are async-only, so call the agent with ainvoke/astream.

Note

MCP tools that fail on the server reach the model as an error ToolMessage so it can retry. When a server asks the user a question mid-call (MCP elicitation), the run pauses with an interrupt of type mcp_elicitation; resume with Command(resume={"responses": {request_key: {"action": "accept", "content": {...}}}}). This also needs a checkpointer.

5.4 Retrieval-augmented agent

from langchain.agents import create_agent
from langchain.embeddings import init_embeddings
from langchain_core.documents import Document
from langchain_core.tools import create_retriever_tool
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_text_splitters import RecursiveCharacterTextSplitter

docs = [Document(page_content=open(p).read(), metadata={"source": p}) for p in ["faq.md", "pricing.md"]]
chunks = RecursiveCharacterTextSplitter(chunk_size=800, chunk_overlap=100).split_documents(docs)

store = InMemoryVectorStore(init_embeddings("openai:text-embedding-3-small"))
store.add_documents(chunks)

kb = create_retriever_tool(
    store.as_retriever(search_kwargs={"k": 4}),
    name="search_kb",
    description="Search the product FAQ and pricing pages.",
)
agent = create_agent("openai:gpt-5.5", tools=[kb], system_prompt="Answer only from search_kb results; cite the source.")
print(agent.invoke({"messages": [{"role": "user", "content": "Is there a student discount?"}]})["messages"][-1].text)

Yes — students get 50% off the Pro plan (source: pricing.md).

Tip

For a persistent store swap InMemoryVectorStore for langchain_chroma.Chroma(collection_name="kb", embedding_function=..., persist_directory="./chroma") or langchain_qdrant.QdrantVectorStore.

5.5 Guardrails: PII redaction and call limits

from langchain.agents import create_agent
from langchain.agents.middleware import (
    ModelCallLimitMiddleware,
    PIIMiddleware,
    ToolCallLimitMiddleware,
)

agent = create_agent(
    "openai:gpt-5.5",
    tools=[search_orders],
    middleware=[
        PIIMiddleware("email", strategy="redact"),                          # user input
        PIIMiddleware("credit_card", strategy="mask", apply_to_output=True),
        PIIMiddleware("api_key", detector=r"sk-[a-zA-Z0-9]{32}", strategy="block"),
        ModelCallLimitMiddleware(run_limit=10, exit_behavior="end"),
        ToolCallLimitMiddleware(tool_name="search_orders", run_limit=3),
    ],
)

Built-in detectors: email, credit_card (Luhn-validated), ip, mac_address, url. Anything else needs detector= (a regex string or a function returning PIIMatch dicts).

Note

PIIMiddleware checks user input by default (apply_to_input=True). Set apply_to_output=True to also scrub AI messages — this additionally installs a stream transformer so streamed tokens and tool events are redacted in flight — and apply_to_tool_results=True to scrub tool outputs.

5.6 Resilience: retries and model fallback

from langchain.agents.middleware import ModelFallbackMiddleware, ModelRetryMiddleware, ToolRetryMiddleware

agent = create_agent(
    "openai:gpt-5.5",
    tools=[search_orders],
    middleware=[
        ModelFallbackMiddleware("anthropic:claude-sonnet-4-5-20250929", "ollama:llama3.1"),
        ModelRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
        ToolRetryMiddleware(max_retries=2, tools=["search_orders"], on_failure="continue"),
    ],
)

Retry delay is initial_delay * backoff_factor ** retry_number, capped at max_delay (default 60 s), with ±25% jitter by default. After retries are exhausted, on_failure="continue" returns an error message to the model (AIMessage for model retries, ToolMessage for tool retries), "error" re-raises, and a callable lets you format the message.

Important

Middleware order matters: the first middleware in the list is the outermost wrapper. Above, a failing model call is retried 3 times by ModelRetryMiddleware before ModelFallbackMiddleware moves on to the next model.

Warning

By default ToolRetryMiddleware retries any exception (GitHub issue #40688 notes this can repeat non-idempotent tool calls after ambiguous transport errors). For tools that change data, pass retry_on=(TimeoutError, ConnectionError) or restrict with tools=[...].

5.7 Switching models at runtime

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.5", configurable_fields=("model", "model_provider", "temperature"), temperature=0)

model.invoke("hi")  # uses gpt-5.5
model.invoke("hi", config={"configurable": {"model": "anthropic:claude-sonnet-4-5-20250929", "temperature": 0.7}})

With config_prefix="writer", the keys become writer_model, writer_temperature and so on, which lets two configurable models live in one app.

Caution

configurable_fields="any" lets callers change api_key and base_url at runtime, potentially redirecting requests to another service. When config comes from untrusted input, list the allowed fields explicitly.

5.8 Planning long tasks with a todo list

from langchain.agents.middleware import TodoListMiddleware

agent = create_agent("openai:gpt-5.5", tools=[read_file], middleware=[TodoListMiddleware()])
result = agent.invoke({"messages": [{"role": "user", "content": "Review these five files and summarize risks."}]})
print(result["todos"])

[{'content': 'Read file 1', 'status': 'completed'}, {'content': 'Read file 2', 'status': 'in_progress'}, ...]

The middleware adds a write_todos tool plus a system-prompt section explaining when to use it, stores the list in state under todos, and allows at most one write_todos call per model turn.

6. Advanced Usage

6.1 Plugins & Extensions: the middleware catalog

Middleware is LangChain's extension mechanism for agents. Everything below is importable from langchain.agents.middleware.

Provider packages ship more middleware:

Warning

Some docstring examples inside langchain_anthropic.middleware import names such as StateTextEditorToolMiddleware from langchain.agents.middleware. Those names do not exist — use the Claude* classes from langchain_anthropic.middleware listed above.

6.2 Writing your own middleware

With decorators — the quickest way:

from typing import Any

from langchain.agents import AgentState, create_agent
from langchain.agents.middleware import after_model, before_model, wrap_model_call, wrap_tool_call
from langchain.chat_models import init_chat_model
from langgraph.runtime import Runtime


@before_model
def log_size(state: AgentState, runtime: Runtime) -> None:
    print(f"calling model with {len(state['messages'])} messages")


@before_model(can_jump_to=["end"])
def stop_on_bye(state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
    if state["messages"][-1].text.strip().lower() == "bye":
        return {"jump_to": "end"}
    return None


@wrap_model_call
def cheaper_model_for_short_chats(request, handler):
    if len(request.messages) < 4:
        request = request.override(model=init_chat_model("openai:gpt-5.4-mini"))
    return handler(request)


@wrap_tool_call
def audit_tools(request, handler):
    print("tool:", request.tool_call["name"], request.tool_call["args"])
    return handler(request)


agent = create_agent("openai:gpt-5.5", tools=[get_weather],
                     middleware=[log_size, stop_on_bye, cheaper_model_for_short_chats, audit_tools])

With a class — when you need configuration, state or several hooks:

from typing import Any
from langchain.agents.middleware import AgentMiddleware, AgentState, hook_config


class MaxTurns(AgentMiddleware):
    def __init__(self, limit: int) -> None:
        super().__init__()
        self.limit = limit

    @hook_config(can_jump_to=["end"])
    def after_model(self, state: AgentState, runtime) -> dict[str, Any] | None:
        ai_turns = sum(1 for m in state["messages"] if m.type == "ai")
        return {"jump_to": "end"} if ai_turns >= self.limit else None

Important

A class that defines only the sync wrap_model_call/wrap_tool_call fails when the agent runs async (ainvoke/astream), and vice versa, with NotImplementedError: Asynchronous implementation of awrap_model_call is not available.... Decorators on a plain function handle both paths for you; for classes, implement both methods or run the agent in the matching mode.

Use request.override(model=..., system_message=..., messages=..., tools=..., tool_choice=..., response_format=..., model_settings=...) to change a model request. Assigning attributes directly (request.model = ...) still works but emits a DeprecationWarning.

Tip

To add custom state fields, give the middleware a state_schema that subclasses AgentState. Fields annotated with PrivateStateAttr/OmitFromInput are hidden from the agent's input and/or output schema. Each middleware instance must have a unique name (the class name by default) — duplicates raise AssertionError: Please remove duplicate middleware instances.

6.3 Running shell commands safely

from langchain.agents.middleware import DockerExecutionPolicy, RedactionRule, ShellToolMiddleware

shell = ShellToolMiddleware(
    workspace_root="./workspace",
    execution_policy=DockerExecutionPolicy(image="python:3.12-alpine3.19", network_enabled=False, read_only_rootfs=True),
    redaction_rules=[RedactionRule(pii_type="email", strategy="redact")],
)
agent = create_agent("openai:gpt-5.5", middleware=[shell])

Caution

With HostExecutionPolicy the agent can modify anything the Python process user can reach. Redaction rules are applied after execution and do not prevent exfiltration.

6.4 Tracing and observability

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="lsv2_..."
export LANGSMITH_PROJECT="my-agent"

Every model call, tool call and middleware hook is then traced. To trim sensitive payloads from middleware spans:

from langchain.agents.middleware import TracePolicy, configure_trace_policy, omit_payload

configure_trace_policy(TracePolicy(process_inputs=omit_payload))  # process-wide default

For local debugging without LangSmith:

from langchain_core.globals import set_debug, set_verbose

set_debug(True)     # prints every run start/end with inputs and outputs
set_verbose(True)   # lighter console output

Token accounting across calls:

from langchain_core.callbacks import get_usage_metadata_callback

with get_usage_metadata_callback() as cb:
    agent.invoke({"messages": [{"role": "user", "content": "Weather in Lima?"}]})
print(cb.usage_metadata)

{'gpt-5.5': {'input_tokens': 312, 'output_tokens': 41, 'total_tokens': 353}}

6.5 Rate limiting and caching

from langchain_core.rate_limiters import InMemoryRateLimiter
from langchain_core.caches import InMemoryCache
from langchain_core.globals import set_llm_cache

limiter = InMemoryRateLimiter(requests_per_second=2, check_every_n_seconds=0.1, max_bucket_size=5)
model = init_chat_model("openai:gpt-5.5", rate_limiter=limiter)

set_llm_cache(InMemoryCache(maxsize=1000))   # identical prompts are answered from memory

Note

InMemoryRateLimiter limits requests per process only (not tokens), and its bucket starts empty, so the very first call waits briefly. InMemoryCache evicts the oldest inserted entry (not least-recently-used) and has no TTL. Cache hits skip the rate limiter, and caching does not apply to streaming calls.

6.6 Streaming events from any runnable

async for event in chain.astream_events({"language": "German", "text": "Thanks"}, version="v2"):
    if event["event"] == "on_chat_model_stream":
        print(event["data"]["chunk"].text, end="")

v2 event names follow on_{chat_model|llm|chain|tool|retriever|prompt}_{start|stream|end}, plus on_tool_error and on_custom_event. There are no on_chain_error or on_llm_error events — errors surface as raised exceptions. version="v1" and astream_log are deprecated (removal in 2.0.0); version="v3" is a beta protocol supported only on chat models and compiled graphs.

6.7 Standard content blocks

Set output_version="v1" (or LC_OUTPUT_VERSION=v1) to store provider-independent content blocks in message.content. Regardless of that setting, message.content_blocks always gives the standardized view:

msg = init_chat_model("anthropic:claude-sonnet-4-5-20250929", output_version="v1").invoke("Think, then answer: 17*3?")
for block in msg.content_blocks:
    print(block["type"])

reasoning
text

Block types: text, reasoning, image, audio, video, file, text-plain, tool_call, tool_call_chunk, invalid_tool_call, server_tool_call, server_tool_call_chunk, server_tool_result, non_standard. Build input blocks with helpers such as create_image_block(url=...) from langchain_core.messages.content.

7. How It Works

7.1 The package layers

 your application
        │
        ▼
 langchain (1.4.3) ── create_agent · middleware · init_chat_model · init_embeddings · langchain.mcp
        │                     │
        │                     └── builds a LangGraph StateGraph (langgraph 1.2.x)
        ▼
 langchain-core (1.6.6) ── Runnable protocol · messages · tools · prompts · parsers · callbacks
        ▲
        │ implement core interfaces
 langchain-openai · langchain-anthropic · langchain-ollama · ... (provider packages)

langchain-core defines interfaces and ships no third-party integrations. Provider packages subclass those interfaces (BaseChatModel, Embeddings, VectorStore, …). langchain adds the agent runtime on top. Because every chat model has the same interface, swapping providers is a one-string change.

7.2 The agent loop

create_agent compiles a graph shaped like this:

START → [before_agent hooks] → [before_model hooks] → model → [after_model hooks] ─┐
            (once)                    ▲                                             │
                                      │   tool calls pending?  yes → tools ─────────┤
                                      └──────────────────────────────────────────── │
                                                                  no → [after_agent hooks] → END

1. before_agent hooks run once.
2. before_model hooks run, then the model node calls the model with the system prompt, messages and bound tools, wrapped by every wrap_model_call middleware.
3. after_model hooks run (in reverse registration order).
4. If the last AIMessage has tool calls that have no ToolMessage yet, each is sent to the tools node (in parallel), wrapped by every wrap_tool_call middleware. Then the loop returns to step 2.
5. The loop ends when the model answers without tool calls, when every executed tool had return_direct=True, when a structured-output tool succeeded, or when middleware sets jump_to: "end".
6. after_agent hooks run once.

Malformed tool calls (arguments that could not be parsed) are answered automatically with an error ToolMessage ("...arguments were malformed or truncated.") so the conversation stays valid for the provider.

7.3 How middleware composes

• Node hooks (before_*, after_*) become graph nodes named <MiddlewareName>.<hook>. A hook can return a state update, or {"jump_to": "model" | "tools" | "end"} if it declared can_jump_to.
• Wrap hooks nest like decorators: middleware=[A, B, C] executes as A(B(C(model_call))). The outer layer can call the inner handler several times (retry), skip it (cache/short-circuit), or change the request and response.
• Tools that middleware registers (via its tools attribute) are added to the agent automatically.

7.4 Messages and state

Agent state is a dict whose messages list uses LangGraph's add_messages reducer: returned messages are appended, and a message with an existing id replaces the old one. RemoveMessage(id=...) deletes a message. structured_response holds the parsed structured output, and middleware may add its own keys (such as todos).

7.5 Where model capabilities come from

Chat models carry an optional profile — a dict of capabilities such as max_input_tokens, tool_calling and structured_output, generated from models.dev data by the langchain-profiles CLI and shipped inside provider packages (data/_profiles.py). create_agent uses it to choose a structured-output strategy, and SummarizationMiddleware needs it for ("fraction", ...) thresholds. When a model has no profile, pass profile={"max_input_tokens": ...} to the model constructor.

8. Troubleshooting

Entries quote the exact message raised by the source (placeholders such as {provider} are filled in at runtime; long messages are shortened with …). They are ordered: installation and model setup → agents → tools → structured output → middleware → memory and prompts → retrieval → MCP → provider-specific. Errors that link to https://docs.langchain.com/oss/python/langchain/errors/<CODE> carry one of the codes INVALID_PROMPT_INPUT, MESSAGE_COERCION_FAILURE or OUTPUT_PARSING_FAILURE.

Error: Initializing {class_name} requires the {pkg} package. Please install it with pip install {pkg}``

Cause: init_chat_model (or create_agent with a model string) resolved a provider whose integration package is not installed. Solution: Install the package named in the message, e.g. pip install langchain-anthropic, or pip install "langchain[anthropic]". Prevention: Pin provider packages in your requirements next to langchain.

Error: Unable to infer model provider for model={model!r}. Please specify 'model_provider' directly.

Cause: The model string has no provider: prefix and its name does not start with a recognized prefix (for example o4-mini, llama3, qwen). Solution: Use the prefixed form ("openai:o4-mini", "ollama:llama3.1") or pass model_provider="...". Prevention: Always use provider:model strings; inference is best-effort.

Error: Unsupported provider={provider!r}. Supported model providers are: …

Cause: The model_provider (or prefix) is not in init_chat_model's registry. Hyphens are normalized to underscores, so google-genai works but gemini does not. Solution: Use a supported key from Section 10.1, or construct the provider's chat model class directly and pass the object. Prevention: Copy provider keys from the reference table.

Error: `model` must be a string (e.g., 'openai:gpt-5.5'), got {type}. If you've already constructed a chat model object, use it directly instead of passing it to init_chat_model().

Cause: A model object was passed to init_chat_model. Solution: Use the object directly — create_agent(model=my_chat_model). Prevention: Only pass strings to init_chat_model.

Error: Inferred model_provider='google_vertexai' from {model_name!r}. This default will change to 'google_genai' in the next major release.

Cause: A bare gemini-... name was inferred as Vertex AI (a DeprecationWarning). Solution: Use google_vertexai:gemini-... for Vertex AI or google_genai:gemini-... for the Gemini API / AI Studio. Prevention: Always prefix Gemini model names.

Error: config_prefix={config_prefix!r} has been set but no fields are configurable.

Cause: init_chat_model(..., config_prefix="x") was given a model but no configurable_fields. Solution: Add configurable_fields=("model", "temperature", ...) or remove config_prefix. Prevention: Use config_prefix only for configurable models.

Error: {name} is not a BaseChatModel attribute and is not implemented on the default model.

Cause: An attribute was accessed on a configurable model (from init_chat_model with configurable_fields) that the underlying default model does not have. Solution: Access provider attributes on a concrete model, or call only Runnable methods and bind_tools / with_structured_output on the configurable wrapper. Prevention: Treat configurable models as Runnables.

Error: Provider '{provider}' is not supported. Supported providers and their required packages: …

Cause: init_embeddings was given a provider outside its 10 supported keys. Solution: Use one of openai, azure_openai, azure_ai, bedrock, cohere, google_genai, google_vertexai, huggingface, mistralai, ollama, or instantiate the embeddings class directly. Prevention: Check Section 10.4.

Error: Invalid model format '{model_name}'. Model name must be in format 'provider:model-name'

Cause: init_embeddings("text-embedding-3-small") — unlike chat models, embeddings never infer the provider. Solution: init_embeddings("openai:text-embedding-3-small") or init_embeddings("text-embedding-3-small", provider="openai"). Prevention: Always include the provider for embeddings.

Error: Could not import {pkg} python package. Please install it with pip install {pkg}``

Cause: The embeddings provider's package is missing. Solution: Install it (e.g. pip install langchain-ollama). Prevention: Keep provider packages in your lockfile.

Error: Model name cannot be empty

Cause: An empty or whitespace-only model string was given to init_embeddings. Solution: Provide a real model name. Prevention: Validate config values before calling.

Error: Tracing using LangChainTracerV1 is no longer supported. Please set the LANGCHAIN_TRACING_V2 environment variable to enable tracing instead.

Cause: The legacy LANGCHAIN_TRACING or LANGCHAIN_HANDLER variable is set. Solution: Unset them and set LANGSMITH_TRACING=true with LANGSMITH_API_KEY. Prevention: Remove old tracing variables from .env files.

Error: Please remove duplicate middleware instances.

Cause: Two middleware in create_agent(middleware=[...]) share a name. The name defaults to the class name, so two instances of the same class collide — for example two ModelRetryMiddleware(...) with different settings. Solution: Override the name property in a subclass, or combine the configuration into one instance. Several PIIMiddleware instances are allowed as long as their PII types differ, because the name is PIIMiddleware[<pii_type>]. Prevention: Give custom middleware unique names.

Error: Middleware added tools that the agent doesn't know how to execute. Unknown tools: [...] Registered tools: [...]

Cause: A wrap_model_call middleware added tools to request.tools that were never passed to create_agent. Solution: Register the tools up front (create_agent(tools=[...]) or the middleware's tools attribute), or implement wrap_tool_call to execute dynamic tools yourself. Prevention: Middleware should filter the tool list, not invent new tools.

Error: ToolStrategy specifies tool '{name}' which wasn't declared in the original response format when creating the agent.

Cause: Middleware replaced response_format with a ToolStrategy containing a schema that was not in the original. Solution: Declare every possible schema in the original response_format (e.g. a union); middleware may only narrow it. Prevention: Treat response_format overrides as subsets.

Error: Command goto is not yet supported in wrap_model_call middleware. Use the jump_to state field with before_model/after_model hooks instead.

Cause: A wrap_model_call returned ExtendedModelResponse(command=Command(goto=...)). Solution: Use a before_model/after_model hook with can_jump_to and return {"jump_to": ...}. Prevention: Only use Command(update=...) inside wrap_model_call. (Command.resume and Command.graph are likewise rejected.)

Error: Synchronous implementation of wrap_model_call is not available. You are likely encountering this error because you defined only the async version (awrap_model_call) and invoked your agent in a synchronous context …

Cause: Your middleware class implements only awrap_model_call, but you called agent.invoke()/stream(). Solution: Implement the sync method, use the @wrap_model_call decorator on a sync function, or call ainvoke()/astream(). Prevention: Implement both sync and async hooks in reusable middleware.

Error: Asynchronous implementation of awrap_model_call is not available. …

Cause: Only the sync wrap_model_call exists, and the agent ran with ainvoke()/astream() (MCP tools force the async path). Solution: Implement awrap_model_call, or use the decorator form. Prevention: Same as above.

Error: Synchronous implementation of wrap_tool_call is not available. …

Cause: Only awrap_tool_call exists and the agent ran synchronously. Solution: Implement wrap_tool_call or run async. Prevention: Implement both.

Error: Asynchronous implementation of awrap_tool_call is not available. …

Cause: Only wrap_tool_call exists and the agent ran asynchronously. Solution: Implement awrap_tool_call or run sync. Prevention: Implement both.

Error: Direct attribute assignment to ModelRequest.{name} is deprecated. Use request.override({name}=...) instead …

Cause: Middleware mutated a ModelRequest (request.model = ...). Solution: request = request.override(model=...) and pass the new request to handler. Prevention: Treat requests as immutable.

Error: Cannot specify both system_prompt and system_message

Cause: Both were passed to ModelRequest(...) or request.override(...). Solution: Use only system_message=SystemMessage(...) (system_prompt is the deprecated form). Prevention: Prefer system_message everywhere.

Error: Recursion limit of 9999 reached without hitting a stop condition. (LangGraph GraphRecursionError)

Cause: The agent looped without ending — for example a tool that keeps failing, or middleware that keeps jumping back to the model. GitHub issue #40767 reports this with PIIMiddleware(apply_to_output=True) blanking tool-call parameters. Solution: Inspect the trace; add ModelCallLimitMiddleware(run_limit=...); if using PII output redaction on tool arguments, restrict it or use apply_to_input only. Prevention: Always cap loops in production agents.

Error: Tool call {name} with id {id} could not be executed - arguments were malformed or truncated.

Cause: Not an exception — an automatic error ToolMessage inserted when the model produced an invalid tool call (often truncated JSON because max_tokens was too low). Solution: Raise the model's max_tokens; the model normally retries. Prevention: Give tool-heavy agents generous output limits.

Error: Tool definition for {name} must include valid type annotations for argument 'args_schema' to behave as expected.

Cause: A BaseTool subclass annotated args_schema: BaseModel instead of args_schema: type[BaseModel]. Solution: Annotate as args_schema: type[BaseModel] = MyArgs. Prevention: Copy the annotation from existing tools.

Error: args_schema must be a subclass of pydantic BaseModel or a JSON schema dict. Got: …

Cause: An invalid object was passed as args_schema. Solution: Pass a Pydantic model class or a JSON-schema dict. Prevention: Validate tool definitions in unit tests.

Error: Arg {docstring_arg} in docstring not found in function signature.

Cause: @tool(parse_docstring=True) found an argument in the Args: section that the function does not have. Solution: Fix the docstring or the signature, or pass error_on_invalid_docstring=False. Prevention: Keep docstrings in sync with signatures.

Error: When tool includes an InjectedToolCallId argument, tool must always be invoked with a full model ToolCall of the form: {'args': {...}, 'name': '...', 'type': 'tool_call', 'tool_call_id': '...'}

Cause: A tool with an InjectedToolCallId parameter was called directly with plain arguments. Solution: Invoke it with a full tool-call dict: tool.invoke({"args": {...}, "name": "t", "type": "tool_call", "id": "call_1"}). Prevention: Test such tools through the agent or with tool-call dicts.

Error: String tool inputs are not allowed when using tools with JSON schema args_schema.

Cause: A tool defined with a JSON-schema dict args_schema was invoked with a string. Solution: Invoke with a dict of arguments. Prevention: Use dict inputs for structured tools.

Error: Too many arguments to single-input tool {name}. Consider using StructuredTool instead.

Cause: A single-input Tool received several arguments. Solution: Use @tool on a typed function or StructuredTool.from_function. Prevention: Avoid the legacy single-string Tool for multi-argument functions.

Error: Function and/or coroutine must be provided

Cause: StructuredTool.from_function() / Tool.from_function() was called without func or coroutine. Solution: Pass at least one of them. Prevention: Prefer the @tool decorator.

Error: The first argument must be a string or a callable with a __name__ for tool decorator.

Cause: @tool(...) was given an unexpected first argument. Solution: Use @tool, @tool("name") or @tool(description="..."). Prevention: Pass options as keywords.

Error: Tool input must be str or dict. If dict, dict arguments must be typed. Either annotate types (e.g., with TypedDict) or pass arg_types into .as_tool to specify.

Cause: runnable.as_tool() could not infer an argument schema from an untyped runnable. Solution: Pass args_schema= or arg_types={"x": int} to as_tool. Prevention: Type your runnable inputs.

Error: Failed to generate JSON schema for '{model_name}': … Tool argument schemas must be JSON-serializable.

Cause: A tool argument uses a custom Python class that Pydantic cannot express as JSON Schema. Solution: Replace it with a Pydantic model, basic types, or a string representation. Prevention: Keep tool arguments JSON-friendly.

Error: Failed to parse structured output for tool '{tool_name}': {source}. (StructuredOutputValidationError)

Cause: The model's structured-output tool call did not validate against your schema, and error handling was off (or it came from ProviderStrategy). Solution: Use ToolStrategy(schema, handle_errors=True) so the model gets the error and retries; loosen the schema; use a stronger model. Prevention: Keep schemas simple and well described with Field(description=...).

Error: Model incorrectly returned multiple structured responses ({names}) when only one is expected. (MultipleStructuredOutputsError)

Cause: With a union ToolStrategy, the model called more than one schema tool in one turn. Solution: Keep handle_errors=True (default) so the agent asks the model to correct itself. Prevention: Describe in the system prompt when each schema applies.

Error: Native structured output expected valid JSON for {schema_name}, but parsing failed: {e}.

Cause: With ProviderStrategy, the model's text was not valid JSON (often a truncated response). Solution: Increase max_tokens; switch to ToolStrategy; confirm the model supports native structured output. Prevention: Let the default auto strategy choose.

Error: Unsupported schema type: {type}. Supported types: Pydantic models, dataclasses, TypedDicts, and JSON schema dicts.

Cause: response_format was given something else (e.g. a plain class or a str). Solution: Convert the schema to one of the four supported kinds. Prevention: Use Pydantic models for structured output.

Error: with_structured_output is not implemented for this model.

Cause: The chat model class does not implement bind_tools (for example the fake test models, or a minimal custom model). Solution: Use a provider model that supports tool calling, or implement bind_tools. Prevention: Check model.profile.get("tool_calling").

Error: Received unsupported arguments {kwargs}

Cause: Extra keyword arguments were passed to the base with_structured_output of a model that does not override it (only method and strict are accepted — and ignored — there). Solution: Remove the extra arguments or use a provider model whose with_structured_output supports them. Prevention: Check the provider's signature.

Error: schema must be specified when method is not 'json_mode'. Received None.

Cause: with_structured_output(None, method=...) on OpenAI/Ollama without json_mode. Solution: Pass a schema, or use method="json_mode". Prevention: Always pass a schema.

Error: This model does not support OpenAI's structured output feature, which is the default method for with_structured_output as of langchain-openai==0.3.

Cause: An OpenAI-compatible model rejected response_format of type json_schema (a UserWarning accompanying the API error). Solution: Use with_structured_output(schema, method="function_calling"). Prevention: Choose the method explicitly for OpenAI-compatible servers.

Error: Invalid schema for OpenAI's structured output feature …

Cause: OpenAI rejected the JSON schema (strict mode forbids some constructs). Solution: Use method="function_calling" or adjust the schema (no unsupported keywords, all fields required in strict mode). Prevention: Test schemas against the provider before shipping.

Error: Invalid interrupt_onconfig for tool '{tool_name}':allowed_decisions must be a non-empty list of decision types …

Cause: A HumanInTheLoopMiddleware entry was a dict without a non-empty allowed_decisions (often a typo such as allowed_decision). Solution: Use {"allowed_decisions": ["approve", "reject"]}, or True for all decisions. Prevention: Build entries with InterruptOnConfig(...) for type checking.

Error: Number of human decisions ({n}) does not match number of hanging tool calls ({m}).

Cause: The Command(resume={"decisions": [...]}) list length differs from len(interrupt.value["action_requests"]). Solution: Send exactly one decision per action request, in order. Prevention: Build decisions by iterating over action_requests.

Error: Unexpected human decision: {decision}. Decision type '{type}' is not allowed for tool '{tool}'. Expected one of {allowed_decisions} based on the tool's configuration.

Cause: The reviewer sent a decision type (e.g. edit) not allowed for that tool. Solution: Offer reviewers only the review_configs[i]["allowed_decisions"] options. Prevention: Drive your approval UI from review_configs.

Error: Reviewer edited tool call {id!r} to {name!r}, which is not an available tool. Available tools: {names}.

Cause: An edit decision named a tool the agent does not have. Solution: Restrict edits to registered tool names. Prevention: Validate edited actions in your UI.

Error: At least one limit must be specified (thread_limit or run_limit)

Cause: ModelCallLimitMiddleware() or ToolCallLimitMiddleware() with no limits. Solution: Pass run_limit= and/or thread_limit=. Prevention: —

Error: Invalid exit_behavior: {exit_behavior}. Must be 'end' or 'error'

Cause: ModelCallLimitMiddleware only supports "end" and "error" (not "continue"). Solution: Use one of those two values. Prevention: Note that ToolCallLimitMiddleware additionally supports "continue".

Error: run_limit ({run_limit}) cannot exceed thread_limit ({thread_limit}).

Cause: ToolCallLimitMiddleware was configured with a run limit above the thread limit. Solution: Make run_limit <= thread_limit. Prevention: —

Error: Model call limits exceeded: thread limit ({n}/{limit}) (ModelCallLimitExceededError)

Cause: ModelCallLimitMiddleware(exit_behavior="error") hit its limit. Solution: Catch the exception, or use exit_behavior="end" to finish gracefully with an explanatory AI message. Prevention: Set limits from observed usage. Thread limits persist across runs of the same thread_id.

Error: '{tool_name}' tool call limit reached: run limit exceeded ({n}/{limit} calls). (ToolCallLimitExceededError)

Cause: ToolCallLimitMiddleware(exit_behavior="error") hit its limit. Solution: Catch it or use "continue" (blocks the tool, lets the model continue) / "end". Prevention: —

Error: max_retries must be >= 0

Cause: Invalid retry configuration (siblings: initial_delay must be >= 0, max_delay must be >= 0, backoff_factor must be >= 0). Solution: Use non-negative values. Prevention: —

Error: on_failure='raise' is deprecated and will be removed in a future version. Use on_failure='error' instead.

Cause: Old ToolRetryMiddleware option (similarly 'return_message' → 'continue'). Solution: Use the new names. Prevention: —

Error: ToolErrorMiddleware requires on_errorand/oraon_error.

Cause: ToolErrorMiddleware() was created with no handler. Solution: Pass on_error=lambda exc, request: .... Prevention: —

Error: ToolErrorMiddleware has no sync on_error; run async (ainvoke/astream) or provide on_error.

Cause: Only aon_error was given but the agent runs synchronously. Solution: Add on_error or run async. Prevention: Provide both handlers for dual-mode agents.

Error: Model profile information is required to use fractional token limits, and is unavailable for the specified model.

Cause: SummarizationMiddleware uses ("fraction", x) but the model has no max_input_tokens profile. Solution: Use ("tokens", N), or construct the model with profile={"max_input_tokens": 128000}. Prevention: Prefer absolute token triggers for self-hosted models.

Error: trigger clause must specify at least one of 'tokens', 'messages', 'fraction'

Cause: An empty dict was given as a trigger clause. Related: Unsupported trigger metric: {k!r}, {k} trigger values must be integers, got {v!r}, Fractional {name} values must be between 0 and 1, got {value}., {name} thresholds must be greater than 0, got {value}. Solution: Use {"tokens": 4000}, ("messages", 50) or ("fraction", 0.8). Prevention: Keep trigger values typed correctly (ints for tokens/messages, 0–1 floats for fraction).

Error: max_tokens_before_summary is deprecated. Use trigger=('tokens', value) instead.

Cause: Old SummarizationMiddleware keyword (similarly messages_to_keep → keep=('messages', value)). Solution: Use trigger= and keep=. Prevention: —

Error: Detected {count} instance(s) of {pii_type} in text content (PIIDetectionError)

Cause: PIIMiddleware(..., strategy="block") found PII. Solution: Catch PIIDetectionError and ask the user to resubmit, or switch to redact/mask. Prevention: Use block only where refusing is acceptable.

Error: Unknown PII type: {pii_type}. Must be one of ['email', 'credit_card', 'ip', 'mac_address', 'url'] or provide a custom detector.

Cause: A custom PII type was named without a detector. Solution: Add detector=r"regex" or a function. Prevention: —

Error: LLMToolEmulator's default model ('anthropic:claude-sonnet-4-5-20250929') is deprecated and will be removed in a future release. Pass model explicitly instead.

Cause: LLMToolEmulator() without model=. Solution: Pass model="openai:gpt-5.4-mini" or any model. Prevention: Always pass models explicitly to middleware.

Error: LLMToolEmulator's default model requires langchain-anthropic to be installed.

Cause: The implicit default model needs the Anthropic package. Solution: Pass model= or install langchain-anthropic. Prevention: Same as above.

Error: Tools in always_include not found in request: {missing}. Available tools: {names}

Cause: LLMToolSelectorMiddleware(always_include=[...]) named a tool the agent does not have. Solution: Fix the names. Prevention: Derive the list from your tools: [t.name for t in tools].

Error: LLMToolSelectorMiddleware: selection model returned a malformed response after {n} retries (expected a dict with a 'tools' list): …

Cause: The selector model did not return structured output. Solution: Use a model that supports structured output, raise max_retries, or set on_parsing_failure="all" / "none" / a fallback list. Prevention: Use a capable selector model.

Error: Model selected invalid tools: {names}

Cause: The selector model returned tool names that do not exist. Solution: Improve tool descriptions or use a stronger selector model. Prevention: Keep tool names short and distinct.

Error: ProviderToolSearchMiddleware could not determine the provider for model {name!r}; server-side tool search supports: anthropic, openai

Cause: Tools were deferred but the model is not an Anthropic or OpenAI model (GitHub issue #40876 reported this for ChatAnthropicBedrock). Solution: Use a supported provider, or remove ProviderToolSearchMiddleware. Prevention: Use LLMToolSelectorMiddleware for provider-independent tool filtering.

Error: ProviderToolSearchMiddleware: searchable_tools references tool(s) not bound to the model: {names}

Cause: searchable_tools lists tools not passed to the agent. Solution: Pass those tools to create_agent. Prevention: —

Error: Path traversal not allowed

Cause: A file-search (or Claude text-editor) tool call used .. or ~ in a path. Solution: None needed — this is a safety check; the model gets the error. Prevention: Tell the model paths are relative to the workspace root.

Error: Shell tool requires either 'command' or 'restart'.

Cause: The model called the shell tool with neither argument (or both: Specify only one of 'command' or 'restart'.). Solution: Usually self-corrects; improve tool_description if frequent. Prevention: —

Error: Startup command '{command}' failed with exit code {code}

Cause: One of ShellToolMiddleware(startup_commands=...) failed. Solution: Run the command manually in the same environment and fix it. Prevention: Keep startup commands idempotent.

Error: HostExecutionPolicy cpu/memory limits require the Python 'resource' module. Either remove the limits or run on a POSIX platform.

Cause: cpu_time_seconds or memory_bytes set on Windows. Solution: Remove the limits, or use DockerExecutionPolicy. Prevention: Use Docker isolation on Windows hosts.

Error: Docker execution policy requires the 'docker' CLI to be installed and available on PATH.

Cause: DockerExecutionPolicy could not find the docker binary (similarly Codex sandbox policy requires the 'codex' CLI…). Solution: Install Docker or pass binary="/path/to/docker". Prevention: —

Error: DockerExecutionPolicy does not support cpu_time_seconds; configure CPU limits using Docker run options such as '--cpus'.

Cause: cpu_time_seconds given to the Docker policy. Solution: Use cpus="1.5" instead. Prevention: —

Error: Input to ChatPromptTemplate is missing variables {missing}. Expected: [...] Received: [...]

Cause: A prompt was invoked without all template variables. A common trigger is literal braces in the template (e.g. JSON examples). Solution: Supply the variables, or escape literal braces as {{ and }}. Prevention: Test prompts with prompt.input_variables.

Error: Cannot have an input variable named 'stop', as it is used internally, please rename.

Cause: stop is reserved. Solution: Rename the variable. Prevention: —

Error: Found overlapping input and partial variables: {names}

Cause: A variable was both partially filled and declared as input. Solution: Remove it from one of the two. Prevention: —

Error: Invalid format specifier in f-string template. Nested replacement fields are not allowed.

Cause: An f-string template contains {x:{y}}; attribute or index access ({a.b}, {a[0]}) is also rejected. Solution: Pre-compute values into plain variables. Prevention: Keep templates to simple {name} fields.

Error: Message dict must contain 'role' and 'content' keys, got {message}

Cause: A dict message lacked role or content. Solution: Use {"role": "user", "content": "..."}. Prevention: —

Error: Unexpected message type: '{type}'. Use one of 'human', 'user', 'ai', 'assistant', 'function', 'tool', 'system', or 'developer'.

Cause: An unknown role such as "chat" or "bot". Solution: Use a supported role. Prevention: Normalize roles when importing chat logs.

Error: Message as a sequence must be (role string, template)

Cause: A tuple message had the wrong length. Solution: Use two-element tuples: ("human", "hi"). Prevention: —

Error: ToolMessage content should be a string or a list of string/dicts.

Cause: A tool returned an object that could not be coerced to a string. Solution: Return a string, a list of content blocks, or use response_format="content_and_artifact" to attach the object as an artifact. Prevention: Serialize tool outputs explicitly.

Error: Using fallback GPT-2 tokenizer for token counting. Token counts may be inaccurate for non-GPT-2 models.

Cause: get_num_tokens fell back to the default GPT-2 tokenizer (requires transformers). Solution: Use a provider model with its own token counting, or count_tokens_approximately. Prevention: Use token_counter="approximate" in trim_messages.

Error: Could not import transformers python package. This is needed in order to calculate get_token_ids.

Cause: Default token counting needs transformers. Solution: pip install transformers, or use a provider-specific counter / count_tokens_approximately. Prevention: —

Error: Asked to cache, but no cache found at langchain.cache.

Cause: A model was created with cache=True but no global cache was set. Solution: Call set_llm_cache(InMemoryCache()) first. Prevention: —

Error: Invalid json output: {text} (OutputParserException)

Cause: JsonOutputParser received text that is not JSON. Solution: Prefer with_structured_output; otherwise add format instructions via parser.get_format_instructions(). Prevention: Use structured output features over text parsing.

Error: defusedxml is not installed. Please install it to use the defusedxml parser.

Cause: XMLOutputParser uses defusedxml by default. Solution: pip install defusedxml. Prevention: Do not switch to parser="xml" unless your stdlib XML is known-safe.

Error: If 'exception_key' is specified then input must be a dictionary.

Cause: with_fallbacks(..., exception_key="error") used with a non-dict input. Solution: Pass dict inputs, or drop exception_key. Prevention: Note the key is written into your input dict in place.

Error: The input to RunnablePassthrough.assign() must be a dict.

Cause: .assign() / .pick() received a non-dict. Solution: Feed a dict (e.g. start the chain with a dict of inputs). Prevention: —

Error: Expected a Runnable, callable or dict.Instead got an unsupported type: {type}

Cause: Something that is not a Runnable, function or dict was put in a | chain (for example a string or a non-dict mapping). Solution: Wrap it: RunnableLambda(fn) or a real dict. Prevention: —

Error: Recursion limit reached when invoking {runnable} with input {input}.

Cause: A RunnableLambda kept returning runnables past recursion_limit (default 25). Solution: Fix the recursion, or raise config={"recursion_limit": N}. Prevention: —

Error: astream_events(version='v3') is only supported on Runnable subclasses that implement the v3 streaming protocol (BaseChatModel, CompiledGraph).

Cause: v3 events requested on a chain. Solution: Use version="v2". Prevention: —

Error: search_type of {search_type} not allowed. Valid values are: ('similarity', 'similarity_score_threshold', 'mmr')

Cause: A typo in as_retriever(search_type=...). Solution: Use one of the three values. Prevention: —

Error: Relevance scores must be between 0 and 1, got {...}

Cause: A UserWarning from a vector store whose relevance function does not match its distance metric. Solution: Pass relevance_score_fn or use a normalized metric. Prevention: —

Error: Using SHA-1 for document hashing. SHA-1 is *not* collision-resistant …

Cause: index() uses the default key_encoder="sha1" (one-time UserWarning). Solution: Pass key_encoder="blake2b" (or sha256/sha512) and rebuild the index once. Prevention: Choose the encoder before your first indexing run.

Error: Unable to import from langchain_text_splitters. Please specify text_splitter or install langchain_text_splitters

Cause: loader.load_and_split() needs the text-splitters package. Solution: pip install -U langchain-text-splitters, or split explicitly. Prevention: Call splitter.split_documents(loader.load()) instead.

Error: chunk_size must be > 0, got {chunk_size}

Cause: Invalid splitter settings; chunk_overlap must also be ≥ 0 and ≤ chunk_size. Solution: Fix the values. Prevention: —

Error: Could not import tiktoken python package. … Please install it with pip install tiktoken.

Cause: TokenTextSplitter / from_tiktoken_encoder need tiktoken (text-splitters declares no extras). Solution: pip install tiktoken. Prevention: Install optional back ends explicitly (NLTK, spaCy, sentence-transformers, bs4, lxml).

Error: json_data must be a dict, got {type}. Top-level lists can be split by passing convert_lists=True.

Cause: RecursiveJsonSplitter.split_json received a list. Solution: Pass convert_lists=True. Prevention: —

Error: Please install FastMCP to use MCPAdapter—pip install fastmcp.

Cause: langchain.mcp imported without FastMCP. Solution: pip install "langchain[mcp]". Prevention: —

Error: MCP target {target!r} is not a valid URL. To run a local MCP server over stdio, ask for it explicitly with Path('server.py'), a fastmcp transport, or an MCPConfig …

Cause: A string that is not an http(s) URL was passed to MCPAdapter — including local script paths. Solution: Wrap local scripts in pathlib.Path(...), or use an MCPConfig dict. Prevention: This is deliberate: string targets can never launch subprocesses.

Error: MCP target {target!r} has scheme {scheme!r}, but a string target must be an http or https URL.

Cause: file:, ws: or a Windows path like C:\server.py was passed as a string. Solution: Same as above. Prevention: —

Error: Resuming the MCP tool {tool!r} needs an answer for every elicitation request, but these had none: {keys}.

Cause: The resume responses dict missed some request keys. Solution: Answer every request["key"] from the interrupt payload with accept, decline or cancel. Prevention: Iterate over interrupt.value["requests"].

Error: Elicitation answer for {key!r} has action {action!r}; expected 'accept', 'decline', or 'cancel'.

Cause: Invalid action in an elicitation answer. Solution: Use one of the three actions. Prevention: —

Error: The MCP tool {tool!r} asked for input that interrupt-based elicitation cannot answer: {kinds}. Only elicitation requests are supported.

Cause: The server asked for sampling or roots, which langchain.mcp refuses. Solution: Use a pre-built fastmcp.Client with your own handlers, or a server that does not need them. Prevention: —

Error: Converting MCP audio content to a LangChain content block is not yet supported.

Cause: An MCP tool returned audio. Solution: Have the server return a file/resource instead. Prevention: —

Error: Unknown MCP content type: {type}. This usually means the installed mcp is newer than the version this adapter supports.

Cause: Version skew between mcp/fastmcp and langchain. Solution: Upgrade langchain, or pin fastmcp to the range in langchain[mcp] (>=4.0.1,<5.0.0). Prevention: Upgrade them together.

Error: Anthropic authentication failed: no API key or authorization credentials were provided. Set the ANTHROPIC_API_KEY environment variable, pass api_key=... to ChatAnthropic, …

Cause: No Anthropic credentials. Solution: export ANTHROPIC_API_KEY=... or pass api_key=. Prevention: —

Error: Received multiple non-consecutive system messages.

Cause: Anthropic accepts system messages only at the start (or in supported mid-conversation positions). Solution: Merge system instructions into one leading SystemMessage. Prevention: Use system_prompt= on the agent rather than inserting system messages mid-conversation.

Error: A non-leading SystemMessage was moved to the top-level system field and now applies to the entire conversation.

Cause: A UserWarning from ChatAnthropic: your mid-conversation system message was hoisted. Solution: Put instructions in the leading system prompt, or use a model that supports mid-conversation system messages. Prevention: —

Error: Malformed url parameter. Must be either an image URL (https://example.com/image.jpg) or base64 encoded string (data:image/png;base64,...)

Cause: An image block for Anthropic had an invalid URL. GitHub issue #40905 notes base64 data URLs with line breaks were rejected. Solution: Use create_image_block(base64=..., mime_type="image/png") with a single-line base64 string. Prevention: Strip newlines from base64 data.

Error: Sync client is not available. This happens when an async callable was provided for the API key. Use async methods (ainvoke, astream) instead, …

Cause: ChatOpenAI(api_key=async_fn) was used synchronously. Solution: Use ainvoke/astream, or provide a string or sync callable. Prevention: —

Error: Cannot specify 'openai_proxy' if one of 'http_client'/'http_async_client' is already specified.

Cause: Both a proxy and a custom HTTP client were given. Solution: Configure the proxy on your own httpx client, or drop the custom client. Prevention: —

Error: Received response with null value for 'choices'. This can happen when using OpenAI-compatible APIs (e.g., vLLM) that return a response in an unexpected format.

Cause: An OpenAI-compatible server returned a non-standard response. Solution: Check the server's API compatibility; use a dedicated provider package if one exists. Prevention: —

Error: As of openai>=1.0.0, Azure endpoints should be specified via the azure_endpointparam notopenai_api_base(or aliasbase_url).

Cause: AzureChatOpenAI(base_url=...) without /openai in the URL, or combined with azure_deployment. Solution: Use azure_endpoint="https://<resource>.openai.azure.com/" plus azure_deployment=. Prevention: Set AZURE_OPENAI_ENDPOINT and OPENAI_API_VERSION.

Error: n must be 1 when streaming.

Cause: n > 1 combined with streaming=True (OpenAI, Azure, Groq, xAI, Fireworks, OpenRouter). Solution: Use n=1 when streaming. Prevention: —

Error: Model {model}not found in Ollama. Please pull the model (usingollama pull {model}) or specify a valid model name.

Cause: ChatOllama(..., validate_model_on_init=True) and the model is not pulled. Solution: ollama pull <model>. Prevention: —

Error: Failed to connect to Ollama. Please check that Ollama is downloaded, running and accessible. https://ollama.com/download

Cause: The Ollama server is not reachable at base_url (or the SDK default). Solution: Start Ollama; pass base_url="http://host:11434" for remote servers (OLLAMA_HOST is not read by LangChain). Prevention: —

Error: temperature must be in the range [0.0, 1.0]

Cause: ChatMistralAI restricts temperature and top_p to 0–1. Solution: Use a value in range. Prevention: —

Error: xAI API key is not set. Please set it in the xai_api_keyfield or in theXAI_API_KEY environment variable.

Cause: Missing xAI key. Similar provider messages: If using default api base, DEEPSEEK_API_KEY must be set., OPENROUTER_API_KEY must be set., You must specify an api key. … FIREWORKS_API_KEY. Solution: Set the named environment variable or pass api_key=. Prevention: —

Error: Perplexity API key not provided. Pass pplx_api_key(orapi_key) … or set the PPLX_API_KEYorPERPLEXITY_API_KEY environment variable.

Cause: Missing Perplexity key. Note ChatPerplexity itself reads only PPLX_API_KEY. Solution: Set PPLX_API_KEY. Prevention: —

Error: search_parameters (Live Search) is deprecated by xAI and is ignored.

Cause: ChatXAI(search_parameters=...). Solution: ChatXAI(model="...").bind_tools([{"type": "web_search"}]). Prevention: —

Error: Only one of 'persist_directory', 'host' and 'chroma_cloud_api_key' is allowed, but got …

Cause: Conflicting Chroma(...) connection options. Solution: Choose local persistence, a server host, or Chroma Cloud (which also needs tenant and database). Prevention: —

Error: The 'fastembed' package is not installed.

Cause: FastEmbedSparse needs pip install "langchain-qdrant[fastembed]" (Python < 3.13). Solution: Install the extra. Prevention: —

9. FAQ

Q: Which package should I import from — langchain, langchain_core or langchain_classic?

Use langchain for agents, middleware and model initialization; it re-exports the everyday types (langchain.messages, langchain.tools, langchain.chat_models, langchain.embeddings, langchain.rate_limiters). Use langchain_core for prompts, output parsers, runnables, documents, vector store interfaces and callbacks. Use langchain_classic only to keep old code running.

Q: Do I need to learn LangGraph?

No. create_agent builds and compiles the LangGraph graph for you. You will meet LangGraph concepts only for persistence (checkpointers, thread_id), interrupts (Command(resume=...)) and stream modes.

Q: Is AgentExecutor still supported?

It lives in langchain-classic and is superseded by create_agent. Classic memory classes are deprecated with create_agent as the named alternative.

Q: How do I swap OpenAI for Anthropic or a local model?

Change the model string: "openai:gpt-5.5" → "anthropic:claude-sonnet-4-5-20250929" or "ollama:llama3.1", and install the provider package. Tools, middleware and structured output keep working.

Q: Why doesn't my agent remember previous messages?

You need both a checkpointer= on create_agent and the same config={"configurable": {"thread_id": ...}} on every call.

Q: How do I stop an agent from looping forever?

Add ModelCallLimitMiddleware(run_limit=N) and/or ToolCallLimitMiddleware(run_limit=N). The graph's own recursion limit is set very high (9,999) by design.

Q: Can one agent use tools from several MCP servers?

Yes — pass an {"mcpServers": {...}} dict to one MCPAdapter; tool names are prefixed with each server's key.

Q: Does LangChain send my data anywhere besides the model provider?

Only if you enable tracing (LANGSMITH_TRACING=true), which sends run inputs and outputs to LangSmith, or configure the LangSmith gateway. Use TracePolicy(process_inputs=omit_payload) to drop payloads from middleware spans.

Q: What is the difference between context and state?

context is immutable per-run data you pass to invoke(..., context=...) and read via runtime.context. state (messages, structured_response, middleware fields) evolves during the run and is saved by the checkpointer.

Q: Why is max_tokens different on my Anthropic model than I expected?

ChatAnthropic fills max_tokens from the model's profile (max_output_tokens), falling back to 4096 when no profile exists. Set it explicitly for predictable behavior.

Q: How do I count tokens and cost across an agent run?

Wrap the call in with get_usage_metadata_callback() as cb: and read cb.usage_metadata, keyed by model name. Each AIMessage also carries usage_metadata.

Q: Can tools return images or files to the model?

Yes — return a list of content blocks (e.g. create_image_block(...)), provided the model supports image tool messages (see the profile's image_tool_message).

Q: How do I test agents without calling a real model?

Use GenericFakeChatModel(messages=iter([...])) or FakeListChatModel(responses=[...]) from langchain_core.language_models, and LLMToolEmulator to fake tool results. Note that fake models do not support with_structured_output.

Q: Is the openwiki/ folder in the repository official documentation?

It is an automatically generated code wiki. The repository's own AGENTS.md says to treat source code and tests as authoritative over it.

Q: Why am I getting deprecation warnings I did not ask for?

Importing langchain_core turns on display of LangChain's deprecation and beta warnings. Wrap code in langchain_core._api.suppress_langchain_deprecation_warning() or suppress_langchain_beta_warning() to silence them locally.

Q: Which Python versions are tested?

CI runs unit tests for langchain-core on 3.10 through 3.14 and for other packages on 3.10 and 3.14.

10. Reference

10.1 init_chat_model providers

10.2 Provider inference from bare model names

10.3 create_agent parameters

Graph node names: model, tools, and <MiddlewareName>.before_agent / .before_model / .after_model / .after_agent — use these in interrupt_before / interrupt_after.

10.4 init_embeddings providers

10.5 Public import map

10.6 CLI Reference

LangChain has no end-user command-line interface. The only console script in the monorepo is langchain-profiles, a maintainer tool from langchain-model-profiles that regenerates model capability data for provider packages.

cd libs/model-profiles
uv run langchain-profiles refresh --provider openai --data-dir ../partners/openai/langchain_openai/data

Provider: openai
Data directory: ../partners/openai/langchain_openai/data

Downloading data from https://models.dev/api.json...
Downloaded <N> providers with <M> models
Extracted <K> models for openai
Loading augmentations...
Writing to ../partners/openai/langchain_openai/data/_profiles.py...

Note

When --data-dir is outside the current directory the CLI asks Continue? (y/N):; pipe echo y | to confirm non-interactively. The refresh command fetches https://models.dev/api.json with a 30-second timeout.

10.7 Useful commands