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