# OpenAI Agent SDKの便利だけど知られていない機能 🌍 プロンプトをコードにハードコードせず、プラットフォーム側で管理・バージョニングしたいと思いませんか？ Prompt テンプレートを使えば、OpenAIプラットフォームで作成したプロンプトをSDKから参照し、変数を差し込んで利用できます。 📌 タイトル：Prompt テンプレート 🔗 URL： 🧩 概要 `instructions` の代わりに `prompt` パラメータを使うと、OpenAIプラットフォームで作成・管理されたプロンプトテンプレートを参照できます。静的な指定では `{"id": "pmpt_123", "version": "1", "variables": {...}}` のように辞書で渡します。動的な指定では非同期関数を渡し、実行時にプロンプト辞書を返すことで、コンテキストに応じた変数の差し込みが可能です。 🛠 使い方 ```python from agents import Agent, RunContextWrapper # 静的テンプレート参照 agent_static = Agent( name="support", prompt={ "id": "pmpt_abc123", "version": "1", "variables": { "company_name": "Acme Corp", "support_level": "premium", }, }, ) # 動的テンプレート参照 async def dynamic_prompt( context: RunContextWrapper[UserContext], agent: Agent, ) -> dict: user = context.context return { "id": "pmpt_abc123", "version": "2", "variables": { "company_name": "support_level": user.plan, "language": user.language, }, } agent_dynamic = Agent( name="dynamic-support", prompt=dynamic_prompt, ) ``` 🏗 本番システムへの組み込み方 ・プロンプトをプラットフォーム側で管理し、コードデプロイなしで更新・ロールバックする ・バージョン指定で安定した動作を保証しつつ、新バージョンを段階的にロールアウトする ・動的テンプレートでユーザー属性に応じた変数を注入する ・チーム間でプロンプトを共有・再利用し、品質の標準化を図る 💡 ユースケース 📝 プロンプトのバージョン管理と段階的ロールアウト 🏢 組織横断的なプロンプトの共有・標準化 🔄 コードデプロイ不要のプロンプト更新 👤 ユーザー属性に応じたテンプレート変数の動的注入 ⚠️ 注意点 `prompt` と `instructions` は排他的で、両方を同時に指定するとエラーになります。プラットフォームにプロンプトが存在しない場合もエラーになるため、デプロイ前にIDとバージョンの存在を確認してください。変数名のタイポにも注意しましょう。 ✨ Prompt テンプレートで、プロンプト管理を「コードの中」から「プラットフォームの管理画面」に移行しましょう。 #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 ツールの結果をそのまま最終出力にしたいのに、モデルが余計な要約を挟んでいませんか？ `tool_use_behavior` を設定すれば、ツール出力をそのまま最終結果にしたり、特定のツールで停止させるなど、出力の制御を細かくカスタマイズできます。 📌 タイトル：tool_use_behavior 🔗 URL： 🧩 概要 `tool_use_behavior` はエージェントがツールを呼び出した後の挙動を制御するオプションです。`"stop_on_first_tool"` を指定すると、最初のツール出力がそのまま最終出力になります。`StopAtTools(stop_at_tool_names=[...])` で特定ツールのみ停止対象にできます。さらにカスタム関数を渡せば、`ToolsToFinalOutputResult(is_final_output=True, final_output=...)` を返すことで、出力を加工してから最終結果にすることも可能です。 🛠 使い方 ```python from agents import Agent, StopAtTools, ToolsToFinalOutputResult # 最初のツール出力をそのまま最終結果に agent_direct = Agent( name="direct", tools=[search_tool], tool_use_behavior="stop_on_first_tool", ) # 特定ツールでのみ停止 agent_selective = Agent( name="selective", tools=[search_tool, format_tool, send_tool], tool_use_behavior=StopAtTools( stop_at_tool_names=["format_tool"] ), ) # カスタム関数で出力を制御 def custom_behavior(context, tool_results): result = tool_results[0] if result.tool_name == "get_answer": return ToolsToFinalOutputResult( is_final_output=True, final_output=f"回答: {result.output}", ) return ToolsToFinalOutputResult(is_final_output=False) agent_custom = Agent( name="custom", tools=[get_answer, search_tool], tool_use_behavior=custom_behavior, ) ``` 🏗 本番システムへの組み込み方 ・API呼び出し結果をそのまま返すプロキシ型エージェントに `"stop_on_first_tool"` を活用する ・パイプライン内の特定ステップで出力を確定させ、無駄なLLM呼び出しを削減する ・カスタム関数で出力フォーマットを統一し、下流システムとのインテグレーションを安定させる ・構造化データ（JSON等）をモデルに要約させず、そのまま後続処理に渡す 💡 ユースケース 🔌 API結果をそのまま返すプロキシエージェント 📊 データベースクエリ結果の直接出力 🔄 パイプラインの中間ステップでの出力確定 🎯 特定ツールの結果だけを最終出力にする選択的制御 ⚠️ 注意点 `"stop_on_first_tool"` を使うと、モデルによる結果の解釈や補足が行われなくなります。ユーザー向けの分かりやすい出力が必要な場合はカスタム関数で調整してください。複数ツールが並列呼び出しされた場合の挙動も事前に確認しましょう。 ✨ `tool_use_behavior` で、エージェントの出力を「モデル任せ」から「設計通り」に制御しましょう。 #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 ネストしたエージェントツールの実行中、進捗をリアルタイムにストリーミングしたいと思いませんか？ `on_stream` コールバックを使えば、子エージェントの実行イベントを親側でリアルタイムに受け取れます。 📌 タイトル：ネストしたエージェント実行のストリーミング 🔗 URL： 🧩 概要 エージェントを `as_tool()` でツール化する際、`on_stream` パラメータにコールバック関数を設定できます。このコールバックは `AgentToolStreamEvent` を受け取り、子エージェントの実行中に発生するイベント（`raw_response_event`、`run_item_stream_event` など）をリアルタイムで処理できます。イベントの種類は通常のストリーミングと同じ形式なので、既存のストリーミングハンドラを再利用できます。 🛠 使い方 ```python from agents import Agent, Runner research_agent = Agent( name="researcher", instructions="トピックについて詳細に調査してください", ) # ストリーミングコールバック async def handle_stream(event): # raw_response_event: モデルのレスポンス # run_item_stream_event: ツール呼び出し等 if hasattr(event, 'data'): print(f"[研究中] {") parent = Agent( name="coordinator", tools=[ research_agent.as_tool( tool_name="research", tool_description="トピックを調査する", on_stream=handle_stream, ), ], ) # ストリーミング実行 async for event in "AIの最新動向を調査して"): print(event) ``` 🏗 本番システムへの組み込み方 ・子エージェントの処理進捗をUIにリアルタイム表示し、ユーザーに待機感を与えない ・`raw_response_event` で生成テキストを逐次表示する ・`run_item_stream_event` でツール実行状況をログに記録する ・既存のストリーミングUIコンポーネントをそのまま再利用できる 💡 ユースケース 🖥 マルチエージェントの処理進捗をリアルタイムUI表示 📝 子エージェントの応答をタイプライター風に逐次表示 🔍 調査エージェントの検索・分析プロセスの可視化 📊 長時間処理の途中経過をユーザーにフィードバック ⚠️ 注意点 `on_stream` コールバックは子エージェントの実行スレッド内で呼ばれるため、重い処理を行うとエージェント全体のパフォーマンスに影響します。イベントハンドラは軽量に保ち、必要に応じて非同期キューに渡すなどの工夫をしてください。また、すべてのイベント型に対応できるよう、未知のイベントを無視するガード処理を入れておくと安全です。 ✨ ストリーミングで、マルチエージェントの「中身が見える」体験をユーザーに届けましょう。 #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 ツールが多すぎてトークンを圧迫していませんか？必要なときだけツールを読み込む仕組みがあります。 `defer_loading` と `ToolSearchTool` を組み合わせれば、モデルが必要なツールを検索して動的にロードでき、トークン消費を大幅に削減できます。 📌 タイトル：Hosted tool search / tool_namespace / defer_loading 🔗 URL： 🧩 概要 `@function_tool(defer_loading=True)` を指定したツールは、初回のモデル呼び出し時にはツールリストに含まれません。代わりに `ToolSearchTool()` をエージェントに追加すると、モデルはまずツールを検索し、必要なものだけをロードして使用します。`tool_namespace` でツールをグループ化することも可能です。大量のツールを持つエージェントで、トークン使用量を最適化する強力な機能です。なお、この機能は `OpenAIResponsesModel` でのみ利用可能です。 🛠 使い方 ```python from agents import Agent, function_tool from agents.tool import ToolSearchTool @function_tool(defer_loading=True, tool_namespace="analytics") def run_report(report_type: str) -> str: return generate_report(report_type) @function_tool(defer_loading=True, tool_namespace="analytics") def export_csv(dataset: str) -> str: return create_csv(dataset) @function_tool(defer_loading=True, tool_namespace="admin") def manage_users(action: str) -> str: return user_management(action) agent = Agent( name="assistant", tools=[ ToolSearchTool(), # ツール検索を有効化 run_report, export_csv, manage_users, ], ) ``` 🏗 本番システムへの組み込み方 ・数十〜数百のツールを持つエージェントでトークンコストを抑える ・`tool_namespace` でツールを論理的にグループ化し、検索精度を向上させる ・頻繁に使うツールは `defer_loading=False`（デフォルト）のままにし、稀に使うツールだけ遅延ロードにする ・ツール追加時にプロンプトサイズを気にせずスケールできる 💡 ユースケース 🧰 多機能SaaSエージェントのツール管理 📊 分析・レポート系ツールのオンデマンドロード 🔧 管理系ツールの必要時のみ表示 🚀 ツール数のスケーラビリティ確保 ⚠️ 注意点 この機能は `OpenAIResponsesModel` でのみ利用可能です。他のモデルプロバイダーでは動作しません。また、遅延ロードされたツールは最初のターンでは使えないため、ユーザーの最初のリクエストに即座に対応する必要があるツールには向きません。 ✨ ツール検索で「必要なときに必要なツールだけ」をロードし、スマートなエージェントを実現しましょう。 #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 ユーザーの権限やプランに応じて、使えるツールを動的に切り替えたいと思いませんか？ `is_enabled` パラメータを使えば、ツールの有効/無効を条件付きで制御し、コンテキストに応じたツールセットを提供できます。 📌 タイトル：ツールの条件付き有効化 🔗 URL： 🧩 概要 `as_tool()` の `is_enabled` パラメータに `True`/`False` のブール値、またはコンテキストとエージェントを受け取るコールバック関数 `(ctx, agent) -> bool` を渡すことで、ツールの有効/無効を動的に制御できます。無効化されたツールはモデルのツールリストに表示されず、トークン消費も発生しません。フィーチャーフラグや権限ベースのアクセス制御に最適です。 🛠 使い方 ```python from agents import Agent, function_tool, RunContextWrapper @function_tool def admin_tool(command: str) -> str: return execute_admin(command) @function_tool def basic_tool(query: str) -> str: return basic_search(query) # コールバックで動的判定 def is_admin(ctx: RunContextWrapper, agent: Agent) -> bool: return ctx.context.user_role == "admin" agent = Agent( name="assistant", tools=[ admin_tool.as_tool(is_enabled=is_admin), basic_tool, ], ) ``` 🏗 本番システムへの組み込み方 ・SaaSのプランに応じてプレミアム機能のツールを出し分ける ・ユーザーのロール（admin/member/viewer）でツールのアクセス権を制御する ・フィーチャーフラグと連携し、新機能のA/Bテストやカナリアリリースに活用する ・コンテキスト情報（リージョン、時間帯など）に基づいてツールセットを最適化する 💡 ユースケース 🔐 管理者のみが使える運用ツールの制御 💎 有料プランユーザー向け高機能ツールの出し分け 🚀 新機能のフィーチャーフラグ連動 🌏 リージョンごとに利用可能なサービスの切り替え ⚠️ 注意点 `is_enabled` が `False` の場合、ツールはモデルに提示されないため、モデルはそのツールの存在自体を知りません。セキュリティ上の制御としては有効ですが、ユーザーに「この機能は利用できません」と案内したい場合は、別途メッセージングの仕組みが必要です。 ✨ 条件付きツール有効化で、ユーザーごとに最適なエージェント体験を提供しましょう。 #OpenAIAgentSDK# #AIAgent#

