Gmail 連携機能
Gmail デスクトップ OAuth 連携機能により、AI エージェントおよび Task Agent から Gmail メッセージの検索・読取およびメール下書きの作成が安全に行えます。
概要と利用前提
本機能は個人利用・単一 Google アカウントの統合を前提としています。
- 読み取り・下書き作成のみ: メールの検索 (
gmail_search_messages)、詳細読取 (gmail_read_message)、下書き作成 (gmail_create_draft) のみに対応しています。 - 送信機能なし: 本アプリケーションにはメール送信機能(
send)は一切実装されていません。下書きを作成した後は、人間のユーザーが Gmail 上で内容を確認し、手動で送信を行います。 - 制限事項: メール送信、下書き更新・削除、添付ファイルダウンロード/本文展開、転送、HTMLメール作成、エイリアス切替、マルチアカウントには対応していません。
セットアップと初回認証
1. Google Cloud Console での設定
- Google Cloud Console にアクセスし、プロジェクトを作成(または選択)します。
- Gmail API を有効化します。
- OAuth 同意画面(OAuth consent screen)を設定します。
- ユーザータイプ: 個人利用(外部テストユーザーに自身の Gmail アドレスを追加)
- 必要なスコープ:
https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.compose
- 認証情報(Credentials) の作成:
- 「認証情報を作成」 → 「OAuth クライアント ID」 を選択
- アプリケーションの種類: デスクトップ アプリ (Desktop App)
- クライアント JSON をダウンロードします。
2. クライアント JSON の配置
ダウンロードした JSON ファイルを以下のデフォルトパスへ配置します。
mkdir -p ~/.config/obsidian-ai-hub/gmail
cp path/to/downloaded_client_secret.json ~/.config/obsidian-ai-hub/gmail/client_secret.json
※ 環境変数 GMAIL_CLIENT_SECRET_PATH でカスタムパスを指定することも可能です。
3. 初回認可の実行 CLI
以下の独占コマンドを実行して、ローカルブラウザで Google アカウントの認可を行います。
uv run python -m obsidian_ai_hub --gmail-authorize
- ブラウザが起動し、Google アカウントのログイン・スコープ承認画面が表示されます。
- 承認が完了すると、所有者限定権限 (0600) で認証トークンが
~/.config/obsidian-ai-hub/gmail/token.jsonに保存されます。 - ターミナルには認証されたメールアドレス、トークン保存パス、承認スコープのみが表示され、トークン本文やシークレットは出力されません。
提供ツール(Capabilities)
AI エージェントおよび Task Agent で以下の3つのツールが利用可能です。
| ツール ID | 承認ポリシー | 説明 | 主な入力 |
|---|---|---|---|
gmail_search_messages | 自動 (auto) | Gmail メッセージの検索・一覧取得 | query, label_ids, max_results (1〜20) |
gmail_read_message | 自動 (auto) | メッセージ詳細・本文テキスト・添付メタデータ読取 | message_id |
gmail_create_draft | 計画確認必須 (plan_required) | 新規または返信のメール下書き作成 | mode (new/reply), body_text, to, subject, reply_to_message_id, reply_all |
本文および添付ファイルの取り扱い
- 本文テキスト抽出: MIME 構造を解析し、
text/plainを優先取得します。text/plainがない場合は標準ライブラリによる HTML-to-text 変換を行い、最大 20,000 文字にクランプします(超過時はtruncated: true)。 - 添付ファイル: 添付ファイルの本文やバイナリデータは LLM に展開されません。ファイル名、MIME タイプ、バイトサイズ等のメタデータのみが返されます。
重複防止と at-most-once 契約(receipt Capability)
メール下書き作成(gmail_create_draft)は Workflow および Task Agent の receipt Capability として管理され、外部副作用を伴うため gmail_draft_requests データベーステーブルにより at-most-once (最大1回) 動作が保証されます。
1. 入出力契約
- 入力契約:
body_textおよびsubjectはnarrative(自由テキスト・テンプレート出力)の流入を許可します。mode,to,cc,bcc,reply_to_message_id,reply_allはstructured限定であり、narrative値の流入は Workflow 公開時の静的検証で拒否されます。
- 出力 receipt:
- 出力フィールド:
status,request_key,gmail_draft_id,gmail_message_id,gmail_thread_id,reused_receipt,receipt_persisted - 後続 Node・条件 Edge・pipe・テンプレートからは一切参照できません(
allowed_uses: [])。
- 出力フィールド:
2. 決定的なリクエストキー
- Workflow:
gmail_draft:wf:{run_id}:{activation_id}(retry attempt や bridge Task ID は含めない) - Task Agent:
gmail_draft:task:{task_id}:{plan_id}:{step_index}(承認済み plan の plan_id を使用)
3. at-most-once と needs_attention 停止規則
- 事前保存 (
creating): Gmail API 呼び出し直前にステータスcreatingが永続化されます。 - 成功時 (
created): Gmail から受領情報(下書き ID、メッセージ ID、スレッド ID)が返された後、ステータスをcreatedに更新します。同一リクエストキーで再実行された場合は、Gmail API を再呼び出しせず保存済みの受領情報を再利用します。 - 入力ハッシュ不一致時: 同一 Action で入力ハッシュが変更された場合、Gmail API を呼び出さずに
needs_attention(要対応)で停止します。 - 不確実な失敗時 (
unknown): 通信障害や途中クラッシュが発生した場合、ステータスはunknownとなり、needs_attentionで停止して自動再試行をブロックします。 - DB 永続化失敗時: Gmail API 呼び出し成功後にローカル receipt の永続化だけが失敗した場合は、取得済み ID を記録し
receipt_persisted: falseでneeds_attention停止します。
再認可とトラブルシューティング
- トークン期限切れ / 権限取り消し: 実行時ツールは自動でブラウザを開きません。トークンが無効またはスコープ不足の場合は、「
--gmail-authorizeを実行してください」というエラーが返されます。再度 CLI で--gmail-authorizeを実行してください。 - 再認可コマンド:
uv run python -m obsidian_ai_hub --gmail-authorize