Pydantic AI 2.71で、上限やツールの例外で止まるエージェントに答えを返させる|WrapUpAtLimitsとReportToolErrorsを2.70と比べて検証
Pydantic AI 2.71.0で、上限やツールの例外で止まっていたエージェントの実行を答えで終えられる
Pydanticが、PythonでAIエージェントを作るためのライブラリ「Pydantic AI」の2.71.0を、日本時間2026年11月19日の昼前にGitHubとPyPIで公開しました(2.71.0のリリースノート)。同時に、エージェントへ機能を足す部品を集めた別のパッケージ「pydantic-ai-harness」の0.71.0も公開されています(PyPIのpydantic-ai-harness 0.71.0)。
Pydantic AIのエージェントは、モデルへの要求と、モデルが呼んだツールの実行を繰り返して答えを作ります。この繰り返しは、次の2つの場面では例外を投げて途中で終わります。1つはUsageLimitsで決めた要求の回数やツールの呼び出しの回数の上限に届いたときのUsageLimitExceededで、もう1つはツールの関数が投げた例外です。どちらも、それまでにモデルが集めた情報は答えにならずに終わります。
pydantic-ai-harness 0.71.0には、この2つの場面を答えで終えるための部品が入りました。上限の手前の最後の要求でツールを止めて答えさせるWrapUpAtLimits(PR #13670)と、ツールの例外をモデルへの「失敗した」という結果に変えるReportToolErrors(PR #13745)です。どちらも、Agentの引数capabilities(エージェントに機能を足す部品のリスト)に入れたときだけ働きます。この記事では、PyPIから2.70.0と2.71.0を別々の仮想環境に入れ、決めた応答を返すテスト用のモデル(FunctionModel)で同じエージェントを動かして、終わり方を比べました。APIキーや外部のモデルは使っていません。
要点
WrapUpAtLimitsとReportToolErrorsを入れると、例外で止まっていた実行が、モデルの答えで終わった
2.70.0と2.71.0に、同じモデルとツールを使わせて比べた結果です。
WrapUpAtLimits
request_limit=3で、3回目の要求がtool_choice='none'(ツールを呼ばせない設定)で送られ、モデルの答えで終わった
2.70.0では、3回の要求のあとにUsageLimitExceededで止まりました。
WrapUpAtLimitsと上限を渡さない実行
WrapUpAtLimitsは既定の要求の上限50回にも効き、50回目の要求で答えた
WrapUpAtLimitsを入れない場合は、50回の要求のあとにUsageLimitExceededで止まりました。
ReportToolErrors
ツールのZeroDivisionErrorが、モデルへの「失敗した」という結果になり、実行が続いた
モデルに渡るのはツール名と例外の型で、メッセージは既定では含みません。
ReportToolErrorsとWrapUpAtLimits
失敗し続けるツールを呼ぶモデルも、ReportToolErrorsとWrapUpAtLimitsの両方を入れると答えで終わった
ReportToolErrorsだけでは、要求の上限でUsageLimitExceededになりました。
Pydantic AI 2.70.0と2.71.0で、同じエージェントの終わり方を比べた
比べたのは、テスト用のモデル3つです。検索のツールを毎回呼び、tool_choice='none'の要求のときだけ文章で答えるモデル。0で割るツールを1回呼び、その結果を受け取ったら文章で答えるモデル。0で割るツールを毎回呼び、tool_choice='none'の要求のときだけ文章で答えるモデルです。2.71.0の列は、表の左の部品をcapabilitiesに入れた結果です。画面が狭いときは、表を横にスクロールできます。
| 場面と入れた部品 | 2.70.0(部品なし) | 2.71.0(部品あり) |
|---|---|---|
検索を呼び続けるモデル、request_limit=3/WrapUpAtLimits |
3回の要求のあとUsageLimitExceeded | 3回目の要求をtool_choice='none'で送り、答えで終了。wrapped_up_by()は'request_limit' |
同じモデル、tool_calls_limit=2/WrapUpAtLimits |
3回目の要求でモデルが呼んだ3つ目の呼び出しの前にUsageLimitExceeded | 2回の呼び出しのあと、3回目の要求をtool_choice='none'で送り、答えで終了。'tool_calls_limit' |
| 同じモデル、上限を渡さない/WrapUpAtLimits | 50回の要求のあとUsageLimitExceeded | 50回目の要求で答えて終了 |
divide(1, 0)を1回呼んで結果で答えるモデル/ReportToolErrors |
ZeroDivisionErrorで実行が止まる | モデルが「`divide` raised ZeroDivisionError」という失敗の結果を受け取り、答えで終了 |
divide(1, 0)を呼び続けるモデル、request_limit=4/2つとも |
ZeroDivisionErrorで実行が止まる | 3回の失敗のあと、4回目の要求で答えて終了。ReportToolErrorsだけではUsageLimitExceeded |
表の注: 2.70.0はpydantic-ai-slim 2.70.0とpydantic-ai-harness 0.70.0、2.71.0はpydantic-ai-slim 2.71.0とpydantic-ai-harness 0.71.0。2.71.0でも、部品を入れなければ2.70.0と同じ例外で止まりました。
WrapUpAtLimitsは、上限の前の最後の要求でツールを止めて答えさせる
WrapUpAtLimitsは、上限の中であと1回しか要求を送れないと分かったとき、その要求を最後の1回にします。使い方は、エージェントのcapabilitiesに入れるだけです。
from pydantic_ai import Agent
from pydantic_ai.usage import UsageLimits
from pydantic_ai_harness import WrapUpAtLimits, wrapped_up_by
agent = Agent(model, capabilities=[WrapUpAtLimits()]) # model は使っているモデル
# async 関数の中か、Jupyter などで実行する
result = await agent.run('調べて', usage_limits=UsageLimits(request_limit=3))
print(result.output)
if limit := wrapped_up_by(result.new_messages()):
print(f'{limit} で打ち切って答えた')
手元の検索の例では、1回目と2回目の要求でモデルが検索のツールを呼び、3回目の要求は、ツールの定義を残したままtool_choiceを'none'(ツールを呼ばせない)にして送られました。テスト用のモデルが受け取った3回目の要求には、ツールの結果のあとに、「予算はこの最後の1回の応答だけで、ツールは使えないので、今ある情報で答え、終わっていないことを書くように」という意味の英文の指示が足されていました。モデルの答えがresult.outputになり、要求は3回、ツールの呼び出しは2回でした。
答えが打ち切りによるものかは、wrapped_up_by()で分かります。打ち切った場合は、きっかけになった上限の名前('request_limit'、'tool_calls_limit'など)を返し、最後まで終わった場合はNoneを返します。打ち切った答えを利用者に見せるときに、「途中で打ち切った答えです」と添える判断に使えます。
usage_limitsを渡さない実行にも効きます。Pydantic AIの既定の要求の上限は50回で(WrapUpAtLimitsのドキュメント)、手元でも、検索を呼び続けるモデルは、WrapUpAtLimitsを入れると50回目の要求で答え、入れないと50回の要求のあとに「The next request would exceed the request_limit of 50.」のUsageLimitExceededで止まりました。
WrapUpAtLimitsを入れても例外で終わる場合
ドキュメントは、次のカードのような場合は今までどおりUsageLimitExceededで終わると説明しています。打ち切った答えを前提にした処理を書くときも、例外を受け止める処理は残しておきます。
出力の検証
最後の答えが出力の型の検証に通らなかった場合。やり直しに使える要求が残っていない。
残りを見積もらない上限と、見積もりを超えたトークン
cost_limitとper_request_input_tokens_limitは、今までどおり例外になる。トークンの上限は、これまでの応答から見積もって最後の要求を決めるが、使った量が見積もりを超えた場合は例外になる。
一度に多くのツール呼び出し
それまでより多くのツールを一度に呼び、tool_calls_limitを超える場合。呼び出しを実行する前に例外になる。
ツールを呼んでしまうモデル
tool_choice='none'を守らないプロバイダーで、最後の要求でもツールを呼んだ場合。tool_calls_limitを使い切っていれば呼び出しが例外になり、実行できた場合も、次に使える要求が残っていなければ例外になる。
ほかに、最後の要求の時点で、要約のために圧縮の部品がモデルへ要求を送る方式(SummarizingCompaction)が履歴の要約を始めると、そのための要求が残っておらず例外になります。ドキュメントは、FallbackCompaction(fallback_on=(UnexpectedModelBehavior, UsageLimitExceeded))で包み、モデルに要求しない方式へ切り替える方法を示しています。親と予算を共有するサブエージェントは、親の最後の要求を使ってしまい、親が例外になります。サブエージェントには自分のSubAgent.usage_limitsを渡し、WrapUpAtLimitsを入れます。
ReportToolErrorsは、ツールの例外をモデルへの失敗の結果に変える
ReportToolErrorsを入れると、ツールの関数が投げた例外は実行を止めず、「このツールは失敗した」という結果(outcome='failed')としてモデルに渡ります。受け取ったモデルは、同じツールをもう一度呼ぶか、別の方法を試すか、あきらめて答えるかを選べます(ReportToolErrorsのドキュメント)。
from pydantic_ai import Agent
from pydantic_ai_harness import ReportToolErrors
agent = Agent(model, capabilities=[ReportToolErrors()])
@agent.tool_plain
def divide(a: float, b: float) -> float:
return a / b
手元では、divide(1, 0)を呼ぶモデルが、ZeroDivisionErrorで止まる代わりに、次の内容の結果を受け取りました。
`divide` raised ZeroDivisionError
モデルに渡るのはツール名と例外の型だけで、例外のメッセージ(この例の「float division by zero」)は含みません。ドキュメントは、メッセージにはファイルのパス、ホスト名、接続文字列が入ることがあるためと説明しています。メッセージもモデルに見せたいときは、format_errorで文を組み立てます。手元では、次の関数で「divide raised ZeroDivisionError: float division by zero」がモデルに渡りました。メッセージを見せるのは、ツールが投げる例外のメッセージに、モデルに渡してよい内容しか入らないと分かっている場合に限ります。
from pydantic_ai import RunContext
from pydantic_ai_harness import ReportToolErrors
from pydantic_ai_harness.report_tool_errors import ToolErrorInfo
def with_message(ctx: RunContext[None], info: ToolErrorInfo) -> str:
return f'{info.name} raised {type(info.error).__name__}: {info.error}'
report = ReportToolErrors(format_error=with_message)
モデルに返す例外の種類は、exceptionsで絞れます。手元では、ReportToolErrors(exceptions=(TimeoutError,))にすると、ZeroDivisionErrorは今までどおり実行を止めました。通信の一時的な失敗のように、モデルが別の手を試せる例外だけを返し、プログラムの誤りによる例外はすぐに止めたい場合に使います。ドキュメントによると、UsageLimitExceededとUserErrorは、ReportToolErrorsを入れても実行を止めます。ツールが投げるModelRetryは今までどおり再試行の指示として働き、ツールのretriesの回数を超えると実行が止まります。
ReportToolErrorsを入れると変わる、今ある例外処理
ドキュメントによると、ReportToolErrorsがモデルに返した例外では、ほかの部品のon_tool_execute_errorのフックは、部品を並べる順に関係なく呼ばれません。手元でも、例外を記録するフックを持つ部品と一緒に入れると、フックは呼ばれなくなり、exceptions=(TimeoutError,)に絞るとZeroDivisionErrorでフックが呼ばれました。このフックで例外を記録したり立て直したりしている場合は、exceptionsでモデルに返す例外を絞り、フックに残したい例外を外します。Temporalの上で動かすツールの例外は、ReportToolErrorsを入れても今までどおり実行を止めます。
失敗し続けるツールを呼ぶモデルは、WrapUpAtLimitsも入れると答えで終わる
ReportToolErrorsは、失敗の回数を数えず、ツールも使える状態のまま残します。ドキュメントによると、tool_calls_limitは成功した呼び出しだけを数えるので、失敗し続けるツールを呼ぶモデルを止めるのはrequest_limitです。手元で、divide(1, 0)を呼び続けるモデルにrequest_limit=4を付けると、ReportToolErrorsだけでは4回目の要求のあとにUsageLimitExceededで止まりました。WrapUpAtLimitsも入れると、3回の失敗のあと、4回目の要求で、テスト用のモデルに用意した答え(3回失敗したので計算できなかった、という文)を返しました。
# import と divide の定義は前の例と同じ
agent = Agent(model, capabilities=[ReportToolErrors(), WrapUpAtLimits()])
result = await agent.run('1を0で割って', usage_limits=UsageLimits(request_limit=4))
Pydantic AI 2.71.0とpydantic-ai-harness 0.71.0を入れて使う手順
WrapUpAtLimitsとReportToolErrorsは、pydantic-ai本体とは別のパッケージ、pydantic-ai-harnessに入っています。pydantic-ai-harness 0.71.0は、pydantic-ai-slim 2.71.0を版まで決めて必要とするので、本体と一緒に上げます。手元のuv pip install --dry-runでは、pydantic-ai==2.70.0とpydantic-ai-harness 0.71.0の組み合わせは「unsatisfiable」で解決できず、2.71.0との組み合わせは解決できました。
1. 一緒に上げる
pydantic-ai 2.71.0とpydantic-ai-harness 0.71.0を同時に入れる。
2. capabilitiesに入れる
打ち切りで答えさせたいエージェントにWrapUpAtLimits、ツールの失敗をモデルに任せたいエージェントにReportToolErrors。
3. 返す例外を決める
ReportToolErrorsのexceptionsで、モデルに返す例外の種類を絞る。on_tool_execute_errorのフックで例外を記録している場合も絞る。モデルに渡してよいメッセージだけならformat_errorで見せる。
4. 打ち切りを見分ける
wrapped_up_by()で打ち切った答えを見分け、UsageLimitExceededを受け止める処理も残す。
# pip の場合(pydantic-ai-slim を使っているなら、使っている extra も付けて
# pydantic-ai-slim[openai]==2.71.0 のように置き換える)
pip install -U "pydantic-ai==2.71.0" "pydantic-ai-harness==0.71.0"
# uv で管理しているプロジェクトの場合
uv add "pydantic-ai==2.71.0" "pydantic-ai-harness==0.71.0"
pydantic-ai-harnessは0.xの版で、Pydantic AI Harnessのドキュメントは、0.xの間はminorの版でAPIが変わることがあり、その場合は非推奨の警告と移行の案内を出すと説明しています。版を固定して使い、上げるときにリリースノートを確かめます。
参考資料
- Pydantic AI 2.71.0のリリースノート
- PyPIのpydantic-ai-harness 0.71.0
- WrapUpAtLimitsのドキュメント(Wrap Up At Limits)
- ReportToolErrorsのドキュメント(Report Tool Errors)
- Pydantic AI Harnessのドキュメント
- 変更のプルリクエスト: #13670(WrapUpAtLimits)、#13745(ReportToolErrors)
検証環境
- macOS 27.2.1(Apple Silicon)、Python 3.13.14、uv 0.11.32
- pydantic-ai-slim 2.70.0+pydantic-ai-harness 0.70.0、pydantic-ai-slim 2.71.0+pydantic-ai-harness 0.71.0(PyPI)
- 検証日: 2026年11月20日
この記事は、AIが調査と下書きを担当し、上記の環境で実際に動かして結果を確かめ、下書きとは別の担当が公開前に本文と出典を確認しています。制作と訂正の方針は編集・訂正方針で公開しています。










