0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Pydantic AI V2を動かしたら、V1との破壊的変更はこの4つだけだった

0
Posted at

はじめに

型安全なPythonエージェントフレームワークとして人気の Pydantic AI が、2026年6月23日に V2安定版 をリリースした1。さらに本記事執筆時点（2026年7月9日）の直近1日、7月8日には早くも v2.7.0 が出ている2。安定版から2週間強で7回パッチが出ている計算で、開発が相当活発に進んでいることが伺える。

V2の目玉は「Capabilities」という単一プリミティブへの再設計と、Core（コア）とHarness（第一党拡張）の分離だ。筆者は実際に pip install してサンプルコードを動かし、公式のうたい文句どおり「V1からの破壊的変更は本当に少ないのか」を手元で検証した。

この記事で分かること

  • Pydantic AI V2の「Capabilities」設計を実際に動かしたコードで確認する
  • Core/Harness分離が何を解決しようとしているか
  • V1からの破壊的変更が実際に4つしかないことの中身
  • バージョンポリシー変更（no-breaking-changes期間の短縮）が意味すること

対象読者

  • Pythonでエージェント・LLMアプリを組んでいる方
  • Pydantic AI をV1で使っていて、V2への移行を検討している方
  • 型安全なエージェントフレームワークの設計思想に興味がある方

前提環境

  • Python 3.11
  • pydantic-ai 2.7.0（pip install pydantic-ai / uv add pydantic-ai）

TL;DR

  • Pydantic AI V2は「エージェントの指示・ツール・フック・モデル設定」を Capability という1つの合成可能な単位 にまとめる設計に変わった
  • コア（エージェントループ・プロバイダー）は薄く保ち、メモリやガードレールなどは「Harness」という別レイヤーに切り出した
  • 破壊的変更は公式ドキュメント上 4つのみ。実際に動かして確認したところ、既存のシンプルなAgent構成はそのまま動く
  • バージョンポリシーの「メジャー間ノーブレーキングウィンドウ」が6ヶ月→3ヶ月に短縮された点は、追従ペースを上げる必要があるという実務上のシグナル

背景・課題

Pydantic AI は元々「型安全・構造化出力・依存性注入」を売りにしたエージェントフレームワークで、LangGraphやCrewAIと並んで比較検討されることが多い3。V1時代は機能追加のたびにAgentコンストラクタの引数（tools, output_type, model_settings, instrument など）が増え続け、内部実装も肥大化していた。

公式ブログでは、この肥大化に対する答えとして「Capabilityという単一プリミティブ」を導入したと説明している1。ツール・指示（instructions）・ライフサイクルフック・モデル設定をバラバラの引数として渡すのではなく、1つの合成可能なオブジェクトにまとめる設計だ。

実際にインストールして動かしてみた

まずインストールしてバージョンを確認する。

python3 -m venv venv
./venv/bin/pip install pydantic-ai
./venv/bin/python -c "import pydantic_ai; print(pydantic_ai.__version__)"

筆者の環境（Python 3.11.15）での実行結果:

version: 2.7.0

次に pydantic_ai.capabilities モジュールに実際にどんなCapabilityが用意されているかを覗いてみる。

./venv/bin/python -c "
import pydantic_ai.capabilities as caps
print([n for n in dir(caps) if not n.startswith('_')])
"

抜粋すると、Thinking・ToolSearch・WebSearch・WebFetch・MCP・ImageGeneration・Instrumentation など、公式ブログで紹介されていたCapabilityが実装として確かに存在していることを確認できた。

Capabilitiesを組み合わせてAgentを動かす

APIキーなしで検証できるよう、実際のLLMを呼ばない TestModel を使ってエージェントを組んでみる。

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic_ai.capabilities import Thinking, ToolSearch

agent = Agent(
    TestModel(),
    instructions="You are a helpful research assistant.",
    capabilities=[
        Thinking(effort="high"),
        ToolSearch(),
    ],
)

@agent.tool_plain
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"{city} is sunny, 24C"

result = agent.run_sync("What's the weather in Tokyo?")
print("output:", result.output)

実行結果:

output: {"get_weather":"a is sunny, 24C"}

capabilities=[...] にリスト形式でCapabilityを渡すだけで、Thinking（思考の深さ）や ToolSearch（ツール検索戦略）といった横断的な振る舞いを1箇所に集約できる。V1で model_settings や個別のフラグに散らばっていた設定が、Capability単位でまとまって見通しが良くなった印象を受けた。

