DEV Community

Cover image for APIバージョニング：AIエージェントにおける破壊的変更への対応
Akira
Akira

Posted on Originally published at apidog.com

APIバージョニング：AIエージェントにおける破壊的変更への対応

APIドリフトからAIエージェントを守る：バージョン固定、コントラクトテスト、実行時検証

APIチームがcustomer_nameをcustomer_full_nameへ変更し、告知・ドキュメント更新・人間が保守するクライアントの修正まで完了したとします。しかし、誰もエージェントをAPIクライアントとして扱っていなければ、エージェントは古いフィールドを送り続けます。APIは未知のキーを無視して200を返し、結果として2週間、エージェントが作成したレコードには名前が空のまま保存される可能性があります。

今すぐApidogを試す

エージェントは、変更に最も気づきにくく、問題をもっともらしくごまかしやすいAPIコンシューマーです。通常のクライアントは例外で停止しますが、エージェントは200を成功と判断し、不完全な結果を使って処理を続けることがあります。

この記事では、エージェントがAPIドリフトに弱い理由、危険な変更、バージョン固定、CI・実行時検証、段階的なアップグレード方法を説明します。AIエージェントが本番環境で壊れる理由もあわせて確認してください。

Apidogが有効なのは、APIドリフトを仕様差分として機械的に検出できるためです。

エージェントが変更に気づきにくい4つの理由

  • 暗黙の許容

    多くのAPIは未知のリクエストフィールドを無視します。フィールド名変更後も古いキーは破棄され、200だけが返るため、失敗が表面化しません。

  • 即興的な対応

    レスポンスに必要な値がなくても、モデルは停止せず、もっともらしい値で補完しようとします。会話では便利でも、API連携では危険です。

  • プロンプト内の説明

    エージェントのツール説明には、APIに関する前提がテキストとして埋め込まれています。API変更によって説明が古くなると、コードを変えなくても誤ったツール呼び出しが発生します。ツールスキーマの設計では、この説明がエージェントの振る舞いに与える影響を解説しています。

  • コンパイラがない

    型付きクライアントは、削除されたフィールドをビルド時に検出できます。一方、エージェントの契約はJSONスキーマや散文に存在するため、呼び出し失敗時、あるいは静かな誤動作が起きるまで見落とされがちです。

通常のクライアントにとって安全な変更でも、エージェントにとって安全とは限りません。変更レビューでは、エージェント向けの影響を別途評価してください。

エージェントを壊す変更

すべてのクライアントにとって破壊的な変更

以下はエージェントにも破壊的ですが、より静かに失敗する傾向があります。

  • エンドポイントの削除
  • フィールドの削除・改名
  • 型の変更
  • オプションパラメータの必須化
  • URLの変更

型付きクライアントには安全でも、エージェントには危険な変更

  • 新しい必須フィールド

    エージェントは検証エラーを受けると、値を生成して修正しようとする場合があります。明確な失敗より危険です。

  • 新しいenum値

    通常のクライアントは未知の値を無視することがありますが、エージェントは意味を推論し、意図しない結論を導く可能性があります。

  • 検証ルールの厳格化

    以前は任意文字列だった入力にパターン制約が追加されても、エージェントは自力で新ルールを学習できません。ルールはエラーメッセージに含めてください。AIエージェント向けAPIエラー設計を参照してください。

  • デフォルト値の変更

    たとえばページネーションの既定値が100から20に変わり、limitを送らないエージェントがデータの5分の1だけを完全な結果として報告することがあります。

  • ドキュメント表現の変更

    動作が同じでも、仕様からツールを生成している場合は、説明文の変更がツール選択を変えることがあります。OpenAPI仕様をエージェントツールに変換する場合は特に注意が必要です。

エージェントにも安全な変更

  • オプションフィールドの追加
  • エンドポイントの追加
  • 既定値を維持したオプションパラメータの追加
  • 検証ルールの緩和

中間カテゴリの変更こそ、標準的なAPI変更レビューで見落とされやすいポイントです。

すべてのリクエストでバージョンを固定する

最初の防御策は、APIを暗黙にアップグレードしないことです。

パス、ヘッダー、アカウント単位のピンなど、APIが提供する方式で明示的にバージョンを送ってください。GitHubのAPIバージョン管理は日付ヘッダーを使い、Stripeはアカウント単位でバージョンを固定します。どちらも「自分で決めるまで動作を変えない」という特性を提供します。

