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

# Zmienne środowiskowe

Zmienne środowiskowe pozwalają definiować wartości dla poszczególnych środowisk: adresy URL narzędzi, sekrety, nagłówki i połączenia uwierzytelniania. Jedna konfiguracja agenta i narzędzi działa we wszystkich środowiskach — adresy URL, klucze API i uwierzytelnianie są dynamicznie rozwiązywane na podstawie środowiska wskazanego podczas rozmowy.

## Przegląd

Bez zmiennych środowiskowych wdrożenie agenta w wielu środowiskach (deweloperskim, stagingowym, produkcyjnym) wymaga powielania agentów i narzędzi dla każdego środowiska, a następnie ręcznego utrzymywania synchronizacji ich konfiguracji. Prowadzi to do:

* **Rozbieżności konfiguracji** między środowiskami
* **Podzielonej analityki** między zduplikowane identyfikatory agentów
* **Problemów z promocją** przy przejściu ze środowiska stagingowego na produkcyjne

Zmienne środowiskowe rozwiązują ten problem, wprowadzając zasób wielokrotnego użytku o zakresie workspace, który przechowuje różne wartości dla każdego środowiska. Narzędzia i serwery MCP odwołują się do tych zmiennych za pomocą składni szablonów, a właściwa wartość jest rozwiązywana w czasie działania na podstawie środowiska rozmowy.

