# OpenAI Agent SDKの便利で実践的な使い方 🌍 自前の MCP サーバーをエージェントに接続しましょう。HTTP・SSE・stdio の3つのトランスポートと、接続管理・承認制御の実践パターンを紹介します。 ローカル MCP サーバーは自社インフラ上で動作するため、低レイテンシ・高セキュリティ・カスタムツールの自由度が得られます。 📌 タイトル：MCP -- Streamable HTTP / SSE / stdio 🔗 URL： 🧩 概要 ローカル MCP サーバーは、自分でホストする MCP サーバーをエージェントのツールとして接続する仕組みです。`MCPServerStreamableHttp`（HTTP ベース、認証・リトライ・タイムアウト対応）、`MCPServerSse`（Server-Sent Events）、`MCPServerStdio`（ローカル CLI プロセス）の3つのトランスポートから選択できます。`MCPServerManager` で複数サーバーの一括接続管理、`require_approval` でツール別の承認制御、`tool_meta_resolver` でテナント情報の注入が可能です。 🛠 使い方 `agents` から `Agent`, `Runner` を、`agents.mcp` から `MCPServerStreamableHttp`, `MCPServerStdio` をインポートします。HTTP 接続の場合は `Agent` の `mcp_servers` に `MCPServerStreamableHttp` を渡し、接続情報は `params` 辞書にまとめて `params={"url": "http://internal-mcp.corp:8080/mcp", "headers": {"Authorization": "Bearer "}, "timeout": 30}` と指定します。stdio 接続の場合は `MCPServerStdio` を使い、`params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]}` でローカル CLI プロセスを起動します。 🏗 実践的な使い方 **MCPServerStreamableHttp で社内 MCP に認証付き接続** 低レイテンシが求められる社内サービスへの接続パターンです。認証ヘッダ、リトライ、タイムアウトを設定します。 `MCPServerStreamableHttp` の `params` に `"url": "http://internal-mcp.corp:8080/mcp"`、`"headers"` で `Authorization` ヘッダに `os.getenv('MCP_TOKEN')` から取得したトークンを設定し、`"timeout": 30` を指定します。リトライ回数は `params` の外側のキーワード引数 `max_retry_attempts=3` で設定します。これを `Agent` の `mcp_servers` に渡すことで、認証付きの社内 MCP 接続が完成します。 **MCPServerStdio でローカル CLI ツールを接続** ファイルシステムサーバーや自作 CLI ツールを stdio トランスポートで接続します。 `MCPServerStdio` で `params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]}` を指定してファイルシステムサーバーを接続します。自作ツールの場合は `params={"command": "python", "args": ["-m", "my_custom_mcp_server"], "env": {"DB_URL": os.getenv("DB_URL")}}` で環境変数を渡します。両方を `Agent` の `mcp_servers` リストに渡せば、複数の stdio ツールを同時利用できます。 **MCPServerManager で複数サーバーの一括管理** 複数の MCP サーバーを効率的に管理し、障害時の再接続も制御します。 `agents.mcp` から `MCPServerManager` をインポートし、`servers` に複数の MCP サーバーインスタンスを渡します。`await manager.connect_all()` で一括接続し、` でアクティブなサーバーを確認できます。`await manager.reconnect(failed_only=True)` で障害が発生したサーバーのみ再接続します。 **require_approval のツール別マップ + tool_meta_resolver** ツールごとに承認ポリシーを変え、さらにツール実行時にテナント情報を注入するパターンです。 ツールごとの承認ポリシーを辞書で定義します。`"search_docs"` と `"read_file"` は `"never"`、`"write_file"`・`"delete_file"`・`"execute_query"` は `"always"` とマッピングします。`tool_meta_resolver` に渡す関数は `MCPToolMetaContext` を受け取り、` からテナント情報を読んで `{"tenant_id": str(tenant_id), "source": "agents-sdk"}` のようなメタデータ辞書を返します（ツール引数そのものを書き換えるのではなく、呼び出しごとの `_meta` として送られます）。`MCPServerStreamableHttp` の `require_approval` にこの辞書を、`tool_meta_resolver` にこの関数を渡すことで、ツール別承認制御とテナント情報の自動付与を実現します。 💡 ユースケース 🏢 MCPServerStreamableHttp で社内 MCP サーバーに認証・タイムアウト付きで低レイテンシ接続 📁 MCPServerStdio でローカルのファイルシステムサーバーや自作 CLI ツールをエージェントに接続 🔄 MCPServerManager で複数サーバーを一括管理し、failed_only=True で障害サーバーのみ再接続 🔐 ツール別 require_approval マップ + tool_meta_resolver でテナント ID を自動注入しマルチテナント対応 ⚠️ 注意点 - MCPServerStdio はローカルプロセスを起動するため、コンテナ環境では対象コマンドがインストールされている必要があります。 - MCPServerManager の reconnect は接続エラーのリカバリであり、ツール実行中のエラーハンドリングは別途必要です。 - tool_meta_resolver で注入する情報にシークレットを含めないでください。ログに出力される可能性があります。 ✨ 3つのトランスポートと MCPServerManager を使いこなせば、社内サービスからローカルツールまで自在に接続できます。まずは stdio で手元のツールを繋いで、HTTP で本番接続に移行していきましょう！ #OpenAIAgentSDK# #AIAgent#

