# OpenAI Agent SDKの便利で実践的な使い方 🌍 モデルに送る入力をフィルタリングしたり、エラー時の挙動を細かく制御したいことはありませんか？ Input filterとError handlerを使えば、エージェントの振る舞いを安全かつ柔軟にカスタマイズできます。 📌 タイトル：Running agents – Hooks and customization / Error handlers 🔗 URL： 🧩 概要 `call_model_input_filter`はモデルへの入力を直前に加工するフックで、履歴のトリミングやシークレットのマスキングに使えます。`error_handlers`はツールエラーやモデル拒否など特定のエラーに対して、例外を投げずにアプリ固有のフォールバック出力を返す仕組みです。これらを組み合わせることで、プロダクションレベルの堅牢なエージェントを構築できます。 🛠 使い方 `agents`から`Agent`, `Runner`, `ErrorHandlers`をインポートします。`trim_history(input_data)`関数で`input_data.messages`を直近10件に制限し、`mask_secrets(input_data)`関数で`msg.content.replace(os.environ.get("API_KEY", ""), "***")`によりシークレットをマスキングします。`handle_refusal(ctx, error)`ではモデル拒否時にドメイン固有のフォールバック出力を返します。エージェントは`Agent(name="chef", instructions="You are a recipe assistant.", call_model_input_filter=trim_history, error_handlers=ErrorHandlers(model_refusal=handle_refusal, max_turns=lambda ctx, err: FallbackOutput(message="処理が完了しませんでした。入力を短くしてお試しください。", include_in_history=False)))`のように設定します。 🏗 実践的な使い方 **履歴トリミングでコスト制御** `call_model_input_filter`で直近N件のメッセージだけをモデルに送ることで、長時間会話でのトークン消費を抑制できます。重要なシステムプロンプトは常に先頭に保持しつつ、古いユーザーメッセージを削除するパターンが実用的です。 **シークレットのマスキング** ツールの戻り値にAPIキーやトークンが含まれる場合、`call_model_input_filter`でモデルに送る前にマスキングできます。モデルが機密情報を学習したり、出力に含めたりするリスクを低減できます。 **システム指示の動的注入** フィルタ内でユーザーの権限レベルやコンテキストに応じたシステム指示を追加注入できます。「この顧客はプレミアムプランです」のような動的な情報をモデルに伝えるのに便利です。 **max_turnsエラーのグレースフルフォールバック** ループに入ったエージェントが`max_turns`に達した場合、例外ではなくユーザー向けの丁寧なメッセージを返せます。`include_in_history=False`にすれば、フォールバック出力が次のターンの履歴に残らず、リトライ時にクリーンな状態を保てます。 **モデル拒否のアプリ固有処理** `ModelRefusalError`をキャッチして汎用エラーを返す代わりに、アプリのドメインモデルに沿った構造化されたフォールバックを返せます。レシピアプリなら`refusal_reason`付きの空レシピ、チャットなら代替提案メッセージなど。 💡 ユースケース 🔒 APIキーやトークンがモデルに送信されるのを防止 📏 長時間チャットの履歴を自動トリミングしてコスト最適化 🔄 max_turnsエラー時にユーザーへ次のアクションを案内 🛡 モデル拒否時にアプリ固有の構造化フォールバックを返却 ⚠️ 注意点 - `call_model_input_filter`でメッセージを削除しすぎると、モデルが文脈を失い回答品質が低下します。重要なシステムプロンプトは必ず残してください。 - `error_handlers`のフォールバック出力が`output_type`と型が一致していることを確認してください。型不一致はランタイムエラーになります。 - `include_in_history=False`にしたフォールバック出力は次ターンで参照できません。ユーザーに表示するだけで会話の文脈には不要な情報に使ってください。 - フィルタやハンドラ内で例外を投げると、エージェント全体が停止します。フィルタ内のロジックは防御的に書いてください。 ✨ Input filterとError handlerを活用して、エッジケースに強い堅牢なエージェントを構築しましょう！ #OpenAIAgentSDK# #AIAgent#