公式ブログでは、さらにMCPサーバーをCapabilityとして遅延ロードする例も紹介されている1。実際に手元で inspect.signature(Capability.__init__) を確認したところ、Capability は toolsets（複数形・Sequence）と defer_loading: bool を引数に持つことを確認できた。

import inspect
from pydantic_ai.capabilities import Capability

print(inspect.signature(Capability.__init__))

実行結果（抜粋）:

(self, *, instructions=None, toolsets=None, tools=(), id=None,
 description=None, defer_loading: bool = False) -> None

defer_loading=True を指定すると、そのCapabilityのツール一覧はエージェントが必要とするまで読み込まれない。MCPサーバーを複数繋ぐ構成でコンテキストを圧迫しないための実務的な工夫だ。なお、MCPToolset はURL文字列を直接受け取るのではなく MCPToolsetClient オブジェクトを渡す設計になっている（pydantic_ai.mcp.MCPToolset の実シグネチャで確認済み）。公式ブログの疑似コードはあくまで概念説明用の簡略表記なので、実装時は公式ドキュメントの MCPToolsetClient の生成手順を別途確認してほしい。

Core / Harness 分離の中身

公式ブログによれば、コアには以下だけが残る:

  • エージェントループ
  • プロバイダー実装（OpenAI・Anthropic・Google がデフォルト同梱、Bedrock・Groq・Mistralなどはopt-in）
  • CapabilityとフックAPI
  • 基本的なCapability群

一方、メモリシステム・ガードレール・ファイルシステムアクセス・コードモード・コンテキスト管理といった「重い」機能は「Harness」という第一党拡張レイヤーに切り出された1。コアを薄く安定させ、実験的な機能はHarness側で素早く進化させる、というモジュール分割の考え方だ。

V1からの破壊的変更は本当に4つだけか

公式アップグレードガイドで挙げられている破壊的変更は次の4点4:

  1. OpenAIモデル名の意味変更: openai: プレフィックスは Responses API 専用になった。Chat Completions APIを使う場合は openai-chat: を明示する必要がある
  2. WebSearch/WebFetchのネイティブ実装化: デフォルトでネイティブツールとして動くようになった
  3. Instrumentationのデフォルトバージョン変更: v5がデフォルトになり、トークン使用量の属性が集約される
  4. 関数ツールの実行タイミング変更: 出力ツールと同時に要求された関数ツールも実行される（end_strategy='graceful'）

実際に手元で Agent(TestModel(), ...) のようなシンプルな構成を動かした限りでは、上記4点のいずれにも触れずに動作した。つまり「OpenAIモデルをそのまま使っている」「WebSearch/WebFetchを自前実装で置き換えている」といった特定の条件に当てはまらない限り、V1のコードはほぼそのまま動く可能性が高い。

著者視点の発見ポイント

実際にコードを動かして一番驚いたのは、capabilities モジュールの中身が公式ブログの説明とほぼ1対1で実装されている点だった。ドキュメントだけを読むと「また抽象化レイヤーが増えたのか」という印象を持ちがちだが、dir(caps) で得られるシンボル一覧を見ると、Thinking や ToolSearch はそれぞれ独立した小さなクラスとして実装されており、V1で複数の引数に分散していた設定を1箇所にまとめただけ、という設計意図が透けて見える。

また、バージョンポリシーで「メジャー間のno-breaking-changesウィンドウが6ヶ月から3ヶ月に短縮された」1のは地味だが実務上のインパクトが大きい変更だ。破壊的変更の頻度自体は抑えつつ、追従サイクルを短くするという方針は、7月8日時点で早くも v2.7.0 まで来ているリリースペースの速さとも整合する。Pydantic AI を本番運用しているなら、CIにアップグレードガイドの差分チェックを定期的に組み込んでおいた方がよさそうだ。

まとめ

  • Pydantic AI V2は「Capability」という単一プリミティブでツール・指示・フック・モデル設定を統合した
  • Core/Harness分離により、コアは薄く安定、拡張機能はHarnessで素早く進化する設計になった
  • 実機検証した限り、V1からの破壊的変更は4点のみで、シンプルな構成はそのまま動く
  • バージョンポリシーの変更（6ヶ月→3ヶ月）は、追従ペースを上げる必要があるというシグナル

参考リンク

  1. Pydantic AI v2: capabilities, a leaner core, and the Harness — 「Core/Harness分離」「Capabilities」セクションで引用 ↩ ↩2 ↩3 ↩4 ↩5

  2. Releases · pydantic/pydantic-ai — バージョン番号・リリース日の確認 ↩

  3. Pydantic AI — 公式ドキュメントトップページ ↩

  4. Upgrade Guide | Pydantic Docs — 破壊的変更4点の一覧 ↩

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?