OpenAI アルトマンCEO「個人のPCに大量のRAMを搭載するのは問題」と発言。ローカルAIより「クラウドで24時間活用すべき」と語る DRAMは5％しか使われないと主張しました。

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 複雑なマルチエージェント構成、頭の中だけで把握できていますか？ draw_graphを使えば、エージェントの構成をGraphvizで視覚的に可視化し、全体像を一目で確認できます。 📌 タイトル：draw_graph によるエージェント可視化 🔗 URL： 🧩 概要 `draw_graph(agent)` を呼び出すだけで、エージェント・ツール・ハンドオフの関係をGraphvizのグラフとして描画できます。エージェントは黄色の四角形、ツールは緑の楕円、MCPサーバーは灰色で表示されます。ハンドオフは実線矢印、ツール接続は点線、MCP接続は破線で区別されます。生成されたグラフは `.view()` でブラウザ表示、`filename=` でファイル保存が可能です。 🛠 使い方 ```python # vizオプション付きでインストール # pip install "openai-agents[viz]" from agents import Agent, function_tool from agents.extensions.visualization import draw_graph @function_tool def search(query: str) -> str: return "results" sub_agent = Agent(name="Researcher", tools=[search]) main_agent = Agent( name="Coordinator", handoffs=[sub_agent], ) # グラフを描画してブラウザで表示 graph = draw_graph(main_agent) graph.view() # ファイルに保存 draw_graph(main_agent, filename="agent_graph") ``` 🏗 本番システムへの組み込み方 ・CI/CDパイプラインでグラフを自動生成し、ドキュメントとして保存する ・コードレビュー時にエージェント構成の変更を視覚的に確認する ・新しいメンバーのオンボーディングに、システム全体像の把握資料として活用する ・構成変更前後のグラフを比較して、意図しないハンドオフの追加・削除を検出する 💡 ユースケース 🗺 マルチエージェントシステムのアーキテクチャドキュメント自動生成 👥 チーム内でのエージェント構成の共有・レビュー 🐛 ハンドオフの循環参照や孤立ツールの検出 📊 プロジェクト提案時のシステム構成図作成 ⚠️ 注意点 利用には `pip install "openai-agents[viz]"` で追加依存（Graphviz）のインストールが必要です。システムにGraphvizバイナリもインストールされている必要があります。非常に大規模なエージェント構成では、グラフが複雑になりすぎる場合があります。 ✨ draw_graphで、エージェント構成を「見える化」してチーム全体の理解を深めましょう。 #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#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 ツールの出力が巨大すぎて、コンテキストウィンドウを圧迫していませんか？ ToolOutputTrimmerを使えば、古いツール出力を自動的にトリミングし、コンテキストを効率的に管理できます。 📌 タイトル：Tool output trimmer 拡張 🔗 URL： 🧩 概要 `ToolOutputTrimmer` は `CallModelInputFilter` として動作し、会話履歴内のツール出力をスライディングウィンドウ方式でトリミングします。直近のターン（デフォルト2ターン）はそのまま保持し、古いターンの出力が `max_output_chars`（デフォルト500文字）を超える場合、先頭 `preview_chars`（デフォルト200文字）だけを残して切り詰めます。元のメッセージは変更せず、浅いコピーで非破壊的に処理されます。 🛠 使い方 ```python from agents import RunConfig from agents.extensions.tool_output_trimmer import ToolOutputTrimmer # デフォルト設定で使用 trimmer = ToolOutputTrimmer() # カスタム設定 trimmer = ToolOutputTrimmer( recent_turns=3, # 直近3ターンは保持 max_output_chars=1000, # 1000文字超でトリミング preview_chars=300, # 先頭300文字を残す trimmable_tools=["search", "fetch_page"], # 特定ツールのみ対象 ) # RunConfigに設定 config = RunConfig(call_model_input_filter=trimmer) result = await "質問", run_config=config) ``` 🏗 本番システムへの組み込み方 ・大量のテキストを返すツール（検索、Web取得など）には積極的に適用する ・`trimmable_tools` で対象ツールを限定し、重要なツール出力は保持する ・`recent_turns` はエージェントの推論に必要な直近のコンテキスト量に合わせて調整する ・非破壊的なので、デバッグ時に元のメッセージを確認できる 💡 ユースケース 🔍 大量の検索結果を返すRAGパイプラインのコンテキスト最適化 📄 長文Webページの取得結果を効率的に管理 🔄 マルチターン会話でのトークン消費量削減 💰 コンテキストウィンドウの有効活用によるAPIコスト最適化 ⚠️ 注意点 トリミングにより古いターンの詳細情報が失われるため、エージェントが過去のツール出力を参照する必要がある場合は `recent_turns` を十分に大きく設定してください。また、`trimmable_tools` を指定しない場合は全ツールが対象になります。 ✨ ToolOutputTrimmerで、長い会話でもコンテキストを賢く管理しましょう。 #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 MCP サーバーを自分で立てなくても、OpenAI がホストする MCP ツールですぐに始められます。DeepWiki でリポジトリ調査、Google Calendar 連携まで、最小コードで実現しましょう。 Hosted MCP server tools は OpenAI 側で管理されるため、インフラ構築不要で MCP の力をエージェントに組み込めます。 📌 タイトル：MCP -- Hosted MCP server tools 🔗 URL： 🧩 概要 Hosted MCP server tools は、OpenAI がホストする MCP サーバーをエージェントのツールとして直接利用する仕組みです。`HostedMCPTool` クラスで接続先を指定するだけで、DeepWiki（リポジトリドキュメント検索）や Google Calendar などの外部サービスをツールとしてエージェントに提供できます。`require_approval` でツール実行前の承認フローを制御し、`on_approval_request` で自動承認と人間エスカレーションを組み合わせられます。 🛠 使い方 `agents` から `Agent`, `Runner`, `HostedMCPTool` をインポートします。`Agent` の `tools` に `HostedMCPTool` を渡し、`tool_config` で `type` を `"mcp"`、`server_label` を `"deepwiki"`、`server_url` を `""`、`require_approval` を `"never"` と指定します。` "openai/openai-agents-python の主要機能を教えて")` で実行し、` で結果を取得します。 🏗 実践的な使い方 **DeepWiki でリポジトリ調査を最小コードで実現** OSS のドキュメントを自分で読み込む必要なく、DeepWiki MCP 経由でリポジトリの構造や機能を調査できます。 `Agent` に `name="OSSAnalyzer"` と調査用の `instructions` を設定し、`tools` に `HostedMCPTool` を渡します。`tool_config` で `server_label="deepwiki"`、`server_url=""`、`require_approval="never"` を指定するだけで、OSS リポジトリの構造・機能を調査できるエージェントが完成します。 **require_approval + on_approval_request で安全な自動承認** 読み取り系は自動承認、書き込み系は人間にエスカレーションするパターンです。 `agents` から `HostedMCPTool` と `MCPToolApprovalRequest`、`MCPToolApprovalFunctionResult` をインポートします。`smart_approval(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult` を定義し、` が `{"read_file", "search", "list_events", "get_event"}` に含まれれば `{"approve": True}` を返して自動承認、それ以外は `ask_human_via_slack` で人間に確認し、却下時は `{"approve": False, "reason": "..."}` を返します。`HostedMCPTool` の `tool_config` で `require_approval="always"` を設定し、`on_approval_request=smart_approval` を渡すことで、読み取り系は自動承認・書き込み系は人間エスカレーションのフローが実現できます。 **connector_id で認証付きサービス接続** Google Calendar のような認証が必要なサービスには、connector_id と auth トークンを渡します。 `Agent` の `tools` に `HostedMCPTool` を渡し、`tool_config` で `server_label="google_calendar"` を指定します。コネクタを使う場合は `server_url` の代わりに `connector_id="connector_googlecalendar"` を指定し、認証は `authorization=os.environ["GOOGLE_CALENDAR_AUTHORIZATION"]` のようにアクセストークンを渡します。これにより、OAuth 認証付きの Google Calendar 連携エージェントを構築できます。 💡 ユースケース 🔍 DeepWiki + HostedMCPTool で OSS リポジトリの構造・機能を最小コードで調査 🛡 require_approval="always" + on_approval_request で読み取りは自動承認、書き込みは人間エスカレーション 📅 connector_id + OAuth トークンで Google Calendar 連携し、空き時間提案エージェントを構築 🤖 複数の Hosted MCP ツールを1つのエージェントに組み合わせてマルチサービス対応 ⚠️ 注意点 - Hosted MCP server は OpenAI 側でホストされるため、レイテンシはネットワーク状況に依存します。タイムアウト設定を適切に行いましょう。 - `require_approval="never"` は読み取り専用サービスにのみ使用し、書き込み可能なサービスでは必ず承認フローを設けてください。 - OAuth トークンの有効期限管理は自前で行う必要があります。リフレッシュトークンの仕組みを組み込みましょう。 ✨ Hosted MCP ツールなら、MCP サーバーのインフラを気にせず外部サービス連携を始められます。まずは DeepWiki でリポジトリ調査から試して、承認フローや認証連携を段階的に追加していきましょう！ #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 エージェントの「お財布事情」を可視化しましょう。トークン使用量の追跡で、テナント別課金もステップ別モニタリングも実現できます。 Usage API を使えば、実行全体のトークン消費量から、ツール呼び出し・ハンドオフごとの内訳まで、きめ細かくコストを把握できます。 📌 タイトル：Usage 🔗 URL： 🧩 概要 OpenAI Agent SDK の Usage 機能は、エージェント実行のトークン消費を追跡するための仕組みです。`result.context_wrapper.usage` で実行全体の合計トークン数を取得でき、`result.context_wrapper.usage.request_usage_entries` でステップごと（ツール呼び出し・ハンドオフ・ガードレール）の内訳を確認できます。さらに RunHooks の `on_agent_end` でリアルタイムにログを記録したり、サードパーティモデル使用時に `ModelSettings(include_usage=True)` で使用量レポートを有効化したりできます。 🛠 使い方 `Agent(name="Assistant", instructions="ユーザーの質問に回答してください。")` でエージェントを作り、`result = await "量子コンピュータについて教えてください")` を実行します。` で合計・入力・出力トークン数を取得できます。`result.context_wrapper.usage.request_usage_entries` をループすれば、各リクエストの `entry.input_tokens` と `entry.output_tokens` でステップごとの内訳も確認できます。 🏗 実践的な使い方 **テナント/ユーザー別コスト計算** SaaS で「テナントごとにいくら使ったか」を記録し、課金や予算管理に活用するパターンです。 `handle_request(tenant_id, user_id, message)` のような関数で `result = await message)` を実行し、`calculate_cost(model="gpt-4.1", input_tokens=result.context_wrapper.usage.input_tokens, output_tokens=result.context_wrapper.usage.output_tokens)` でコストを算出、`await billing_db.record(tenant_id=tenant_id, user_id=user_id, total_tokens= cost_usd=cost, timestamp= でテナント別に記録します。 **ステップ別モニタリング** `request_usage_entries` で、どのツール呼び出しやハンドオフがトークンを消費しているかを特定します。 `result = await "売上レポートを作成して")` の後、`result.context_wrapper.usage.request_usage_entries` を `enumerate` でループし、各ステップの `entry.input_tokens` と `entry.output_tokens` を確認します。`entry.input_tokens > 5000` のような閾値で警告を出せば、トークン消費の多いステップを特定できます。 **RunHooks でリアルタイムログ** `on_agent_end` フックでエージェント終了時に使用量をログに記録します。 `RunHooks` を継承した `UsageLoggingHooks` クラスを作り、`on_agent_end(self, context: RunContextWrapper, agent: Agent, output)` メソッドで `context.usage` からトークン使用量を取得し、`"agent_completed", agent_name= total_tokens= ...)` で構造化ログに記録します。`await "質問", hooks=UsageLoggingHooks())` のように `hooks` パラメータで渡します。 **サードパーティモデルでの使用量レポート有効化** OpenAI 以外のモデルアダプタを使う場合、明示的に使用量レポートを有効にする必要があります。 サードパーティモデルでは `Agent(name="ThirdPartyAgent", instructions="...", model=my_custom_model_adapter, model_settings=ModelSettings(include_usage=True))` のように `ModelSettings(include_usage=True)` を明示的に設定して、使用量レポートを有効化します。 💡 ユースケース 💰 テナント別・ユーザー別のトークン消費をDBに記録し、従量課金の基盤を構築 📊 request_usage_entries でステップ別のトークン消費を可視化し、コスト最適化のボトルネックを特定 🔔 RunHooks の on_agent_end で使用量を構造化ログに記録し、リアルタイムでダッシュボード監視 🔌 サードパーティモデル利用時に ModelSettings(include_usage=True) で使用量追跡を漏れなく有効化 ⚠️ 注意点 - ` はリトライやガードレール再実行分も含まれるため、表示上のステップ数より多くなる場合があります。 - サードパーティモデルでは `include_usage=True` を設定しないと使用量がゼロで返ることがあります。アダプタのドキュメントを確認してください。 - コスト計算はモデルの料金体系に依存します。モデルごとの入力/出力トークン単価を正確に反映させましょう。 ✨ トークン使用量を3つのレベル（合計・ステップ別・フック）で追跡すれば、コスト管理も品質監視も万全です。まずは result.context_wrapper.usage から始めて、必要に応じてステップ別やフックでの追跡を追加していきましょう！ #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 エージェントの会話履歴に機密情報が含まれているのに、平文で保存していませんか？ EncryptedSessionを使えば、会話データをFernet暗号化で保護し、TTLによる自動失効も設定できます。 📌 タイトル：暗号化セッション (EncryptedSession) 🔗 URL： 🧩 概要 `EncryptedSession` は、任意のセッションバックエンドを `underlying_session` としてラップし会話データを暗号化するドロップインラッパーです。Fernet暗号化を採用し、HKDF（info 文字列 `"agents.session-store.hkdf.v1"`、salt は session_id）によるセッションごとの鍵導出でセッション間の暗号分離を実現します。`ttl`（既定 600 秒）を超えた項目は取得時に自動的にスキップされます。マスターキーには `Fernet.generate_key()` などの高エントロピーな値を使います（生の文字列も互換性のため受け付けますが、パスワードのような低エントロピーの秘密は不適切です）。 🛠 使い方 ```python import os from cryptography.fernet import Fernet from agents import SQLiteSession from agents.extensions.memory import EncryptedSession # 基底セッションを暗号化でラップ base_session = SQLiteSession("chat-001", "sessions.db") # マスターキーは Fernet.generate_key() などの高エントロピーな値を使う encryption_key = Fernet.generate_key().decode("ascii") encrypted = EncryptedSession( session_id="chat-001", underlying_session=base_session, encryption_key=encryption_key, ttl=3600, # 1時間で失効（既定は 600 秒） ) # 永続化する場合は同じキーを Secret Manager 等から読み込んで再利用する encrypted = EncryptedSession( session_id="chat-001", underlying_session=base_session, encryption_key=os.environ["SESSION_ENCRYPTION_KEY"], ttl=7200, ) # 通常のセッションと同じインターフェースで利用可能 items = await encrypted.get_items() ``` 🏗 本番システムへの組み込み方 ・医療・金融など規制業界のコンプライアンス要件に対応する ・HKDFによりセッションごとに異なる暗号鍵が導出されるため、1セッションの漏洩が他に波及しない ・TTLを設定して、一定期間後に復号不能にする「暗号学的データ消去」を実現する ・既存のSQLiteSession / RedisSession等をそのままラップでき、移行コストが極めて低い 💡 ユースケース 🏥 医療情報を含む会話の暗号化保存 🏦 金融データを扱うエージェントのセキュリティ強化 🔐 GDPRの「忘れられる権利」対応（TTL失効） 🛡 マルチテナント環境でのセッション間データ分離 ⚠️ 注意点 利用には `pip install 'openai-agents[encrypt]'` で `encrypt` extra をインストールしてください。暗号化されたデータに対しては `find_turns_by_content()` などの内容検索が機能しません。検索が必要な場合は検索用のインデックスを別途管理する必要があります。また、暗号鍵を紛失するとデータが復元不能になるため、鍵の安全な管理（Secret Manager等）が必須です。`encryption_key` を変更しても既存レコードは再暗号化されないため、古いデータの復号には元のキーが必要です。 ✨ EncryptedSessionで、会話データの保護をコード1行で実現しましょう。 #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利で実践的な使い方 🌍 エージェントに必要な情報を型安全に注入しましょう！ Local contextを使えば、ユーザー情報やロガー、データフェッチャーを依存注入のように渡せます。 📌 タイトル：Context management – Local context 🔗 URL： 🧩 概要 OpenAI Agent SDKのLocal context機能は、エージェントとツールに対して型安全な依存注入を提供します。`context`パラメータにPydanticモデルやdataclassを渡すことで、ツール関数内からユーザー情報やロガー、外部サービスのクライアントにアクセスできます。`Agent[UserInfo]`のジェネリック型により、コンテキストの型不一致をコンパイル時に検出できます。 🛠 使い方 `dataclass` で `UserInfo(uid, name, is_premium)` を定義し、`@tool` デコレータ付きの関数で `ToolContext[UserInfo]` を受け取ります。例えば `get_recommendations(wrapper: ToolContext[UserInfo], category: str)` では `wrapper.context` からユーザー情報にアクセスし、` に応じてプレミアム/通常のおすすめを返せます。`debug_tool` では `wrapper.tool_name`、`wrapper.tool_call_id`、`wrapper.tool_arguments` でデバッグ情報を取得できます。エージェントは `Agent[UserInfo]` のジェネリック型で定義し、`Agent(name="personal_assistant", instructions="ユーザーに合わせた回答をしてください", tools=[get_recommendations, debug_tool])` のようにツールを登録します。実行時は `UserInfo(uid="u_12345", name="田中太郎", is_premium=True)` を作り、`await "おすすめの本を教えて", context=user)` で渡します。 より実践的には、`AppContext` dataclass に `user: UserInfo`、`logger: logging.Logger`、`db: DatabaseClient`、`feature_flags: dict[str, bool]` をまとめます。`fetch_order_history(wrapper: ToolContext[AppContext], limit: int = 10)` では `ctx = wrapper.context` でコンテキストを取得し、` でログ出力、`ctx.feature_flags.get("new_order_api")` でフィーチャーフラグに応じた分岐、`ctx.db.get_orders(ctx.user.uid, limit)` でDB問い合わせを行います。`Agent[AppContext]` として `Agent(name="order_assistant", tools=[fetch_order_history])` を定義します。 🏗 実践的な使い方 Local contextの最大の価値は、ツール関数をピュアなビジネスロジックに保てることです。ユーザー情報やDBクライアントをグローバル変数で参照する代わりに、contextから注入することで、テスタビリティが大幅に向上します。テスト時にはモックのコンテキストを渡すだけです。 `ToolContext`の`tool_name`、`tool_call_id`、`tool_arguments`は、構造化ログに不可欠です。どのツールがどの引数で呼ばれたかをトレースでき、本番環境のデバッグが容易になります。 `Agent[UserInfo]`のジェネリック型を使うと、型チェッカー（mypy等）がコンテキストの型不一致を検出します。例えば、`Agent[UserInfo]`に`AppContext`を渡そうとするとコンパイルエラーになります。これにより、ランタイムエラーを防げます。 フィーチャーフラグや設定値もコンテキスト経由で渡すパターンが有効です。環境ごとに異なる挙動を、コンテキストの値で制御できます。 💡 ユースケース 👤 ユーザーのプレミアム/フリー区分に応じたパーソナライズ 📝 tool_call_idを使った構造化ログとトレーシング 🧪 テスト時のモックコンテキスト注入によるユニットテスト 🚩 フィーチャーフラグによるツールの挙動切り替え ⚠️ 注意点 - コンテキストにシークレット（APIキー等）を含めると、ステートのシリアライズ時に漏洩する可能性があります - コンテキストオブジェクトは実行中に共有されるため、ミュータブルな状態の変更はスレッドセーフに注意してください - `Agent[T]`のジェネリック型チェックは静的解析ツール依存です。ランタイムでは強制されません - 巨大なオブジェクト（大量データ等）をコンテキストに入れるとメモリ効率が悪化します ✨ Local contextにより、クリーンなアーキテクチャでテスタブルなエージェントが構築できます！ #OpenAIAgentSDK# #AIAgent#

