【連載】pydantic-ai徹底解説 (1) はじめての pydantic-ai

今回は Python で LLM(大規模言語モデル)を活用するための強力なフレームワーク「pydantic-ai」を紹介します。
pydantic-ai は、Pydantic を活用した構造化レスポンスや型安全性、エージェント(Agent)・ツール(関数)呼び出し、依存性注入などを組み合わせ、LLM ベースのアプリケーション開発を容易にします。

本連載の第一回では、「pydantic-ai」の基本概念を理解し、最もシンプルな例を通して、どのようにエージェントを作り、モデルに問い合わせるかを実演します。

pydantic-ai とは

pydantic-ai は、LLMエージェントフレームワークです。
特徴は次の通りです。

Pydanticによる型安全な構造化レスポンス： LLMの出力は生のテキストですが、pydantic-aiでは最終結果をPydanticモデルで定義可能。モデルはLLMにJSONで応答を促し、構造化データとして受け取ります。これにより、バリデーション失敗時はLLMに再試行させることもできます。
モデル非依存のアーキテクチャ：OpenAI、Gemini(Google VertexAI経由)、Groqなど複数のモデルをプラグイン的に利用可能。
ツール(関数)呼び出し： LLMに対して関数一覧を渡し、LLMが必要な情報を取得するために関数を呼び出すといった高度なRAGやエージェント的挙動を簡潔に実装できます。
依存性注入(DI)：システムプロンプトやツール関数は外部リソース(DB接続、APIクライアントなど)をDIで受け取り、テスト性や拡張性に優れます。
ストリーミング対応：LLMの結果をストリームしながら処理することもサポート。
テスト/エバリュエーション支援：TestModelやFunctionModelにより、本物のLLMを呼ばずにユニットテストが可能です。

基本的な使い方

まずは、最小の「Hello World」的な例を見てみます。
ここでは以下を前提とします。

gemini-1.5-flash (Google Geminiモデル)を使用する例 (環境変数でAPIキー設定済み)
単純な1回の問い合わせでの応答を取得

from pydantic_ai import Agent

# エージェントを作成
agent = Agent(
    'gemini-1.5-flash',
    system_prompt='Be concise, reply with one sentence.'  # システムプロンプト例
)

# run_sync で同期的な問い合わせを行う
result = agent.run_sync('Where does "hello world" come from?')

# 最終的なテキストレスポンスを表示
print(result.data)
# 例）"The first known use of "hello, world" was in a 1974 textbook about the C programming language."

ここで注目すべき点は、Agent インスタンス生成時にモデル名やシステムプロンプトを指定できることです。また、run_sync実行後に得られるresultはRunResultオブジェクトで、.dataで出力テキストを取得します。

この時点ではまだ pydantic-ai の真価である構造化レスポンスやツール呼び出しは使っていませんが、これが基本的な流れです。
すなわち、

Agentインスタンス生成
agent.run()またはagent.run_sync()でLLMへ問い合わせ
result.dataで応答取得

といったシンプルなステップでLLMが利用できます。

まとめ

本記事では pydantic-ai の概要と、最も基本的な「エージェントを使ってLLMに問い合わせ、結果を取得する」流れを紹介しました。ここまでですでに、エージェントを介してモデルへ問い合わせる基本形が理解できたと思います。

次回はもう少し踏み込んで、pydanticモデルによる構造化レスポンスや、ツール呼び出し、依存性注入など、pydantic-ai の特徴的な機能を解説していきます。

📒ノートブック

参考サイト