Environment variables

Environment variables let you define per-environment values for tool URLs, secrets, headers, and auth connections. A single agent and tool configuration works across all your environments — URLs, API keys, and authentication resolve dynamically based on the environment specified at conversation time.

Overview

Without environment variables, deploying an agent across multiple environments (development, staging, production) requires duplicating agents and tools for each environment, then manually keeping their configurations in sync. This leads to:

• Configuration drift between environments
• Fragmented analytics across duplicated agent IDs
• Promotion friction when moving from staging to production

Environment variables solve this by introducing a reusable, workspace-scoped resource that stores different values per environment. Tools and MCP servers reference these variables using template syntax, and the correct value is resolved at runtime based on the conversation’s environment.

Core concepts

Environment variables

An environment variable is a workspace-scoped resource with a label and a set of per-environment values. There are three types:

Each environment variable must have a value for the default production environment. Additional environments (e.g., staging, development) are optional.

Template syntax

Reference environment variables in URL fields using the {{system_env__<label>}} syntax:

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

Given an environment variable api_host with values api (production) and staging.api (staging), this resolves to:

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

This syntax is consistent with dynamic variables and works in URL fields for server tools and MCP server connections.

Resolution and fallback

When a conversation runs in a specific environment, the system resolves environment variables as follows:

1. Look up the value for the requested environment (e.g., staging)
2. If no value exists for that environment, fall back to the production value
3. If the variable cannot be resolved, the tool call fails with a configuration error

This fallback behavior means you only need to define values for environments that differ from production.

Creating environment variables

From the dashboard

Navigate to Developers > Environment Variables in the ElevenLabs dashboard.

Using the API

Create environment variables programmatically with the API:

$
curl -X POST "https://api.elevenlabs.io/v1/convai/environment-variables" \
>
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "label": "api_host",
>
    "type": "string",
>
    "values": {
>
      "production": "api",
>
      "staging": "staging.api",
>
      "development": "dev.api"
>
    }
>
  }'

Using environment variables

In server tool URLs

Use the template syntax in the URL field of a server tool to make the base URL resolve per environment.

For example, a tool URL configured as:

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

resolves to https://api.example.com/v1/weather?lat=40.7&lon=-74.0 in production and https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0 in staging.

You can combine multiple environment variables and literal segments in a single URL:

https://{{system_env__api_host}}.example.com/{{system_env__api_version}}/weather

API example

1
from elevenlabs.client import ElevenLabs
2
3
client = ElevenLabs(api_key="your-api-key")
4
5
agent = client.conversational_ai.agents.create(
6
conversation_config={
7
"agent": {
8
"first_message": "Hello! How can I help?",
9
"prompt": {"prompt": "You are a helpful assistant."},
10
},
11
"tools": [
12
{
13
"type": "webhook",
14
"name": "get_data",
15
"description": "Fetches data from the API",
16
"api_schema": {
17
"url": "https://{{system_env__api_host}}.example.com/v1/data",
18
"method": "GET",
19
},
20
}
21
],
22
},
23
)

In server tool headers

Secret environment variables can be used in request headers. Instead of hardcoding a secret ID, reference an environment variable so different secrets are used per environment. When configuring a tool header in the dashboard, select an environment variable instead of a static secret. At runtime, the header value resolves to the secret stored for the current environment.

API example

Pass an environment variable reference in the request_headers field:

1
{
2
  "api_schema": {
3
    "url": "https://{{system_env__api_host}}.example.com/v1/data",
4
    "method": "GET",
5
    "request_headers": {
6
      "X-Api-Key": { "env_var_label": "my_api_key" }
7
    }
8
  }
9
}

In server tool auth connections

Auth connections (OAuth2, JWT, Basic Auth) can also be resolved per environment. This is useful when your staging and production environments use different OAuth clients or token endpoints.

In the tool configuration, select an environment variable of type auth_connection instead of directly selecting an auth connection. The correct auth connection for the current environment is resolved at runtime.

API example

Reference an environment variable in the auth_connection field:

1
{
2
  "api_schema": {
3
    "url": "https://{{system_env__api_host}}.example.com/v1/data",
4
    "method": "GET",
5
    "auth_connection": { "env_var_label": "my_oauth_connection" }
6
  }
7
}

In MCP server connections

Environment variables work with MCP server connections in the same way they work with server tools. You can use them in:

• Server URL: Template the MCP server URL to point to different servers per environment
• Request headers: Use secret environment variables for authentication headers
• Auth connections: Use auth connection environment variables for OAuth-based MCP servers

For example, an MCP server URL configured as:

https://{{system_env__mcp_host}}.example.com/mcp

resolves to different MCP server endpoints depending on the environment.

In custom LLM configurations

When using a custom LLM, environment variables can template the API key and request headers. This lets you use different model endpoints and credentials across environments.

The custom LLM URL field supports the same {{system_env__<label>}} template syntax. The api_key field accepts an environment variable reference so different API keys are used per environment.

API example

1
{
2
  "conversation_config": {
3
    "agent": {
4
      "prompt": { "prompt": "You are a helpful assistant." },
5
      "llm": {
6
        "custom_llm": {
7
          "url": "https://{{system_env__llm_host}}.example.com/v1/chat/completions",
8
          "model_id": "my-model",
9
          "api_key": { "env_var_label": "llm_api_key" }
10
        }
11
      }
12
    }
13
  }
14
}

Specifying the environment

The environment is set at conversation start time and persists for the entire conversation. If no environment is specified, it defaults to production.

When testing in the dashboard, select the environment from the dropdown in the agent preview:

WebSocket

Pass the environment query parameter when connecting to the conversation WebSocket:

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

WebRTC (Signed URL / Token)

When using WebRTC, pass the environment parameter when requesting a conversation token:

1
from elevenlabs.client import ElevenLabs
2
3
client = ElevenLabs(api_key="your-api-key")
4
5
token = client.conversational_ai.conversation.get_token(
6
agent_id="your-agent-id",
7
environment="staging",
8
)

React SDK

Pass the environment option in the useConversation hook or when starting a session:

1
import { useConversation } from '@11labs/react';
2
3
function Agent() {
4
  const conversation = useConversation();
5
6
  const connect = async () => {
7
    await conversation.startSession({
8
      agentId: 'your-agent-id',
9
      environment: 'staging',
10
    });
11
  };
12
13
  return <button onClick={connect}>Start conversation</button>;
14
}

Example: multi-environment agent

This example demonstrates a complete setup with a single agent that uses different API backends and credentials across development, staging, and production.

1
conversation = client.conversational_ai.conversation.get_signed_url(
2
    agent_id="your-agent-id",
3
    environment="development",
4
)

Naming constraints

• Labels: Alphanumeric characters and underscores only (e.g., base_url, api_key_v2)
• Environment names: Alphanumeric characters, underscores, and hyphens (e.g., production, staging, dev-us-east)
• Every environment variable must have a production value

Next steps