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

# Variabili d'ambiente

Le variabili d'ambiente ti consentono di definire valori specifici per ambiente per URL degli strumenti, segreti, header e connessioni di autenticazione. Un'unica configurazione di agente e strumenti funziona in tutti i tuoi ambienti: URL, chiavi API e autenticazione vengono risolti dinamicamente in base all'ambiente specificato al momento della conversazione.

## Panoramica

Senza variabili d'ambiente, distribuire un agente in più ambienti (sviluppo, staging, produzione) richiede di duplicare agenti e strumenti per ogni ambiente e poi mantenere manualmente sincronizzate le loro configurazioni. Ciò comporta:

* **Deriva della configurazione** tra gli ambienti
* **Analytics frammentate** tra ID agente duplicati
* **Attrito nella promozione** durante il passaggio dallo staging alla produzione

Le variabili d'ambiente risolvono questo problema introducendo una risorsa riutilizzabile a livello di workspace che archivia valori diversi per ambiente. Gli strumenti e i server MCP fanno riferimento a queste variabili usando la sintassi dei template e il valore corretto viene risolto in fase di runtime in base all'ambiente della conversazione.

![Panoramica delle variabili d'ambiente](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## Concetti principali

### Variabili d'ambiente

Una variabile d'ambiente è una risorsa a livello di workspace con un'etichetta e un insieme di valori per ambiente. Esistono tre tipi:

| Tipo                 | Descrizione                                               | Esempio di utilizzo                                |
| -------------------- | --------------------------------------------------------- | -------------------------------------------------- |
| **Stringa**          | Valori di testo semplice che variano per ambiente         | URL di base, hostname, valori di configurazione    |
| **Segreto**          | Riferimenti a segreti del workspace, risolti per ambiente | Chiavi API, bearer token, segreti di firma webhook |
| **Connessione auth** | Riferimenti a connessioni auth, risolti per ambiente      | Credenziali OAuth2, configurazioni JWT             |

Ogni variabile d'ambiente deve avere un valore per l'ambiente predefinito `production`. Gli ambienti aggiuntivi, come `staging` e `development`, sono facoltativi.

### Sintassi dei template

Fai riferimento alle variabili d'ambiente nei campi URL usando la sintassi `{{system__env_<label>}}`:

```
https://{{system__env_api_host}}.example.com/v1/text-to-speech
```

Data una variabile d'ambiente `api_host` con i valori `api` (produzione) e `staging.api` (staging), viene risolta come segue:

* In `production`: `https://api.example.com/v1/text-to-speech`
* In `staging`: `https://staging.api.example.com/v1/text-to-speech`

Questa sintassi è coerente con le [variabili dinamiche](/docs/it/eleven-agents/customization/personalization/dynamic-variables) e funziona nei campi URL per gli strumenti webhook e le connessioni ai server MCP.

> **Note**
>
> Le variabili d'ambiente sono supportate anche negli URL e negli header dei **webhook pre-chiamata**
> (il webhook Conversation Initiation Client Data) e negli URL dei **webhook post-chiamata** configurati in
> **Sviluppatori > Webhook**. I template vengono risolti usando l'ambiente della conversazione, così la stessa
> configurazione webhook può avere come destinazione endpoint diversi per ambiente. Per i webhook pre-chiamata, l'
> ambiente può essere impostato in anticipo sul numero di telefono o restituito dinamicamente nella risposta del webhook
> (consulta [Telefonia](#telephony-twilio-and-sip-trunk) qui sotto).

> **Note**
>
> Gli URL devono iniziare con `https://` prima di qualsiasi riferimento a una variabile d'ambiente. Ad esempio, `https://   {{ system__env_api_host }}.example.com/v1/data` è valido, mentre `{{ system__env_api_host }}/v1/data`
> non lo è. Questo è necessario per la convalida e la sicurezza: i valori delle variabili d'ambiente non possono controllare
> il protocollo.

### Risoluzione e fallback

Quando una conversazione viene eseguita in un ambiente specifico, il sistema risolve le variabili d'ambiente come segue:

1. Cerca il valore per l'ambiente richiesto, ad esempio `staging`
2. Se non esiste alcun valore per quell'ambiente, **usa come fallback il valore `production`**
3. Se la variabile non può essere risolta, la chiamata dello strumento non riesce con un errore di configurazione

Questo comportamento di fallback significa che devi definire valori solo per gli ambienti che differiscono dalla produzione.

## Creazione di variabili d'ambiente

> **Note**
>
> Le variabili d'ambiente non sono ancora gestibili tramite la CLI di ElevenLabs: usa la dashboard o l'SDK.

#### Crea dalla dashboard

Vai a **Sviluppatori > Variabili d'ambiente** nella dashboard di ElevenLabs.

#### Crea un ambiente

Definisci ambienti che corrispondono alle fasi di distribuzione, ad esempio `eu`, `india`, `staging`. L'ambiente `production` è sempre disponibile per impostazione predefinita.

#### Crea una variabile

Fai clic su **Add variable** e scegli il tipo di variabile:

* **Stringa**: inserisci un'etichetta e imposta un valore per ogni ambiente
* **Segreto**: seleziona un segreto del workspace esistente per ogni ambiente
* **Connessione auth**: seleziona una connessione auth esistente per ogni ambiente

![Crea variabile](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### Crea tramite l'API

#### Stringa

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="api_host",
    type="string",
    values={
        "production": "api",
        "staging": "staging.api",
        "development": "dev.api",
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "api_host",
  type: "string",
  values: {
    production: "api",
    staging: "staging.api",
    development: "dev.api",
  },
});
```

#### Segreto

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_api_key",
    type="secret",
    values={
        "production": {"secret_id": "your-production-secret-id"},
        "staging": {"secret_id": "your-staging-secret-id"},
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_api_key",
  type: "secret",
  values: {
    production: { secretId: "your-production-secret-id" },
    staging: { secretId: "your-staging-secret-id" },
  },
});
```

#### Connessione auth

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_oauth_connection",
    type="auth_connection",
    values={
        "production": {"auth_connection_id": "your-production-auth-connection-id"},
        "staging": {"auth_connection_id": "your-staging-auth-connection-id"},
    },
)
```

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_oauth_connection",
  type: "auth_connection",
  values: {
    production: { authConnectionId: "your-production-auth-connection-id" },
    staging: { authConnectionId: "your-staging-auth-connection-id" },
  },
});
```

## Utilizzo delle variabili d'ambiente

### Negli URL degli strumenti webhook

Usa la sintassi dei template nel campo URL di uno [strumento webhook](/docs/it/eleven-agents/customization/tools/webhook-tools) per fare in modo che l'URL di base venga risolto in base all'ambiente.

![Variabile d'ambiente nell'URL dello strumento](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

Ad esempio, un URL dello strumento configurato come segue:

```
https://{{system__env_api_host}}.example.com/v1/weather?lat={latitude}&lon={longitude}
```

viene risolto in `https://api.example.com/v1/weather?lat=40.7&lon=-74.0` in produzione e in `https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0` in staging.

Puoi combinare più variabili d'ambiente e segmenti letterali in un unico URL:

```
https://{{system__env_api_host}}.example.com/{{system__env_api_version}}/weather
```

#### Esempio API

**`Python`**

```python title="Python"

from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="your-api-key")

agent = client.conversational_ai.agents.create(
    conversation_config={
        "agent": {
            "first_message": "Hello! How can I help?",
            "prompt": {"prompt": "You are a helpful assistant."},
        },
        "tools": [
            {
                "type": "webhook",
                "name": "get_data",
                "description": "Fetches data from the API",
                "api_schema": {
                    "url": "https://{{system__env_api_host}}.example.com/v1/data",
                    "method": "GET",
                },
            }
        ],
    },
)
```

**`JavaScript`**

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

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const agent = await client.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hello! How can I help?",
      prompt: { prompt: "You are a helpful assistant." },
    },
    tools: [
      {
        type: "webhook",
        name: "get_data",
        description: "Fetches data from the API",
        apiSchema: {
          url: "https://{{system__env_api_host}}.example.com/v1/data",
          method: "GET",
        },
      },
    ],
  },
});
```

### Negli header degli strumenti webhook

Le variabili d'ambiente segrete possono essere usate negli header delle richieste. Anziché inserire direttamente un ID segreto, fai riferimento a una variabile d'ambiente per usare segreti diversi in base all'ambiente. Quando configuri un header dello strumento nella dashboard, seleziona una variabile d'ambiente anziché un segreto statico. In fase di runtime, il valore dell'header viene risolto nel segreto memorizzato per l'ambiente corrente.

#### Esempio API

Passa un riferimento a una variabile d'ambiente nel campo `request_headers`:

```json
{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "request_headers": {
      "X-Api-Key": { "env_var_label": "my_api_key" }
    }
  }
}
```

### Nelle connessioni di autenticazione degli strumenti webhook

Anche le connessioni di autenticazione (OAuth2, JWT, Basic Auth) possono essere risolte in base all'ambiente. È utile quando gli ambienti di staging e produzione usano client OAuth o endpoint token diversi.

![Connessione di autenticazione con variabile d'ambiente](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

Nella configurazione dello strumento, seleziona una variabile d'ambiente di tipo `auth_connection` anziché selezionare direttamente una connessione di autenticazione. La connessione di autenticazione corretta per l'ambiente corrente viene risolta in fase di runtime.

#### Esempio API

Fai riferimento a una variabile d'ambiente nel campo `auth_connection`:

```json
{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "auth_connection": { "env_var_label": "my_oauth_connection" }
  }
}
```

### Nelle connessioni ai server MCP

Le variabili d'ambiente funzionano con le connessioni ai [server MCP](/docs/it/eleven-agents/customization/tools/mcp) allo stesso modo degli strumenti webhook. Puoi usarle in:

* **URL del server**: Usa un template per l'URL del server MCP in modo che punti a server diversi per ambiente
* **Header delle richieste**: Usa variabili d'ambiente segrete per gli header di autenticazione
* **Connessioni di autenticazione**: Usa variabili d'ambiente per connessioni di autenticazione con server MCP basati su OAuth

Ad esempio, un URL del server MCP configurato come segue:

```
https://{{system__env_mcp_host}}.example.com/mcp
```

viene risolto in endpoint del server MCP diversi a seconda dell'ambiente.

### Nelle configurazioni LLM personalizzate

Quando usi un [LLM personalizzato](/docs/it/eleven-agents/customization/llm/custom-llm), le variabili d'ambiente possono creare template per la chiave API e gli header delle richieste. In questo modo puoi usare endpoint dei modelli e credenziali diversi nei vari ambienti.

Il campo URL dell'LLM personalizzato supporta la stessa sintassi di template `{{system__env_<label>}}`. Il campo `api_key` accetta un riferimento a una variabile d'ambiente, così da usare chiavi API diverse per ambiente.

#### Esempio API

```json
{
  "conversation_config": {
    "agent": {
      "prompt": { "prompt": "You are a helpful assistant." },
      "llm": {
        "custom_llm": {
          "url": "https://{{system__env_llm_host}}.example.com/v1/chat/completions",
          "model_id": "my-model",
          "api_key": { "env_var_label": "llm_api_key" }
        }
      }
    }
  }
}
```

## Specificare l'ambiente

L'ambiente viene impostato all'avvio della conversazione e rimane invariato per l'intera conversazione. Se non viene specificato alcun ambiente, viene usato `production` per impostazione predefinita.

Durante i test nella dashboard, seleziona l'ambiente dal menu a discesa nell'anteprima dell'agente:

![Selettore dell'ambiente nell'anteprima
dell'agente](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### WebSocket

Passa il parametro query `environment` quando ti connetti al WebSocket della conversazione:

```
wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<agent_id>&environment=staging
```

### WebRTC (URL firmato / token)

Quando usi WebRTC, passa il parametro `environment` quando richiedi un token di conversazione:

**`Python`**

```python title="Python"
from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="your-api-key")

