Agora Conversational AI Engine は、AI エージェントの柔軟な運用を実現するため、一連の RESTful API を提供しています。これら API を用いることで、AI エージェントの作成とチャンネルへの参加、そこからの退出といったライフサイクル管理や、動作設定の変更といった操作をプログラムから実行できます。
AI エージェントの対話品質を左右する大規模言語モデル (LLM) や音声合成 (TTS) との連携についても、RESTful API を通じて詳細な設定が可能です。開発者は、利用したい外部の LLM サービスや TTS サービスに関する情報を API リクエストのボディに含めることで、Conversational AI Engine にこれらのサービスと連携する AI エージェントを構築・制御させることができます。
これにより、API を通じて LLM のモデル選定や応答特性の調整、TTS の声質や言語の選択といった、AIエージェントの核心的な動作に関わるカスタマイズを行えます。
本記事のデモでは、この RESTful API を活用して AI エージェントを操作し、実際に対話を行うまでの具体的な手順を追っていきます。 その主な流れは、以下の 3 つのステップに集約されます。
それでは、これらのステップに沿って、具体的な手順を見ていきましょう。
尚、ここからは Agora アカウントへのサインアップおよび Agora プロジェクトの設定反映済みである前提で解説します。これらがまだの場合、前回の記事からお読みください。
⚠️ デモ実施にあたっての準備と注意点
本デモを進めるにあたり、以下の準備と点にご留意ください。
今回は手順をシンプルにするため、ターミナル (コマンドプロンプト) 上で、curl コマンドから RESTful API にアクセスして、AI エージェントの設定・制御を行なうこととします。
RESTful API の使用条件として、各リクエストには、Basic 認証のための Authorization Header を含める必要があります。
Authorization: Basic <your_base64_encoded_credentials>
ヘッダーの中にある <your_base64_encoded_credentials> の部分には、Base64 エンコードした Customer ID・Customer Secret を指定します。
Customer ID・Customer Secret は Agora Console から生成いただけます。取得方法は本記事のスコープ外となりますため、公式ドキュメント (RESTtful authentication) からご覧ください。
注意: Customer ID ・ Customer Secret は第三者に知られないよう、厳重に管理してください。
Customer ID・Customer Secret を生成したら、これらをコロン文字「: 」で結合し、Base64 エンコードします。
こちらは、公式ドキュメント (RESTtful authentication) がサーバーサイドのサンプルコード (Basic authentication sample code) として、数種類紹介されております。
Secure Mode を選択して Agora プロジェクト作成した場合 (下画像)、各クライアントはチャンネルへの接続の時に認証用の Token を求められます。
※ Testing Mode の場合は AppID のみ
通常、クライアント毎に Token を発行するアプリケーションサーバーの構築が必要ですが、簡易検証として、Console のプロジェクト画面から、一時 Token が発行できます (下画像、赤枠の箇所)。
※ 参考リンク
AI エージェントの設定、起動には Join API を使います:
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/join>
今回は LLM を Gemini、TTS を Elevenlabs とした設定例を紹介します。
ここでは紹介していないパラメーターの種類や設定値等は以下ドキュメントをご覧ください:
設定例：
"name": "my_first_ai_agent",
"properties": {
"channel": "test",
"token": "<your_token>",
"agent_rtc_uid": "0",
"remote_rtc_uids": ["*"],
"idle_timeout": 60,
...
"properties": {
...
"llm": {
"url": "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
"api_key": "<your_llm_api_key>",
"system_messages": [
{
"role": "system",
"content": "You are a helpful chatbot."
}
],
"greeting_message": "こんにちは",
"params": {
"model": "gemini-2.0-flash"
},
"style": "openai",
},
...
properties.llm: LLM の設定項目
"properties": {
...
"asr": {
"language": "ja-JP"
},
...
properties.asr:
"properties": {
...
"tts": {
"vendor": "elevenlabs",
"params": {
"key": "<your_tts_api_key>",
"model_id": "eleven_flash_v2_5",
"voice_id": "<your_voice_id>"
}
}
properties.tts: TTS の設定項目
AI エージェントの設定が完成したら、これをHTTP リクエストボディに含めて POST 送信します。
ここでは curl コマンドを使った例を紹介しますが、別の REST クライアントでの代替も可能です。
エンドポイントの {appid} や、<your_base64_encoded_credentials> など、その他プレースホルダーを箇所を置きかえて、実行ください:
curl -X POST https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/join \
-H 'Authorization: Basic <your_base64_encoded_credentials>' \
-H 'Content-Type: application/json' \
-d '{
"name": "my_first_ai_agent",
"properties": {
"channel": "test",
"token": "<your_token>",
"agent_rtc_uid": "0",
"remote_rtc_uids": ["*"],
"idle_timeout": 60,
"llm": {
"url": "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
"api_key": "<your_llm_api_key>",
"system_messages": [
{
"role": "system",
"content": "You are a helpful chatbot."
}
],
"greeting_message": "こんにちは",
"params": {
"model": "gemini-2.0-flash"
},
"style": "openai",
},
"asr": {
"language": "ja-JP"
},
"tts": {
"vendor": "elevenlabs",
"params": {
"key": "<your_tts_api_key>",
"model_id": "eleven_flash_v2_5",
"voice_id": "<your_voice_id>"
}
}
}
}'
リクエストが成功すると、AI エージェントの ID、タイムスタンプ、実行ステータスを含む JSON レスポンスが返されます。
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"create_ts": 1737111452,
"status": "RUNNING"
}
Join API で参加させた AI エージェントとの対話は、Agora Video/Voice SDK で実装したクライアントアプリから行えます。
ここでは、Web ベースの Agora Web Demo ( https://webdemo-global.agora.io/index.html ) を使って確認してみましょう。
Agora Web Demo の利用には、Agora アカウントへのサインインが必要になります。
サインイン後、再度デモにアクセスしてください。
「Initialize Settings」から、Join API で使った App ID のプロジェクト名を選択後、「Setup」を押して反映します
「Quick Start > Video & Voice Calling」などのサンプルで、画面の指示に沿って、AI エージェントがいる同じチャンネルに接続します。
Web Demo でチャンネルに接続後、以下の点を確認しましょう。
AIエ ージェントとの対話をお楽しみください。
※ 音声が聞こえない時は…
挨拶メッセージが聞こえないなど、AI エージェントとの音声対話がうまくいかない場合は、以下の点を確認してみてください。
AIエージェントとの対話が終了したら、エージェントをチャンネルから退出させ、停止させる必要があります。これには Leave API を使用します。
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/leave
curlコマンドでの実行例:
エンドポイントの {appid} および {agentId}、そして <your_base64_encoded_credentials> を実際の値に置き換えて実行してください。
curl -X POST \
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/leave \
-H "Authorization: Basic <your_base64_encoded_credentials>"
レスポンス:
リクエストが成功すると、HTTPステータスコード 200 OK が返され、レスポンスボディは空です。 何か問題が発生した場合は、200以外のHTTPステータスコードと共に、エラーの理由を示す情報がレスポンスボディに含まれて返されます。例えば、以下のような形式です。
{
"detail": "core: db failed, task not found",
"reason": "TaskNotFound"
}
本記事では、RESTful API を制御して、AI エージェントの設定・制御、そして実際に Web クライアントとの対話する方法を紹介しました。
今回紹介した以外の API も用意されていますので、これらを組み合わせることで、より柔軟に AI エージェントの制御が可能になると思います。
以下、一部の紹介です:
また、今回は簡潔にするため curl を使ってエージェントを手動で制御しましたが、実際の運用では、クライアントアプリケーションからのリクエストと連携できるよう、バックエンドのアプリケーションサーバーを構築することが一般的です。
このサーバーのセットアップ手順や、Conversational AI Engine との連携方法について詳しく解説した記事が、Agora社の技術ブログで多数公開されていますので、ぜひ参考にしてください。