リアルタイム音声AI（会話型AI）を簡単に実現！Agora Conversational AI Engine 入門 その 2: RESTful API による AI エージェントの制御と LLM/TTS 連携

Conversational AI Engine の RESTful API とは：機能と連携の仕組み

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 Agent をチャンネルに入室させるデモ

本記事のデモでは、この RESTful API を活用して AI エージェントを操作し、実際に対話を行うまでの具体的な手順を追っていきます。 その主な流れは、以下の 3 つのステップに集約されます。

ステップ 1: AI エージェントの設定・起動

• まず、API を利用するための認証情報 (Customer ID・Customer Secret など) を準備します。
• 次に、Join API を使用して AI エージェントを特定のチャンネルに起動させます。この際、連携させたい LLM（例: Gemini）や TTS（例: Elevenlabs）といった外部サービスの設定も API リクエストに含めて行います。

ステップ 2: クライアントとの対話

• AI エージェントがチャンネルで稼働したら、Agora Web Demo のようなクライアントアプリケーションから同じチャンネルに接続し、AI エージェントとの音声対話を試します。

ステップ 3: AIエージェントの退出・停止

• 対話が終了した後、Leave API を使用して AI エージェントをチャンネルから退出させ、停止させます。

それでは、これらのステップに沿って、具体的な手順を見ていきましょう。

尚、ここからは Agora アカウントへのサインアップおよび Agora プロジェクトの設定反映済みである前提で解説します。これらがまだの場合、前回の記事からお読みください。

⚠️ デモ実施にあたっての準備と注意点

本デモを進めるにあたり、以下の準備と点にご留意ください。

• Agora アカウント: 本デモで紹介する機能のご利用には、Agora へのサインアップとプロジェクトの作成が必要です。
• LLM と TTS の準備: 本デモでは、外部のサードパーティ製 LLM (例: Gemini) および TTS (例: Elevenlabs) と連携します。これらのサービスのアカウント登録とAPIキーの取得は、各自で行っていただく必要があります。
• 利用料金について:
  • Agora Conversational AI Engine のご利用（APIコールやエージェントの稼働時間など）に応じて、Agora のクレジットが消費されます。無料トライアル枠を超過した場合は、料金が発生します。
  • 連携するサードパーティの LLM および TTS の利用についても、各サービスの料金規定に基づき、別途料金が発生する可能性があります。ご利用前に各サービスの料金体系をご確認ください。

今回は手順をシンプルにするため、ターミナル (コマンドプロンプト) 上で、curl コマンドから RESTful API にアクセスして、AI エージェントの設定・制御を行なうこととします。

ステップ 1:  AI エージェントの設定、起動

1-1: Customer ID・Customer Secret の入手

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 は第三者に知られないよう、厳重に管理してください。

1-2: Authorization Header の作成

Customer ID・Customer Secret を生成したら、これらをコロン文字「: 」で結合し、Base64 エンコードします。
こちらは、公式ドキュメント (RESTtful authentication) がサーバーサイドのサンプルコード (Basic authentication sample code) として、数種類紹介されております。

1-3: 一時 Token の発行

Secure Mode を選択して Agora プロジェクト作成した場合 (下画像)、各クライアントはチャンネルへの接続の時に認証用の Token を求められます。
※ Testing Mode の場合は AppID のみ

通常、クライアント毎に Token を発行するアプリケーションサーバーの構築が必要ですが、簡易検証として、Console のプロジェクト画面から、一時 Token が発行できます (下画像、赤枠の箇所)。
※ 参考リンク

1-4: AI エージェントの設定、起動

AI  エージェントの設定、起動には Join API を使います:

• エンドポイント: POST
  

  　https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/join>

• パスパラメータ:
  {appid}: あなたの Agora プロジェクトの App ID に置き換えます。

今回は LLM を Gemini、TTS を Elevenlabs とした設定例を紹介します。
ここでは紹介していないパラメーターの種類や設定値等は以下ドキュメントをご覧ください:

• ドキュメント: 
  https://docs.agora.io/en/conversational-ai/rest-api/join

設定例：

  "name": "my_first_ai_agent",

