Agora ConvoAI と Dify を連携させ、会話 AI 開発を加速する

※ 本記事は、Agora 公式ドキュメントを含む以下情報を基に、編集・構成しました。
・https://docs.agora.io/en/conversational-ai/models/llm/dify
・https://docs.agora.io/en/conversational-ai/get-started/manage-agora-account
・https://marketplace.dify.ai/plugins/plutoless/convoai

はじめに

近年、LLM (大規模言語モデル) を活用したアプリケーション開発が急速に進んでいますが、より高度でインタラクティブな体験を提供するためには、外部サービスとの柔軟な連携が鍵となります。

本記事では、特に音声対話 AI の開発において、Agora の AI エンジンと Dify という 2つの強力なツールを連携させる具体的な方法に焦点を当てます。それぞれのツールの概要から、連携の手順、そしてユースケースに応じた連携方法の比較までを掘り下げていきます。

Agora Conversational AI Engine とは？

Agora Conversational AI Engine (以下、Agora ConvoAI) は、リアルタイム通信技術のグローバルリーダーである Agora が提供する会話型 AI ソリューションです。低遅延かつ高品質な音声認識・合成技術を基盤とし、人間のように自然な対話が可能なボイスアシスタントや AI エージェントを開発できます。

Dify とは？

Dify は、LLM アプリケーションを効率的に構築・運用するためのオープンソースプラットフォームです。プロンプトエンジニアリング、RAG (Retrieval-Augmented Generation)、エージェント機能などを GUI ベースで直感的に操作でき、バックエンドサービスとして API エンドポイントを簡単に作成できる点が特徴です。

連携前の準備

本格的な連携手順に入る前に、以下の準備が完了している必要があります。

Agora アカウントの準備:

Agora コンソールでアカウント登録を完了し、ログインできる状態にしておきます。

新規プロジェクトの作成、ConvoAI サービスの有効化: 

Dify アプリケーションの準備:

上記の準備が整ったら、Dify 側で Agora のプラグインをインストールし、API エンドポイントを作成します。

1. Dify プラグインのインストール

