Project Settings

Project settings give administrators and developers control over who can access the project, which models and tools are available, how the runtime behaves, and what security and compliance policies the system enforces. The Settings section covers membership, API keys, model configuration, runtime tuning, data retention, integrations, agent behavior overrides, PII protection, and channel policies.

Overview

The Settings section is organized into five groups. Click any item to jump to its detailed documentation.

General

Setting	Purpose
Members	Manage project membership and role-based access control.
API Keys	Create and manage SDK and Platform keys for programmatic access.
Models	Configure which LLM models are available for agents.
Runtime Config	Tune extraction pipeline, NLU, multi-intent handling, and inference.
Data Retention	Set TTL for eval transcripts, scores, and production data.
Config Variables	Define compile-time key-value pairs for agents and tools.
Localization	Manage locale JSON assets and Git-synced translations.

Integrations

Setting	Purpose
Git	Connect a Git repository for version-controlled agent definitions.
Auth Profiles	Manage authentication credentials for connectors and integrations.

Agent Behavior

Setting	Purpose
Behavior Profiles	Define context-driven overrides for agent conversation behavior.
Alert Settings	Configure workflow approvals and proactive notifications.
Agent Transfer	Set session TTLs, routing, voice gateway, and PII handling for human handoff.
Agent Assist	Enable AI-powered suggestions for human agents in transfer sessions.

Security & Observability

Setting	Purpose
PII Protection	Configure PII detection patterns and redaction strategies.
Public API Access	Control which APIs end-users can access through identity providers.
Attachments	Configure file upload behavior and allowed MIME types.
Omnichannel	Configure cross-channel session continuity and recall.

Catalog

Setting	Purpose
Templates	Browse and manage response templates for agents.
Imported Modules	View modules imported from the catalog or other projects.
Module Publishing	Publish project resources as reusable modules.
Trace Dimensions	Configure custom metadata fields for trace data.

Advanced

Setting	Purpose
Advanced	Project deletion, feature flags, webhooks, and additional policies.

Before You Begin

Confirm the following before modifying project settings:

• Most settings pages require Admin access. Developers can view settings but cannot modify membership, API keys, or security controls.
• Adding project members requires them to already exist as workspace members. Only workspace Owners and Admins can invite new people into the workspace.
• Model configuration requires at least one LLM provider configured at the workspace level under Admin → Models.
• Git integration requires a repository URL and authentication (SSH key or personal access token) prepared in advance.

Accessing Project Settings

Navigation: Project → Sidebar → Settings

---

Members

The Members page lets you view and manage who has access to your project and what they can do.

Navigation: Project → Settings → Members

The page displays a table of all project members with name, email, role, join date, and a Remove action. To add a new project member, click Add Member, select an existing workspace member, choose a role, and save.

Project roles

Role	Capabilities
Admin	Full access: manage members, settings, agents, deployments.
Developer	Create and modify agents, tools, workflows, imports, and project resources.
Tester	Read project resources, create and read sessions, run simulations, view analytics.
Viewer	Read-only access to project resources, sessions, and analytics.

Click the Remove action next to a member to revoke their access immediately.

---

API Keys

The API Keys page lets you create and manage API keys for programmatic access to the project runtime.

Navigation: Project → Settings → API Keys

Tabs

Tab	Purpose
SDK Keys	Keys that client-side SDKs and web widgets use to interact with the project runtime.
Platform Keys	Keys for server-to-server integrations and administrative API access.

To create a key, click Create Key, provide a descriptive name, and optionally set an expiration date. Each key entry shows the key name, a masked key prefix, and the last-used date. Click the delete icon next to a key to revoke it permanently.

Use separate keys for each environment (development, staging, production) and rotate them regularly.

---

Models

The Model Configuration page lets you configure which LLM models are available for agents in this project.

Navigation: Project → Settings → Models

Click Add from Catalog to browse models from your workspace catalog. The first model you add becomes the default for new agents. Click Configure Workspace to manage workspace-level model providers and registrations.

Each model entry shows the model name, provider, supported capabilities (chat, function calling, vision, streaming), token limits, and pricing information.

---

Runtime Configuration

