# 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の便利で実践的な使い方 🌍 MCP サーバーのツールを「全部見せる」のではなく、フィルタ・プロンプト・キャッシュで賢く制御しましょう。権限スコープの絞り込みから動的フィルタリングまで、安全で高速な MCP 活用パターンです。 ツールフィルタで権限を最小化し、プロンプトで動的指示を取得し、キャッシュでレイテンシを削減する -- MCP の運用を本格化する3つの機能です。 📌 タイトル：MCP -- Tool filtering / Prompts / Caching 🔗 URL： 🧩 概要 MCP サーバーが公開するツールをそのまますべてエージェントに渡すと、不要なツール呼び出しや権限超過のリスクがあります。`create_static_tool_filter` で許可するツールを静的に制限し、動的フィルタ関数で実行時の条件（ロール・テナント等）に応じてツールを出し分けできます。`get_prompt` で MCP サーバーから動的な指示を取得し、`cache_tools_list=True` でツール一覧のキャッシュによりレイテンシを改善、`invalidate_tools_cache()` で変更時にキャッシュをクリアします。 🛠 使い方 `agents.mcp` から `MCPServerStreamableHttp` と `create_static_tool_filter` をインポートします。`MCPServerStreamableHttp` の `tool_filter` に `create_static_tool_filter(allowed_tool_names=["read_file", "write_file"])` を渡すことで、エージェントが使えるツールを `read_file` と `write_file` のみに制限できます。 🏗 実践的な使い方 **create_static_tool_filter で権限スコープを絞り込む** エージェントの役割に応じて、使えるツールを最小限に制限するパターンです。 読み取り専用エージェント用には `create_static_tool_filter(allowed_tool_names=["read_file", "search_docs", "list_files"])` でフィルタを作成し、`MCPServerStreamableHttp` の `tool_filter` に渡します。フルアクセス用には `allowed_tool_names=["read_file", "write_file", "delete_file", "search_docs"]` と設定します。同じ MCP サーバーでもエージェントの役割に応じて異なるツールセットを公開できます。 **動的フィルタで danger_ ツールを非表示にする** ロールに応じて危険なツールを動的に非表示にするパターンです。 `agents.mcp` から `ToolFilterContext` をインポートし、`role_based_filter` 関数を定義します。` が `"CodeReviewer"` で `"danger_")` の場合に `False` を返してツールを非表示にし、それ以外は `True` を返します。この関数を `MCPServerStreamableHttp` の `tool_filter` に渡すことで、ロールに応じた動的なツールフィルタリングが実現できます。 **get_prompt で MCP サーバーから動的指示を取得** MCP サーバーが提供するプロンプトを取得して、エージェントの指示を動的に構成します。 `MCPServerStreamableHttp` を作成し、`async with mcp:` のコンテキスト内で `prompt_result = await mcp.get_prompt("operation_guidelines")` を呼び出して MCP サーバーからプロンプトを取得します（第2引数に `{"focus": "..."}` のような引数辞書も渡せます）。取得した `prompt_result.messages[0].content.text` を `Agent` の `instructions` に埋め込むことで、エージェントの指示を動的に構成できます。 **cache_tools_list でレイテンシを改善** ツール一覧の取得をキャッシュし、MCP サーバーへの不要なリクエストを減らします。 `MCPServerStreamableHttp` の `cache_tools_list=True` を設定すると、ツール一覧の取得結果がキャッシュされ、MCP サーバーへの不要なリクエストが削減されます。ツールが追加・変更された場合は `await mcp.invalidate_tools_cache()` でキャッシュをクリアします。 💡 ユースケース 🔒 create_static_tool_filter で read_file/write_file のみ許可し、最小権限の原則を実現 🎭 動的フィルタで CodeReviewer には danger_ ツールを非表示にし、ロール別のアクセス制御 📜 get_prompt で MCP サーバーから最新の運用ガイドラインを取得し、エージェントの指示を動的に更新 ⚡ cache_tools_list=True でツール一覧キャッシュを有効化し、繰り返しのツール取得レイテンシを削減 ⚠️ 注意点 - 静的フィルタの `allowed_tool_names` はツール名のタイプミスに注意してください。存在しないツール名を指定してもエラーにならず、単にフィルタされないだけです。 - 動的フィルタは毎回のツール一覧取得時に実行されるため、重い処理を入れるとレイテンシに影響します。 - `cache_tools_list=True` 使用時にツールが追加・変更された場合、`invalidate_tools_cache()` を呼ばないと古い一覧が使われ続けます。 ✨ フィルタ・プロンプト・キャッシュの3つを組み合わせれば、MCP ツールの安全性・柔軟性・パフォーマンスを同時に向上できます。まずは静的フィルタで権限を絞り、必要に応じて動的フィルタやキャッシュを導入していきましょう！ #OpenAIAgentSDK# #AIAgent#