![Przegląd zmiennych środowiskowych](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## Kluczowe pojęcia

### Zmienne środowiskowe

Zmienna środowiskowa to zasób o zakresie workspace z etykietą i zestawem wartości dla poszczególnych środowisk. Istnieją trzy typy:

| Typ                 | Opis                                                                | Przykładowe zastosowanie                                  |
| ------------------- | ------------------------------------------------------------------- | --------------------------------------------------------- |
| **String**          | Wartości zwykłego tekstu różniące się między środowiskami           | Bazowe adresy URL, nazwy hostów, wartości konfiguracji    |
| **Secret**          | Odwołania do sekretów workspace, rozwiązywane dla środowiska        | Klucze API, tokeny bearer, sekrety podpisywania webhooków |
| **Auth connection** | Odwołania do połączeń uwierzytelniania, rozwiązywane dla środowiska | Dane uwierzytelniające OAuth2, konfiguracje JWT           |

Każda zmienna środowiskowa musi mieć wartość dla domyślnego środowiska `production`. Dodatkowe środowiska (np. `staging`, `development`) są opcjonalne.

### Składnia szablonów

Odwołuj się do zmiennych środowiskowych w polach URL za pomocą składni `{{system__env_<label>}}`:

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

Dla zmiennej środowiskowej `api_host` z wartościami `api` (production) i `staging.api` (staging) zostanie to rozwiązane jako:

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

Ta składnia jest zgodna ze [zmiennymi dynamicznymi](/docs/pl/eleven-agents/customization/personalization/dynamic-variables) i działa w polach URL narzędzi webhook oraz połączeń serwerów MCP.

> **Note**
>
> Zmienne środowiskowe są też obsługiwane w adresach URL i nagłówkach **webhooków przed rozmową**
> (Conversation Initiation Client Data Webhook) oraz w adresach URL **webhooków po rozmowie** skonfigurowanych
> w **Developers > Webhooks**. Szablony są rozwiązywane na podstawie środowiska rozmowy, więc ta sama
> konfiguracja webhooka może kierować do różnych endpointów w zależności od środowiska. W przypadku webhooków przed rozmową
> środowisko można ustawić z góry dla numeru telefonu lub zwrócić dynamicznie w odpowiedzi webhooka
> (zobacz [Telephony](#telephony-twilio-and-sip-trunk) poniżej).

> **Note**
>
> Adresy URL muszą zaczynać się od `https://` przed wszelkimi odwołaniami do zmiennych środowiskowych. Na przykład `https://   {{ system__env_api_host }}.example.com/v1/data` jest poprawne, ale `{{ system__env_api_host }}/v1/data`
> nie. Jest to wymagane do walidacji i zabezpieczeń — wartości zmiennych środowiskowych nie mogą kontrolować
> protokołu.

### Rozwiązywanie i fallback

Gdy rozmowa odbywa się w konkretnym środowisku, system rozwiązuje zmienne środowiskowe w następujący sposób:

1. Wyszukuje wartość dla żądanego środowiska (np. `staging`)
2. Jeśli dla tego środowiska nie ma wartości, **używa wartości `production` jako fallbacku**
3. Jeśli nie można rozwiązać zmiennej, wywołanie narzędzia kończy się błędem konfiguracji

To zachowanie fallbacku oznacza, że wystarczy zdefiniować wartości dla środowisk różniących się od produkcyjnego.

## Tworzenie zmiennych środowiskowych

> **Note**
>
> Zmiennymi środowiskowymi nie można jeszcze zarządzać przez CLI ElevenLabs — użyj panelu lub SDK.

#### Utwórz w panelu

W panelu ElevenLabs przejdź do **Developers > Environment Variables**.

#### Utwórz środowisko

Zdefiniuj środowiska odpowiadające etapom wdrożenia (np. `eu`, `india`, `staging`). Środowisko `production` jest zawsze dostępne domyślnie.

#### Utwórz zmienną

Kliknij **Add variable** i wybierz typ zmiennej:

* **String**: Wpisz etykietę i ustaw wartość dla każdego środowiska
* **Secret**: Wybierz istniejący sekret workspace'u dla każdego środowiska
* **Auth connection**: Wybierz istniejące połączenie autoryzacji dla każdego środowiska

![Tworzenie zmiennej](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### Utwórz przez API

#### String

```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",
  },
});
```

#### Secret

```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" },
  },
});
```

#### Połączenie autoryzacji

```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" },
  },
});
```

## Korzystanie ze zmiennych środowiskowych

### W adresach URL narzędzi webhook

Użyj składni szablonu w polu URL [narzędzia webhook](/docs/pl/eleven-agents/customization/tools/webhook-tools), aby adres bazowy był rozwiązywany dla danego środowiska.

![Zmienna środowiskowa w URL narzędzia](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

Na przykład URL narzędzia skonfigurowany jako:

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

jest rozwiązywany jako `https://api.example.com/v1/weather?lat=40.7&lon=-74.0` w produkcji i `https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0` w stagingu.

W jednym URL możesz łączyć wiele zmiennych środowiskowych i fragmentów tekstu:

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

#### Przykład 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",
        },
      },
    ],
  },
});
```

### W nagłówkach narzędzi webhook

Tajnych zmiennych środowiskowych można używać w nagłówkach żądań. Zamiast wpisywać na stałe identyfikator sekretu, wskaż zmienną środowiskową, aby używać innych sekretów w poszczególnych środowiskach. Podczas konfiguracji nagłówka narzędzia w panelu wybierz zmienną środowiskową zamiast statycznego sekretu. W czasie działania wartość nagłówka jest rozwiązywana do sekretu zapisanego dla bieżącego środowiska.

#### Przykład API

Przekaż odwołanie do zmiennej środowiskowej w polu `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" }
    }
  }
}
```

### W połączeniach autoryzacji narzędzi webhook

Połączenia autoryzacji (OAuth2, JWT, Basic Auth) można też rozwiązywać dla każdego środowiska. Jest to przydatne, gdy środowiska stagingowe i produkcyjne używają innych klientów OAuth lub endpointów tokenów.

![Połączenie autoryzacji zmiennej środowiskowej](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

W konfiguracji narzędzia wybierz zmienną środowiskową typu `auth_connection` zamiast bezpośrednio wybierać połączenie autoryzacji. Właściwe połączenie autoryzacji dla bieżącego środowiska jest rozwiązywane w czasie działania.

#### Przykład API

Wskaż zmienną środowiskową w polu `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" }
  }
}
```

### W połączeniach serwerów MCP

Zmienne środowiskowe działają z połączeniami [serwerów MCP](/docs/pl/eleven-agents/customization/tools/mcp) tak samo jak z narzędziami webhook. Możesz ich używać w:

* **URL serwera**: Użyj szablonu URL serwera MCP, aby wskazywał inne serwery w zależności od środowiska
* **Nagłówkach żądań**: Użyj tajnych zmiennych środowiskowych w nagłówkach uwierzytelniania
* **Połączeniach autoryzacji**: Użyj zmiennych środowiskowych połączeń autoryzacji dla serwerów MCP opartych na OAuth

Na przykład URL serwera MCP skonfigurowany jako:

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

jest rozwiązywany do różnych endpointów serwera MCP zależnie od środowiska.

### W konfiguracjach własnego LLM

Podczas używania [własnego LLM](/docs/pl/eleven-agents/customization/llm/custom-llm) zmienne środowiskowe mogą służyć jako szablony dla klucza API i nagłówków żądań. Pozwala to używać różnych endpointów modeli i danych uwierzytelniających w różnych środowiskach.

Pole URL własnego LLM obsługuje tę samą składnię szablonu `{{system__env_<label>}}`. Pole `api_key` przyjmuje odwołanie do zmiennej środowiskowej, więc w każdym środowisku używany jest inny klucz API.

#### Przykład 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" }
        }
      }
    }
  }
}
```

## Określanie środowiska

Środowisko jest ustawiane przy rozpoczęciu rozmowy i pozostaje takie samo przez całą rozmowę. Jeśli nie podasz środowiska, domyślnie użyte zostanie `production`.

