groundy
Agents & Frameworks

LangChain Middleware vs Pydantic AI Capabilities: Where Custom Code Lives

LangChain middleware and Pydantic AI capabilities are distinct extension points. Vendor docs define their shapes, but do not establish equivalence or porting paths for cross-c

Published 4 references
On this page9 sections

When behavior must run on every model call, tool call, or agent lifecycle event, LangChain’s documented home for it is a middleware class that subclasses AgentMiddleware inside the create_agent harness. Pydantic AI’s documented home is a capability attached through the Agent constructor’s capabilities list. Those are different extension architectures, not two names for the same mechanism, according to LangChain’s integration documentation and Pydantic AI’s overview.

The practical consequence is that agent maintainability depends heavily on where cross-cutting policy is attached. A rate limit, output limit, argument-repair concern, or second-opinion consult can become part of the framework-specific structure rather than remaining an isolated application decision. Treat the resulting porting cost as editorial judgment, not a measured result: neither documentation page lays out how LangChain middleware maps onto Pydantic AI capabilities.

The two extension points have different shapes

LangChain describes an agent as “Agent = Model + Harness.” Its create_agent function supplies the harness around the model loop, consisting of the prompt, tools, and middleware that shapes behavior, according to LangChain’s agent overview. For behavior associated with model calls, tool calls, or lifecycle events, the documented extension point is therefore part of the harness, not an unrelated utility called ad hoc by application code.

The integration documentation adds a useful distinction between two middleware categories:

  • Provider-specific middleware covers behavior such as prompt caching, native tool execution, and content moderation.
  • Cross-provider middleware covers concerns such as rate limiting, PII detection, logging, and guardrails.

That taxonomy helps with placement, but it does not mean every LangChain customization belongs in middleware. The same integration documentation describes integration packages implementing components such as chat models, tools, and retrievers against LangChain interface standards. The placement rule here concerns behavior that cuts across agent execution, not every possible extension.

Pydantic AI starts from a different primitive. Its documentation says that a capability bundles “tools, instructions, hooks, and model settings” into reusable units. Capabilities are instantiated and passed to Agent at construction time. The documented example includes Coder, WebSearch, and Advisor, with the last described as providing a second opinion from another model when the agent is stuck, in Pydantic AI’s overview:

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness import Advisor, Coder
agent = Agent(
'anthropic:claude-fable-5-2',
capabilities=[
Coder(), # files, shell, repo context, sub-agents, context management
WebSearch(), # look up docs and error messages on the web
Advisor('openai:gpt-6.1-sol'), # a second opinion from another model when stuck
],
)

This is composition through reusable capability objects. A capability can carry tools, instructions, hooks, and model settings together, while LangChain middleware is documented as a subclass hooking agent execution. The Pydantic AI overview does not establish that its hooks expose the same three surfaces as LangChain middleware. It would therefore be unsafe to convert the architectural contrast into a claim that every middleware can be rewritten as one capability, or the reverse.

Use Coder whole when the whole bundle fits

Pydantic AI explicitly avoids making its bundled Coder capability an all-or-nothing black box. The documentation says it can be used whole or replaced by the blocks it bundles, and states that the two forms are equivalent. The named blocks are:

  • FileSystem
  • Shell
  • RepoContext
  • SubAgents
  • ClearToolResults
  • ToolOutputLimits
  • RepairToolArguments

That gives developers a real granularity decision. My recommendation, as editorial synthesis from the documented bundle, is to use Coder whole when its file, shell, repository-context, sub-agent, and context-management concerns all belong in the agent. If the requirement is narrower, such as tool-output limits or tool-argument repair, selecting the relevant blocks makes the intended boundary easier to see in the agent definition.

The documentation supports the equivalence of the whole and decomposed forms. It does not explain each block’s internal failure behavior or establish that every conceivable custom combination has been tested. Decomposition is a documented composition choice, not evidence about runtime reliability.

There is also a packaging detail worth catching before writing installation instructions. In the documented example, WebSearch comes from pydantic_ai.capabilities, while Advisor and Coder come from the separate pydantic_ai_harness package. Do not present all three as imports from one package. Neither page publishes package versions, so current package requirements still need checking against the package documentation before implementation.

A placement matrix, not an equivalence chart

The following matrix maps each concern to the extension point each vendor documents. “Not documented” means the documentation does not establish a counterpart; it does not prove that none exists.

