Dify のトリガー機能を試す（Gmail / GitHub 連携）

はじめに

Dify の 1.10.0-rc.1 で、新しい トリガー機能 がリリースされました。

これは、簡単にいえば、指定したスケジュール や Webhook の受信、SaaS 上での何らかの動き などを契機に、イベントドリブンなワークフローの実行 ができるようになる機能です。

先日リリースされたナレッジパイプラインとあわせて今年の目玉機能のひとつとされていたもので、開発目線では実装へのコントリビューションが積極的に募集され進捗も公開されていた点がめずらしいケースでした。

それはそれとして、1.10.0-rc.1 時点 の情報を、主に SaaS との連携 を中心にまとめます。リリース名の通り現時点では RC 版 であり、正式版では仕様が変わる可能性はもちろんあるので、その点はご了承ください。

はじめに
TL; DR
前提：トリガ機能の種類と仕組み
環境の準備
プラグインの準備
試行： Gmail 連携
試行： GitHub 連携
おわりに

TL; DR

スケジュールトリガ は、Dify 以外に必要なものがないため、利用はとても簡単です。Webhook トリガ も、送信側に Dify へのリーチャビリティがありさえすればよく、利用は簡単です。

一方で、SaaS と連携したトリガ を利用するには、Dify が SaaS 側からの POST リクエストを受け取れる必要 があります。したがって、OAuth の認証も考慮すると、多くの場合で Dify 側のエンドポイントを正規の SSL 証明書で HTTPS 化してインタネットに公開する ことが求められるため、セルフホスト環境での利用には一定のハードルがある と考えたほうがよいでしょう。他方、クラウド版 では利用のハードルは低く、比較的気軽に使えると考えられます。

現時点では、1.10.0-rc.1 をセルフホスト すれば、いずれの機能も試用できます。ただし、SaaS と連携したトリガを試したい場合は、プラグインを自分でソースコードからパッケージすること と、前述のとおり 正規の証明書を取得して Dify を HTTPS でインタネットに公開すること が必要になる場合があります。

前提：トリガ機能の種類と仕組み

トリガ機能には、大まかには次の三つの種類があります。

スケジュール機能
Webhook 機能
SaaS 連携機能

スケジュール機能

スケジュールトリガ では、N 時間ごと・日次・週次・月次から選択するか、Cron 形式でのスケジュールを設定できます。

設定すると、worker_beat コンテナ（Dify の 1.7.0 から追加されています）でスケジュールが管理されます。コンテナ名の通り、このあたりの実装は Cerely Beat です。

指定した時間になると worker_beat コンテナからタスクがキックされ、あとは Cerely の Worker たる worker コンテナが後続の処理を担います。

これは組み込みの機能で、プラグインなしで動作 します。Dify 外への接続要件もなく、非常に気軽に使える、便利で強力な機能です。

Webhook 機能

Webhook トリガ を設定すると、ノードごとに一意の URL が発行されます。

これを外部から叩くことで、後続の処理が流れ始める仕組みです。この URL へのリクエストは、api コンテナが受け取っています。

これも組み込みの機能で、プラグインなしで動作 します。Webhook の送信側から Dify の URL に到達できさえすればよく、curl や Invoke-WebRequest などを使えばテストも簡単です。例えば企業のプライベートネットワーク内などでも便利に利用できるでしょう。

SaaS 連携機能

外部の SaaS で発生したイベント をトリガにできる機能で、動作には SaaS ごとに専用のプラグインが必要 です。

プラグインごとの設定で、Dify 側で 目的のイベントに応じた Subscription を作成 すると、その Subscription ごとに一意の URL が発行されます。この URL を SaaS 側の Webhook 送信機能に（手動または自動で）登録することで、Dify に SaaS 側のイベントが届くようになります。この URL へのリクエストは、api コンテナが受け取っています。

その仕様から、つまり、

SaaS 側から Dify 宛に HTTP でイベントを POST してもらう

ことで動作するため、Dify 側のエンドポイントをインタネットに公開する必要がある といえます。さらに、細かい要件は SaaS 側の仕様にも依存するものの、OAuth での認証プロセスも含めると、Dify 側のエンドポイントは 正規の SSL 証明書で保護された HTTPS であることが要求されることも多いでしょう。

