teams-meeting-pipeline

Teams 会議パイプライン

ユーザーから Microsoft Teams の会議の要約、文字起こし、録画、アクションアイテム、Graph サブスクリプション、または Teams 会議パイプラインに関する運用上の質問があった場合は、必ずこのスキルを使用してください。どの言語でも機能します。以下のトリガー例は一例であり、すべてを網羅しているわけではありません。

オペレーター向けの操作はすべて、ターミナルツール経由で実行する hermes teams-pipeline サブコマンドです。このパイプライン用の新しいモデルツールはありません。操作には CLI を使用します。

このスキルを使用する場面

ユーザーから次のような依頼があった場合に使用します。

• Teams 会議を要約する／アクションアイテムを抽出する／会議メモを取得する
• パイプラインの状態を確認する、保存済みの会議ジョブを調べる、または最近の会議を確認する
• 失敗した、または新しい要約が必要な保存済みジョブを再生／再実行する
• 環境変数や設定の変更後に Microsoft Graph のセットアップを検証する
• 「会議の要約が届かない」または「新しい会議が取り込まれない」といった問題をトラブルシューティングする
• Graph webhook サブスクリプションを管理する（作成、更新、削除、確認）
• サブスクリプションの自動更新を設定する（以下の注意事項を参照）

多言語でのトリガー例（一部）：

• 英語：「summarize the Teams meeting」、「pipeline status」、「replay job X」
• トルコ語：「Teams meeting özetle」、「action item çıkar」、「toplantı notu」、「pipeline durumu」、「replay job」

前提条件

パイプラインを使用する前に、${HERMES_HOME:-~/.hermes}/.env で以下が設定されていることを確認してください。

MSGRAPH_TENANT_ID=...
MSGRAPH_CLIENT_ID=...
MSGRAPH_CLIENT_SECRET=...

不足している項目がある場合は、Azure アプリ登録ガイド /docs/guides/microsoft-graph-app-registration をユーザーに案内してください。パイプラインを動作させるには、管理者の同意を得た Graph アプリケーション権限を持つ Azure AD アプリ登録が必要です。

コマンドリファレンス

状態と確認（ここから開始）

hermes teams-pipeline validate              # config snapshot — run first after any change
hermes teams-pipeline token-health          # Graph token status
hermes teams-pipeline token-health --force-refresh   # force a fresh token acquisition
hermes teams-pipeline list                  # recent meeting jobs
hermes teams-pipeline list --status failed  # only failed jobs
hermes teams-pipeline show <job-id>         # full detail of one job
hermes teams-pipeline subscriptions         # current Graph webhook subscriptions

再実行／デバッグ

hermes teams-pipeline run <job-id>          # replay a stored job (re-summarize, re-deliver)
hermes teams-pipeline fetch --meeting-id <id>   # dry-run: resolve meeting + transcript without persisting
hermes teams-pipeline fetch --join-web-url "<url>"   # dry-run by join URL
hermes teams-pipeline fetch --join-web-url "<url>" --organizer-user-id <id>   # organizer-scoped lookup (required for /meet/ short URLs)

サブスクリプション管理

hermes teams-pipeline subscribe \
  --resource communications/onlineMeetings/getAllTranscripts \
  --notification-url https://<your-public-host>/msgraph/webhook \
  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"

hermes teams-pipeline renew-subscription <sub-id> --expiration <iso-8601>
hermes teams-pipeline delete-subscription <sub-id>
hermes teams-pipeline maintain-subscriptions            # renew near-expiry ones
hermes teams-pipeline maintain-subscriptions --dry-run  # show what would be renewed

よくある依頼への判断フロー

• ユーザーから「今日の会議の要約が届かなかったのはなぜ？」と尋ねられた場合 → まず list --status failed を実行し、該当する行の show <job-id> を実行します。ジョブ自体が存在しない場合は、subscriptions を確認します。webhook の有効期限が切れている可能性があります（以下の注意事項を参照）。
• ユーザーから「セットアップは動作していますか？」と尋ねられた場合 → validate、次に token-health、続いて subscriptions を実行します。3つすべてが正常なら、テスト用の会議を依頼し、list で新しい行が追加されたか確認します。
• ユーザーから「会議 X の要約を再実行して」と依頼された場合 → list でジョブ ID を見つけ、run <job-id> で再実行します。再び失敗した場合は、show <job-id> でエラーを調べ、fetch --meeting-id でアーティファクトの解決をドライランします。
• ユーザーから「会議 X をパイプラインに追加して」と依頼された場合 → 通常は追加しません。パイプラインは会議ごとではなく、サブスクリプションによって動作します。特定の過去の会議を要約したい場合は、fetch で文字起こしを取得し、ジョブを作成してから run を使用します。

重要な注意点：Graph サブスクリプションの有効期限は 72 時間です

Microsoft Graph の webhook サブスクリプションの有効期間は最大 72 時間で、自動更新されません。maintain-subscriptions がスケジュールされていない場合、手動でサブスクリプションを作成してから 3 日後に、会議の通知が気づかれないまま届かなくなります。

ユーザーから「昨日はパイプラインが動作していたのに、今日は何も届かない」と報告された場合：

1. hermes teams-pipeline subscriptions を実行します。空であるか、すべてのエントリの expirationDateTime が過去の日時なら、それが原因です。
2. 上記のとおり subscribe で再作成します。
3. すぐに hermes cron add、systemd タイマー、または通常の crontab を使って自動更新を設定します。運用手順書 /docs/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production に、3つの方法がすべて記載されています。72 時間の上限に対して十分な余裕を確保するには、12 時間間隔が安全です（6倍の余裕があります）。

その他の注意点

• トランスクリプトがまだ利用できません。 Teams は、会議の終了後にトランスクリプトのアーティファクトを生成するまで少し時間がかかります。終了したばかりの会議に対して fetch --meeting-id を実行すると、空の結果が返ることがあります。2～5 分待ってから再試行するか、Graph Webhook による自然な取り込みを待ってください。
• 配信モードが一致していません。 要約が生成されている（list に成功と表示される）のに Teams に何も届かない場合は、platforms.teams.extra.delivery_mode と、対応するターゲット設定（incoming_webhook_url または chat_id または team_id+channel_id）を確認してください。書き込み処理はこれらを config.yaml または TEAMS_* 環境変数から読み込みます。
• Graph アプリのアクセス許可。 トークンの取得には成功する（token-health が合格する）のに Graph API 呼び出しで 401/403 が返る場合、アクセス許可の追加後に管理者の同意が再度付与されていない可能性があります。ユーザーに Azure ポータルでアプリ登録を開き直し、もう一度「管理者の同意を付与」をクリックしてもらってください。

関連ドキュメント

このスキルの説明だけでは情報が足りない場合は、以下を案内してください。

• Azure アプリ登録の手順：/docs/guides/microsoft-graph-app-registration
• パイプラインのセットアップ全体：/docs/user-guide/messaging/teams-meetings
• 運用者向け手順書（更新の自動化、トラブルシューティング、本番稼働チェックリスト）：/docs/guides/operate-teams-meeting-pipeline
• Webhook リスナーのセットアップ：/docs/user-guide/messaging/msgraph-webhook