Environment Variables: Customizing AI Agent Behavior and Integrations
This page explains how to use environment variables to customize the behavior, integrations, and prompts of your Flametree AI agents. Environment variables allow you to set system-wide or agent-specific parameters, override prompts, and control integrations without modifying the agent’s core configuration.
Prerequisites
- Access to the Flametree platform with permissions to edit AI agents
- Basic understanding of agent configuration and advanced settings
How to Set Environment Variables
- Open the desired AI agent’s card.
- Go to Advanced card (right-hand section).
- Open Set Environment Variables.
- Click the plus icon to add a new parameter:
- key: The variable name (for example,
START_PHRASE) - value: The value to assign
- key: The variable name (for example,
- Use Secret option to make a variable masked/unmusked. If a variable was saved with the Secret option, you will not be able to unmask it in the UI. To change the Secret parameter value to false for a masked variable, you must set a new value.
- Click Save.
- Save and Restart the agent for changes to take effect.
❗️ Important: Changes to environment variables require a manual agent restart.
Environment Variables by Topic
Agent Customization
| Variable | Description | Default |
|---|---|---|
GAC_SYSTEM | Field system of the Global Agent Config | Always reply in English language |
ENABLE_FILLER_PHRASES | Enables filler phrases in custom-stateful agents | False |
FILLER_PHRASES_WITH_CHAIN | Phrase generation principle (chain or agent) | False |
REPHRASING_IT_TEXT | Custom text for error message | I apologize, but I'm unable to provide an answer... |
START_PHRASE | Sets the initial greeting message | Example: Hello! How can I help you today? |
START_PHRASE_APPENDIX | Additional text to append to the greeting phrase | "" |
PROMPT_FIELD_<AGENT_NAME>_<PROMPT_FIELD_NAME> | Overrides a specific prompt field for an agent | Example: Key: PROMPT_FIELD_MYAGENT_IDENTITYValue: You are a friendly assistant. |
OMIT_THOUGHT_PREMESSAGE | If True, agent will not receive message chunk of format "Thought: thought_num" in the end of the prompt | False |
BETA_FAST_FORM_TOOL | Beta feature - instead of filling one session result during one agent call, FormAgent fills all needed fields in one agent call | False |
MODEL_KWARGS | Additional parameters for creating the LLM handler in code through the LangChain object. Value must be a JSON string with parameters. | {} |
LLM_KWARGS | Additional parameters that will be included in the generation request sent to the LLM provider. Value must be a JSON string with parameters. | {} |
Language and Speech Settings
| Variable | Description | Default |
|---|---|---|
REPLY_IN_USER_LANGUAGE | Reply in user's detected language | False |
TRANSLATE_TO_EN | Translate user messages to English before sending to the model | False |
WHISPER_LANGUAGE | Language(s) for speech recognition (STT) | Example: en, en,kk,ru |
WHISPER_PROMPT | Custom prompt for the Whisper model. Prompting guide | - |
VAD_THRESHOLD | Voice activity detection threshold for STT | 0.6 |
LANG_DETECTION_MIN_LENGTH | Minimum message length to trigger language detection | 20 |
ENABLE_NER | Enables masking for named entities in translation | False |
TTS_AZURE_SSML_MODE | Enable SSML mode with XML in Azure TTS | False |
Knowledge Base
| Variable | Description | Default |
|---|---|---|
SHOW_RAG_CHUNK_NUMBERS | Display chunk numbers in KB responses | False |
SEARCH_TOOL_TOP_K | Top K for vector search in search tool | 15 |
KB_SEARCH_CONTEXT_WINDOW | Size of context window in chunks for SingleSearchFAQ tool | 4 |
KB_SEARCH_MAX_SOURCES_LEN | Max length of context chunks from KB in SingleSearchFAQ tool (symbols) | 25000 |
Session
| Variable | Description | Default |
|---|---|---|
SESSION_TIMEOUT_SEC | Session timeout (3*24*60*60 seconds) | 259200 |
DOUBLE_TEXTING_TIMEOUT | Timeout for grouping sequential WhatsApp messages (seconds) | 0 |
CUSTOM_STOP_MESSAGE | Custom stop message on session stop | "" |
SIMPLE_AGENT_FLOW | Enables SimpleAgent instance for custom session types | False |
Summarization
| Variable | Description | Default |
|---|---|---|
ENABLE_SUMMARIZATION | Enable/disable scratchpad summarization | True |
SUMMARY_LIMIT | Limit at which summarization of old scratchpad records begins | 20 |
SUMMARY_MEMORY_LIMIT | Limit at which prepared summary is inserted into the scratchpad | 30 |
Integrations
| Variable | Description | Default |
|---|---|---|
SHOW_VOICE_TRANSCRIPTION | Show transcription text for voice messages. WhatsApp and Telegram only | True |
LOG_WEBHOOK_MESSAGES | Whether to log all requests that come to WhatsApp webhook | False |
WA_REGISTRATION_DELAY | Delay (seconds) between WhatsApp webhook registration attempts. WhatsApp only. | 5.0 |
WA_REGISTRATION_COUNT | Number of WhatsApp webhook registration attempts. WhatsApp only. | 20 |
WEBHOOK_MESSAGES_LOGS_DIR | Directory path to store WhatsApp webhook logs (used if LOG_WEBHOOK_MESSAGES is true). WhatsApp only. | None |
TELEGRAM_SHOW_KEYBOARD_REPLY | Enables keyboard in Telegram integration (legacy) | True |
FB_REGISTRATION_DELAY | Delay (seconds) between Facebook Messenger webhook registration attempts. Facebook Messenger only. | 5.0 |
FB_REGISTRATION_COUNT | Number of Facebook Messenger webhook registration attempts. Facebook Messenger only. | 20 |
INTERCOM_TEAM_ID_FILTER | A comma-separated list of Intercom team IDs from which the agent should accept messages. For example: INTERCOM_TEAM_ID_FILTER=7727961,7727960 | True |
EMAIL_RETRY_LIMIT | Define number of email client request attempts before graceful exit. IMAP/SMTP channel only. | 3 |
EMAIL_MAX_ATTACHMENT_BYTES | Maximum size of inbound email attachments to decode and forward (in bytes). Set to 0 to disable limiting. IMAP/SMTP channel only. | 10485760 (10 MB) |
EMAIL_NAME | Display From name for the email account(s). IMAP/SMTP channel only. | None |
IMAP_MAILBOX | IMAP mailbox to monitor. IMAP/SMTP channel only. | INBOX |
SMTP_ATTEMPTS | Number of SMTP send attempts. IMAP/SMTP channel only. | 5 |
SMTP_DELAY | Delay between SMTP attempts (seconds). IMAP/SMTP channel only. | 5 |
FULL_EMAIL_ADDRESS | Full email address with display name. Has a higher priority than EMAIL_NAME. IMAP/SMTP channel only. | None |
FROM_TEMPLATE | Template for sender display format. IMAP/SMTP channel only. | {} <{}> |
MESSAGE_CONTENT_TYPE | Email content type. IMAP/SMTP channel only. | text/plain |
INFOBIP_SHORT_DOMAIN | Custom short domain for URL tracking. Infobip only. | go.flm3.com |
BIRD_TEMPLATE_LOCALE | Default locale for Bird message templates. Bird API only. | None |
BIRD_SESSION_TIMEOUT | Session timeout in seconds. Bird API only. | 86400 (24h) |
IS_OUTBOUND_ONLY | If true, Bird channel operates in outbound-only mode. Bird API only. | false |
BIRD_OUTBOUND_SESSION_IS_ENDED_MESSAGE | Message sent when outbound session ends. Bird API only. | See code default |
FLAMETREE_CALLBACK_PORT | Port for webhook server. Bird API only. | None |
BIRD_WEBHOOK_ADDRESS | Explicit webhook callback URL. Bird API only. | None |
FLAMETREE_CALLBACK_URL | Fallback webhook callback URL. Bird API only. | None |
BIRD_CRON_SUBSCRIPTION_RENEWAL | Cron expression for webhook subscription renewal. Bird API only. | 0 0 * * * |
BIRD_SENDER_NAME | Displayed sender name for Bird messages. Bird API only. | Flametree AI Agent |
System
| Variable | Description | Default |
|---|---|---|
LOG_LEVEL | Controls the verbosity of system logs. Available levels: DEBUG (most verbose), INFO (standard), WARNING, ERROR (least verbose) | INFO |
Common Issues & Solutions
Changes to environment variables don’t take effect
Solution: Save your changes and restart the agent to apply new environment variables.
Prompt override not working
Solution: Check the variable name format (PROMPT_FIELD_<AGENT_NAME>_<PROMPT_FIELD_NAME>) and ensure there are no typos or case mismatches.
FAQ
How do I set the initial greeting phrase?
Set the START_PHRASE environment variable in the agent’s advanced settings.