Cross-cutting concernLangChain placementPydantic AI placementEvidence status
Behavior hooked to model calls, tool calls, or lifecycle eventsMiddleware subclassing AgentMiddleware, inside the create_agent harnessCapability supplied through Agent(capabilities=[...]); capabilities can bundle hooksBoth placements are vendor-documented. Equivalent hook coverage is not established.
Prompt caching, native tool execution, or content moderationProvider-specific middleware categoryNo corresponding category in the Pydantic AI overviewLangChain vendor documentation only
Rate limiting, PII detection, logging, or guardrailsCross-provider middleware categoryNo corresponding named capabilities in the Pydantic AI overviewLangChain vendor documentation only
Tool-argument repairThe LangChain integration guide names no middleware for this concernRepairToolArguments, used as a block in the documented decomposition of CoderPydantic AI vendor documentation; repair internals not documented
Tool-output limitsThe LangChain integration guide names no middleware for this concernToolOutputLimits, used whole within Coder or in its documented decompositionPydantic AI vendor documentation; limit internals not documented
Second opinion from another model when stuckNo counterpart documented in the LangChain pagesAdvisor capability attached at Agent constructionPydantic AI vendor documentation
Files, shell, repository context, sub-agents, and context management as one bundleNo counterpart documented in the LangChain pagesCoder whole, or its documented blocksPydantic AI vendor documentation
Web lookup for documentation and error messagesNo counterpart documented in the LangChain pagesWebSearch capability imported from pydantic_ai.capabilitiesPydantic AI vendor documentation

The matrix’s main value is negative as well as positive. It shows where the documentation gives a direct answer and where a seemingly symmetrical row would only be guesswork. In particular, the presence of RepairToolArguments and ToolOutputLimits on the Pydantic AI side does not justify inventing matching LangChain middleware names.

What the documentation does not settle

As of mid-November 2026, the LangChain and Pydantic AI pages establish the extension-point interfaces, but not the details needed to treat this article as an API reference:

  • The LangChain pages do not name middleware hook methods. They should not be reconstructed from naming conventions or assumed from another version. The integration page defers hooks, state updates, and middleware patterns to a separate custom middleware guide.
  • Neither vendor page publishes package versions, release dates, or deprecation status. The documented names and imports need checking against the versions a project actually installs.
  • Python and JavaScript parity is not established. The LangChain integration page sits under a JavaScript contributing path but describes integration packages as Python packages. That is not enough to claim identical middleware support across languages.
  • Mechanism-specific failure modes are absent. Neither page documents how middleware or capabilities fail, and the GitHub-issue study cited later does not break its topics out by extension mechanism, so this comparison cannot rank their reliability.
  • Error behavior per capability block is not documented. Pydantic AI documents the equivalence of Coder and its blocks, but the overview does not demonstrate error behavior for each block or every standalone combination.

These gaps change the next action. Before committing implementation details, check the current API references for hook signatures, imports, package requirements, and language support, then exercise the required failure paths in the target application. That verification follows from what the documentation leaves open; it is not a claim that either choice has already been proven safe.

Porting cost is the architectural risk

The portability judgment is editorial synthesis. Neither the LangChain pages nor the Pydantic AI overview demonstrates interchangeability, so I would treat cross-cutting code attached to either mechanism as framework-committed. A LangChain middleware subclass expresses behavior through the agent harness. A Pydantic AI capability expresses a reusable bundle attached at construction. The Pydantic AI overview does point to vendor material that goes further: it says “The comparisons show where Pydantic AI differs from LangChain” and that “the migration skills let your coding agent port an existing application over.” Whether that comparison and migration material covers middleware-to-capability logic is not settled by the overview itself, so until that material is checked, moving between the two mechanisms should be budgeted as redesign work, not assumed to be a renaming exercise.

Where practical, keep application policy separate from the framework-specific attachment. Decisions about which concerns apply, when a second opinion is wanted, or what the agent is permitted to do can remain application-owned even when enforcement is attached through middleware or a capability. That separation may reduce the amount of policy embedded in framework classes or objects, but it does not make the adapter portable and does not eliminate rewriting.

The broader maintenance stakes are real, although not mechanism-specific. An empirical study of developer challenges in AI agent systems extracted 4,783 Stack Overflow posts using 15 agent-related tags, including several LangChain and LangGraph tags. It also gathered 67,193 GitHub issues across 18 agent-framework repositories and retained 64,098 after filtering. Those numbers show substantial developer friction across agent-framework ecosystems. They do not show that middleware or capabilities caused the issues, and they should not be used to invent a failure rate for either extension point.

The decision is therefore to place the behavior where each framework’s documentation says it belongs, choose Coder whole or decomposed according to the scope actually required, and keep portability claims modest. The documentation supports those placement choices. It does not support a promise that cross-cutting logic will move cleanly between frameworks.

Frequently Asked Questions

Where does LangChain document the home for behavior that runs on every model call or agent lifecycle event?

When behavior must run on every model call, tool call, or agent lifecycle event, LangChain’s documented home for it is a middleware class that subclasses AgentMiddleware inside the create_agent harness.

How are Pydantic AI capabilities attached to an agent?

Pydantic AI’s documented home is a capability attached through the Agent constructor’s capabilities list.

Which package provides the Coder and Advisor capabilities in the documented example?

In the documented example, WebSearch comes from pydantic_ai.capabilities, while Advisor and Coder come from the separate pydantic_ai_harness package.

References

Follow the links in the article for context. The supporting material is collected here for further reading.

  1. LangChain integration documentationdocs.langchain.comAccessed
  2. Pydantic AI overviewpydantic.devAccessed
  3. LangChain agent overviewdocs.langchain.comAccessed

Join the discussion

Share a useful perspective or ask a question about this article.

Discussion guidelinesComments privacy