> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 聊天模式

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

## 概述

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

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

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

## 创建纯文本智能体

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

#### 通过控制台更新

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

#### 通过 CLI 更新

#### 拉取智能体配置

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### 编辑 \`agent_configs/\<agent-name>.json\`

设置 `conversation_config.conversation.text_only`：

```json
{
  "conversation_config": {
    "conversation": {
      "text_only": true
    }
  }
}
```

#### 推送更改

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### 通过 API 更新

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "conversation": {"text_only": True},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    conversation: { textOnly: true },
  },
});
```

> **Info**
>
> 有关完整 API 参考文档和所有可用配置选项，请参阅 [Create Agent API 文档中的 text only 字段](/docs/zh/api-reference/agents/create#request.body.conversation_config.conversation.text_only)。

## 纯文本模式的运行时覆盖

如需在运行时通过覆盖启用聊天模式（而非在智能体级别配置），可在对话配置中使用 `textOnly` 覆盖：

```python
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()
```

```javascript
const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  overrides: {
    conversation: {
      textOnly: true,
    },
  },
});
```

此配置可确保：

* 不使用音频输入/输出
* 所有通信均通过文本消息进行
* 对话在类似聊天界面的模式下运行

## 重要说明

> **Warning**
>
> **关键**：使用聊天模式时，必须确保已启用并正确配置 `agent_response` 事件/回调。否则，智能体的文本回复将不会发送或显示给用户。

> **Info**
>
> **安全覆盖**：使用运行时覆盖（而非智能体级别配置）时，必须在智能体安全设置中启用对话覆盖。前往智能体的 **安全** 标签页并启用相应覆盖。详情请参阅[覆盖文档](/docs/zh/eleven-agents/customization/personalization/overrides)。

### 关键要求

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

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

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

### 示例：处理智能体响应

```python
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()
```

```javascript
const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  overrides: {
    conversation: {
      textOnly: true,
    },
  },
  // Critical: Handle agent responses
  onMessage: (message) => {
    if (message.type === "agent_response") {
      console.log("Agent:", message.text);
      // Display in your UI
      displayAgentMessage(message.text);
    }
  },
});
```

## 发送文本消息

在聊天模式下，需要以编程方式发送用户消息，而不是通过音频发送：

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

```javascript
// Send a text message to the agent
conversation.sendUserMessage({
  text: "Hello, how can you help me today?",
});
```

## 并发优势

与语音对话相比，聊天模式具有显著的并发优势：

* **更高限额**：纯聊天对话的并发限额是语音对话的 25 倍
* **独立资源池**：文本对话使用专用并发池，不受语音对话并发限额影响
* **可扩展性**：非常适合客户支持、聊天机器人或自动化测试等高吞吐量应用

| 套餐      | 语音并发数 | 纯聊天并发数   |
| ------- | ----- | -------- |
| 免费版     | 4     | 100      |
| Starter | 6     | 150      |
| Creator | 10    | 250      |
| Pro     | 20    | 500      |
| Scale   | 30    | 750      |
| 商业版     | 30    | 750      |
| 企业版     | 提升    | 提升（25 倍） |

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

## 使用场景

聊天模式非常适合：

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

## 故障排除

### 智能体未响应

如果未显示智能体回复：

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

## 后续步骤

* 了解如何[自定义智能体行为](/docs/zh/eleven-agents/customization/llm)
* 探索用于高级交互的[客户端事件](/docs/zh/eleven-agents/customization/events/client-events)
* 查看如何设置[身份验证](/docs/zh/eleven-agents/customization/authentication)，以实现安全对话