# ADKの便利で実践的な使い方 ## 🎛️ エージェントの振る舞いを自在に制御！ADKのCallbacks機能 LLM呼び出しの前にガードレールをかけたい、ツール実行前にバリデーションしたい…そんな要望、ADKの **Callbacks** なら全部叶います！🔧 ## 📌 タイトル Callbacks（コールバック） ## 🔗 URL ## 🧩 概要 Callbacksは、エージェントの実行フローの重要なポイントにフックを仕掛け、振る舞いを観察・カスタマイズ・制御するための仕組みです。フレームワークのコアを変更することなく、6種類のコールバックで柔軟な制御が可能です。 - **before_agent / after_agent**：エージェント実行の前後 - **before_model / after_model**：LLM呼び出しの前後 - **before_tool / after_tool**：ツール実行の前後 最大のポイントは **戻り値によるフロー制御**。`None` を返せば通常続行、特定のオブジェクトを返せばその先の処理をスキップできます。 ## 🛠 使い方 **LLM呼び出しをスキップする（入力ガードレール/キャッシュ）：** `before_model_callback` を定義し、引数として `CallbackContext` と `LlmRequest` を受け取り、戻り値を `Optional[LlmResponse]` とします。`llm_request.contents[-1].parts[0].text` からユーザーの最後のメッセージを取得し、禁止ワードが含まれていれば `LlmResponse` に `Content(role="model")` と拒否メッセージを詰めて返すことでLLM呼び出しをスキップします。問題なければ `None` を返して通常のLLM呼び出しを続行します。 **ツール実行をスキップする（バリデーション/モック）：** `before_tool_callback` を定義し、`context`、`tool`、`args` を受け取ります。戻り値は `Optional[Dict]` です。`validate_args(args)` で引数を検証し、不正であれば `{"error": "引数が不正です"}` という辞書を返してツール実行をスキップします。正常であれば `None` を返して通常実行を続行します。 **エージェント実行をスキップする：** `before_agent_callback` を定義し、`context` を受け取り、戻り値を `Optional[Content]` とします。`is_authorized(context)` で権限チェックを行い、権限がなければ `Content(role="model", parts=[Part(text="権限がありません")])` を返してエージェント実行をスキップします。認可済みであれば `None` を返して通常続行します。 ## 🏗 実践的な使い方 **入力ガードレール + レスポンスキャッシュの組み合わせ：** `smart_before_model` 関数を定義し、`ctx` と `req` を受け取り `Optional[LlmResponse]` を返します。まず Step 1 として `req.contents[-1].parts[0].text` からユーザー入力を取得し、`contains_pii()` で個人情報を検出した場合は拒否メッセージ入りの `LlmResponse` を返してLLM呼び出しをスキップします。次に Step 2 として `hash(user_input)` でキャッシュキーを生成し、`ctx.state.get(f"cache:{cache_key}")` でキャッシュを検索します。キャッシュがあればそのテキストを `LlmResponse` に詰めて返し、なければ `None` を返してLLM呼び出しに進みます。最後に `LlmAgent` を作成する際、`name="SecureAgent"`、`model="gemini-2.0-flash"` を指定し、`before_model_callback=smart_before_model` でこのコールバックを登録します。 ## 💡 ユースケース - 🛡️ **入力ガードレール**：不適切な入力やプロンプトインジェクションをLLM呼び出し前にブロック - 💾 **レスポンスキャッシュ**：同じ質問にはキャッシュから即座に応答しコスト削減 - 🔍 **デバッグ・ログ**：各実行ポイントでリクエスト/レスポンスを記録 - ✅ **ツールバリデーション**：ツール引数の事前検証でエラーを未然に防止 - 🧪 **テスト用モック**：本番ツールの代わりにモックレスポンスを返す ## ⚠️ 注意点 - コールバックは同期的に実行されるため、重い処理（外部API呼び出し等）は避けてください - `before_*` で値を返すと後続処理が完全にスキップされるため、意図しないスキップに注意 - セキュリティガードレールをエージェント横断で適用したい場合は、Callbacksよりも **Plugins** の利用を検討してください - エラーハンドリングは必ず try-except で囲み、コールバックのエラーがエージェント全体をクラッシュさせないようにしましょう ## ✨ まとめ ADKのCallbacksは、エージェントの実行フローに対する「外科手術的な制御」を可能にします。ガードレール、キャッシュ、ログ、バリデーション…あらゆるクロスカッティングな関心事を、コアロジックを汚さずに実装できます。まずは `before_model_callback` から始めてみましょう！ #ADK# #AIAgent#