チャットモード | ElevenLabs Documentation

チャットモードでは、エージェントをチャットエージェントとして動作させられます。つまり、オーディオの入力／出力なしでテキストのみの会話を行えます。これは、チャットインターフェースの構築、エージェントのテスト、またはオーディオが必要ない場合に便利です。

概要

チャットモードを有効にする主な方法は2つあります。

エージェント設定：API経由で作成する際に、エージェントをテキスト専用モードに設定
実行時の上書き：SDKの上書きを使用して、プログラムでテキスト専用の会話を強制

このガイドでは、両方のアプローチと、異なるSDKでチャットモードを実装する方法を説明します。

テキスト専用エージェントの作成

エージェントをテキスト専用モードに設定すると、そのエージェントとのすべての会話でデフォルトになります。

ダッシュボードで更新

CLIで更新

APIで更新

ダッシュボードでエージェントを開き、Advancedタブに移動してText onlyトグルを有効にします。変更を保存してください。

完全なAPIリファレンスと利用可能なすべての設定オプションについては、Create Agent APIドキュメントのテキスト専用フィールドを参照してください。

テキスト専用モードの実行時上書き

エージェントレベルで設定するのではなく、上書きを使用して実行時にチャットモードを有効にするには、会話設定でtextOnly上書きを使用します。

from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
# Configure for text-only mode with proper structure
conversation_override = {
    "conversation": {
        "text_only": True
    }
}
config = ConversationInitiationData(
    conversation_config_override=conversation_override
)
conversation = Conversation(
    elevenlabs,
    agent_id,
    requires_auth=bool(api_key),
    config=config,
    # Important: Ensure agent_response callback is set
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
)
conversation.start_session()

この設定により、以下が保証されます。

オーディオ入力／出力を使用しない
すべての通信がテキストメッセージで行われる
会話がチャットのようなインターフェースモードで動作する

重要な注意事項

重要：チャットモードを使用する場合は、agent_responseイベント／コールバックが有効化され、適切に設定されていることを確認する必要があります。これがない場合、エージェントのテキスト応答は送信もユーザーへの表示もされません。

セキュリティ上書き：実行時上書き（エージェントレベルの設定ではないもの）を使用する場合は、エージェントのセキュリティ設定で会話の上書きを有効にする必要があります。エージェントの Securityタブに移動し、適切な上書きを有効にしてください。詳細は上書きに関するドキュメントを参照してください。

主な要件

エージェント応答イベント：エージェントのテキストメッセージを受信・表示するために、常にagent_responseコールバックまたはイベントハンドラーを設定してください。
エージェント設定：エージェント設定でチャットモードを指定している場合、上書きを指定しなくても自動的にテキスト専用の会話が使用されます。
オーディオインターフェースは不要：テキスト専用モードでは、オーディオインターフェースの設定やマイク権限のリクエストは必要ありません。

例：エージェント応答の処理

def handle_agent_response(response):
    """Critical handler for displaying agent messages"""
    print(f"Agent: {response}")  # Update your UI with the response
    update_chat_ui(response)
config = ConversationInitiationData(
    conversation_config_override={"conversation": {"text_only": True}}
)
conversation = Conversation(
  elevenlabs,
  agent_id,
  config=config,
  callback_agent_response=handle_agent_response,
)
conversation.start_session()

テキストメッセージの送信

チャットモードでは、オーディオではなくプログラムでユーザーメッセージを送信する必要があります。

# Send a text message to the agent
conversation.send_user_message("Hello, how can you help me today?")

同時実行のメリット

チャットモードは、音声会話と比較して大きな同時実行上のメリットがあります。

より高い上限：チャット専用会話の同時実行上限は、音声会話の25倍です
独立したプール：テキスト会話は、音声会話の上限とは独立した専用の同時実行プールを使用します
スケーラビリティ：カスタマーサポート、チャットボット、自動テストなど、高スループットのアプリケーションに最適です

プラン	音声の同時実行数	チャット専用の同時実行数
無料	4	100
スターター	6	150
クリエイター	10	250
プロ	20	500
スケール	30	750
ビジネス	30	750
エンタープライズ	拡張	拡張（25倍）

接続開始時には、チャット専用会話はハンドシェイク処理中にまず合計同時実行上限に対して確認され、接続が確立されると別のチャット専用同時実行プールに移されます。

ユースケース

チャットモードは、以下の用途に最適です。

チャットインターフェース：音声を使用しない従来型のチャットUIの構築
テスト：オーディオ依存なしでエージェントロジックをテスト
アクセシビリティ：ユーザーにテキストベースの代替手段を提供
静かな環境：オーディオ入力／出力が適さない場合
統合テスト：エージェント会話の自動テスト

トラブルシューティング

エージェントが応答しない

エージェントの応答が表示されない場合：

agent_responseコールバックが適切に設定されていることを確認します。
エージェントがチャットモードに設定されているか、textOnly上書きが設定されていることを確認します。
WebSocket接続が正常に確立されていることを確認します。

次のステップ

エージェントの動作をカスタマイズする
高度なインタラクションのためのクライアントイベントを確認する
安全な会話のための認証設定を確認する