• Dify コンソールにログインし、トップナビゲーションバーから Plugins  ( https://cloud.dify.ai/plugins ) をクリックして Marketplace を開きます。

• Agora Conversational AI プラグインを検索し、Install をクリックします。
  ※ 「Verified by a Dify partner」アイコンが付いている方をお使いください
  

• または、プラグインの紹介ページを開き、Install をクリックします。
  https://marketplace.dify.ai/plugins/plutoless/convoai

• インストール後、Plugins ( https://cloud.dify.ai/plugins ) に戻り、Agora Conversational AI が追加されていることを確認します。

2. Agora コンソールの設定

• Agora コンソール  ( https://console.agora.io/ ) にログインし、プロジェクトを選択または新規作成します。
  
  
• プロジェクトの設定画面にある Conversational AI 機能が無効になっている場合は、有効化します。
  ※ 一度有効化すると、元に戻すことはできません

• プロジェクトの App ID を控えておきます。

• プロジェクトに対して Primary Certificate を既に有効にしている場合は、ConvoAI 側からも Token を用いてチャンネルへの接続が必要なため、この値も控えておきます。

• 以下のドキュメントの手順に沿って、RESTful API ページから Customer ID と Customer Secret を生成して控えておきます。
  ※ Customer ID と Customer Secret は、厳重に保管してください
  Generate Customer ID and Customer Secret

3. Dify での API エンドポイント作成

• インストールした Agora Conversational AI プラグインをクリックします。
• エンドポイントの追加・設定パネルが出てきたら「+」をクリックし、設定を行います。
• 後続のステップで紹介する 3つの連携方法をスムーズに試すため、赤くマークされている必須項目すべてに正しい情報を入力することを推奨します。
• App には、LLM として連携したい、作成済みの Dify アプリケーションを指定します。
• Agora App ID、 Agora RESTful Customer ID、 Agora RESTful Customer Secret には、それぞれ Agora コンソールから取得した値を入力します。

• ASR Vendor および ASR Language は、今回はそれぞれ「Ares」「ja-JP」とします。

• TTS Vendor では、連携したい TTS のベンダーを、一覧から選択ください。
• TTS Params の欄には、TTS の API Key、音声モデル等の情報を JSON 形式で入力します。各　 TTS ベンダーにおいて設定可能なパラメーター情報は、以下ドキュメントからご確認いただけます。
  https://docs.agora.io/en/conversational-ai/models/tts/overview

※ 入力例

"tts": {
  "vendor": "elevenlabs",
  "params": {
    "key": "<your_elevenlabs_key>",
    "model_id": "eleven_flash_v2_5",
    "voice_id": "pNInz6obpgDQGcFmaJgB",
    "sample_rate": 24000
  }
}

• Agora プロジェクトの設定に応じて、Agora App Certificate には、Agora コンソールから取得した Primary Certificate を入力ください。
  ※ Primary Certificate を有効にしていない場合は、空白のままにしてください

• そのほかの任意項目については、ドキュメントを参考に必要に応じて記入ください。
  https://marketplace.dify.ai/plugins/plutoless/convoai
• 設定項目の記載が終わったら「Save」を押して作業を完了してください。
  
  

4. エンドポイント情報の保存

• 設定を保存すると、Dify が Endpoint URL を生成します。

連携方法の手順紹介

Agora ConvoAI と Dify を連携させる方法には、大きく分けて以下の 3つのアプローチがあります。

1. 動作確認用 Web ページ (convoai-web):
   ・コーディング不要で、ブラウザから動作確認やデモを行うための方法です。
2. Dify エンドポイント実行型 (convoai-start/-stop):
   ・Dify が生成した API (/convoai-start など) を呼び出し、会話セッションを制御する方法です。
3. Agora API 実行型 (dify-completion):
   ・Agora ConvoAI の join API を呼び出し、Dify を LLM プロバイダーとして (/dify-completion) 組み込む方法です。

ここでは、これら 3つの方法を順に詳しく見ていきましょう。

方法1: 動作確認用 Web ページ (convoai-web)

これは、Dify の Agora Conversational AI プラグインで API エンドポイントを作成すると自動的に利用可能になる、テスト・デモ用の Web ページです。「連携前の準備」で取得した Endpoint URL の末尾を /convoai-web/index.html に置き換えてブラウザでアクセスするだけで、設定した Dify エージェントと音声で会話できます。

アクセス URL の例

https://[.....].ai-plugin.io/convoai-web/index.html

方法2: Dify エンドポイント実行型 (convoai-start/-stop)

この方法では、 Dify プラグインが生成したエンドポイントを操作して、会話セッションを開始・停止します。

会話開始

会話を開始するために必要なパラメータは以下の通りです。

• base_url: エンドポイントのベース URL
• channel: 接続したいチャンネル名

サンプルコード (cURL)

# 会話を開始する
curl 'https://[.....].ai-plugin.io/convoai/convoai-start' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  --data-raw '{"base_url":"https://[.....].ai-plugin.io","channel":"..."}'

成功すると、対話相手であるエージェント ID ( agent_id ) を含むレスポンスを返します。
この値は、会話を停止する際に必要な情報となります。

{"agent_id":"A42AE72JP99LM29DH77DP24EJ76KP49Y","create_ts":1760956899,"status":"RUNNING"}

会話停止

会話を停止するために必要なパラメータは以下の通りです。
agent_id: 対話相手のエージェント ID
サンプルコード (cURL)

# 会話を停止する
curl 'https://[.....].ai-plugin.io/convoai/convoai-stop' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  --data-raw '{"agent_id":"A42AE72JP99LM29DH77DP24EJ76KP49Y"}'

方法3: Agora API 実行型 (dify-completion)

Agora ConvoAI が用意する join RESTful API を使い、エージェントを起動する方法です。この方法では、設定パラメータの一部として Dify を LLM プロバイダーとして組み込む形になります。

サンプルコード (JSON)

以下は、ConvoAI エージェントを起動する join API に渡すリクエストボディのうち、llm パラメータ設定のサンプルです。

"llm": {
  "url": "https://xxxxxx.ai-plugin.io/convoai/dify-completion",
  "api_key": "<API Key generated by Dify plugin>",
  "style": "dify",
  "params": {
      "model": "default"
  } 
}

【方法3 のための補足: ASR/TTS 設定について】

この方法では、Dify は単なる LLM プロバイダーとして機能するため、 Dify プラグイン側の ASR/TTS 設定ではなく、API リクエストで設定した方が使われます。
Dify プラグインの設定は「App」の選択と「Endpoint URL」「API Key」の取得さえできれば、他の項目はダミーでも動作します。

必要なパラメータ:

• url: Dify プラグインが生成したカスタムエンドポイント URL (/convoai/dify-completion) を指定します。
• api_key: Dify のエンドポイント設定画面で生成された API キーを指定します。
• style: "dify" を設定し、Dify のメッセージ形式とワークフロー処理を使用します。
• model: "default" を設定し、Dify アプリケーションで設定されたモデルを使用します。

この API が必要とするその他のパラメータ含む、具体的な情報は、下記ドキュメントからご確認ください。
https://docs.agora.io/en/conversational-ai/rest-api/join

各連携方法の比較

ここまで 3つの連携方法を紹介してきましたが、開発者はどれを選択すべきでしょうか。ここで、それぞれの方法がどのようなユースケースに適しているか、概要を説明します。

「方法1: 動作確認用 Web ページ」が適しているケース:

• コーディングを一切行わず、Dify で設定したエージェントが音声対話で正しく動作するかを迅速にテストしたい場合。
• 開発者以外の人にデモンストレーションとして機能を見せたい場合。
  
  

「方法2: Dify エンドポイント実行型」が適しているケース:

• Agora ConvoAI の複雑な API 仕様を意識せず、Dify 上で事前設定した内容で手軽に音声対話を開始・停止したい場合。
• 既存システムへの組み込みを、よりシンプルな API コールで迅速に実現したい場合。
  
  

「方法3: Agora API 実行型」が適しているケース:

• ASR や TTS の種類、言語、声のモデルなどを、API 実行時に動的に指定・変更したい場合。これは、Agora ConvoAI の RESTful API (/join など) の JSON ペイロードで、リクエストごとに ASR/TTS/LLM の設定を上書きできるためです (例: ユーザーごとに言語や声を変える)。
• Dify の RAG/ワークフローを活用しつつ、Agora ConvoAI が提供する最新・全ての機能をフル活用したい場合。

詳細は以下の表で比較します。

おわりに

本記事では、Agora ConvoAI と Dify を連携させるための 3つの具体的な方法と、それぞれの特徴について解説しました。

• 動作確認用 Web ページは、コーディング不要で迅速なテストとデモを可能にします。
• Dify エンドポイント実行型は、既存システムへのシンプルな API 統合を実現します。
• Agora API 実行型は、Dify の強力なワークフローと Agora ConvoAI の最新機能を最大限に引き出す、最も柔軟で強力な連携方法です。

プロジェクトの要件や開発フェーズに応じて適切な連携方法を選択することで、より洗練された会話型 AI アプリケーションの開発が可能になります。ぜひ、これらの方法を試し、次世代の音声対話体験を構築してみてください。