The supportable answer is not that one framework breaks agent code more often. It is that the two projects put migration risk in different places. Pydantic AI Harness’s documentation explicitly permits API changes between 0.x minor releases, with deprecation warnings and release-note migration guidance as the notice mechanism. It also documents a rename that affects previously saved agent specs. LangChain’s integration documentation instead defines compatibility through langchain-core base classes and interface standards, but makes no promise about breaking changes between releases.
For an adoption decision, that means budgeting for different work. With Pydantic AI Harness, audit both Python APIs and persisted YAML or JSON specs whenever you move a minor version. With LangChain, audit the core interfaces, integration packages and import paths your code uses, then check primary release notes for the migration policy that the fetched interface page does not supply. Pin versions and run upgrades with warnings enabled in either case.
Two scope limits matter throughout. The Pydantic evidence concerns Pydantic AI Harness, not the whole pydantic-ai agent library. LangChain’s reported 1.0 migrations come from one third-party explainer rather than LangChain release notes. Neither project’s current version number is established by the supplied pages, and this evidence cannot support an overall stability ranking.
The upgrade question feature guides skip: who owns your migration pain?
A compatibility contract answers several separate questions:
- Which names and behavior are expected to remain usable?
- How much notice precedes a change?
- Does compatibility cover only source code, or also saved configuration and serialized state?
- When an old path stops working, is there a documented temporary shim or replacement package?
- Can an upgrade change agent results even when every import still succeeds?
Pydantic AI Harness gives an unusually direct answer to the first two questions: change is allowed between 0.x minor releases, and warnings plus release notes are the documented upgrade route. LangChain’s fetched page answers a different question: integration components implement centrally defined interfaces. That identifies an architectural boundary, but it does not establish how often the boundary changes or how long old interfaces remain supported.
The practical distinction is between a stated change policy and an interface model. Treating either as a measured breakage rate would go beyond the evidence.
Pydantic AI Harness permits change and documents the migration route
The Harness documentation states:
While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.
That is useful information for planning, but it should not be compressed into either “0.x means constant breakage” or “warnings make upgrades safe.” The policy allows change; it does not quantify its frequency. The supplied documentation provides one concrete migration example, not a churn rate.
There is also a behavioral change worth testing. According to the same documentation, PydanticAIDocs serializes under the name PydanticAIDocs in YAML and JSON agent specs. Earlier releases declared no default capability ID, and duplicate-instance failure moved from run start, where it appeared as a tool-name conflict, to agent-build time as a UserError. Code that still imports can therefore encounter a failure at a different stage of application startup or execution.
For operations, that distinction changes the test. An import check is not enough. Build an agent, create duplicate capability instances where your configuration permits them, and exercise saved-spec loading before promoting an upgrade.
The PyaiDocs rename leaves old specs dependent on a deprecated shim
The documented rename from PyaiDocs to PydanticAIDocs shows why serialization belongs in the migration budget.
Specs saved before the rename retain the old block name. To keep loading them, the documentation says to pass the deprecated PyaiDocs class, imported from pydantic_ai_harness.docs, alongside or instead of PydanticAIDocs. That class emits a deprecation warning and preserves the PyaiDocs serialization name. Re-saving the spec with PydanticAIDocs completes the documented migration.
This creates two different migration states:
- Compatibility state: old spec files remain loadable because the deprecated class retains their old serialization name.
- Migrated state: the specs have been re-saved with
PydanticAIDocs, so they use the new serialization name.
Updating Python references without addressing persisted specs leaves the document migration unfinished. Conversely, keeping the shim without re-saving leaves the application dependent on a class already marked deprecated.
A sensible migration procedure follows from those documented mechanics, although this procedure is my synthesis rather than a vendor-published checklist: inventory saved specs containing the old block name, pin the Harness version while converting them, capture deprecation warnings, test loading through the shim, and then verify the re-saved artifacts independently before removing the old compatibility path. If those specs are customer data or shared workspace artifacts, include their owners in the rollout rather than treating the rename as a local code edit.
LangChain defines an interface boundary, not a release guarantee
LangChain’s integration guide says that integration packages implement components adhering to LangChain interface standards. Those components subclass base classes in langchain-core; the page names chat models, tools and retrievers among the examples.
It gets more specific for implementers. Named base classes include BaseChatModel, Embeddings, BaseTool and AgentMiddleware. Checkpointers and sandboxes are additional integration component types. Provider-specific middleware belongs in the provider’s integration package, such as langchain-anthropic, while cross-provider middleware can be published separately.
That architecture gives an adopter a useful test boundary: a chat-model integration can be checked against the chat-model interface, and middleware can be checked against the middleware interface. It does not follow that langchain-core, every integration package and every import path share a no-breakage guarantee. The fetched page names the standards but says nothing about release cadence, deprecation periods or compatibility between releases.
There is a further citation wrinkle: the page sits in LangChain’s JavaScript documentation tree while describing Python integration packages. Its account of the interface model is direct vendor evidence; it is not sufficient evidence for a Python release policy.
What reportedly moved at LangChain 1.0
The strongest account of LangChain-side migration in the brief is Atlan’s third-party explainer, published on 26 May 2026, not a primary migration guide.
Atlan reports that since LangChain 1.0 in October 2025, all LangChain agents run on the LangGraph runtime with “no migration required.” If accurate for the code being considered, that is an important counterweight: a runtime change does not necessarily force every current-style agent to be rewritten.
The same page reports several changes that matter more to older codebases:
AgentExecutor-era code andlangchain-communityre-exports moved into a separatelangchain-classicpackage.- Legacy in-process memory classes such as
ConversationBufferMemorywere deprecated in 1.0, with production memory routed through LangGraph’s checkpointer. - The standalone
langchain-mcp-adapterspackage was archived, and MCP support moved underlangchain.mcp, installed aslangchain[mcp].
These reports are not necessarily contradictory. An application using the current agent abstraction may need no runtime migration, while an older application can still face package, import and memory changes. The deciding question is which generation of APIs your repository actually uses.
Atlan also reports that Octomind moved away from LangChain toward direct API calls, citing too many abstraction layers and opaque internal state. That is one team’s reported experience, not a measurement of LangChain upgrade frequency or a prediction that other teams will benefit from the same move.
Before publishing a stability judgment or starting a large migration, verify these points against LangChain’s own release notes and migration documentation. In particular, langchain-classic should be treated as a reported escape hatch whose current support terms still need checking, not as proof of permanent legacy compatibility.
The comparison that the evidence actually supports
| Decision axis | Pydantic AI Harness | LangChain |
|---|---|---|
| Documented compatibility boundary | Harness APIs and capability-spec serialization under an explicit 0.x policy | Integration components implementing langchain-core interface standards |
| Permission for scheduled change | API may change between 0.x minor releases | The fetched interface page makes no inter-release change promise |
| Documented notice or migration route | Deprecation warnings and release-note migration guidance | Central interface standards are documented; a general deprecation policy is not established by the fetched page |
| Worked migration evidence | PyaiDocs specs load through a deprecated shim until re-saved as PydanticAIDocs | Third-party reporting describes langchain-classic, memory deprecations and MCP package changes |
| What remains unknown | Breakage frequency across Harness releases and the policy for the wider agent library | Primary release-note history, deprecation cadence, current package versions and measured breakage frequency |
This table supports a migration-planning comparison. It does not support assigning either project a lower breakage score.
Deprecation warnings do not predict when invocation fails
An empirical study of deprecated Python APIs helps explain why. After a deprecation announcement, 56.4% of studied mappings retained the source definition and 68.6% retained an executable original invocation. Among 753 mappings with at least one observed ending event, 25.2% were source-first or invocation-first rather than ending in the same release.
Those figures describe the studied Python libraries, not Pydantic AI Harness or LangChain. They nevertheless undermine two tempting assumptions: a deprecation warning does not mean the old call immediately stops working, and surviving source code does not guarantee that the public call remains available.
The same study found that removal of a deprecated access path or public alias was the most frequent invocation-first break mechanism, accounting for 20 of 43 cases, or 46.5%. Its JAX example describes the public jax.tree_flatten binding being disabled between versions 0.5.3 and 0.6.0 while the internal definition remained. Python aliases, re-exports, inheritance and dynamic attribute resolution can separate the continued existence of an implementation from the availability of the path your application calls.
For an adopter, the test is therefore behavioral: execute the original public invocation in the upgraded environment. Grepping the dependency for a function definition can produce false reassurance.
Package-level notices need a separate check. A study of package-level Python deprecation describes a typical mechanism with three steps: declaring deprecation, delivering the message to consumers and updating the package index so deprecated packages or releases are harder to find. An API warning in application logs and a package’s installation or archival status are different signals. Your audit should inspect both.
A clean upgrade can still change agent outcomes
Code compatibility is not the whole regression surface. A harness-evolution study using AppWorld and Qwen3.5-4B evaluates repaired and regressed tasks relative to a base harness and frames harness evolution as nonstationary. In other words, changes in execution support can improve some tasks while worsening others.
That research does not measure either framework compared here. It does justify adding outcome tests to the upgrade gate. A suite that checks only imports, class construction and spec loading can miss changes in tool use or task completion.
The Pydantic documentation’s shift in duplicate-instance failure timing makes the same point at a smaller scale: the location and type of failure can change even when the surrounding application remains recognizable. For either framework, retain a fixed set of representative agent tasks and compare outcomes across the pinned old and new versions. Treat repaired and regressed cases separately so that aggregate improvement does not hide a workflow your application depends on.
A pre-adoption deprecation audit
The following checklist is a synthesis of the vendor documentation and deprecation studies above. It is not a procedure published by either framework.
-
Name the exact layer you depend on. Record whether the application uses Pydantic AI Harness APIs, saved Harness specs, LangChain core abstractions, provider integrations, middleware, memory or MCP imports. Do not generalize a Harness policy to all of Pydantic AI.
-
Pin and record the version pair. Capture both the starting and target versions, then read the intervening release notes. For Harness, include every minor release because its stated 0.x policy permits changes between them. For LangChain, this step supplies the release evidence missing from the fetched interface page.
-
Turn warnings into reviewable output. Run tests with deprecation warnings visible and retain them in CI logs. A warning is a migration input, not proof of either imminent failure or continued safety.
-
Exercise old access paths. Test the actual imports and calls used by the application in a clean upgraded environment. Do not substitute a search for an internal definition, given the study’s access-path and alias findings.
-
Round-trip persisted artifacts. For Harness specs, test pre-rename files with the documented shim and verify artifacts re-saved under
PydanticAIDocs. Include serialization names in version-control review; a working Python import does not establish document compatibility. -
Check package-level escape hatches. Determine whether a migration depends on a deprecated class, an archived adapter or a legacy package. Verify its current support and removal terms before relying on it. The reported existence of
langchain-classicis not itself a support-duration guarantee. -
Run behavioral evaluations. Compare representative tasks under the old and new dependency sets and inspect regressions individually. This follows from the harness-evolution research, not from a vendor promise.
-
Price unfinished migrations. A shim can defer spec rewriting, and a legacy package can defer import restructuring, but both leave work in the codebase. Budget that work explicitly rather than calling the upgrade complete when the application starts.
Budget the risk you can document
I would not classify either option as low-maintenance from these sources alone. For a Pydantic AI Harness adoption, I would accept the 0.x policy only with pinned minor upgrades, warnings captured in CI and a test fixture for every persisted spec format the application must read. The PyaiDocs migration shows that the project can document a workable compatibility route, but one rename does not establish how disruptive future releases will be.
For LangChain, I would first classify the codebase by API generation. Current-style agents may not require the runtime migration described by Atlan, while AgentExecutor, legacy memory or standalone MCP dependencies point toward concrete migration work. The central interface model tells you where to test; it does not remove the need to inspect primary release notes.
If your production constraint is that saved artifacts and public imports must survive upgrades without planned intervention, the supplied evidence is insufficient to certify either path. Pydantic AI Harness explicitly reserves room for minor-release API changes. LangChain may turn out to have the stronger release policy, but that policy has to be established from its own release notes before it can justify the safer choice.
Frequently Asked Questions
What is the documented migration route for Pydantic AI Harness 0.x releases?
While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.
How do I load old PyaiDocs specs after the rename to PydanticAIDocs?
Specs saved before the rename retain the old block name. To keep loading them, the documentation says to pass the deprecated PyaiDocs class, imported from pydantic_ai_harness.docs, alongside or instead of PydanticAIDocs. That class emits a deprecation warning and preserves the PyaiDocs serialization name. Re-saving the spec with PydanticAIDocs completes the documented migration.

Join the discussion
Share a useful perspective or ask a question about this article.