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

# Detecção de idioma

## Visão geral

A ferramenta de sistema `language detection` permite que seu agente da ElevenLabs alterne o idioma de saída para qualquer idioma compatível com o agente.
Essa ferramenta de sistema não é ativada automaticamente. A descrição dela pode ser personalizada para atender ao seu caso de uso específico.

> **Note**
>
> Sempre que possível, recomendamos ativar todos os idiomas para um agente e ativar a ferramenta de sistema de
> detecção de idioma.

Nossa ferramenta de detecção de idioma aciona a mudança de idioma em dois casos, ambos com base no idioma e no conteúdo detectados no áudio recebido:

* `detection`: se um usuário falar um idioma diferente do idioma de saída atual, uma mudança será acionada
* `content`: se o usuário pedir, no idioma atual, para mudar para um novo idioma, uma mudança será acionada

**Objetivo**: Mudar automaticamente para o idioma detectado do usuário durante as conversas.

**Condições de acionamento**: O LLM deve chamar esta ferramenta quando:

* O usuário falar em um idioma diferente do idioma atual da conversa
* O usuário solicitar explicitamente a mudança de idioma
* Houver necessidade de suporte a vários idiomas na conversa

**Parâmetros**:

* `reason` (string, obrigatório): O motivo para a mudança de idioma
* `language` (string, obrigatório): O código do idioma para o qual mudar (deve estar na lista de idiomas compatíveis)

**Formato da chamada de função**:

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

**Implementação**: Configure os idiomas compatíveis nas configurações do agente e adicione a ferramenta de sistema de detecção de idioma. O agente mudará automaticamente a voz e as respostas para corresponder aos idiomas detectados.

## Ativando a detecção de idioma

#### Configurar idiomas compatíveis

Os idiomas para os quais o agente pode alternar devem ser definidos na aba de configurações `Agent`.

![Idiomas do agente](/docs/_fern-img/633707d54276febd3baa054c4f41b186225b74f606307a46e8262607befc8381.webp)

#### Adicionar a ferramenta de detecção de idioma

Ative a detecção de idioma adicionando a ferramenta de sistema pré-configurada às ferramentas do seu agente na aba `Agent`.
Ela fica disponível automaticamente como opção ao selecionar `add tool`.

![Ferramenta de sistema](/docs/_fern-img/3d17048ab2bc1a0547c49056abb98f624caf866927ff1714af27f898b06ab18f.webp)

#### Configurar a descrição da ferramenta

Adicione uma descrição que especifique quando chamar a ferramenta.

![Descrição](/docs/_fern-img/3bebc9fe07dba7121bce7793f3793858c710fc8ea1c221347604eb05929271df.webp)

## Restringindo a mudança ao início da conversa

Em uma conversa longa, falas de fundo ou um sotaque incomum podem ocasionalmente acionar uma mudança que a
pessoa que ligou não pretendia. Ativar `only_at_conversation_start` limita as mudanças aos dois primeiros turnos
do usuário.

Se o idioma não mudar nesses dois turnos, a detecção de idioma será desativada pelo restante
da conversa: todas as tentativas posteriores falharão e o agente continuará falando o idioma atual. Se
o idioma mudar nessa janela, a mudança continuará disponível pelo restante da
conversa, para que uma detecção incorreta ainda possa ser corrigida.

A opção vem desativada por padrão.

#### Atualizar pelo painel

Selecione a ferramenta **Detect language** na aba **Tools** e ative **Only at start of conversation**.

#### Atualizar pela CLI

#### Baixar a configuração do agente

```bash
elevenlabs agents pull
```

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

Defina `only_at_conversation_start` na ferramenta de detecção de idioma. Os campos ao redor foram
omitidos aqui para maior brevidade.

```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
            }
          }
        }
      }
    }
  }
}
```

#### Enviar suas alterações

```bash
elevenlabs agents push
```

#### Atualizar pela 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**
>
> Quando a mudança é bloqueada, a ferramenta retorna um erro ao LLM instruindo-o a continuar falando
> o idioma atual. O motivo não é informado à pessoa que ligou.

## Implementação da API

Ao criar um agente pela API, você pode adicionar a ferramenta `language detection` à configuração do agente. Ela deve ser definida como uma ferramenta de sistema:

```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**
>
> Deixe a descrição em branco para usar o prompt padrão de detecção de idioma.