# OpenAI Agent SDKの便利で実践的な使い方
🌍 長大なコンテキストも安定運用へ。ModelSettings の高度な設定とリトライ戦略で、本番環境でも安心してエージェントを動かしましょう。
モデルの挙動を細かく制御する ModelSettings と、API エラーに自動対応する ModelRetrySettings を組み合わせることで、プロダクションレベルの堅牢なエージェントを構築できます。
📌 タイトル:高度なModelSettings / リトライ
🔗 URL:
🧩 概要
ModelSettings は Agent のモデル呼び出し時のパラメータを一括制御するクラスです。`truncation="auto"` でコンテキスト溢れを自動処理し、`context_management` で 200k トークン閾値のコンパクション(要約圧縮)を設定し、`prompt_cache_retention="24h"` でキャッシュを長時間保持してコストを削減できます。さらに `ModelRetrySettings` で 429/503 などの一時的エラーに対する指数バックオフリトライを宣言的に設定でき、`provider_suggested()` ポリシーでリプレイ安全性も確保します。
🛠 使い方
`Agent`, `ModelSettings`, `ModelRetrySettings` を `agents` からインポートし、`retry_policies` も合わせてインポートします。`Agent` の `model_settings` に `ModelSettings` を渡し、`truncation="auto"`、`context_management` に `[{"type": "compaction", "compact_threshold": 200000}]`(リスト形式)を指定、`prompt_cache_retention="24h"` でキャッシュ保持を設定します。`retry` には `ModelRetrySettings` を使い、`max_retries=4`、`backoff` に `initial_delay=0.5`、`max_delay=5.0`、`multiplier=2.0`、`jitter=True` を設定します。`policy` には `retry_policies.any()` で `provider_suggested()`、`retry_after()`、`network_error()`、`http_status([429, 503])` を組み合わせます。
🏗 実践的な使い方
**コンテキスト溢れへの防御的設定**
長い会話や大量のツール出力でコンテキストが溢れると、API がエラーを返します。`truncation="auto"` を設定すると、古い会話アイテムを自動的に落として処理を続行できます。
`Agent` の `model_settings` に `ModelSettings(truncation="auto", context_management=[{"type": "compaction", "compact_threshold": 200000}])` を設定します。
**コスト最適化のためのキャッシュ保持**
同じプロンプトプレフィックスを繰り返し使うワークフローでは、`prompt_cache_retention` を設定することでキャッシュヒット率を上げ、コストとレイテンシを削減できます。
`Agent` に `ModelSettings(prompt_cache_retention="24h")` を設定した `batch_agent` を作成し、`for doc in documents` ループで `await f"分析対象:\n{doc}")` を繰り返し呼び出します。
**本番向けリトライ戦略**
`provider_suggested()` を最初のポリシーに置くことで、プロバイダが「リトライ不可」と判断したリクエスト(abort エラーやストリーミング出力開始後など)を誤ってリトライすることを防ぎます。
`ModelRetrySettings` で `max_retries=3`、`backoff` に `initial_delay=1.0`、`max_delay=10.0`、`multiplier=2.0`、`jitter=True` を設定します。`policy` には `retry_policies.any()` で `provider_suggested()`(常に最初に配置)、`retry_after()`、`http_status([429, 500, 502, 503])` を組み合わせます。
💡 ユースケース
📚 大量ドキュメント分析で `truncation="auto"` + `context_management` を設定し、コンテキスト溢れを自動回避
💰 バッチ処理で `prompt_cache_retention="24h"` を設定し、同一プレフィックスのキャッシュヒットでコスト削減
🔄 429/503 エラーに `ModelRetrySettings` の指数バックオフで自動リトライし、一時的な API 障害を乗り越える
🛡 `provider_suggested()` を最優先ポリシーに置き、リプレイ不安全なリクエストの誤リトライを防止
⚠️ 注意点
- `truncation="auto"` は古いメッセージを暗黙的に落とすため、重要な初期コンテキストが失われる可能性があります。重要情報は instructions に含めるか、最新メッセージとして再送してください。
- `context_management` のコンパクションは API レベルで行われ、`OpenAIResponsesCompactionSession` とは異なるメカニズムです。両方を同時に使う場合は挙動の違いを理解しておきましょう。
- `provider_suggested()` は `previous_response_id` や `conversation_id` を使うステートフルな呼び出しで特に重要です。汎用ポリシーだけでは安全性が不十分な場合があります。
✨ ModelSettings のきめ細やかな設定とリトライ戦略を組み合わせれば、本番環境でも安定して動作するエージェントを実現できます。まずは `truncation` と `retry` から始めてみましょう!
#
OpenAIAgentSDK# #
AIAgent#