token = client.conversational_ai.conversation.get_token(
agent_id="your-agent-id",
environment="staging",
)

```

**`JavaScript`**

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

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const token = await client.conversationalAi.conversation.getToken({
    agentId: "your-agent-id",
    environment: "staging",
});
```

**`cURL`**

```bash title="cURL"
curl "https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=<agent_id>&environment=staging" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

### Telefonia (Twilio e trunk SIP)

I numeri di telefono possono essere associati a un ambiente specifico e a uno specifico [branch dell'agente](/docs/it/eleven-agents/operate/versioning), rendendo più semplice instradare un numero di telefono di test a un branch di sviluppo di un agente i cui strumenti vengono eseguiti su un'API di sviluppo.

![Selettori dell'ambiente e del branch
del numero di telefono](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

Per le chiamate in entrata, l'ambiente viene risolto in questo ordine:

1. Il valore `environment` restituito dal tuo [webhook di avvio della conversazione](/docs/it/eleven-agents/customization/personalization#conversation-initiation-webhooks), se il tuo server ne fornisce uno dinamicamente per chiamata
2. L'ambiente memorizzato nel **numero di telefono** stesso
3. `production` come predefinito

La stessa precedenza si applica a `branch_id`. Gli URL e gli header del webhook pre-chiamata, nonché gli URL del webhook post-chiamata, risolvono quindi i template `{{system__env_*}}` usando l'ambiente scelto.

Associa un numero di telefono a un ambiente e a un branch (richiede l'SDK Python `elevenlabs` ≥ 2.47.0 o `@elevenlabs/elevenlabs-js` ≥ 2.47.0):

**`Python`**

```python title="Python"
import os
from dotenv import load_dotenv
from elevenlabs import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