DEFAULT_HEADERS = {
    "X-API-Version": "2026-06-01",
    "User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}
Enter fullscreen mode Exit fullscreen mode

User-Agentも重要です。APIプロバイダーが非推奨化を通知するとき、識別可能なエージェントなら連絡を受けられます。既定のライブラリ文字列だけを送るクライアントでは、通知先を特定できません。

自社APIを運用しているなら、バージョンを公開して維持してください。最適なAPIバージョン管理戦略とApidogでのAPIバージョン管理が参考になります。

バージョン管理のないサードパーティAPIでは、構築時に想定したレスポンス形状を記録し、継続的に検証してください。

実行前にAPIドリフトを検出する

バージョン固定は猶予を作りますが、アップグレードや無版管理APIの変更を防ぐものではありません。次の3層で検出してください。

1. スケジュールで仕様差分を確認する

プロバイダーがOpenAPIドキュメントを公開しているなら、毎日取得し、ツール生成に使ったコピーと比較します。

確認対象は次のとおりです。

  • フィールドの削除
  • 型の変更
  • 必須化
  • enumの追加
  • 説明文の変更

Apidogでは、インポートした定義をプロジェクト内に保持し、バージョン間の差分を確認できます。「何か変わったか」を調査ではなくレポートとして扱えます。

2. 呼び出すエンドポイントにコントラクトテストを置く

各エージェントツールについて、既知の正常なリクエストを送り、レスポンス形状を検証します。

  • 必須フィールドが存在する
  • 値が期待する型である
  • enum値が許可された集合に含まれる

この方法は、仕様を公開しないAPIのドリフトにも有効です。APIコントラクトテストと双方向コントラクトテストを参照してください。

3. 実行時にレスポンス形状を検証する

ツールラッパー内でレスポンスを期待スキーマに照合し、欠落は失敗、新規フィールドは警告として扱います。

def check_shape(tool_name, payload, expected):
    missing = [f for f in expected["required"] if f not in payload]
    extra = [f for f in payload if f not in expected["properties"]]
    if missing:
        log.error("api_drift", tool=tool_name, missing=missing)
        raise ApiDriftError(f"{tool_name}: missing fields {missing}")
    if extra:
        log.warning("api_new_fields", tool=tool_name, fields=extra)
    return payload
Enter fullscreen mode Exit fullscreen mode

必須フィールドが欠けている場合、エージェントは不完全なデータで作業しようとしています。そこで停止してください。新しいフィールドは通常追加的なので、実行を止めずに警告として記録します。両方をエージェントツール呼び出しのトレースへ送ると、調査しやすくなります。

4. スキーマだけでなく振る舞いも監視する

変更された既定値、厳格化されたレート制限、レスポンス遅延は、スキーマ差分だけでは見えません。少なくとも次をエンドポイント単位で追跡してください。

  • 完了タスクあたりのツール呼び出し数
  • 再試行率
  • 平均レスポンスサイズ

これらが段階的に変化した場合、アップストリームで変更が起きた可能性があります。

エージェントを壊さずにアップグレードする

新しいAPIバージョンへの移行は、エージェント自体の変更として扱ってください。

  1. ツールを手編集せず、仕様から再生成する

    スキーマと説明文の同期を保てます。

  2. 生成済みツール定義の差分を確認する

    API変更ログより、実際の影響範囲を正確に把握できます。

  3. 新バージョンのモックでエージェントを実行する

    本番に出す前に、タスクスイート全体を新しいレスポンス形状で試します。本番ではなくモックに対してエージェントを実行する方法を利用してください。

  4. ツール選択スイートを再実行する

    説明文の変更は、モデルが選ぶツールを変えることがあります。固定プロンプトに対するツール選択を検証してください。非決定性AIエージェントのテストが参考になります。

  5. フラグ配下で段階的にロールアウトする

    古いバージョンを固定したまま、一部トラフィックから新バージョンを有効化します。呼び出し数、再試行率、レスポンスサイズなどを少なくとも1日監視してください。

本番に到達した3つのドリフト例

名前変更されたフィールド

customer_nameが変更され、すべての呼び出しは200を返し続けました。しかし、すべてのレコードで名前が空になり、人間がレポートを見るまで2週間発見されませんでした。

レスポンスの実行時形状チェックがあれば、期待していた読み取りフィールドの欠落を最初の呼び出しで検出できたはずです。

厳格化されたページネーションの既定値

プロバイダーが既定ページサイズを100から20へ減らしました。limitを送らないエージェントは20件だけを見て、それを完全なデータセットとして要約しました。エラーはなく、要約だけが自信を持って間違っていました。

修正は明示的にlimitを送る一行です。既定値に依存することは、他者の判断に対する未宣言の依存関係を作ることでもあります。

新しいenum値

支払いAPIにstatus: "disputed"が追加されました。型付きクライアントはそれを無視しましたが、エージェントは「係争中」を「返金済み」と解釈し、実際には一致していない帳簿を一致していると報告しました。

enumを明示的に検証していれば、モデルに意味を推論させる代わりに、未知の値として停止できました。

これらの変更はすべて告知され、プロバイダー側では追加的または軽微と分類されていました。しかし、エージェントには破壊的でした。この分類の差を設計に取り込む必要があります。

非推奨化を作業項目として扱う

非推奨化の警告は、変更ログ、メール、レスポンスヘッダーで届きます。しかし、エージェントの保守者に届かないことは珍しくありません。

DeprecationヘッダーとSunsetヘッダーを記録し、初回検出時にアラートを出してください。3%の呼び出しで見えるヘッダーでも、サンセット日には全面障害になる可能性があります。

また、次のインベントリを維持してください。

エージェント名 / プロバイダー / APIバージョン / エンドポイント / 所有者
Enter fullscreen mode Exit fullscreen mode

10行程度のファイルでも十分です。非推奨通知を受けたとき、「影響を受けるか」をgrepに何時間もかけず、1分で答えられます。

ドリフトに担当者を割り当てる

仕様差分、失敗したコントラクトテスト、初めて観測した非推奨ヘッダーは、いずれも期限付きの作業項目です。所有者のいないアラートは、障害が起きる日まで放置されます。

チームが普段から作業を追跡している場所にドリフトを登録してください。Sharklyでは、タスクをエージェントまたはクルーに割り当て、目標・実行トレース・レビューを一か所に集約できます。「支払いAPIがこのエンドポイントを非推奨にした」という通知を、スレッドのメッセージではなく、結果を持つ担当タスクに変えられます。

どのツールを使う場合でも原則は同じです。所有者のいないドリフトアラートは、将来の障害です。

チェックリスト

  • すべてのリクエストが明示的なAPIバージョンと識別可能なUser-Agentを送信している。
  • サードパーティ仕様をスケジュールで取得し、差分を比較している。
  • エージェントが呼び出せるすべてのツールに、レスポンス形状を検証するコントラクトテストがある。
  • ツールラッパーが実行時にレスポンスを検証し、欠落時は失敗、新規項目は警告している。
  • エンドポイントごとの振る舞いメトリクスを追跡している。
  • バージョンアップ時はツールを手編集せず、再生成している。
  • タスクスイートとツール選択スイートを、新バージョンのモックで先に実行している。
  • ロールアウトをフラグで制御し、旧バージョンを固定したまま戻せる。

APIチームが変更を継続的に出すこと自体は問題ではありません。重要なのは、エージェントを変化に気づけるAPIクライアントにすることです。バージョンを固定し、コントラクトテストを実行し、実行時にレスポンス形状を検証してください。本番前の仕様比較と次バージョンのモックには、Apidogをダウンロードして活用できます。

よくある質問

サードパーティAPIの仕様変更はどのくらいの頻度で確認すべきですか？

ほとんどの場合、毎日で十分です。仕様が公開されていないAPIでは、CIで実行するコントラクトテストに頼ってください。外部から同じ種類のドリフトを検出できます。

常に最も古い動作バージョンに固定すべきですか？

いいえ。目的はアップグレードを意図的な作業にすることです。固定したうえで、計画に従ってアップグレードしてください。削除されるまで古いバージョンに留まると、計画的な変更が緊急対応になります。

API変更後もエージェントが正常に動くなら問題ありませんか？

仮定せずに検証してください。フィールド名変更後も200を返すような静かな失敗は、成功した実行だけでは見つかりません。形状アサーションで確認します。

エージェント向けに自社APIを別の方法でバージョン管理すべきですか？

方法自体を変える必要はありませんが、より厳格に扱うべきです。新しい必須フィールド、enum値、既定値変更は、型付きクライアントには追加的でも、エージェントには破壊的になり得ます。同じように告知・検証してください。

どのエージェントがどのエンドポイントを呼んでいるかは、どう確認しますか？

トレースを使います。実行ごとのツール名とエンドポイントから依存関係マップを作れば、非推奨化の影響範囲を特定できます。エージェントツール呼び出しのトレースを参照してください。

エージェントはAPI変更に自律的に適応できますか？

適応できる場合もありますが、それに依存すべきではありません。欠落フィールドを即興で補うモデルは、問題のシグナルなしにもっともらしい出力を作ります。大きく失敗させ、ツール定義と実装を修正してください。

Top comments (0)