# 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#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 ガードレールで、エージェントの入出力を安全に制御しましょう！ 安価な高速モデルで事前チェックを行い、不適切なリクエストをブロックしてコストを削減できます。 📌 タイトル：Guardrails 🔗 URL： 🧩 概要 Guardrailsは、エージェントの入力と出力に対してチェックを実行する仕組みです。入力ガードレール（Input guardrails）はユーザー入力を検証し、出力ガードレール（Output guardrails）はエージェントの応答を検証します。安価な高速モデルをガードレールに使い、高価なモデルの不要な実行を防ぐことで、コスト最適化を実現できます。トリップワイヤー方式で、問題を検出した時点で実行を即座に中断します。 🛠 使い方 `agents`から`Agent`, `InputGuardrail`, `OutputGuardrail`, `GuardrailFunctionOutput`をインポートします。ガードレール関数`check_homework_request(context, agent, input_data)`を定義し、内部で` input_data)`を呼び出して分類結果を取得します。戻り値は`GuardrailFunctionOutput(output_info= tripwire_triggered="TutorBot", instructions="You are a tutoring assistant.", input_guardrails=[InputGuardrail(guardrail_function=check_homework_request)])`のように定義します。 🏗 実践的な使い方 **安価モデルによる事前フィルタリング（コスト削減）** 高価なメインモデルを実行する前に、安価な高速モデルで「宿題の代行」「不正利用」などを検出してブロックします。トリップワイヤーが発動すると、メインモデルの実行がスキップされるためコスト削減になります。 安価な分類用エージェント`Agent(name="Classifier", model="gpt-4o-mini", output_type=ClassificationResult)`を定義し、`abuse_check`関数内で` input_data)`を実行します。`tripwire_triggered="Assistant", model="gpt-4o", input_guardrails=[InputGuardrail(guardrail_function=abuse_check)])`に設定します。 **出力ガードレールによるコンテンツチェック** エージェントの応答に機密情報や不適切な内容が含まれていないかを検証します。 出力ガードレール関数`check_sensitive_output(context, agent, output)`を定義し、` f"Check this output for sensitive content: {output}")`で機密情報の有無を判定します。`tripwire_triggered="SupportBot", output_guardrails=[OutputGuardrail(guardrail_function=check_sensitive_output)])`のように設定します。 **サポートボットの関連性チェック** ユーザーの質問がサポート範囲内かを事前に判定し、範囲外の質問には早期に対応します。 関連性チェック関数`relevance_check(context, agent, input_data)`で` input_data)`を実行し、`tripwire_triggered=not "SupportBot", instructions="Answer customer support questions about our product.", input_guardrails=[InputGuardrail(guardrail_function=relevance_check)])`として設定します。 💡 ユースケース 🛡 宿題代行・不正利用リクエストのブロック（コスト削減） 🔍 機密情報の出力防止（PII、社内情報の漏洩防止） 📋 サポートボットの対応範囲制御 ⚡ 安価モデルによる事前スクリーニングでAPI費用を最適化 ⚠️ 注意点 - ガードレールのトリップワイヤーが発動すると`InputGuardrailTripwireTriggered`例外が発生します。適切にキャッチして処理してください - 入力ガードレールはメインモデルと**並列**で実行されるため（デフォルト）、ガードレールが間に合わない場合はメインの実行が進む可能性があります - ガードレール自体のモデル呼び出しコストも考慮してください - 複数のガードレールを設定でき、いずれかが発動すれば中断されます ✨ ガードレールを活用して、安全性とコスト効率を両立したエージェントを構築しましょう！ #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 ツールの入出力にもガードレールを設定して、セキュリティを強化しましょう！ ツール引数のチェックや出力のマスキングで、機密情報の漏洩や不正な操作を防止できます。 📌 タイトル：Guardrails – Tool guardrails 🔗 URL： 🧩 概要 Tool guardrailsは、ツールの実行前（引数チェック）と実行後（出力チェック）にガードレールを設定する仕組みです。APIキーの混入防止、機密データのマスキング、特定の操作のブロックなど、ツールレベルでのセキュリティ制御を実現します。マネージャーパターンやHandoff、委任を使う複雑なワークフローでも、個別のツールに対してきめ細かいチェックを適用できます。 🛠 使い方 `agents`から`Agent`, `function_tool`をインポートします。`@function_tool`デコレータでツール関数`search_api(query: str) -> str`を定義し、`Agent(name="SecureAgent", tools=[search_api], tool_guardrails=[check_tool_args])`のように`tool_guardrails`にチェック関数を設定します。 🏗 実践的な使い方 **APIキーの混入をブロック（reject_content）** ツール引数に`sk-`で始まるAPIキーが含まれていないかチェックし、検出時にツール実行をブロックします。 `re`と`GuardrailFunctionOutput`をインポートし、`reject_api_keys(context, agent, tool_call)`関数で` str(tool_call.arguments))`によりAPIキーの混入を検出します。`tripwire_triggered=has_api_key`で検出時にブロックし、`Agent(name="SecureAgent", tools=[search_api, call_external_service], tool_guardrails=[reject_api_keys])`として設定します。 **ツール出力の機密データマスキング** ツール実行後の出力に含まれる機密情報（メールアドレス、電話番号など）を自動的にマスキングします。 `mask_sensitive_output(context, agent, tool_call, tool_output)`関数でツール出力に対して`re.sub(r'[\w.+-]+@[\w-]+\.[\w.]+', '[MASKED_EMAIL]', str(tool_output))`でメールアドレスを、`re.sub(r'\d{3}-\d{4}-\d{4}', '[MASKED_PHONE]', masked)`で電話番号をマスキングします。`GuardrailFunctionOutput(output_info={"masked": True}, tripwire_triggered=False, modified_output=masked)`で加工済み出力を返し、`Agent(name="DataAgent", tools=[query_customer_db], tool_guardrails=[mask_sensitive_output])`として設定します。 **複雑なワークフローでの個別ツールチェック** マネージャーパターンやHandoff、委任を組み合わせた複雑なワークフローでも、特定のツールに対してきめ細かいガードレールを適用できます。 `check_delete_permission(context, agent, tool_call)`関数で` == "delete_record"`の場合に`context.get("user_role", "viewer")`で権限を確認し、`user_role not in ["admin", "editor"]`なら`tripwire_triggered=True`でブロックします。それ以外のツールは`tripwire_triggered=False`でスキップします。`Agent(name="Manager", tools=[query_db, update_record, delete_record], tool_guardrails=[check_delete_permission, reject_api_keys])`のように複数のガードレールを組み合わせて設定できます。 💡 ユースケース 🔑 ツール引数へのAPIキー・シークレット混入防止 🎭 ツール出力からのPII（個人情報）自動マスキング 🚫 権限に基づく特定ツール操作のブロック 🔒 複雑なマルチエージェントワークフローでのセキュリティ制御 ⚠️ 注意点 - ツールガードレールはツールの実行ごとに呼び出されるため、パフォーマンスへの影響を考慮してください - 正規表現によるチェックは完全ではありません。重要なセキュリティ要件には複数の防御層を設けてください - マスキング処理は元のデータ型を変更する可能性があるため、後続の処理に影響がないか確認してください - 複数のツールガードレールを設定した場合、すべてが順に実行されます ✨ ツールガードレールで、エージェントのツール操作をきめ細かく制御し、セキュリティを強化しましょう！ #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 LLM の出力を「文字列のまま祈る」のではなく、型安全な構造化データとして受け取りましょう。output_type を使えば、壊れた JSON に悩まされる日々とはお別れです。 output_type に Pydantic モデル・dataclass・TypedDict を指定するだけで、エージェントの出力が自動的にバリデーション済みの構造化データになります。 📌 タイトル：Agents -- Output types 🔗 URL： 🧩 概要 Agent の `output_type` パラメータを設定すると、LLM の出力が Structured Outputs として強制されます。Pydantic BaseModel、dataclass、TypedDict のいずれかを指定でき、出力は自動的にパースされバリデーションされます。これにより、下流のコードが安全に構造化データを扱えるようになります。`output_type` を設定すると、エージェントのファイナル出力はテキストではなく指定した型のオブジェクトになります。 🛠 使い方 `BaseModel` を継承した `CalendarEvent` クラスに `name: str`, `date: str`, `participants: list[str]` フィールドを定義し、`Agent` の `output_type=CalendarEvent` に指定します。` ...)` の ` が `CalendarEvent` 型として返され、` や `event.participants` で型安全にアクセスできます。 🏗 実践的な使い方 **メールからカレンダーイベントを抽出して API 登録** 構造化出力をそのまま外部 API に渡すパイプラインです。 ` email_body)` で抽出した ` を `CalendarEvent` 型として受け取り、`calendar_api.create_event(title= date= attendees=event.participants)` でそのまま外部 API に渡します。 **Enum 出力による分岐オーケストレーション** 分類結果を enum で返し、コードで確実に分岐させるパターンです。 `TicketCategory(str, Enum)` で `billing`, `technical`, `general` を定義し、`Classification(BaseModel)` に `category: TicketCategory` と `confidence: float` を持たせます。`Agent` の `output_type=Classification` を設定して分類を実行し、` を `match` 文で分岐して `handoff_to_billing`, `handoff_to_engineering`, `handoff_to_general` にルーティングします。 **ビジネスクリティカルな処理での型保証** 「壊れた JSON は絶対に許容できない」業務で、Structured Outputs が安全弁として機能します。 `InvoiceData(BaseModel)` に `invoice_number: str`, `amount: float`, `currency: str`, `due_date: str`, `line_items: list[dict[str, str | float]]` を定義し、`Agent` の `output_type=InvoiceData` に指定することで、請求書データの構造化抽出を型安全に保証します。 💡 ユースケース 📧 メールから CalendarEvent(name, date, participants) を抽出し、カレンダー API に自動登録 🏷 サポートチケットを Enum 分類し、category に応じてコードで確実にルーティング 💰 請求書・契約書の構造化抽出で「壊れた JSON が許されない」業務処理を型安全に 📊 アンケート自由記述を構造化データに変換し、集計パイプラインに直接投入 ⚠️ 注意点 - output_type を指定すると、エージェントの最終出力は必ずその型になります。通常のテキスト応答は返せなくなるため、テキスト応答が必要な場合は output_type を設定しないでください。 - 複雑すぎるネスト構造は LLM の出力精度を下げる可能性があります。できるだけフラットな構造を心がけましょう。 - Optional フィールドを適切に使い、LLM が情報を見つけられなかった場合の None を許容する設計にしましょう。 ✨ output_type を活用すれば、LLM の出力をそのままビジネスロジックに組み込めます。「パースして祈る」から「型で保証する」へ、一歩進んだエージェント開発を始めましょう！ #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 エージェントの内部で何が起きているか、可視化できていますか？ライフサイクルフックを使えば、ロギング・監査・パフォーマンス最適化をエージェントの動作に透過的に組み込めます。 RunHooks と AgentHooks で、エージェントの開始/終了、LLM 呼び出し、ツール実行、ハンドオフの各イベントにカスタムロジックを差し込めます。 📌 タイトル：Agents -- Lifecycle events (hooks) 🔗 URL： 🧩 概要 OpenAI Agent SDK には、エージェントのライフサイクルの各段階でカスタムコードを実行するためのフック機構があります。`RunHooks` はワークフロー全体に適用され、`AgentHooks` は特定のエージェントに適用されます。利用可能なフックには `on_agent_start`/`on_agent_end`、`on_llm_start`/`on_llm_end`、`on_tool_start`/`on_tool_end`、`on_handoff` があります。これらを使って、ロギング、メトリクス収集、監査証跡、データのプリフェッチなどを実装できます。 🛠 使い方 `RunHooks` を継承した `LoggingHooks` クラスを定義し、`async def on_agent_start(self, context, agent)` と `async def on_agent_end(self, context, agent, output)` をオーバーライドしてエージェントの開始・終了時にログを出力します。`Agent` を作成し、` "こんにちは", run_hooks=LoggingHooks())` の `run_hooks` 引数にフックインスタンスを渡して実行します。 🏗 実践的な使い方 **on_llm_end でアウトプットアイテム数ロギング、on_agent_end でトークン使用量ロギング** ワークフロー全体の RunHooks と特定エージェントの AgentHooks を組み合わせて、包括的な監視を実現します。 `RunHooks` を継承した `MetricsRunHooks` クラスでは、`on_agent_end` でワークフロー全体の `total_tokens` や `prompt_tokens` をロギングします。`AgentHooks` を継承した `DetailedAgentHooks` クラスでは、`on_llm_end` で `response.output` のアイテム数を記録します。`Agent` の `hooks=DetailedAgentHooks()` で特定エージェントにフックを適用し、` ..., run_hooks=MetricsRunHooks())` でワークフロー全体のフックも同時に適用して包括的な監視を実現します。 **on_tool_start の ToolContext で監査ログ・分散トレーシング** ツール実行の前後でトレース情報を記録し、問題発生時の調査を容易にします。 `AgentHooks` を継承した `AuditHooks` クラスで、`on_tool_start` では `context.context.trace_id` を取得し、` ` タイムスタンプを構造化ログに記録します。`on_tool_end` では同じ `trace_id` と ` に加え、`result is not None` で成功判定を記録し、分散トレーシングと監査ログを実現します。 **on_handoff でデータプリフェッチによるレイテンシ削減** ハンドオフ先のエージェントが必要とするデータを事前に取得しておくことで、応答速度を改善します。 `RunHooks` を継承した `PrefetchHooks` クラスの `on_handoff` で、` が `"OrderSupportAgent"` の場合に `await db.fetch_orders( と `await db.fetch_payment_methods( を事前取得し、ユーザーコンテキストに格納します。ハンドオフ先が必要なデータを先読みすることでレイテンシを削減します。 💡 ユースケース 📊 on_llm_end で LLM レスポンスのアウトプットアイテム数を記録し、出力品質の監視に活用 💰 on_agent_end でトークン使用量をロギングし、コスト管理ダッシュボードに連携 🔍 on_tool_start/end でツール実行の監査ログと分散トレーシングを自動記録 ⚡ on_handoff でハンドオフ先が必要なデータをプリフェッチし、応答レイテンシを削減 ⚠️ 注意点 - フック内で例外が発生すると、エージェントの実行自体に影響を与える可能性があります。フック内ではtry/exceptで確実にエラーを処理してください。 - フック内で重い処理を行うとエージェント全体のレイテンシが増加します。非同期 I/O やバックグラウンドタスクの活用を検討してください。 - RunHooks と AgentHooks の使い分けを意識しましょう。ワークフロー横断の監視は RunHooks、特定エージェントの詳細監視は AgentHooks が適切です。 ✨ ライフサイクルフックは、エージェントの動作を「ブラックボックス」から「完全可視化」に変えてくれます。本番運用に欠かせない監視・監査・最適化を、エージェントのロジックを汚さずに実現しましょう！ #OpenAIAgentSDK# #AIAgent#