The Runtime Configuration page lets you configure the extraction pipeline, multi-intent handling, inference, currency conversion, and lookup tables for this project.

Navigation: Project → Settings → Runtime Config

Extraction Pipeline Configure how user input gets extracted into structured field values.

Setting	Description	Default
Extraction Strategy	How fields get extracted from user messages (auto, ml, or rules).	auto
Correction Detection	Method for detecting when users correct previous answers (ml or rules).	ml
NLU Provider	NLU provider for entity extraction and intent detection (standard or custom).	standard

Additional sections include multi-intent handling, inference settings, currency conversion tables, and lookup tables for entity resolution.

Click Save to apply changes. Click Reset to Defaults to restore all values to their original settings.

---

Data Retention

The Data Retention page configures how long eval transcripts, eval scores, and production score rows remain available for this tenant.

Navigation: Project → Settings → Data Retention

Retention categories

Category	Description	Default
Eval conversations	Retention period for evaluation conversation transcripts.	730 days
Eval scores	Duration for which the system stores evaluation score records.	730 days
Production scores	Availability period for production scoring data.	365 days
Synthetic eval runs	Retention period for synthetic evaluation run data.	30 days

Retention Windows Below the summary cards, the Retention Windows section lets you edit the TTL (time-to-live) value in days for each category.

Field	Description
Eval conversation transcript TTL	Number of days to retain evaluation conversation transcripts.
Eval score TTL	Number of days to retain evaluation score records.
Production score TTL	Number of days to retain production scoring data.
Synthetic eval TTL	Number of days to retain synthetic evaluation run data.

Click Save to apply changes or Reset to restore all values to their defaults.

---

Config Variables

The Config Variables page lets you define key-value pairs that the system resolves at compile time through {{config.KEY}} syntax.

Navigation: Project → Settings → Config Variables

Config variables store API endpoints used by multiple tools, feature flags, and business-specific values that agent personas reference. The page shows all defined variables with a filter-by-key search and namespace grouping. Click Namespaces to organize variables into logical groups.

Add a Variable

Click Add Variable to create a new entry. Each variable includes the following fields:

Field	Description
Key	Unique identifier for the variable (for example, API_BASE_URL). Reference in code as {{config.KEY}}.
Value	The value assigned to the key, resolved at compile time.
Namespaces	Logical grouping for the variable. Defaults to Auto.
Description	Optional description explaining the variable’s purpose.

Click the checkmark to save or the × to discard. You can override variables per deployment environment.

Config variables resolve at compile time. Changes require recompilation to take effect.

---

Localization

The Localization page lets you manage locale JSON assets with a full-width editor and sync them through the existing Git integration.

Navigation: Project → Settings → Localization

The page displays the total number of assets, locales, and shared assets. The platform stores locale assets as project-level JSON files and exports them to Git under the same path contract that project import/export uses (for example, locales/en/_shared.json or locales/fr/booking_agent.json). If Git is not connected, a status indicator shows Git not connected with a link to Open Git Settings.

Create a Localization Asset

Click New Asset to open the asset editor. Complete the following fields:

Field	Description
Relative Path	The locale file path in canonical locale/asset.json format (for example, en/_shared.json). Keep paths in this shape so Git, export, and import round-trip cleanly.
Description	Optional context for translators and reviewers.
JSON Editor	Full-width code editor for the locale JSON content. Edit the asset directly in the browser.

Use Upload JSON to import an existing file, or Prettify to auto-format the JSON content. Click Save to create the asset.

---

Git Integration

The Git page lets you connect a Git repository to sync agents and localization assets with version control.

Navigation: Project → Settings → Git

Connect a Repository

Click Connect Repository to open the connection dialog. Configure the following fields:

