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

# Rilevamento della lingua

## Panoramica

Lo strumento di sistema `language detection` consente al tuo agente ElevenLabs di cambiare la lingua di output con qualsiasi lingua supportata dall'agente.
Questo strumento di sistema non è abilitato automaticamente. La sua descrizione può essere personalizzata in base al tuo caso d'uso specifico.

> **Note**
>
> Quando possibile, consigliamo di abilitare tutte le lingue per un agente e di abilitare lo strumento di sistema per il rilevamento della lingua.

Il nostro strumento di rilevamento della lingua attiva il cambio di lingua in due casi, entrambi basati sulla lingua e sul contenuto rilevati nell'audio ricevuto:

* `detection`: se un utente parla una lingua diversa da quella di output corrente, viene attivato un cambio
* `content`: se l'utente chiede nella lingua corrente di passare a una nuova lingua, viene attivato un cambio

**Scopo**: passa automaticamente alla lingua rilevata dell'utente durante le conversazioni.

**Condizioni di attivazione**: l'LLM deve chiamare questo strumento quando:

* L'utente parla una lingua diversa da quella della conversazione corrente
* L'utente richiede esplicitamente di cambiare lingua
* Per la conversazione è necessario il supporto multilingue

**Parametri**:

* `reason` (stringa, obbligatorio): il motivo del cambio di lingua
* `language` (stringa, obbligatorio): il codice della lingua da usare (deve essere nell'elenco delle lingue supportate)

**Formato della chiamata di funzione**:

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

**Implementazione**: configura le lingue supportate nelle impostazioni dell'agente e aggiungi lo strumento di sistema per il rilevamento della lingua. L'agente adatterà automaticamente la voce e le risposte alle lingue rilevate.

## Abilitare il rilevamento della lingua

#### Configura le lingue supportate

Le lingue a cui l'agente può passare devono essere definite nella scheda delle impostazioni `Agent`.

![Lingue dell'agente](/docs/_fern-img/633707d54276febd3baa054c4f41b186225b74f606307a46e8262607befc8381.webp)

#### Aggiungi lo strumento di rilevamento della lingua

Abilita il rilevamento della lingua aggiungendo lo strumento di sistema preconfigurato agli strumenti del tuo agente nella scheda `Agent`.
È disponibile automaticamente come opzione quando selezioni `add tool`.

![Strumento di sistema](/docs/_fern-img/3d17048ab2bc1a0547c49056abb98f624caf866927ff1714af27f898b06ab18f.webp)

#### Configura la descrizione dello strumento

Aggiungi una descrizione che specifichi quando chiamare lo strumento

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

## Limitare il cambio all'inizio della conversazione

In una conversazione lunga, rumori di fondo o un accento insolito possono occasionalmente attivare un cambio che il
chiamante non intendeva. Abilitando `only_at_conversation_start`, il cambio viene limitato ai primi due turni
dell'utente.

Se la lingua non cambia durante questi due turni, il rilevamento della lingua viene disabilitato per il resto
della conversazione: ogni tentativo successivo fallisce e l'agente continua a parlare nella lingua corrente. Se
invece la lingua cambia entro questa finestra, il cambio rimane disponibile per il resto della
conversazione, quindi un rilevamento errato può comunque essere corretto.

L'opzione è disabilitata per impostazione predefinita.

#### Aggiorna dalla dashboard

Seleziona lo strumento **Rileva lingua** nella scheda **Strumenti** e abilita **Solo all'inizio della conversazione**.

#### Aggiorna tramite CLI

#### Scarica la configurazione dell'agente

```bash
elevenlabs agents pull
```

#### Modifica \`agent\_configs/\<agent-name>.json\`

Imposta `only_at_conversation_start` nello strumento di rilevamento della lingua. I campi circostanti sono
omessi qui per brevità.

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

#### Invia le modifiche

```bash
elevenlabs agents push
```

#### Aggiorna tramite 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 il cambio è bloccato, lo strumento restituisce un errore all'LLM, indicandogli di continuare a parlare
> nella lingua corrente. Il motivo non viene comunicato al chiamante.

## Implementazione API

Quando crei un agente tramite API, puoi aggiungere lo strumento `language detection` alla configurazione dell'agente. Deve essere definito come strumento di 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**
>
> Lascia vuota la descrizione per usare il prompt predefinito di rilevamento della lingua.