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 Agentfrom pydantic_ai.capabilities import WebSearchfrom 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:
FileSystemShellRepoContextSubAgentsClearToolResultsToolOutputLimitsRepairToolArguments
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 concern | LangChain placement | Pydantic AI placement | Evidence status |
|---|---|---|---|
| Behavior hooked to model calls, tool calls, or lifecycle events | Middleware subclassing AgentMiddleware, inside the create_agent harness | Capability supplied through Agent(capabilities=[...]); capabilities can bundle hooks | Both placements are vendor-documented. Equivalent hook coverage is not established. |
| Prompt caching, native tool execution, or content moderation | Provider-specific middleware category | No corresponding category in the Pydantic AI overview | LangChain vendor documentation only |
| Rate limiting, PII detection, logging, or guardrails | Cross-provider middleware category | No corresponding named capabilities in the Pydantic AI overview | LangChain vendor documentation only |
| Tool-argument repair | The LangChain integration guide names no middleware for this concern | RepairToolArguments, used as a block in the documented decomposition of Coder | Pydantic AI vendor documentation; repair internals not documented |
| Tool-output limits | The LangChain integration guide names no middleware for this concern | ToolOutputLimits, used whole within Coder or in its documented decomposition | Pydantic AI vendor documentation; limit internals not documented |
| Second opinion from another model when stuck | No counterpart documented in the LangChain pages | Advisor capability attached at Agent construction | Pydantic AI vendor documentation |
| Files, shell, repository context, sub-agents, and context management as one bundle | No counterpart documented in the LangChain pages | Coder whole, or its documented blocks | Pydantic AI vendor documentation |
| Web lookup for documentation and error messages | No counterpart documented in the LangChain pages | WebSearch capability imported from pydantic_ai.capabilities | Pydantic 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
Coderand 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.
Join the discussion
Share a useful perspective or ask a question about this article.