跳到导航
指南

聊天模式

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

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

概述

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

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

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

创建仅文本智能体

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

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

有关完整 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 事件/回调。 否则，智能体的文本回复不会发送给用户或显示给用户。

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

主要要求

  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 连接已成功建立

后续步骤