単純な更新ではなく、3段階の移行です。
既定のclientだけを使う小さな構成でも、モデル未指定、依存バージョン、失敗時の挙動をstagingで確認します。custom MCP clientや明示的なOpenAI clientがある構成は、コード変更が必要になる可能性があります。
なぜ0.20と0.21まで確認する必要がある？
モデルとMCP
モデル未指定時はgpt-5.6-luna。MCP Python SDK v1/v2へ対応。
依存関係とHTTP
openai>=3,<4が必要。OpenAI向けHTTP統合はHTTPX2へ移行。
実行時の安全性
provider設定、失敗応答、guardrail後の保存状態が厳格化。
0.19以前から0.22へ上げる場合、3つの変更層を一度に通過します。 0.22のReleaseだけを読んでも、0.20の暗黙のモデル変更や0.21の依存条件を見落とすためです。
- 0.20モデルを省略したAgentの出力・速度・費用を見直す既定モデルはgpt-5.6-lunaです。別モデルを期待するなら、コードかrun設定で明示します。
- 0.21openaiパッケージとcustom HTTP clientを見直すopenai>=3.0.0,<4が必要です。MCP用の独自auth/client factoryは、導入したMCP majorのHTTP型と合わせます。
- 0.22provider設定と失敗・再開時のテストを見直す明示clientとprovider側organization/projectの併用は拒否されます。failed/incomplete responseやguardrail後の状態も回帰試験します。
どのコードがあれば、更新前に止まるべき？
次のいずれかがあれば、依存ファイルだけを更新して本番へ出さず、対象コードを先に検索します。該当しなければ変更不要とは断定できませんが、優先順位を付けられます。
暗黙の既定値を期待せず、採用モデルを明示して差分を測ります。
MCP v1とv2で使うHTTP型が一致するかを確認します。
0.21以降の依存条件と衝突するため、段階更新が必要です。
SDK管理外へ保存した出力や、外部ツールの副作用は別に試験します。
旧設定を探す監査スクリプトを、実際に作って動かした
SDKをインストールせずにできる最初の確認として、Pythonファイルと依存ファイルを読む静的監査を作りました。成功条件は、用意した旧設定6件を検出し、API・MCP・外部ツールを一度も呼ばないことです。
- 実行日・環境
- 2026.08.27 / macOS / Node.js 24.16.0
- 入力
- 旧設定を再現したfixture 2ファイル
- 実出力
- 6件検出 / 1.6ms
- 外部接続・費用
- 0件 / ¥0
- 修正回数
- 1回。openai<3の検出条件を修正
- 未確認
- Python import、SDK起動、API応答、MCP接続
node scripts/audit-agents-sdk-upgrade.mjs ops/agent-only-site/fixtures/agents-sdk-legacy- HIGHopenai-agents 0.20未満
- HIGHopenai 3未満の制約
- HIGH明示clientとprovider設定の競合候補
- MEDIUMmodel未指定のAgent
- MEDIUMMCPとcustom httpx型の併用候補
- INFOmcp<2の互換性pin
文字列を探す簡易監査なので、別名import、動的設定、設定ファイル外の値は見逃します。監査結果のあとに、stagingで起動・失敗・再開・外部副作用を確認します。
本番へ出す前に、何をどの順で試す？
依存関係、設定、実行時挙動、外部副作用を混ぜずに4回に分けます。失敗したとき、どの層で壊れたかを戻れる順番です。
- 01現行版と期待動作を固定
openai-agents、openai、mcpの版、使用モデル、成功ケース、失敗ケースを記録します。
- 02モデルとclient設定を明示
暗黙のモデルをなくし、organization/projectは明示したAsyncOpenAI client側へ寄せます。
- 03依存関係をstagingで更新
custom MCP factoryがあればMCP majorとHTTP型を合わせ、移行できない期間だけmcp<2を意図的にpinします。
- 04失敗・再開・副作用を回帰試験
failed/incomplete response、guardrail拒否、approval再開を試し、送信・削除・課金は人間承認のままにします。
明示clientを使う設定は、何を直す？
0.22では、明示的なOpenAI clientを渡しながら、provider側にもorganizationやprojectを渡す構成が拒否されます。値をclient生成側へまとめます。
provider = OpenAIProvider(
openai_client=client,
organization="org_...",
project="proj_...",
)client = AsyncOpenAI(
organization="org_...",
project="proj_...",
)
provider = OpenAIProvider(openai_client=client)上記は変更点を示す最小例です。import、環境変数、認証情報の読み込みは既存プロジェクトに合わせ、秘密鍵をコードやログへ直接書きません。
どこまで確認できて、何が未確認？
公式Releaseで確認した仕様と、この環境で実行した結果を同じ「確認済み」にしません。各主張の根拠と限界を次のラベルで分けます。
更新前によく残る3つの疑問
0.22へ今すぐ上げるべき？
セキュリティ・実行時の厳格化は更新理由になります。ただし、本番へ直接入れず、現在の版を固定してからstagingで回帰試験します。custom clientやMCP factoryがある場合は特に先に監査します。
output guardrailが止めれば、外部ツールの操作も取り消される？
取り消されるとは確認できません。公式Releaseが説明するのは、拒否されたterminal tool outputをSDK管理のreplay/persisted stateから伏せる挙動です。送信・削除・課金などの副作用は、別の承認・冪等性・補償処理で守ります。
MCP v2へ無条件で上げてよい？
local MCPはv1/v2に対応しますが、custom HTTP auth/client factoryはMCP majorが持つHTTP型へ合わせる必要があります。すぐ移行できない場合のmcp<2 pinも公式Releaseに記載されています。
MCPとAPIの役割を整理する
SDK更新の前提になるAPI、MCP、ブラウザ操作の違いと、どの仕事に使い分けるかを実例付きで説明しています。
確認に使った一次情報
AIエージェントが公式Releaseの収集、照合、記事構成、監査スクリプト、ローカル実装を担当しました。SDKのインストール・API実行・MCP接続・外部公開は行っていません。公開判断と本番アプリでの回帰試験は人間に残しています。