AIエージェントのAPI連携では、モデルにHTTP通信を直接任せるのではなく、許可した操作だけを提供する接続層を用意します。 接続層は、認証情報の保管、入力検証、タイムアウト、再試行、監査記録を担当します。 設計の焦点は「呼び出せるか」ではなく、誰の権限で何を実行し、失敗したときに安全に止まれるかです。
AIエージェント開発を体系的に学びたい方は、AIエージェントが学べるおすすめスクールで、AI活用、Python実装、マンツーマン支援の違いを比較できます。
| 設計項目 | 接続層の役割 | エージェントへ返す情報 |
|---|---|---|
| 認証 | 資格情報の取得と更新 | 操作の可否 |
| 入力 | 型と業務条件の検証 | 修正できるエラー |
| 通信 | 期限と再試行の制御 | 成功、失敗、保留 |
| 更新 | 重複実行の防止 | 処理IDと状態 |
| 監査 | 呼び出し記録 | 必要最小限の結果 |
APIごとに操作名と入力を固定する
汎用の「任意URLを呼ぶ」道具を渡すと、接続先と操作を制御できません。「顧客番号から契約状態を取得する」「下書きチケットを作成する」のように、業務単位の操作として公開します。
OpenAPI Initiativeの公式仕様では、APIのパス、操作、入力、応答、セキュリティ要件を機械可読に記述できます。Google CloudのAPI設計ガイドも、リソースと標準操作を一貫して設計する考え方を示しています。
公開前の確認手順。
- 読み取りと更新を別の操作にする
- 必須入力と許容値を定義する
- 返却する項目を必要最小限にする
- 業務エラーと通信エラーを分ける
- 更新操作へ確認条件を付ける
認証情報はモデルの文脈へ入れない
APIキーやアクセストークンをプロンプトへ書くと、出力やログへ混ざる危険があります。資格情報は接続層で保管し、エージェントには操作の成功、権限不足、再認証の必要性だけを返します。
OAuth 2.0のRFC 6749は、利用者の認可を得てアクセストークンを発行する枠組みを定義しています。OAuth 2.0 Security Best Current Practiceでは、現在の脅威を踏まえた安全な実装上の推奨事項が整理されています。
| 認証方式 | 向く用途 | 主な注意点 |
|---|---|---|
| APIキー | サーバー間の限定操作 | 保存先と交換手順 |
| OAuth | 利用者ごとの代理操作 | 同意範囲と更新 |
| サービスアカウント | 組織内の定期処理 | 権限の過大付与 |
| 短期トークン | 一時的な実行 | 期限切れ処理 |
再試行してよい失敗を限定する
すべてのエラーを自動再試行すると、二重登録や負荷増大を招きます。タイムアウト、一時的な混雑、明示された待機時間など、回復可能な失敗だけを対象にします。認証失敗、入力不備、権限不足は、そのまま繰り返しても直りません。
HTTP SemanticsのRFC 9110では、状態コードやRetry-Afterなどの意味が定義されています。待機時間を尊重し、試行回数に上限を置き、一定回数を超えたら人または保留キューへ渡します。
再試行の判断項目。
- 同じ要求を繰り返しても結果が壊れないか
- サーバーが待機時間を返しているか
- 最大試行回数と総待ち時間を決めたか
- 一部成功を検出できるか
- 処理IDで重複を見分けられるか
結果を成功、確認待ち、失敗に分ける
エージェントへ生のエラー全文を返すだけでは、次の行動を安定して選べません。接続層で「成功」「利用者の確認待ち」「入力修正が必要」「一時失敗」「恒久失敗」へ正規化し、再実行の可否も添えます。
ログには、操作名、利用者、対象、処理ID、開始時刻、結果を残します。トークンや個人情報の全文は記録せず、調査に必要な識別子へ絞ります。
AIエージェントの作り方では、API接続を含む試作全体の組み立て方を確認できます。
AIエージェントのAPI連携でよくある質問
APIキーをプロンプトへ書いてもよいですか？
書かない方が安全です。APIキーは秘密情報の保管機能やサーバー側の環境へ置き、接続層が要求時に付与します。モデルへはキーそのものではなく、操作が許可されたか、再認証が必要かという状態だけを渡します。
エラーが出たら何回まで再試行すべきですか？
一律の回数では決められません。APIの公式仕様、処理の重複可能性、許容待ち時間を基に上限を設定します。認証や入力のエラーは再試行せず、一時的な混雑だけを間隔を広げながら再試行します。
更新APIを自動実行させるときの注意点は何ですか？
対象と変更内容を実行前に表示し、取り消しにくい操作では利用者の確認を挟みます。処理IDによる重複防止、権限の最小化、監査ログ、取り消し手段も用意し、読み取り操作とは別に扱います。
API連携は権限と失敗の境界から設計する
安全なAPI連携は、モデルの賢さではなく、接続層が許可する操作と失敗時の遷移で決まります。正常系より先に、資格情報の扱いと止まり方を決めます。
- APIは業務単位の狭い操作として公開
- 認証情報は接続層へ置き、モデルへ渡さない
- 再試行は回復可能で重複しない失敗だけ
- 結果は次の行動を選べる状態へ正規化
接続後の品質を確かめるには、AIエージェントのテスト方法で出力と操作を分けて試験します。
