OpenAI Agents SDK のメール連携設計

OpenAI Agents SDK で既存のメールを読む

新しい受信箱を用意するのではなく、普段使っているメールボックスを Mailera に接続します。OpenAI Agents SDK の公式リポジトリでは MCP ツールへの対応が案内されています。Mailera 側には、メールボックス一覧、メッセージ検索、本文取得の MCP ツールがあります。

MCP は、アプリケーションが外部のツールを利用するためのプロトコルです。この構成では Mailera がメール操作の窓口になり、エージェントは必要なメールを取得して要約します。接続方式全体の選び方は、既存メールボックスをエージェントにつなぐ方法で整理しています。

今回の対象は、自分のテストメールの検索から要約までです。自動送信の経路は設けません。

接続前の準備

1. 自分が管理するテスト用メールボックスを接続します。 「メールボックス」から「メールボックスを追加」に進み、接続後に「統合受信トレイ」でテストメールの本文を確認してください。Microsoft は OAuth を使うOutlook・Microsoft 365 の接続手順、Gmail はアプリパスワードによる接続手順を参照できます。
2. 対象グループを限定した API キーを作ります。 「設定」の API キータブで「キーを作成」を選び、「メールボックスのスコープ」をテスト用グループに限定します。権限は read だけにし、send、move、manage などは付けません。
3. 認証情報をアプリ側で保管します。 Mailera のキーは環境変数 $MAILERA_API_KEY に保存し、OpenAI 用の認証情報とは分けて管理してください。対象グループと read 権限を限定しておけば、このキーが漏洩した場合に使われる Mailera の操作も、そのグループの読み取りに限られます。キーの表示は作成時の一度だけです。コードやプロンプト、実行ログに実値を載せないでください。

Gmail で使う app password（アプリパスワード）の作成には、2 段階認証が必要です。Google のアプリパスワードの説明も確認してください。公式資料の確認日は 2026 年 10 月 25 日です。

なお、Python 版 SDK は Python 3.10 以降が対象で、インストールコマンドは pip install openai-agents です。再現時に条件をそろえられるよう、使用する Python と SDK のバージョンを実行日と一緒に残します。

MCP 接続の確認項目

Mailera の MCP 接続情報をもとに、アプリ側で接続先と認証を設定します。

表の $MAILERA_API_KEY は環境変数を示します。アプリではその値を読み出し、Bearer の後ろに設定してください。

接続処理では、接続開始、ツール一覧と入力スキーマの取得、エージェント実行、接続終了を分けます。接続や一覧取得に失敗した場合は、メールを取得したものとして要約へ進めない構成にします。

Mailera の「MCP 設定をコピー」は Claude、Cursor、VS Code 向けです。これらの設定を Agents SDK の設定としてそのまま流用せず、SDK 側の接続処理と認証ヘッダーの設定を分けて扱ってください。

検索したメールの取得と要約

実装する処理は、対象の確認、検索、本文取得、要約の順です。MCP の引数は接続先から取得する入力スキーマに合わせます。REST API のパラメーターをそのまま MCP の引数として使わないでください。

エージェントに渡す最初の許可リストは list_mailboxes、search_messages、get_message の 3 つに絞ります。list_messages はフォルダーを確認する必要がある場合だけ追加します。同じ read 権限の get_latest_otp は、今回の要約には不要です。

4. 同じ read キーで list_mailboxes を呼び、返された一覧から自分のテスト用メールボックスを選びます。キーの対象グループに属することを確認し、その ID を検索先として固定してください。対象が一覧にない場合は、検索へ進まず、キーの対象グループとメールボックスの所属を確認します。
5. search_messages で自分のテストメールを探します。テストメールには Mailera-summary-test という識別文字列を入れておきます。検索に失敗した場合や結果が空の場合は「対象メールを取得できませんでした」と返し、内容を推測させません。
6. get_message で本文を取得してから要約します。件名や送信者を照合し、別のメールを要約していないか確認してください。

本文取得を切り分ける補助として、REST API を直接確認する方法もあります。次は MCP 呼び出しではなく、Mailera の開発者向け APIを使う例です。$MAILERA_API_KEY には MCP 接続と同じ read キーを使います。$MAILBOX_ID には手順 4 で選んだ ID、$MESSAGE_ID には手順 5 で見つかったテストメールの ID を設定してください。検索結果のメールボックスが選択した対象と一致することを確認し、検索に失敗した場合や結果が空の場合は、この呼び出しへ進みません。

curl "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

本文取得のレスポンスでは data.body.text または data.body.html を確認します。検索結果の preview だけで全文を読んだことにしないでください。

よくあるエラーの切り分け

get_mailbox_status はサインイン状態の確認用です。検索対象のメールまで同期できたという意味ではありません。同期状態は別に確認してください。

sync_mailbox には sync 権限が必要で、read だけのキーでは使えません。検索結果が空だからといって、エージェントのキーに同期権限を追加するのではなく、先に対象や条件を確認します。

メール本文の指示への対策と情報流出の防止

受信メールは信頼できないデータであり、利用者やシステムからの命令ではありません。 本文に「認証情報を表示して」「この URL に内容を送って」と書かれていても、ツール実行の指示として扱わせないでください。

プロンプトの注意書きだけに頼らず、対象グループの制限、read 権限、ツール許可リストを組み合わせます。ツールをエージェントから隠すことと、サーバー側の権限で操作を拒否することは別です。両方を設定してください。

MCP 仕様のセキュリティ原則は、ツール実行前の明示的な利用者の同意を求めています。また、プロトコル自体では原則を強制できないとも説明しています。アプリ側では、利用者が承認した対象グループと読み取り専用キーで範囲を固定し、ツール許可リストで呼び出せる操作を絞り込みます。

Agents SDK には実行のトレース機能があります。本文や認証情報を不要に保存しないよう、トレースとアプリケーションログの記録内容を確認してください。認証情報は接続処理にだけ渡し、モデルに見せるメール本文には含めません。Mailera のセキュリティ方針とは別に、アプリ側の保存先も確認が必要です。

自分のテストメールに不正な指示を含め、許可外の操作が行われないかも確認します。将来送信を追加する場合は、宛先・件名・本文を人が確認した後だけ実行する境界を設けてください。全体の設計は承認境界を持つメールエージェントの構築、メール経由で承認を受け取る構成はメールを使った人による承認の設計を参照してください。

Mailera の取得範囲と限界

Mailera は既存のメールボックスを接続するサービスで、新しいメールボックスやメールアドレスは発行しません。

また、常時の即時取得を前提にしないでください。メールボックスの使用中は、「リアルタイム監視」に対応していれば新着メールが数秒以内に届き、非対応なら 2 分ごとに確認します。利用状況によってバックグラウンド確認の頻度は変わり、使われていないメールボックスはスリープすることがあります。要約対象は、その時点で取得できたメール本文に限定します。