Environment variables
Environment variables fine-tune an agent's runtime behavior without changing its main configuration. You set them per agent in the Advanced card — see Set environment variables. Changes take effect only after the agent restarts.
Keys are case-sensitive. Booleans accept true or false. A variable you have not
set uses the default listed below.
note
This page lists the variables most agents need. The platform accepts any key/value pair, and support teams sometimes provide additional variables for specific setups — variables not listed here keep working.
Agent behavior
| Variable | What it does | Default |
|---|---|---|
START_PHRASE | The agent's welcome message — the first message a customer sees. In Simple mode, the same value is edited as the Welcome message field. | Not set |
START_META | Metadata attached to the welcome message, such as quick-reply buttons. JSON, for example {"option_lines":["Hey","You"]}. | Not set |
REPHRASING_IT_TEXT | The text shown when the agent fails to produce a valid reply. | Oops! Error on my side. Can you ask again in a different way? |
PROMPT_FIELD_<AGENT>_<FIELD> | Overrides one prompt field for one agent class. The name is case-sensitive; a mismatch is silently ignored. | Not set |
MODEL_KWARGS | Extra parameters sent with each generation request to the LLM provider. JSON string. | Not set |
LLM_KWARGS | Extra parameters for constructing the LLM handler. JSON string. | Not set |
Session
| Variable | What it does | Default |
|---|---|---|
SESSION_TIMEOUT_SEC | Closes the session this long after the last handled message or agent turn, in seconds. Each handled activity restarts the countdown. | 259200 (3 days) |
OPERATOR_SESSION_TIMEOUT_SEC | The same timeout for operator and Copilot sessions, in seconds. A negative value disables the timeout. | 864000 (10 days) |
PROCESS_TIMEOUT_SESS2V | The maximum time one agent turn may take before it is aborted, in seconds. | 120 |
CUSTOM_STOP_MESSAGE | A message sent to the customer when the session stops. | Empty |
MAX_AGENT_ERRORS | The number of agent errors during one run after which the agent is marked failed. | 10 |
Memory and summarization
The agent keeps two working memories: the scratchpad (its own reasoning steps) and the chat history. When a conversation grows past the limits below, older records are summarized so the agent keeps context without an ever-growing prompt.
| Variable | What it does | Default |
|---|---|---|
MEMORY_SIZE | Scratchpad length in messages. Oldest records drop past the limit. | 15 |
CONVERSATION_MEM_LIMIT | Chat-history length in messages. Oldest records drop past the limit. | 16 |
ENABLE_SUMMARIZATION | Summarize old scratchpad records instead of dropping them. | true |
ENABLE_CONVERSATION_SUMMARIZATION | Run the conversation summarization step in the main flow. | true |
SUMMARY_LIMIT | The scratchpad length that triggers summarization of the oldest records. | 15 |
SUMMARY_MEMORY_LIMIT | The scratchpad length at which a prepared summary replaces the summarized records. | 25 |
Knowledge search
| Variable | What it does | Default |
|---|---|---|
SHOW_RAG_SOURCES | Include the sources a knowledge-based answer came from. The portal sets this from the Show RAG sources switch in the Advanced card — change the switch instead of setting the variable. | Follows the switch |
SHOW_RAG_CHUNK_NUMBERS | Include chunk numbers in knowledge-based answers. | false |
SEARCH_TOOL_TOP_K | The number of top results the knowledge search returns. | 15 |
KB_SEARCH_CONTEXT_WINDOW | The context window, in chunks, used around each search hit. | 4 |
KB_SEARCH_MAX_SOURCES_LEN | The maximum total length of source excerpts, in characters. | 25000 |
Language and speech
| Variable | What it does | Default |
|---|---|---|
REPLY_IN_USER_LANGUAGE | Translate agent replies into the customer's detected language. Requires a translator integration. | false |
TRANSLATE_TO_EN | Translate customer messages to English before they reach the model. Requires a translator integration. | false |
LANG_DETECTION_MIN_LENGTH | The minimum message length, in characters, that triggers language detection. | 20 |
ENABLE_NER | Mask named entities during translation. | false |
WHISPER_LANGUAGE | The language (or comma-separated languages) for speech recognition, for example en or en,kk,ru. | Depends on the speech model |
WHISPER_PROMPT | A custom prompt for the speech-recognition model. | Not set |
VAD_THRESHOLD | The voice-activity-detection threshold for speech recognition. | 0.6 (chat), 0.65 (SIP voice) |
TTS_AZURE_SSML_MODE | Send SSML markup to Azure text-to-speech. | false |
Channels
| Variable | What it does | Default |
|---|---|---|
SHOW_VOICE_TRANSCRIPTION | Show the transcription text for customer voice messages. Telegram and WhatsApp only. | true |
LOG_WEBHOOK_MESSAGES | Log every request that reaches the WhatsApp webhook. | false |
INTERCOM_TEAM_ID_FILTER | A comma-separated list of Intercom team IDs the agent accepts messages from, for example 7727961,7727960. Unset accepts all teams. | Not set |
EMAIL_RETRY_LIMIT | The number of email client request attempts before giving up. Email channel only. | 10 |
MCP servers
Connect the agent to Model Context Protocol servers. Each variable that ends in
MCP_ENDPOINT defines one server; to configure several, give each its own prefix —
for example WEATHER_MCP_ENDPOINT and CRM_MCP_ENDPOINT. Every other variable
below uses the same prefix as its server, or no prefix for the default server.
| Variable | What it does | Default |
|---|---|---|
[PREFIX_]MCP_ENDPOINT | Required. The server URL (HTTP) or execution command (stdio). Defines the server. | Not set |
[PREFIX_]MCP_TRANSPORT | The protocol: streamable_http, http_sse, or stdio. | streamable_http |
[PREFIX_]MCP_AUTH_TYPE | The auth method: none, bearer, token, api_key, basic, or custom (auth through MCP_CUSTOM_HEADERS). | none |
[PREFIX_]MCP_AUTH_TOKEN | The token, for bearer authentication. | Not set |
[PREFIX_]MCP_TOKEN | The token, for token authentication. | Not set |
[PREFIX_]MCP_API_KEY | The API key value, for API-key authentication. | Not set |
[PREFIX_]MCP_API_KEY_HEADER | The HTTP header that carries the API key. | X-API-Key |
[PREFIX_]MCP_API_KEY_QUERY_PARAM | A query parameter that carries the API key instead of a header. | Not set |
[PREFIX_]MCP_USERNAME / [PREFIX_]MCP_PASSWORD | The credentials, for basic authentication. | Not set |
[PREFIX_]MCP_CUSTOM_HEADERS | Custom HTTP headers as a JSON string. | Not set |
[PREFIX_]MCP_CAPABILITIES | The server capabilities to use, comma-separated. | tools |
[PREFIX_]MCP_TIMEOUT | The request timeout, in seconds. | 30 |
[PREFIX_]MCP_CONNECT_TIMEOUT | The connection timeout, in seconds. | 5 |
[PREFIX_]MCP_INACTIVITY_TIMEOUT | How long an idle server connection is kept, in seconds. | 600 |
[PREFIX_]MCP_MAX_RETRIES | The number of retry attempts. | 3 |
[PREFIX_]MCP_MIN_ACTORS | The minimum number of pooled connections to the server. | 0 |
[PREFIX_]MCP_MAX_ACTORS | The maximum number of pooled connections to the server. Must be at least 1 and at least MCP_MIN_ACTORS. | 5 |
[PREFIX_]MCP_INCLUDE_TOOLS | A comma-separated substring filter — only matching tools are exposed. | Not set |
[PREFIX_]MCP_EXCLUDE_TOOLS | A comma-separated substring filter — matching tools are hidden. | Not set |
[PREFIX_]MCP_NAME_TRANSFORMER | Tool-name transformation rules, for example camel, snake, or s/old/new/g. | Not set |
Logging
| Variable | What it does | Default |
|---|---|---|
LOG_LEVEL | The verbosity of the agent's system logs: DEBUG (most verbose), INFO, WARNING, or ERROR (least verbose). Raise it to INFO or DEBUG while troubleshooting, then set it back — verbose logs grow fast. | ERROR |
Spam detection
Spam detection scores every customer message and blocks messages that look like random characters or unreadable text. Turn it on and tune it entirely through environment variables.
| Variable | What it does | Default |
|---|---|---|
SPAM_DETECTION_ENABLED | Master switch. All other SPAM_DETECTION_* variables apply only when this is true. | false |
SPAM_DETECTION_MESSAGE | The reply sent to the customer when a message is blocked. | Your message was detected as spam and was not delivered. |
SPAM_DETECTION_CONFIDENCE_THRESHOLD | The hard threshold (0–1): a single message at or above it is blocked immediately. Lower is stricter. | 0.5 |
SPAM_DETECTION_WEIGHTED_THRESHOLD | The soft threshold (0–1) for the weighted average over recent messages. | 0.35 |
SPAM_DETECTION_HISTORY_SIZE | The number of recent messages in the weighted check. | 5 |
SPAM_DETECTION_MIN_MESSAGES_FOR_DECISION | The minimum message count before the soft threshold applies. | 3 |
SPAM_DETECTION_TIME_DECAY_FACTOR | The decay applied to older messages in the weighted check, in (0, 1]. Lower forgets old messages faster. | 0.9 |
Advanced setups can replace the scoring pipeline (SPAM_DETECTION_COMPONENTS_CONFIG)
and the exclusion rules (SPAM_DETECTION_EXCLUSION_RULES) with custom JSON.
Common issues
- A variable has no effect. The agent was not restarted. In Simple mode, click Save; in Advanced mode, stop and start the agent.
- A secret value cannot be revealed. Expected: values saved with Secret stay masked. To change one, enter a new value.
- A prompt override is ignored.
PROMPT_FIELD_*names are case-sensitive — the agent and field names must match exactly.
Related pages
- Advanced settings — where you set the variables
- Prompts — the welcome message and
START_PHRASE - LLM model settings — model parameters configured outside environment variables
- Troubleshooting — agent-level diagnostics