Field	Description
Provider	The Git hosting provider (for example, GitHub).
Repository URL	The full URL of the repository (for example, https://github.com/org/repo).
Branch	The branch to sync with (for example, main).
Sync Path	The directory path within the repository to sync. Use / for the repository root.
Use Auth Profile	Toggle to use an existing auth profile instead of inline credentials.
Credential Type	Authentication method: Personal Access Token or SSH Key.
Secret ID	The secret reference identifier for the credential.
Conflict Strategy	How the system resolves conflicts when both Studio and the repository have changes.

Test the connection before saving. When Git integration is enabled, you can push agent definitions to the repository, pull changes into Studio, and use conflict resolution tools to manage simultaneous edits.

---

Auth Profiles

The Auth Profiles page lets you manage authentication credentials for connectors and integrations.

Navigation: Project → Settings → Auth Profiles

Tabs

Tab	Purpose
All Profiles	View and manage all authentication profiles configured for the project.
Integrations	View profiles associated with specific third-party integrations.

Each profile entry displays the profile name, test status, active/inactive status, environment scope, auth type, source, and whether it is project-level or inherited from the workspace. Workspace-inherited profiles show a Manage in Workspace link and cannot be edited at the project level.

Create an Auth Profile

Click Add Profile to open the profile type selector. Choose from the following authentication types:

Basic Authentication

Type	Description
API Key	Static API key sent through header or query parameter.
Bearer Token	Static bearer token in Authorization header.
Basic Auth	HTTP Basic authentication with username and password.
Custom Header	Send one or more custom auth headers.

OAuth 2.0

Type	Description
OAuth 2.0 App	OAuth application credentials (client ID + secret).
Client Credentials	Machine-to-machine OAuth through client credentials grant.

Enterprise Identity

Type	Description
Azure AD	Microsoft Entra ID (Azure Active Directory) for enterprise SSO.
mTLS	Mutual TLS with client certificate and private key.
AWS IAM (SigV4)	Sign requests with AWS Signature Version 4.
SSH Key	Authenticate with SSH private key credentials.
Digest Auth	HTTP Digest authentication with challenge-response.
Kerberos	SPNEGO/Kerberos authentication for enterprise systems.
SAML	SAML assertion-based authentication flow.
HAWK	HAWK MAC request signing.
WS-Security	SOAP WS-Security UsernameToken / certificate auth.

---

Behavior Profiles

The Behavior Profiles page lets you define context-driven overrides for agent conversation behavior. Profiles layer on top of any agent baseline when their conditions match, without modifying the core agent definition.

Navigation: Project → Settings → Behavior Profiles

Create a Behavior Profile

Click Create Profile to open the structured editor. The profile header includes the following fields:

Field	Description
Profile Name	A unique identifier for the profile (for example, voice_support).
Priority	Numeric priority. Lower values take precedence when multiple profiles match.
WHEN Expression	A boolean expression that determines when this profile activates (for example, true for always-on, or a context variable check).

Below the header, the profile editor organizes settings into three behavior sections:

Speaking

Setting	Description
Style	Response style (for example, warm and concise).
Tone	Response tone (for example, reassuring).
Emotion	Emotional register (for example, calm).
Pace	Response pacing (for example, steady).
Language Policy	Language selection policy (Inherit, Fixed, or Detect).
Fixed Language	The language code when Language Policy is Fixed (for example, en-US).
Max Sentences	Maximum number of sentences per response.
One Thing at a Time	Whether the agent addresses one topic per turn.
Tool Lead-in	How the agent introduces tool invocations.
Tool Results Style	How the agent presents tool results to the user.
Tool Result Points	Number of key points to extract from tool results.
Internal Handoffs	Behavior when handing off to another agent.
Human Handoffs	Behavior when handing off to a human operator.

Listening

Setting	Description
Barge-In	How the agent handles user interruptions mid-response.
On Pause	Behavior when the user pauses mid-utterance.
On Overlap	Behavior when user and agent speak simultaneously.
Unclear Audio	How the agent handles unclear or noisy input.
Self-Correction	How the agent detects and handles user self-corrections.

Interaction

Setting	Description
Answer Shape	The structure of responses (for example, direct, exploratory).
Detail	Level of detail in responses.
Initiative	How proactively the agent guides the conversation.
Grounding	How the agent establishes shared understanding.
Clarification	When and how the agent asks clarifying questions.
Max Clarification Questions	Maximum number of clarification questions per turn.
Assume When Low Risk	Whether the agent assumes intent when the risk of misunderstanding is low.
Confirm Parameters	Whether the agent confirms parameters before executing actions.
Confirm Actions	Whether the agent confirms actions before performing them.
Uncertainty	How the agent communicates uncertainty.
Offer Next Steps	Whether the agent proactively suggests next steps.
Empathy	Level of empathetic language in responses.
On Correction	Behavior when the user corrects the agent.
On Confusion	Behavior when the user appears confused.
On Misheard	Behavior when the system misrecognizes audio input.
Repair Attempts	Maximum number of repair attempts before escalation.
Avoid Re-asking	Whether the agent avoids repeating questions already answered.
Remember Constraints	Whether the agent tracks and respects stated constraints across turns.
Closure	How the agent closes a conversation or topic.

Authoring Note A free-text field for documentation. Describe when this profile layers on top of any agent baseline.

All settings default to Inherit, meaning the agent’s base configuration applies. Override any setting to customize behavior for the profile’s conditions. Click Save to create the profile, or switch to Raw DSL to edit the profile definition as code.

---

Alert Settings

The Alerts page serves as an inbox for workflow approvals and proactive notifications.

Navigation: Project → Settings → Alert Settings

Tabs

Tab	Purpose
Approvals	Review and act on pending workflow and agent approvals, data entry requests, and completed items.
Alert Rules	Configure rules that trigger proactive notifications based on system events or thresholds.

Filter the Approvals tab by source (Workflow or Agent) and type (All, Approvals, Data Entry). Toggle Include completed to view historical approvals alongside pending items.

The Approvals tab requires the human_task:read permission. If your role lacks this permission, the system displays a “Forbidden: missing required permission” message.

---

Agent Transfer

The Agent Transfer Settings page configures defaults for agent transfer sessions, routing, voice gateway, and PII handling.

Navigation: Project → Settings → Agent Transfer

The page organizes content into four collapsible sections:

Section	Description
Session Lifecycle	TTL and concurrency limits for transfer sessions by channel.
Default Routing	Default connection, queue, and priority for agent transfers.
Voice Gateway	Voice-specific transfer settings for SIP-based handoffs.
PII Handling	Control how the system handles PII during transfers.

Session Lifecycle

Setting	Description	Default
Chat TTL	Session timeout for chat channels (minutes).	0.5
Email TTL	Session timeout for email channels (minutes).	4
Voice TTL	Session timeout for voice channels (minutes). 0 = end with call.	0
Messaging TTL	Session timeout for messaging channels (minutes).	0.5

Default Routing

Configure the default connection, queue, and priority that the system uses when an agent initiates a transfer. These defaults apply unless the agent or workflow overrides them at runtime.

Voice Gateway

Configure voice-specific transfer settings for SIP-based handoffs, including SIP headers, DTMF relay, and call recording behavior during transfers.

PII Handling

Control how the system handles personally identifiable information during transfers. Configure which PII fields pass through, get masked, or get redacted when the conversation hands off to a human operator.

Click Save to apply changes or Reset to restore all values to defaults.

---

Agent Assist

The Agent Assist page manages Agent Assist connections for this project.

Navigation: Project → Settings → Agent Assist

Project Settings The Enable Agent Assist for this project toggle controls whether the Agent Assist facade is available. When enabled, human agents receive AI-powered suggestions, knowledge lookups, and response drafts in real time. When disabled, the facade returns 404.

Connections Click Add connection to configure a new Agent Assist integration with endpoint and authentication credentials.

---

PII Protection

The PII Protection page configures PII detection patterns, redaction strategies, and consumer access controls for this project.

Navigation: Project → Settings → PII Protection

Global Settings

Setting	Description	Default
PII Detection	Scan agent inputs for PII using active patterns.	Enabled
PII Output Redaction	Apply redaction to agent outputs before delivery to consumers.	Disabled

Credential, secret, and high-risk token scrubbing stays active for logs, traces, session history, and normal API responses even when configurable PII detection is disabled.

Built-in Patterns

Built-in patterns use optimized detection. You can configure redaction, per-consumer access, and enabled state. Disable high-risk patterns only with intention.

Pattern	Tag	Description
Email Address	Email	Detects email addresses in text.
Phone Number	Phone	Detects phone numbers (US and international formats).
Social Security Number	SSN	Detects US Social Security Numbers (XXX-XX-XXXX).
Credit Card Number	Credit Card	Detects credit/debit card numbers (Visa, MC, Amex, etc.).
IP Address	IP Address	Detects IPv4 and IPv6 addresses.

Click Configure next to any pattern to adjust its redaction strategy, consumer access rules, and enabled state.

Custom Patterns

Click Add Pattern to define organization-specific PII detection rules. The Create PII Pattern dialog includes the following sections:

Basics

Field	Description
Name	A unique name for the pattern (for example, US Social Security Number). Required.
Description	Optional description of what the pattern detects.
Enabled	Toggle to activate or deactivate the pattern.

Detection

Field	Description
Regex Pattern	The regular expression that matches sensitive data. Required.
PII Type	Classification of the PII type (Custom or a predefined category).
Validator Expression	Optional secondary regex to post-filter matches. The system keeps only matches that pass this regex.

Redaction Strategy

Option	Description
Predefined Label	Replace matched text with a configurable label (default: [REDACTED_<TYPE>]).
Masked	Replace matched text with placeholder characters.
Random	Replace matched text with random characters.

When you select Predefined Label, configure the Redaction Label field to customize the replacement text.

Consumer Access

Field	Description
Default Render Mode	How PII appears by default: Redacted, Tokenized, or Original.
Per-Consumer Overrides	Click Add Consumer to set render mode overrides for specific consumers.

LLM consumers cannot receive original plaintext. The system stores a saved LLM override of Original as Tokenized, and an Original default adds an explicit LLM Tokenized override.

Live Test Enter sample text in the Sample Text field to test pattern detection before saving. The test runs the regex pattern and validator expression against the input and shows matches with the configured redaction applied.

---

Public API Access

The Public API Access page configures which APIs end-users can access when authenticating through their organization’s identity provider (Azure AD, Okta, Google).

Navigation: Project → Settings → Public API Access

Query API

Toggle the Query API to allow authenticated end-users to query agents through the public API endpoint. When enabled, the following configuration fields appear:

Field	Description
Identity Providers (Auth Profiles)	Select one or more OIDC-compatible auth profiles (OAuth 2.0 App or Azure AD). End-users authenticate through their organization’s IdP.
Allowed Email Domains	Comma-separated list of email domains that can authenticate. Leave empty to allow all domains.
Allowed Origins (CORS)	Comma-separated list of browser origins allowed to make API calls.
Allowed Redirect URIs (OAuth Flow)	Comma-separated full URIs where OAuth redirect responses can go. Exact match only — no wildcards.

Session & Rate Limits

Field	Description	Default
Session Token TTL (seconds)	How long search session tokens remain valid (60–3600 seconds).	900 (15 min)
Per User (req/min)	Maximum API requests per user per minute.	—
Per Project (req/min)	Maximum API requests per project per minute.	—

---

Attachments

The Attachment Settings page configures file upload behavior for this project.

Navigation: Project → Settings → Attachments

General

Setting	Description	Default
Enable Attachments	Allow file uploads in chat sessions.	Enabled (inherited)

Upload Limits

Setting	Description	Default
Maximum File Size	Maximum file size per upload.	20 MB
Allowed File Types	MIME types permitted for upload (maximum 50).	18 types (see below)

Default allowed file types include image/jpeg, image/png, image/gif, image/webp, application/pdf, text/markdown, text/plain, text/csv, application/json, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, audio/mpeg, audio/wav, audio/webm, video/mp4, and video/webm.

To add a custom MIME type, enter it in the Add MIME type field and click the add button. To remove an allowed type, click the × next to it.

Processing

Setting	Description	Default
PII Policy	How the system handles PII detected in attachments.	Redact
Default Processing Mode	How the system processes newly uploaded files.	Full

Info

Setting	Description	Default
Max Files Per Session	Maximum number of files per session (read-only).	100

Click Save Changes to apply.

---

Omnichannel

The Omnichannel page configures cross-channel session continuity.

Navigation: Project → Settings → Omnichannel

Omnichannel settings allow users who start a conversation on one channel to continue it on another without losing context.

Conversation Recall

Setting	Description	Default
Enable cross-channel recall	Allow sessions to transfer across channels.	Disabled
Maximum messages to recall	Number of messages carried over to the new channel.	20
Maximum age (days)	How old a conversation can be and still qualify for recall.	30

Allowed channels Lists all supported channels (web, voice, sms, whatsapp, email, slack, teams) with toggles for cross-channel recall participation.

Identity Requirements

Setting	Description	Default
Require identity verification	Whether the system requires identity verification for cross-channel recall.	Enabled
Minimum identity tier	The minimum identity verification tier required to recall sessions.	2 - Verified

Consent

Setting	Description	Default
Require explicit consent	Whether the user must explicitly consent before cross-channel recall.	Enabled

Live Transcript Sync Configure real-time transcript synchronization settings for cross-channel sessions.

Click Save Settings to apply changes.

If you see a “Failed to save settings” error, verify that your role has write permissions for project settings.

---

Templates

The Template Catalog displays all available response templates for agents in this project.

Navigation: Project → Settings → Templates

Categories

Category	Description
Content	Structured content responses (Markdown, HTML, Adaptive Card, Slack Block Kit).
Media	Media-rich responses (WhatsApp, AG-UI, Carousel).
Data	Data-driven responses.
Input	Collecting user input (Quick Replies).
Feedback	Collecting user feedback.

Each template card shows the template name, description, content type, web rendering mode, preview mode, and DSL insertability. Click New Asset to create a custom template.

---

Imported Modules

The Imported Modules page shows modules imported into this project from the catalog or other projects.

Navigation: Project → Settings → Imported Modules

Imported modules are reusable agent components (agents, tools, workflows) that other teams publish. The page lists all imported modules with their name, version, source project, and import date.

---

Module Publishing

The Module Publishing page lets you publish agents, tools, or workflows from this project as reusable modules that other projects can import.

Navigation: Project → Settings → Module Publishing

Publishing a module makes it available in the workspace module catalog. Configure which resources to include, set versioning, and manage access controls.

---

Trace Dimensions

The Trace Dimensions page lets you configure custom dimensions for trace data that appear in session traces and analytics.

Navigation: Project → Settings → Trace Dimensions

Define custom metadata fields that the system captures with every trace event. For each dimension, specify a name, source, and data type. Custom dimensions enrich trace data for granular filtering and analysis in the session browser and insights dashboard.

---

Advanced

The Advanced Settings page configures advanced execution parameters for this project.

Navigation: Project → Settings → Advanced

LLM Thinking

Setting	Description	Default
Enable Thinking	When enabled, the LLM provides detailed reasoning (thought) for each tool call. This improves traceability but increases token usage.	Disabled

LLM Task Prompts

Customize the prompts that the system uses for entity extraction, correction detection, validation, and inference. Each prompt ships with a default system prompt and can be expanded to view or edit.

Prompt	Description
Entity Extraction Prompt	System prompt for extracting field values from user messages during data collection.
Correction Detection Prompt	Detects when a user corrects a previously provided value (for example, “actually my name is…”).
Field Validation Prompt	Validates extracted values against field rules and constraints before accepting them.
Field Inference Prompt	Infers missing field values from context when the user provides related information.

Escalation Templates

Customize the escalation confirmation messages that users see when a conversation hands off to a human agent. Each channel type has its own template:

Channel	Description
Digital Channel	Shown in web chat and messaging apps. Supports markdown formatting and emoji.
Voice Channel	Read aloud by TTS on voice/phone channels. Keep it short and natural.
Plain Text	Fallback for SMS and channels without rich formatting support.

Each template supports {{reason}} and {{priority}} variables that the system substitutes at runtime with the actual escalation reason and priority level.

The Danger Zone section permanently deletes the project and all its agents, tools, deployments, and settings. This action cannot be undone. Click Delete Project to proceed.

Settings Versions

The Settings Versions section lets you create versioned snapshots of all project settings. Click Create Version to save the current settings state. Versions enable deployment pinning, allowing you to associate a specific settings version with a deployment environment.