• name: AI エージェントのユニークな識別子 (ID) 

  "properties": {
    "channel": "test",
    "token": "<your_token>",
    "agent_rtc_uid": "0",
    "remote_rtc_uids": ["*"],
    "idle_timeout": 60,
    ...

• properties.channel: 接続先のチャンネル名
• properties.token: 接続時の認証 Token
• properties.agent_rtc_uid: 接続先チャンネルでの AI エージェントの uid。「0」 を指定する場合は、ランダムな整数 uid が割り振られる
• properties.remote_rtc_uids: 対話相手のユーザー uid 一覧。全ユーザー対象の場合は [ "*" ]  と指定
• properties.idle_timeout: 対話相手の全ユーザーが退出後、AI エージェントが自動停止・退出するまでの待機時間（秒）

  "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 の設定項目

• url: 連携したい LLM のエンドポイント URL
• api_key:  LLM の API キー
• system_messages: AI エージェントのペルソナや回答スタイルの設定、行動制約・制限の設定など、基本的な指示や前提条件を LLM に与えるためのデータ・メッセージ。System Message Developer Message など、messages に相当
• greeting_message: 最初のユーザー参加時に AI エージェントが発する挨拶メッセージ
• params: 連携する LLM に対する追加パラメーター
• params.model: 使用したい LLM のモデル名
• style: リクエスト形式スタイル。openai または gemini が指定可能

  "properties": {
    ...
    "asr": {
      "language": "ja-JP"
    },
    ...

properties.asr:

• language: ユーザーがAIエージェントと対話する際に使用する言語（ASRが認識する言語）を指定 ( 例："ja-JP", “en-US” )

  "properties": {
    ...
    "tts": {
      "vendor": "elevenlabs",
      "params": {
        "key": "<your_tts_api_key>",
        "model_id": "eleven_flash_v2_5",
        "voice_id": "<your_voice_id>"
      }
    }

properties.tts: TTS の設定項目

• vendor: 連携したい TTS のベンダー名。microsoft, elevenlabs から選択可能
• params: 選択したベンダー固有の設定パラメーター (TTS vendor configuration)

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"
}

ステップ 2: クライアントとの対話

Join API で参加させた AI エージェントとの対話は、Agora Video/Voice SDK で実装したクライアントアプリから行えます。
ここでは、Web ベースの Agora Web Demo ( https://webdemo-global.agora.io/index.html ) を使って確認してみましょう。

2-1: Agora Web Demo へのアクセス

Agora Web Demo の利用には、Agora アカウントへのサインインが必要になります。
サインイン後、再度デモにアクセスしてください。

2-2: Web Demo の初期化

「Initialize Settings」から、Join API で使った App ID のプロジェクト名を選択後、「Setup」を押して反映します

2-3: Web Demo からの接続

「Quick Start > Video & Voice Calling」などのサンプルで、画面の指示に沿って、AI エージェントがいる同じチャンネルに接続します。

2-4: AI エージェントとの対話

Web Demo でチャンネルに接続後、以下の点を確認しましょう。

• AIエージェントの存在確認: もしチャンネル内に AI エージェントが見当たらない（または応答がない）場合は、idle_timeout の時間に達し、AI エージェントが自動的に退出した可能性があります。その際は「ステップ 1」から AI エージェントを再起動してください。
• 挨拶メッセージの確認: AI エージェントが正常に動作していれば、greeting_message で設定した挨拶が音声で再生されます。これが確認できれば成功です。

AIエ ージェントとの対話をお楽しみください。

※ 音声が聞こえない時は…
挨拶メッセージが聞こえないなど、AI エージェントとの音声対話がうまくいかない場合は、以下の点を確認してみてください。

• Join APIリクエスト内容: api_key (LLM/TTS)、url (LLM)、モデル名、ボイス ID などが正しく設定されているか
• 外部サービス (LLM/TTS) の状態: 契約プランの利用上限やクレジット残高、サービス側の障害情報など
• 基本的な音声設定: Web デモやPCのスピーカー・マイク設定
  
  

ステップ 3: AI エージェントの退出、停止

AIエージェントとの対話が終了したら、エージェントをチャンネルから退出させ、停止させる必要があります。これには Leave API を使用します。

• エンドポイント: POST

  　https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/leave

• パスパラメータ:
  {appid}: あなたの Agora プロジェクトの App ID に置き換えます。
  {agentId}: ステップ1-4の Join API の成功レスポンスで取得した agent_id に置き換えます。
• リクエストボディ: このAPIでは、リクエストボディは不要です。
• ドキュメント:
  https://docs.agora.io/en/conversational-ai/rest-api/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 エージェントの制御が可能になると思います。

以下、一部の紹介です: 

• Query agent status: 指定した AI エージェントの現在の稼働状態（例：RUNNING, STOPPEDなど）を確認します
• Speak: AIエージェントに任意のテキストを指定して発話させることができます
• History: AIエージェントとの対話履歴を取得します

また、今回は簡潔にするため curl を使ってエージェントを手動で制御しましたが、実際の運用では、クライアントアプリケーションからのリクエストと連携できるよう、バックエンドのアプリケーションサーバーを構築することが一般的です。

このサーバーのセットアップ手順や、Conversational AI Engine との連携方法について詳しく解説した記事が、Agora社の技術ブログで多数公開されていますので、ぜひ参考にしてください。

• Build a Conversational AI Backend with Python and Agora
• Building an Agora Conversational AI Backend with Fastify
• Build an Agora Conversational AI Backend with Express
• Build an Agora Conversational AI Service using Golang
• Build a Conversational AI App with Next.js and Agora