elevenlabs.conversational_ai.phone_numbers.update(
    phone_number_id="phnum_8901k4t9z5defmb8vh3e9361y7nj",
    environment="staging",
    branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
)
```

**`JavaScript`**

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", {
  environment: "staging",
  branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
});
```

**`cURL`**

```bash title="cURL"
curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj"
  }'
```

Per le chiamate in uscita, passa il campo `environment` quando avvii la chiamata tramite gli endpoint in uscita Twilio o trunk SIP.

### SDK React

Passa l'opzione `environment` nell'hook `useConversation` o quando avvii una sessione:

```tsx
import { useConversation } from "@11labs/react";

function Agent() {
  const conversation = useConversation();

  const connect = async () => {
    await conversation.startSession({
      agentId: "your-agent-id",
      environment: "staging",
    });
  };

  return <button onClick={connect}>Start conversation</button>;
}
```

## Esempio: agente multi-ambiente

Questo esempio mostra una configurazione completa con un singolo agente che usa backend API e credenziali diversi tra sviluppo, staging e produzione.

#### Crea variabili d'ambiente

Crea tre variabili d'ambiente nella dashboard o tramite API:

| Etichetta     | Tipo                          | Sviluppo        | Staging             | Produzione       |
| ------------- | ----------------------------- | --------------- | ------------------- | ---------------- |
| `api_host`    | Stringa                       | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | Segreto                       | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | Connessione di autenticazione | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

