Looking for the JS/TS version? Check out LangChain.js.
To help you ship LangChain apps to production faster, check out LangSmith. LangSmith is a unified developer platform for building, testing, and monitoring LLM applications.
uv add langchainLangChain is the easiest way to start building agents and applications powered by LLMs. With under 10 lines of code, you can connect to OpenAI, Anthropic, Google, and more. LangChain provides a pre-built agent architecture and model integrations to help you get started quickly and seamlessly incorporate LLMs into your agents and applications.
We recommend you use LangChain if you want to quickly build agents and autonomous applications. Use LangGraph, our low-level agent orchestration framework and runtime, when you have more advanced needs that require a combination of deterministic and agentic workflows, heavy customization, and carefully controlled latency.
LangChain agents are built on top of LangGraph in order to provide durable execution, streaming, human-in-the-loop, persistence, and more. (You do not need to know LangGraph for basic LangChain agent usage.)
For full documentation, see the API reference. For conceptual guides, tutorials, and examples on using LangChain, see the LangChain Docs. You can also chat with the docs using Chat LangChain.
See our Releases and Versioning policies.
As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
For detailed information on how to contribute, see the Contributing Guide.
Base class for structured output errors.
Raised when model returns multiple structured output tool calls when only one is expected.
Raised when structured output tool call arguments fail to parse according to the schema.
Use a tool calling strategy for model responses.
Use the model provider's native structured output method.
Information for tracking structured output tool metadata.
This contains all necessary information to handle structured responses generated via tool calls, including the original schema, its type clas
Information for tracking native structured output metadata.
This contains all necessary information to handle structured responses generated via native provider output, including the original schema,
Automatically select the best strategy for structured output.
Typed sync handle for a nested named-agent execution.
Surfaces on run.subagents when a nested run's lc_agent_name differs
from its parent's (i.e., a create_agent(name=...) dispatched from a too
Typed async handle for a nested named-agent execution.
Promote nested named agents into typed handles on run.subagents.
The base _TasksLifecycleBase records each namespace's lc_agent_name
(set by create_agent(name=...)) and, on every task start,
Return selected tool-execution exceptions to the model as error ToolMessages.
on_error is called for each exception raised by tool execution. Return content
(a str or a list of content blocks)
Uses an LLM to select relevant tools before calling the main model.
When an agent has many tools available, this middleware filters them down to only the most relevant ones for the user's query. This
Raise ModelRefusalError for responses containing a standard refusal block.
Add this middleware to create_agent to treat a refusal as an error instead of
a successful final answer. Model calls wit
Allow low-risk tool calls and block risky calls using a decision model.
The middleware intercepts explicitly configured tools immediately before execution
and asks a Noul question for the probabili
Middleware that automatically retries failed tool calls with configurable backoff.
Supports retrying on specific exceptions and exponential backoff.
A model available to the router and the criterion for selecting it.
Select an agent's model with a decision model's Choice answer.
The middleware classifies the latest human message once before an agent run,
stores the complete ChoiceAnswer in agent state, and us
Dictionary-based trigger specification for AND conditions.
All specified thresholds in a single TriggerClause must be met for the clause to
trigger summarization (AND semantics). When multiple clau
Summarizes conversation history when token limits are approached.
This middleware monitors message token counts and automatically summarizes older messages when a threshold is reached, preserving rec
Defer selected tools behind provider-native tool search.
Instead of sending every tool schema on every turn, this middleware marks
selected tools as deferred (via extras["defer_loading"]) and injec
Configuration contract for persistent shell sessions.
Concrete subclasses encapsulate how a shell process is launched and constrained.
Each policy documents its security guarantees and the operating
Run the shell directly on the host process.
This policy is best suited for trusted or single-tenant environments (CI jobs, developer workstations, pre-sandboxed containers) where the agent must acces
Launch the shell through the Codex CLI sandbox.
Ideal when you have the Codex CLI installed and want the additional syscall and filesystem restrictions provided by Anthropic's Seatbelt (macOS) or Lan
Run the shell inside a dedicated Docker container.
Choose this policy when commands originate from untrusted users or you require strong isolation between sessions. By default the workspace is bind-m
Agent state extension for tracking shell session resources.
Structured result from command execution.
Persistent shell session that supports sequential command execution.
Middleware that registers a persistent shell tool for agents.
The middleware exposes a single long-lived shell session. Use the execution policy to match your deployment's security posture:
Represents an individual match of sensitive data.
Raised when configured to block on detected sensitive values.
Configuration for handling a single PII type.
Resolved redaction rule ready for execution.
Middleware that automatically retries failed model calls with configurable backoff.
Supports retrying on specific exceptions and exponential backoff.
State schema for ModelCallLimitMiddleware.
Extends AgentState with model call tracking fields.
Exception raised when model call limits are exceeded.
This exception is raised when the configured exit behavior is 'error' and either
the thread or run model call limit has been exceeded.
Tracks model call counts and enforces limits.
This middleware monitors the number of model calls made during agent execution and can terminate the agent when specified limits are reached. It supports
Protocol describing a context editing strategy.
Configuration for clearing tool outputs when token limits are exceeded.
Automatically prune tool results to manage context size.
The middleware applies a sequence of edits when the total input token count exceeds configured thresholds.
Currently the ClearToolUsesEdit
Provides Glob and Grep search over filesystem files.
This middleware adds two tools that search through local filesystem:
Automatic fallback to alternative models on errors.
Retries failed model calls with alternative models in sequence until
success or all models exhausted. Primary model specified in create_agent.
Keep internal model calls out of run.messages and the raw event log.
Used by middleware that makes internal model calls and runs before built-in transformers.
For tagged events, streamed `message-
Represents an action with a name and args.
Represents an action request with a name, args, and description.
Policy for reviewing a HITL request.
Request for human feedback on a sequence of actions requested by a model.
Response when a human approves the action.
Response when a human edits the action.
Response when a human rejects the action.
Response when a human answers on behalf of the tool, skipping execution.
Used for "ask user" style tools whose real implementation is the human's response. The tool is not executed; instead, a synthe
Interrupt value raised once per gated tool call in per_call mode.
Takes the place of HITLRequest. Answer it with a single Decision, keyed by the
interrupt's ID, not a HITLResponse. The interr
Response payload for a HITLRequest.
Configuration for an action requiring human in the loop.
This is the configuration format used in the HumanInTheLoopMiddleware.__init__
method.
Pause the agent so a person can review tool calls before they run.
Each tool in interrupt_on needs a decision before it runs: approve, edit, reject,
or respond. The pause is a LangGraph interrupt
State schema for ToolCallLimitMiddleware.
Extends AgentState with tool call tracking fields.
The count fields are dictionaries mapping tool names to execution counts. This allows multiple middle
Exception raised when tool call limits are exceeded.
This exception is raised when the configured exit behavior is 'error' and either
the thread or run tool call limit has been exceeded.
Track tool call counts and enforces limits during agent execution.
This middleware monitors the number of tool calls made and can terminate or restrict execution when limits are exceeded. It supports
Detect and handle Personally Identifiable Information (PII) in conversations.
This middleware detects common PII types and applies configurable strategies to handle them. It can detect emails, credit
A single todo item with content and status.
State schema for the todo middleware.
Input schema for the write_todos tool.
Middleware that provides todo list management capabilities to agents.
This middleware adds a write_todos tool that allows agents to create and manage
structured task lists for complex multi-step op
Model request information for the agent.
Response from model execution including messages and optional structured output.
The result will usually contain a single AIMessage, but may include an additional
ToolMessage if the model used a
Model response with an optional 'Command' from 'wrap_model_call' middleware.
Use this to return a 'Command' alongside the model response from a 'wrap_model_call' handler. The command is applied as an
Annotation used to mark state attributes as omitted from input or output schemas.
State schema for the agent.
Input state schema for the agent.
Output state schema for the agent.
Base middleware class for an agent.
Subclass this and implement any of the defined methods to customize agent behavior between steps in the main agent loop.
Emulates specified tools using an LLM instead of executing them.
This middleware allows selective emulation of tools for testing purposes.
By default (when tools=None), all tools are emulated. You
A request for data matching a schema.
A request for the human to visit an address.
Interrupt payload raised while an MCP tool call waits on input.
An answer to an MCPElicitationRequest.
A refusal to answer an MCPElicitationRequest, leaving the call to go on.
A refusal that abandons the tool call rather than just the question.
Value used to resume a run interrupted by an MCP elicitation.
Artifact attached to the ToolMessage produced by an MCP tool call.
Wrapping the structured content in a TypedDict leaves room for further
MCP result fields without changing the artifact's shape.
Adapt an MCP target into LangChain tools.
MCPAdapter uses FastMCP for protocol negotiation and connection management,
then converts discovered MCP tools into asynchronous LangChain tools. The
resul
Initialize a chat model from any supported provider using a unified interface.
Two main use cases:
Creates an agent graph that calls tools in a loop until a stopping condition is met.
For more details on using create_agent,
visit the [Agents](https://docs.langchain.com/oss/python/langchain/agent
Validate retry parameters.
Return whether an exception should be retried by default.
Check if an exception should trigger a retry.
Calculate delay for a retry attempt with exponential backoff and optional jitter.
Set the process-wide default TracePolicy for agent middleware hook spans.
Call once at startup. A middleware's own trace_policy overrides this wholesale
(no field-level merge). Pass None to cle
Detect email addresses in content.
Detect credit card numbers in content using Luhn validation.
Detect IPv4 or IPv6 addresses in content.
Detect MAC addresses in content.
Detect URLs in content using regex and stdlib validation.
Apply the configured strategy to matches within content.
Return a callable detector for the given configuration.
Fast file pattern matching tool that works with any codebase size.
Supports glob patterns like **/*.js or src/**/*.ts.
Returns matching file paths sorted by modification time.
Use this tool whe
Fast content search tool that works with any codebase size.
Searches file contents using regular expressions. Supports full regex syntax and filters files by pattern with the include parameter.
Return metadata that marks a model call as internal to middleware.
Create and manage a structured task list for your current work session.
Decorator to configure hook behavior in middleware methods.
Use this decorator on before_model or after_model methods in middleware classes
to configure their behavior. Currently supports specify
Decorator used to dynamically create a middleware with the before_model hook.
Decorator used to dynamically create a middleware with the after_model hook.
Decorator used to dynamically create a middleware with the before_agent hook.
Decorator used to dynamically create a middleware with the after_agent hook.
Async version is aafter_agent.
Decorator used to dynamically generate system prompts for the model.
This is a convenience decorator that creates middleware using wrap_model_call
specifically for dynamic prompt generation. The de
Create middleware with wrap_model_call hook from a function.
Converts a function with handler callback into middleware that can intercept model calls, implement retry logic, handle errors, and rewr
Create middleware with wrap_tool_call hook from a function.
Async version is awrap_tool_call.
Converts a function with handler callback into middleware that can intercept tool calls, implement r
Initialize an embedding model from a model name and optional provider.
Requires the integration package for the chosen model provider to be installed.
See the model_provider para
Convert one MCP tool into a LangChain tool.
The returned tool calls the MCP tool through client on every invocation.
FastMCP clients are reentrant, so the tool can open the client itself
whether or
Main entrypoint into LangChain.
Message and message content types.
Includes message types for different roles (e.g., human, AI, system), as well as types for message content blocks (e.g., text, image, audio) and tool calls.
Entrypoint to using chat models in LangChain.
Factory functions for chat models.
Entrypoint to building Agents with LangChain.
Types for setting agent response formats.
Agent factory for creating agents with middleware support.
Entrypoint to using middleware plugins with Agents.
Tool error middleware for agents.
LLM-based tool selector middleware.
Opt-in error handling for explicit model refusals.
Tool-risk middleware driven by a decision model.
Tool retry middleware for agents.
Model-routing middleware driven by a decision model.
Summarization middleware.
Provider-side tool search middleware.
Middleware that exposes a persistent shell tool to agents.
Model retry middleware for agents.
Call tracking middleware for agents.
Context editing middleware.
Mirrors Anthropic's context editing capabilities by clearing older tool results once the conversation grows beyond a configurable token threshold.
The implementation is i
File search middleware for Anthropic text editor and memory tools.
This module provides Glob and Grep search tools that operate on files stored in state or filesystem.
Model fallback middleware for agents.
When an outer caching middleware modifies a request, those changes happen before the fallback loop runs. Provider-specific cache settings can cause API errors if
Tag and filter middleware-internal model calls.
Tag internal calls with internal_call_metadata() and declare
transformers = (InternalCallTransformer,) on the middleware class to keep
them out of
Human in the loop middleware.
Tool call limit middleware for agents.
PII detection and handling middleware for agents.
Planning and task management middleware for agents.
Types for middleware and agents.
Tool emulator middleware for testing.
Embeddings models.
With the release of langchain 1.0.0, several embeddings modules were moved to
langchain-classic, such as CacheBackedEmbeddings and all co
Factory functions for embeddings.
LangChain MCP adapters for connecting MCP servers with LangChain applications.
Interrupt-driven elicitation has its own types — the interrupt payload, the answers a run resumes with, and the discrimi
Answer MCP elicitation requests with a LangGraph interrupt.
A server needing input mid-call returns an InputRequiredResult and expects the
tools/call to be retried with answers. This module drive
Convert MCP tools and tool results into LangChain-native values.
Tool results follow langchain-mcp-adapters, so a call made through
langchain.mcp reaches a model in the same shape as one loaded b
Adapt MCP tools into LangChain tools suitable for create_agent.
Base abstraction and in-memory implementation of rate limiters.
These rate limiters can be used to limit the rate of requests to an API.
The rate limiters can be used together with BaseChatModel.
Tools.
Utils file included for backwards compat imports.
Union type for all supported response format strategies.
Type for specifying which exceptions to retry on.
Can be either:
isinstance checks)True if itType for specifying failure handling behavior.
Can be either:
'error' or 'continue')
'error': Re-raise the exception, stopping agent execution.Behavior when the selection model keeps returning a malformed response.
Can be either:
'error': Raise a ValueError (the default).'none': Select no tools.'all': Select every availableGenerates a summary from the messages selected for summarization.
Either a chat model (or model string) prompted with the summary prompt, or a
Runnable or callable taking the messages and returning
Union type for context size specifications.
Can be either:
ContextFraction: A
fraction of the model's maximum input tokens.Tool name or tool instance that can be deferred behind provider tool search.
Return type for model call handlers.
Middleware can return either:
ModelResponse: Full response with messages and optional structured outputAIMessage: Simplified return for simple use casesValues a form answer may carry, as narrow as mcp.types.ElicitResult.content.
One question an MCP server asks before finishing a tool call. Narrow on mode.
One answer to an MCPElicitationRequest. Narrow on action; only accept carries content.
LangChain content blocks an MCP tool result can convert into.
Anything MCPAdapter accepts as its target.
Every transport fastmcp.Client accepts, plus a pre-built fastmcp.Client.
A str target is the one member narrowed relative to fastmcp.Client: it