Podczas testowania w panelu wybierz środowisko z listy rozwijanej w podglądzie agenta:

![Selektor środowiska w podglądzie
agenta](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### WebSocket

Przekaż parametr zapytania `environment` podczas łączenia z WebSocketem rozmowy:

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

### WebRTC (podpisany URL / token)

Podczas używania WebRTC przekaż parametr `environment` przy żądaniu tokenu rozmowy:

**`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 i trunk SIP)

Numery telefonów można przypiąć do konkretnego środowiska i [gałęzi agenta](/docs/pl/eleven-agents/operate/versioning), co ułatwia skierowanie testowego numeru telefonu do gałęzi deweloperskiej agenta, którego narzędzia działają na deweloperskim API.

![Selektory środowiska i gałęzi
numeru telefonu](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

W przypadku połączeń przychodzących środowisko jest rozwiązywane w tej kolejności:

1. Wartość `environment` zwrócona przez [webhook inicjujący rozmowę](/docs/pl/eleven-agents/customization/personalization#conversation-initiation-webhooks), jeśli serwer dynamicznie podaje ją dla każdego połączenia
2. Środowisko zapisane dla samego **numeru telefonu**
3. Domyślne `production`

Ta sama kolejność obowiązuje dla `branch_id`. Adresy URL i nagłówki webhooków przed połączeniem oraz adresy URL webhooków po połączeniu rozwiązują następnie szablony `{{system__env_*}}` przy użyciu wybranego środowiska.

Przypnij numer telefonu do środowiska i gałęzi (wymaga Python SDK `elevenlabs` ≥ 2.47.0 lub `@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"
  }'
```

W przypadku połączeń wychodzących przekaż pole `environment` podczas inicjowania połączenia przez endpointy wychodzące Twilio lub trunk SIP.

### React SDK

Przekaż opcję `environment` w hooku `useConversation` lub podczas rozpoczynania sesji:

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

## Przykład: agent dla wielu środowisk

Ten przykład pokazuje pełną konfigurację jednego agenta, który używa różnych backendów API i danych uwierzytelniających w środowiskach deweloperskim, stagingowym i produkcyjnym.

#### Utwórz zmienne środowiskowe

Utwórz w panelu lub przez API trzy zmienne środowiskowe:

| Etykieta      | Typ                    | Deweloperskie   | Staging             | Produkcyjne      |
| ------------- | ---------------------- | --------------- | ------------------- | ---------------- |
| `api_host`    | String                 | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | Secret                 | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | Połączenie autoryzacji | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

#### Skonfiguruj narzędzia z odwołaniami do zmiennych środowiskowych

Skonfiguruj narzędzia webhook za pomocą składni szablonu:

* **URL**: `https://{{system__env_api_host}}.example.com/v1/orders`
* **Nagłówki**: Wskaż zmienną środowiskową `api_key` dla nagłówka `X-Api-Key`
* **Autoryzacja**: Wskaż zmienną środowiskową `oauth_creds` dla uwierzytelniania OAuth

#### Określ środowisko podczas rozpoczynania rozmowy

Przy rozpoczynaniu rozmowy przekaż docelowe środowisko:

**`Deweloperskie`**

```python title="Deweloperskie"
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",
)
```

**`Produkcyjne (domyślne)`**

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

#### Filtruj według środowiska

Środowisko jest śledzone dla każdej rozmowy. Filtruj pulpity analityczne i historię rozmów według środowiska, aby oddzielić wskaźniki dla poszczególnych etapów wdrożenia.

![Filtruj analitykę według środowiska](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![Filtruj historię rozmów według środowiska](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

### Ograniczenia nazewnictwa

* **Etykiety**: Tylko znaki alfanumeryczne i podkreślenia (np. `base_url`, `api_key_v2`)
* **Nazwy środowisk**: Muszą zaczynać się małą literą i mogą zawierać tylko małe litery, cyfry, podkreślenia oraz myślniki; maksymalnie 64 znaki (np. `production`, `staging`, `dev-us-east`)
* Każda zmienna środowiskowa musi mieć wartość `production`

## Kolejne kroki

#### [Narzędzia webhook](/docs/pl/eleven-agents/customization/tools/webhook-tools)

Skonfiguruj narzędzia webhook z adresami URL i uwierzytelnianiem zależnymi od środowiska

#### [Serwery MCP](/docs/pl/eleven-agents/customization/tools/mcp)

Połącz serwery MCP z konfiguracją dla każdego środowiska

#### [Własny LLM](/docs/pl/eleven-agents/customization/llm/custom-llm)

Używaj różnych endpointów modeli w zależności od środowiska

#### [Wersjonowanie](/docs/pl/eleven-agents/operate/versioning)

Połącz zmienne środowiskowe z gałęziami i podziałem ruchu