Configuration Reference
Reference documentation for FoundationaLLM configuration settings.
Overview
FoundationaLLM uses Azure App Configuration as the central store for application settings and feature flags. Secrets are stored in Azure Key Vault and referenced from App Configuration. This page describes how configuration keys are organized and lists the keys you are most likely to work with.
The canonical list of keys, with descriptions and default values, is defined in src/dotnet/Common/Constants/Data/AppConfiguration.json in the FoundationaLLM repository. The AppConfigurationKeys and AppConfigurationKeySections classes are generated from that file.
Configuration Sources
| Source | Purpose |
|---|---|
| Azure App Configuration | Application settings, feature flags, branding, and Agent Portal themes. |
| Azure Key Vault | Secrets such as API keys and connection strings. App Configuration holds Key Vault references to them. |
| Environment variables | Bootstrap settings that each service needs before it can read App Configuration. |
Model and service endpoints (for example Azure OpenAI, Amazon Bedrock, or MCP servers) are not App Configuration keys. They are API endpoint configuration resources, managed under Platform > API Endpoints.
Key Structure
Keys follow a hierarchical naming convention:
FoundationaLLM:{Namespace}:{Setting}
For example, FoundationaLLM:APIEndpoints:CoreAPI:Essentials:APIUrl. API settings are grouped under FoundationaLLM:APIEndpoints:{ServiceName}, with Essentials for connection settings (URL, API key, Application Insights connection string) and Configuration for service behavior.
Feature flags use the App Configuration feature flag format: .appconfig.featureflag/FoundationaLLM.{FeatureName}.
Instance Settings
| Key | Description |
|---|---|
FoundationaLLM:Instance:Id |
The unique identifier of the FoundationaLLM instance. Used in every Management API and Core API URL. |
FoundationaLLM:Instance:StatusMessage |
An instance-wide status message shown by the portals. |
FoundationaLLM:Instance:AgentWelcomeMessage |
An instance-wide message appended to all agent welcome messages. |
FoundationaLLM:Instance:SelfServiceAgentAIModels |
A comma-separated list of AI model names that can be used in self-service agent management. |
FoundationaLLM:Instance:PlatformDataSource |
The data source that provides the Azure Cosmos DB database used by platform features. |
FoundationaLLM:Instance:SecurityGroupRetrievalStrategy |
How the instance retrieves the security groups of a user. |
FoundationaLLM:Instance:IdentitySubstitutionSecurityPrincipalId |
The security principal allowed to substitute its identity with the value of the X-USER-IDENTITY header. |
FoundationaLLM:Instance:IdentitySubstitutionUserPrincipalNamePattern |
The regular expression that validates UPNs allowed in the X-USER-IDENTITY header. |
API Endpoints
| Key | Description |
|---|---|
FoundationaLLM:APIEndpoints:CoreAPI:Essentials:APIUrl |
Core API base URL. |
FoundationaLLM:APIEndpoints:ManagementAPI:Essentials:APIUrl |
Management API base URL. |
FoundationaLLM:APIEndpoints:AuthorizationAPI:Essentials:APIUrl |
Authorization API base URL. |
FoundationaLLM:APIEndpoints:AuthorizationAPI:Essentials:APIScope |
OAuth scope for the Authorization API. |
FoundationaLLM:APIEndpoints:StateAPI:Essentials:APIUrl |
State API base URL. |
FoundationaLLM:APIEndpoints:{ServiceName}:Essentials:APIKey |
(Key Vault reference) API key used by internal services such as the Orchestration API, LangChain API, Gateway API, Context API, and Data Pipeline API. |
FoundationaLLM:APIEndpoints:{ServiceName}:Essentials:AppInsightsConnectionString |
(Key Vault reference) Application Insights connection string for the service. |
Core API Configuration
| Key | Description |
|---|---|
FoundationaLLM:APIEndpoints:CoreAPI:Configuration:AllowedUploadFileExtensions |
Comma-separated list of file extensions that users can upload. |
FoundationaLLM:APIEndpoints:CoreAPI:Configuration:MaxUploadsPerMessage |
The maximum number of files that can be uploaded for a single message (default 10). |
FoundationaLLM:APIEndpoints:CoreAPI:Configuration:CompletionResponsePollingIntervalMilliseconds |
The polling interval used to check for completion responses. |
FoundationaLLM:APIEndpoints:CoreAPI:Configuration:AzureOpenAIAssistantsFileSearchFileExtensions |
File extensions supported by the Azure OpenAI Assistants file search tool. |
FoundationaLLM:APIEndpoints:CoreAPI:Configuration:AzureAIAgentsFileSearchFileExtensions |
File extensions supported by the Azure AI Agent Service file search tool. |
LangChain API Configuration
These keys are used by the FoundationaLLM function-calling workflow. Manage them on the Agent Workflows tab under Platform > Configuration.
| Key | Description |
|---|---|
FoundationaLLM:APIEndpoints:LangChainAPI:Configuration:WorkflowMainStatusMessages |
Pipe-separated (\|) status messages shown while the workflow determines whether tools are needed. Supports {current_round} and {max_rounds}. |
FoundationaLLM:APIEndpoints:LangChainAPI:Configuration:WorkflowToolStatusMessages |
Pipe-separated status messages shown while the workflow runs tools. Supports {current_round} and {max_rounds}. |
FoundationaLLM:APIEndpoints:LangChainAPI:Configuration:WorkflowToolEscalation:StatusMessages |
Pipe-separated status messages shown during the tool escalation pass. |
FoundationaLLM:APIEndpoints:LangChainAPI:Configuration:WorkflowToolEscalation:ToolsRequiringRouterPrompt |
Comma-separated tool resource names (for example Platform-Tool-Code) for tools that require the workflow router prompt when they are bound. Empty or missing means no tool requires it. |
Gateway API Configuration
| Key | Description |
|---|---|
FoundationaLLM:APIEndpoints:GatewayAPI:Configuration:AzureOpenAIAccounts |
Semicolon-separated list of the Azure OpenAI accounts used by the Gateway API. |
FoundationaLLM:APIEndpoints:GatewayAPI:Configuration:CompletionRequestMaxSizeTokens |
Maximum tokens in a single completion request (default 20000). |
FoundationaLLM:APIEndpoints:GatewayAPI:Configuration:EmbeddingRequestMaxSizeTokens |
Maximum tokens in a single embedding request (default 6400). |
FoundationaLLM:APIEndpoints:GatewayAPI:Configuration:TokenRateLimitMultiplier |
Multiplier applied to deployment token rate limits. |
Portal Settings
User Portal
| Key | Description | Default |
|---|---|---|
FoundationaLLM:UserPortal:Configuration:ShowLastConversationOnStartup |
Show the last conversation when the user signs in. | false |
FoundationaLLM:UserPortal:Configuration:ShowMessageRating |
Show rating options on agent messages. | true |
FoundationaLLM:UserPortal:Configuration:ShowMessageTokens |
Show token counts on messages. | true |
FoundationaLLM:UserPortal:Configuration:ShowViewPrompt |
Show the View Prompt button on agent messages. | true |
FoundationaLLM:UserPortal:Configuration:ShowFileUpload |
Allow file upload on chat messages. | true |
FoundationaLLM:UserPortal:Configuration:FeaturedAgentNames |
Comma-separated list of featured agent names. Managed on the Featured Agents tab under Platform > Configuration. | |
FoundationaLLM:UserPortal:Configuration:SelfServiceAgentTemplate |
The agent template used for self-service agent creation. Managed on the Self-Service tab under Platform > Configuration. | BasicAgentTemplate |
FoundationaLLM:UserPortal:Configuration:AgentManagementPermissionRequestUrl |
The URL where users request agent management permissions. |
The agent-level portal experience settings (for example show_message_tokens on an agent) control what users see for each agent.
Authentication
| Key prefix | Description |
|---|---|
FoundationaLLM:UserPortal:Authentication:Entra:* |
User Portal Entra ID settings: Instance, TenantId, ClientId, Scopes, CallbackPath, TimeoutInMinutes. |
FoundationaLLM:ManagementPortal:Authentication:Entra:* |
Management Portal Entra ID settings: Instance, TenantId, ClientId, Scopes, CallbackPath. |
FoundationaLLM:APIEndpoints:CoreAPI:Configuration:Entra:* |
Core API Entra ID settings: Instance, TenantId, ClientId, Scopes, CallbackPath, RequireScopes, AllowACLAuthorization. |
FoundationaLLM:APIEndpoints:ManagementAPI:Configuration:Entra:* |
Management API Entra ID settings, with the same keys as the Core API. |
Branding and Themes
User Portal branding keys use the prefix FoundationaLLM:Branding: (for example FoundationaLLM:Branding:CompanyName, FoundationaLLM:Branding:LogoUrl, FoundationaLLM:Branding:PrimaryColor, and FoundationaLLM:Branding:KioskMode). Agent Portal themes are stored under FoundationaLLM:AgentPortal:Themes: (a Manifest key plus one key per theme). Manage both on the Platform > Themes page. For the full list and defaults, see the Branding Reference.
Feature Flags
| Feature flag | Description | Default |
|---|---|---|
FoundationaLLM.Agent.PrivateStore |
Enables the agent private store (the Private Storage tab in the agent editor). | true |
FoundationaLLM.Agent.SelfService |
Enables agent self-service. | false |
FoundationaLLM.AgentPortal.SelfService |
Enables Agent Portal self-service. | false |
FoundationaLLM.AgentPortal.Canvas |
Enables the Agent Portal canvas. | false |
FoundationaLLM.Preview |
Enables preview features, such as Dynamic Compute and the agent's Realtime Speech Configuration. | false |
FoundationaLLM.ManagementPortal.Sandbox |
Enables the Management Portal sandbox features (Platform > Sandboxes and the agent's Sandbox tab). | false |
FoundationaLLM.User.TokenUsage |
Enables the user token usage feature. | false |
The full App Configuration key of each flag is .appconfig.featureflag/{flag name}. Enable or disable flags, edit their descriptions, and add exceptions by UPN (users for whom a disabled flag is turned on) on the Feature Flags tab under Platform > Configuration.
Resource Provider Settings
| Key | Description |
|---|---|
FoundationaLLM:ResourceProviders:{ProviderName}:Storage:AccountName |
The storage account used by a resource provider, for example FoundationaLLM:ResourceProviders:Agent:Storage:AccountName. |
FoundationaLLM:ResourceProviders:{ProviderName}:Storage:AuthenticationType |
How the resource provider authenticates to its storage account. |
FoundationaLLM:ResourceProvidersCache:EnableCache |
Whether resource providers cache resources (default true). |
FoundationaLLM:ResourceProvidersCache:AbsoluteCacheExpirationSeconds |
Absolute cache expiration in seconds (default 3600). |
FoundationaLLM:ResourceProvidersCache:SlidingCacheExpirationSeconds |
Sliding cache expiration in seconds (default 3600). |
FoundationaLLM:ResourceProvidersCache:CacheSizeLimit |
Maximum number of cached items (default 10000). |
Quota definitions are not App Configuration keys. They are FoundationaLLM.Quota/quotas resources, managed under Quotas > Quotas. See Quotas.
Environment Variables
| Variable | Used by | Description |
|---|---|---|
FoundationaLLM_AppConfig_ConnectionString |
.NET services | Connection string for Azure App Configuration. |
FOUNDATIONALLM_APP_CONFIGURATION_URI |
Python services | Endpoint of Azure App Configuration. |
FOUNDATIONALLM_VERSION |
All services | The build version, used to check the minimum version required by configuration entries. |
AZURE_CLIENT_ID |
All services | The client ID of the user-assigned managed identity. |
Key Vault References
Secrets are stored in Key Vault. App Configuration stores a Key Vault reference (content type application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8) whose value points to the secret:
{
"uri": "https://{keyvault-name}.vault.azure.net/secrets/{secret-name}"
}
Services resolve these references at run time with their managed identity.
Accessing Configuration
Management Portal
In the sidebar, select Platform > Configuration. The page has these tabs:
| Tab | Keys |
|---|---|
| Status Message | FoundationaLLM:Instance:StatusMessage |
| Welcome Message | FoundationaLLM:Instance:AgentWelcomeMessage |
| Self-Service | FoundationaLLM:UserPortal:Configuration:SelfServiceAgentTemplate and FoundationaLLM:Instance:SelfServiceAgentAIModels |
| Featured Agents | FoundationaLLM:UserPortal:Configuration:FeaturedAgentNames |
| Feature Flags | .appconfig.featureflag/* |
| Agent Workflows | The LangChain API workflow keys listed above. |
Branding and themes are on Platform > Themes. See Configuration.
Azure Portal
- Open your Azure App Configuration resource.
- Use Configuration explorer to browse keys.
- Use Feature manager for feature flags.
Management API
App Configuration values are appConfigurations resources of the FoundationaLLM.Configuration resource provider. The resource name is the key, and a trailing * acts as a filter:
GET {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/FoundationaLLM:Branding:*?api-version=2024-02-16
GET {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/FoundationaLLM:Instance:StatusMessage?api-version=2024-02-16
POST {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Configuration/appConfigurations/FoundationaLLM:Instance:StatusMessage?api-version=2024-02-16
Best Practices
- Use Key Vault for all secrets and sensitive values.
- Change values through the Management Portal or Management API where possible, so that changes go through FoundationaLLM authorization.
- Document changes when modifying configuration.
- Test in non-production before applying changes to production.
- Monitor configuration changes through App Configuration audit logs.