# OpenAI Agent SDKの便利だけど知られていない機能 🌍 会話の途中から「もしあの時違う回答をしていたら？」と試したくなったことはありませんか？ AdvancedSQLiteSessionの会話ブランチング機能を使えば、会話履歴の任意の地点から分岐を作り、代替パスを探索できます。 📌 タイトル：AdvancedSQLiteSession の会話ブランチング 🔗 URL： 🧩 概要 `AdvancedSQLiteSession` は、ターン番号や検索語句を指定して会話を分岐させる機能を備えています。`create_branch_from_turn(turn_number)` で特定のターンから、`create_branch_from_content(search_term)` で特定の内容を含むターンから分岐を作成できます。`list_branches()` で一覧、`switch_to_branch()` で切替、`delete_branch()` で削除も可能です。 🛠 使い方 ```python from agents.extensions.memory import AdvancedSQLiteSession session = AdvancedSQLiteSession( session_id="chat-001", db_path="sessions.db", create_tables=True, # 既定は False。ブランチ用テーブルの作成に必要 ) # ターン3の時点から新しいブランチを作成 branch_id = await session.create_branch_from_turn(turn_number=3) # 特定のキーワードを含むターンからブランチを作成 branch_id = await session.create_branch_from_content("APIの設計について") # ブランチの管理 branches = await session.list_branches() await session.switch_to_branch(branch_id) await session.delete_branch(branch_id, force=True) # 現在のブランチを削除するには force=True ``` 🏗 本番システムへの組み込み方 ・ユーザーが「やり直したい」と言った際に、直前のターンからブランチを作成して再試行する ・エージェント評価で、同じ入力に対して複数の応答パスを比較分析する ・顧客サポートで、異なる解決策を並行で探索し最適なものを選ぶ ・会話のチェックポイントとしてブランチを活用し、重要な分岐点を記録する 💡 ユースケース 🔀 会話の「what-if」分析 🧪 エージェント応答品質のA/Bテスト 🎯 複数の解決策パスの並行探索 📝 会話履歴のチェックポイント管理 ⚠️ 注意点 ブランチが増えるとストレージ使用量が増加します。不要なブランチは定期的に `delete_branch()` で削除してください（現在のブランチを消す場合は `force=True`、`main` は削除できません）。ブランチ ID はセッション ID の生存期間中ユニークで、削除やセッションのクリア後も再利用できないため、新しいブランチには別の名前を付けます。また、ブランチ間の切り替え時にコンテキストの混乱が起きないよう、ブランチのラベル管理を適切に行いましょう。 ✨ 会話ブランチングで、エージェントとの対話に「タイムトラベル」の自由を加えましょう。 #OpenAIAgentSDK# #AIAgent#