指南

聊天模式

使用聊天模式，将智能体配置为仅文本对话

聊天模式让智能体能够充当聊天智能体，即进行无需音频输入/输出的纯文本对话。这适用于构建聊天界面、测试智能体，或无需音频的场景。

概述

启用聊天模式主要有两种方式：

  1. 智能体配置：通过 API 创建智能体时，将其配置为纯文本模式
  2. 运行时覆盖：使用 SDK 覆盖以编程方式强制进行纯文本对话

本指南介绍这两种方法，以及如何在不同 SDK 中实现聊天模式。

创建纯文本智能体

将智能体配置为纯文本模式，使其成为与该智能体进行每次对话时的默认设置。

在控制台中打开智能体，前往 高级 标签页，启用 仅文本 开关。保存更改。

有关完整 API 参考文档和所有可用配置选项，请参阅 Create Agent API 文档中的 text only 字段。

纯文本模式的运行时覆盖

如需在运行时通过覆盖启用聊天模式（而非在智能体级别配置），可在对话配置中使用 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 事件/回调。否则，智能体的文本回复将不会发送或显示给用户。

安全覆盖：使用运行时覆盖（而非智能体级别配置）时，必须在智能体安全设置中启用对话覆盖。前往智能体的 安全 标签页并启用相应覆盖。详情请参阅覆盖文档。

关键要求

  1. 智能体响应事件：始终配置 agent_response 回调或事件处理程序，以接收并显示智能体的文本消息。

  2. 智能体配置：如果在智能体设置中专门设为聊天模式，将自动使用纯文本对话，无需覆盖。

  3. 无需音频界面：使用纯文本模式时，无需配置音频界面或请求麦克风权限。

示例：处理智能体响应

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 倍
  • 独立资源池：文本对话使用专用并发池，不受语音对话并发限额影响
  • 可扩展性：非常适合客户支持、聊天机器人或自动化测试等高吞吐量应用
套餐语音并发数纯聊天并发数
免费版4100
Starter6150
Creator10250
Pro20500
Scale30750
商业版30750
企业版提升提升（25 倍）

在发起连接时，纯聊天对话会在握手期间先按总并发限额检查；连接建立后，再转移至独立的纯聊天并发池。

使用场景

聊天模式非常适合：

  • 聊天界面：构建无需语音的传统聊天 UI
  • 测试：无需依赖音频即可测试智能体逻辑
  • 无障碍访问：为用户提供基于文本的替代方案
  • 安静环境：不适合音频输入/输出时
  • 集成测试：自动化测试智能体对话

故障排除

智能体未响应

如果未显示智能体回复：

  1. 确认已正确配置 agent_response 回调
  2. 检查智能体是否已配置聊天模式，或是否设置了 textOnly 覆盖
  3. 确保 WebSocket 连接已成功建立

后续步骤