この意味で、もともとインタネット上でサービスされている クラウド版の Dify では特別な工夫なく使えるため 利用のハードルは低い といえます。一方で セルフホスト環境 では、そもそもの 環境の用意それ自体に技術的なハードル がありますし、加えて、特に企業でのユースケースではインタネットにエンドポイントを露出させることに対して セキュリティポリシなどの管理面や運用面でもハードル があることが予想されます。

が、いずれにしても、うまく活用できれば強力な機能であることは確かです。

環境の準備

今回は、SaaS 連携を試す ことを目的に環境を準備します。

1.10.0-rc.1 をチェックアウト したうえで、標準の docker-compose.yaml の隣に、今回は次の docker-compose.override.yaml を用意しました（ドメインは example.com に置き換えています）。

services:
  api:
    environment: &env
      CONSOLE_API_URL: https://dify.example.com
      CONSOLE_WEB_URL: https://dify.example.com
      SERVICE_API_URL: https://dify.example.com
      TRIGGER_URL: https://dify.example.com
      APP_API_URL: https://dify.example.com
      APP_WEB_URL: https://dify.example.com
      FILES_URL: https://dify.example.com
      INTERNAL_FILES_URL: https://dify.example.com

  worker:
    environment: *env

  worker_beat:
    environment: *env

  plugin_daemon:
    environment:
      FORCE_VERIFYING_SIGNATURE: "false"
      ENFORCE_LANGGENIUS_PLUGIN_SIGNATURES: "false"

  nginx:
    environment:
      NGINX_HTTPS_ENABLED: "true"

ポイントは以下あたりです。

api サービスで、*_URL 系の指定を正規の HTTPS な URL にしています
- アンカ（&）とエイリアス（*）で、worker と worker_beat にも同じ設定をしています
plugin_daemon サービスで、自分でパッケージしたプラグイン（後述）をインストールできるように、次の二つを false にしています
- FORCE_VERIFYING_SIGNATURE：パッケージの署名の検証を強制する
- ENFORCE_LANGGENIUS_PLUGIN_SIGNATURES： author が langgenus のプラグインは署名を必須にする
nginx サービスで、HTTPS を有効化しています

なお今回、.env ファイルは .env.example をコピーしたまま、何も手を加えずに放置です。.env ファイルをいじらなくても、上記のように docker-compose.override.yaml に書けばそれが優先されます。この手法は、.env ファイルの差分を気にしなくてよくなるうえ、環境変数以外の細かいカスタマイズも一元管理できるので、なかなか楽です。

ファイルができたら、あとは docker compose up -d しておしまいです。試した範囲ではイメージの差し替えは不要でした。

プラグインの準備

現時点ではトリガ機能は正式版ではないので、プラグインはまだマーケットプレイスでは公開されていません。このため、SaaS 連携のトリガを使いたい場合は、開発中のプラグインのソースコードを持ってきて、自分でパッケージします。

開発中のプラグインは、だいたい dify-official-plugins か dify-plugin-sdks の Feature ブランチにあることが多く、今回もそうでした。本エントリ公開時点では以下が入っています。

langgenius/dify-official-plugins： feat/triggers ブランチの triggers ディレクトリ
- GitHub Trigger（今回試したもの）
- Linear Trigger
- Notion Trigger
- RSSHub Trigger
- Typeform Trigger
langgenius/dify-plugin-sdks： feat/trigger ブランチの python/examples ディレクトリ
- Dropbox Trigger
- GitHub Trigger
- Gmail Trigger（今回試したもの）
- Google Drive Trigger
- Lark Trigger
- Slack Trigger
- Telegram Trigger

これを Dify のプラグイン開発の通常のお作法でパッケージします。

dify plugin package ./github_trigger
dify plugin package ./gmail_trigger

今回は Gmail と GitHub を試したかったので、dify-official-plugins から GitHub Trigger を、 dify-plugin-sdks から Gmail Trigger をそれぞれパッケージしました。あとは Dify にインストールするだけです。

