> 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.

# 语言检测

## 概述

`language detection` 系统工具可让 ElevenLabs 智能体将输出语言切换为其支持的任意语言。
此系统工具不会自动启用。你可以自定义其描述以适应具体用例。

> **Note**
>
> 建议尽可能为智能体启用所有语言，并启用语言检测系统工具。

语言检测工具会在两种情况下触发语言切换，均基于接收音频检测到的语言和内容：

* `detection`：如果用户使用的语言与当前输出语言不同，将触发切换
* `content`：如果用户以当前语言要求切换至新语言，将触发切换

**用途：** 在对话期间自动切换至检测到的用户语言。

**触发条件：** LLM 应在以下情况调用此工具：

* 用户使用与当前对话语言不同的语言
* 用户明确要求切换语言
* 对话需要多语言支持

**参数：**

* `reason`（字符串，必填）：切换语言的原因
* `language`（字符串，必填）：要切换至的语言代码（必须在支持的语言列表中）

**函数调用格式：**

```json
{
  "type": "function",
  "function": {
    "name": "language_detection",
    "arguments": "{\"reason\": \"User requested Spanish\", \"language\": \"es\"}"
  }
}
```

**实现方式：** 在智能体设置中配置支持的语言，并添加语言检测系统工具。智能体会自动切换音色和回复，以匹配检测到的语言。

## 启用语言检测

#### 配置支持的语言

必须在 `Agent` 设置标签页中定义智能体可切换至的语言。

![智能体语言](/docs/_fern-img/633707d54276febd3baa054c4f41b186225b74f606307a46e8262607befc8381.webp)

#### 添加语言检测工具

在 `Agent` 标签页中，将预配置的系统工具添加到智能体的工具列表以启用语言检测。
选择 `add tool` 时，该工具会自动显示为可选项。

![系统工具](/docs/_fern-img/3d17048ab2bc1a0547c49056abb98f624caf866927ff1714af27f898b06ab18f.webp)

#### 配置工具描述

添加说明何时调用该工具的描述

![描述](/docs/_fern-img/3bebc9fe07dba7121bce7793f3793858c710fc8ea1c221347604eb05929271df.webp)

## 将切换限制在对话开始时

在较长的对话中，背景语音或不常见的口音有时可能会触发并非来电者本意的切换。
启用 `only_at_conversation_start` 可将切换限制在用户的前两轮发言内。

如果语言未在这两轮内切换，对话其余时间将禁用语言检测：之后的每次尝试都会失败，
智能体将继续使用当前语言。如果语言在该时间窗口内切换，则对话其余时间仍可继续切换，
因此仍可纠正错误的检测结果。

此选项默认禁用。

#### 通过控制台更新

在 **Tools** 标签页中选择 **Detect language** 工具，并启用 **Only at start of conversation**。

#### 通过 CLI 更新

#### 拉取智能体配置

```bash
elevenlabs agents pull
```

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

在语言检测工具上设置 `only_at_conversation_start`。为简洁起见，
此处省略了周边字段。

```json
{
  "conversation_config": {
    "agent": {
      "prompt": {
        "built_in_tools": {
          "language_detection": {
            "type": "system",
            "name": "language_detection",
            "params": {
              "system_tool_type": "language_detection",
              "only_at_conversation_start": true
            }
          }
        }
      }
    }
  }
}
```

#### 推送更改

```bash
elevenlabs agents push
```

#### 通过 API 更新

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "prompt": {
                "built_in_tools": {
                    "language_detection": {
                        "type": "system",
                        "name": "language_detection",
                        "params": {
                            "system_tool_type": "language_detection",
                            "only_at_conversation_start": True,
                        },
                    }
                }
            }
        }
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      prompt: {
        builtInTools: {
          languageDetection: {
            type: "system",
            name: "language_detection",
            params: {
              systemToolType: "language_detection",
              onlyAtConversationStart: true,
            },
          },
        },
      },
    },
  },
});
```

> **Note**
>
> 当切换被阻止时，工具会向 LLM 返回错误，指示其继续使用当前语言。
> 不会向来电者透露原因。

## API 实现

通过 API 创建智能体时，可以将 `language detection` 工具添加到智能体配置中。它应定义为系统工具：

```python
from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs

elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

# Create language presets
language_presets = {
    "nl": {"overrides": {"agent": {"first_message": "Hoi, hoe gaat het met je?"}}},
    "fi": {"overrides": {"agent": {"first_message": "Hei, kuinka voit?"}}},
    "tr": {"overrides": {"agent": {"first_message": "Merhaba, nasılsın?"}}},
    "ru": {"overrides": {"agent": {"first_message": "Привет, как ты?"}}},
    "pt": {"overrides": {"agent": {"first_message": "Oi, como você está?"}}},
}

response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi how are you?",
            prompt={
                "built_in_tools": {
                    "language_detection": {
                        "type": "system",
                        "name": "language_detection",
                        # Optional: customize when the tool should be triggered
                        "description": "",
                        "params": {"system_tool_type": "language_detection"},
                    }
                },
            },
        ),
        language_presets=language_presets,
    ),
)
```

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

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY",
});

await elevenlabs.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hi, how are you?",
      prompt: {
        builtInTools: {
          languageDetection: {
            type: "system",
            name: "language_detection",
            description: "", // Optional: Customize when the tool should be triggered
            params: { systemToolType: "language_detection" },
          },
        },
      },
    },
    languagePresets: {
      nl: { overrides: { agent: { firstMessage: "Hoi, hoe gaat het met je?" } } },
      fi: {
        overrides: { agent: { firstMessage: "Hei, kuinka voit?" } },
        firstMessageTranslation: {
          sourceHash: '{"firstMessage":"Hi how are you?","language":"en"}',
          text: "Hei, kuinka voit?",
        },
      },
      tr: { overrides: { agent: { firstMessage: "Merhaba, nasılsın?" } } },
      ru: { overrides: { agent: { firstMessage: "Привет, как ты?" } } },
      pt: { overrides: { agent: { firstMessage: "Oi, como você está?" } } },
      ar: { overrides: { agent: { firstMessage: "مرحبًا كيف حالك؟" } } },
    },
  },
});
```

```bash
curl -X POST https://api.elevenlabs.io/v1/convai/agents/create \
     -H "xi-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "conversation_config": {
    "agent": {
      "first_message": "Hi how are you?",
      "prompt": {
        "built_in_tools": {
          "language_detection": {
            "type": "system",
            "name": "language_detection",
            "description": "",
            "params": { "system_tool_type": "language_detection" }
          }
        }
      }
    },
    "language_presets": {
      "nl": {
        "overrides": {
          "agent": {
            "prompt": null,
            "first_message": "Hoi, hoe gaat het met je?",
            "language": null
          },
          "tts": null
        }
      },
      "fi": {
        "overrides": {
          "agent": {
            "prompt": null,
            "first_message": "Hei, kuinka voit?",
            "language": null
          },
          "tts": null
        }
      },
      "tr": {
        "overrides": {
          "agent": {
            "prompt": null,
            "first_message": "Merhaba, nasılsın?",
            "language": null
          },
          "tts": null
        }
      },
      "ru": {
        "overrides": {
          "agent": {
            "prompt": null,
            "first_message": "Привет, как ты?",
            "language": null
          },
          "tts": null
        }
      },
      "pt": {
        "overrides": {
          "agent": {
            "prompt": null,
            "first_message": "Oi, como você está?",
            "language": null
          },
          "tts": null
        }
      },
      "ar": {
        "overrides": {
          "agent": {
            "prompt": null,
            "first_message": "مرحبًا كيف حالك؟",
            "language": null
          },
          "tts": null
        }
      }
    }
  }
}'
```

> **Tip**
>
> 将描述留空即可使用默认语言检测提示词。