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アプリケーションの開発が可能になります。ぜひ、これらの方法を試し、次世代の音声対話体験を構築してみてください。