#### Configura gli strumenti con riferimenti a variabili d'ambiente

Configura gli strumenti webhook usando la sintassi dei template:

* **URL**: `https://{{system__env_api_host}}.example.com/v1/orders`
* **Header**: Fai riferimento alla variabile d'ambiente `api_key` per l'header `X-Api-Key`
* **Autenticazione**: Fai riferimento alla variabile d'ambiente `oauth_creds` per l'autenticazione OAuth

#### Specifica l'ambiente al momento della conversazione

Quando avvii una conversazione, passa l'ambiente di destinazione:

**`Sviluppo`**

```python title="Sviluppo"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="development",
)
```

**`Staging`**

```python title="Staging"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)
```

**`Produzione (predefinito)`**

```python title="Produzione (predefinito)"
# No environment parameter needed — defaults to production
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
)
```

#### Filtra per ambiente

L'ambiente viene monitorato per ogni conversazione. Filtra le dashboard di analisi e la cronologia delle conversazioni per ambiente per isolare le metriche di ogni fase di deployment.

![Filtra l'analisi per ambiente](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![Filtra la cronologia delle conversazioni per ambiente](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

### Vincoli di denominazione

* **Etichette**: Solo caratteri alfanumerici e trattini bassi (ad es. `base_url`, `api_key_v2`)
* **Nomi degli ambienti**: Devono iniziare con una lettera minuscola e possono contenere solo lettere minuscole, cifre, trattini bassi e trattini, fino a 64 caratteri (ad es. `production`, `staging`, `dev-us-east`)
* Ogni variabile d'ambiente deve avere un valore `production`

## Passaggi successivi

#### [Strumenti webhook](/docs/it/eleven-agents/customization/tools/webhook-tools)

Configura strumenti webhook con URL e autenticazione basati sull'ambiente

#### [Server MCP](/docs/it/eleven-agents/customization/tools/mcp)

Connetti server MCP con una configurazione per ambiente

#### [LLM personalizzato](/docs/it/eleven-agents/customization/llm/custom-llm)

Usa endpoint dei modelli diversi nei vari ambienti

#### [Versioning](/docs/it/eleven-agents/operate/versioning)

Combina variabili d'ambiente con branch e suddivisione del traffico