なお、Gmail Trigger はそのままでは動かず、修正が必要でした。修正は PR で送っているので、マージ前に手元で試したい場合は差分をあててからパッケージしてください。

Gmail と GitHub 以外のプラグインは細かい確認はしていませんが、manifest.yaml の meta.minimum_dify_version をいじらないとインストールができないパタンが多そうです。また、requirements.txt の dify_plugin は、最低でも 0.6.0b13 以降にしておくと安心です。どのプラグインも成熟しているとはいえないため、すんなり動けばラッキーくらいの気持ちで覚悟を持つとよいと思います。

試行： Gmail 連携

現時点の実装では、Gmail 用のトリガは次の 4 種類のイベントに対応しているようです。

メッセージの受信
メッセージの削除
メッセージのラベルの追加
メッセージのラベルの削除

今回はこのうち、メッセージの受信 を試しました。プラグインの README がけっこう細かいので、それを見ながら設定するとどうにかなりますが、大まかには構成のポイントは次のあたりです。

Gmail の API だけでなく、Cloud Pub/Sub の API も有効にする
Cloud Pub/Sub の Topic に Gmail のイベントが流れるようにする
Cloud Pub/Sub に Push な Subscription を作って、Dify の URL を入れる

Dify 側の Subscription の設定は例えばこんな感じです。Callback URL 欄に表示される URL を、Cloud Pub/Sub の Push 先にします。Label IDs は、今回は INBOX（受信トレイ）だけ選択しています。

Cloud Pub/Sub 側の設定例。Push の Subscription を作っています。

動作確認用のワークフローも作りました。トリガされたことがわかりさえすればよいので、トリガノードの出力を Template でダンプするだけのやつです。

Gmail にメールが届くと、トリガが実行されます。届いたメールと、それによって動いたワークフローのログがこんな感じです。

いい感じですね。

試行： GitHub 連携

現時点の実装では、GitHub 用のトリガは例えば以下のようなイベント（全部で 50 種類）に対応しているようです。

Issue の作成、コメントの追加
Pull Request の作成、レビュ、レビュコメントの追加
スターの追加
リリースの追加
ほか

今回は、シンプルに Issue の作成 を試しました。プラグインの README では PAK での認証が推奨されていましたが、GitHub 側での Webhook の作成がコケたので、OAuth にしています。

Dify 側の Subscription の設定はこんな感じです。リポジトリを選択して、受け取りたいイベントを選択します。今回は Issue 関係を選んでいます。

Subscription ができると、GitHub 側に設定が走り、指定したリポジトリに Webhook が自動で構成されます。投げ先の URL だけでなく、Dify 側で設定したとおりに投げるイベントの種類も自動で構成されました。

この状態で、指定したリポジトリに Issue を作成しました（後から画面を撮ったのでクローズ済みに見えますが、もちろん、作成しただけでイベントは発火します）。

ワークフローがトリガされたことがわかります。

GitHub 側でも、Webhook の送信履歴を確認できます。

いい感じですね。

おわりに

個人的に、SaaS 連携のトリガには Pull 型の実装、つまり Dify への インバウンド通信が必要ないアーキテクチャを期待 していたのですが、今のところは今回紹介したように Push 型 の実装のようでした。仮に Pull 型を目指した場合、Dify 側でサブスクライバ相当のプロセスなりスレッドなりを常駐させる必要も出てきそうなので、オーバヘッドを回避したか、アーキテクチャをシンプルにしたか、何か理由はあるものとは思います。

そんなわけで、正式版がリリースされたらクラウド版ではたいへん便利に使えると思いますが、Dify は残念ながら（運用負荷を飲んででも）セルフホストしたほうが機能が安定する傾向もあるので、セルフホスト環境での利用ハードルがすこし高い点は惜しいポイントです。

とはいえ、未来永劫このままということが決まっているわけでもなく、エンハンスは今後も続いていくでしょうし、引き続きの進化には期待したいですね。

@kurokobo

くろいです。ギターアンサンブルやら音響やらがフィールドの IT やさんなアルトギター弾き。たまこう 48 期ぎたさん、SFC '07 おんぞう、新日本ギターアンサンブル、Rubinetto。今は野良気味。