Skip to main content
Version: 3.2.x

Configuration

All AI features are configured in the AI plugin, accessible at Admin > Plugins > AI. Before configuring features in the CMS, ensure the AI plugin dependencies and infrastructure have been set up (see Getting started).

note

The plugin may already have a baseline configuration set via environment properties by the ops team. Settings configured in the CMS override those defaults. Property-based defaults are not visible in the CMS UI.

The plugin has two levels of configuration:

  • Global settings—The top-level fields (such as the text embedding generator) apply across all sites.
  • Default Config—The Default Config section contains the chat client, the enable toggles for Create with Esca and Ask Esca, and a list of agents. These settings apply to all sites by default. Each agent (such as Create with Esca Agent or Ask Esca Agent) is an item in the Agents list with its own configuration form.

To override the default configuration for a specific site, navigate to Admin > Sites & Settings, select the site, and open the Plugins tab. Any settings configured there take precedence over the defaults for that site.

Global settings​

The following settings are configured at the top level of the plugin and apply to both Create with Esca and Ask Esca across all sites.

Text embedding generator​

The text embedding generator converts content into vector representations for semantic search. This setting is required if Ask Esca is enabled.

To configure the text embedding generator:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. From the Text Embedding Generator list, select a provider (for example, OpenAI Text Embedding Generator).
  4. Configure the provider-specific fields, such as Model.
  5. Click Save.

Default Config​

The Default Config section contains settings that apply to all sites unless overridden at the site level. It holds the chat client, enable toggles for Create with Esca and Ask Esca, and an Agents list where you add agent records (Create with Esca Agent, Ask Esca Agent) to customize per-agent behavior.

note

The structural system prompt for each agent is defined in code and is not editable from the CMS. Editor-facing prompt customization is additive: configure Brand Guidelines (on Create with Esca Agent) or Additional Instructions (on Ask Esca Agent) to layer extra guidance on top of the structural prompt.

Chat client​

The chat client handles all LLM interactions for both Create with Esca and Ask Esca. It is configured under Default Config.

To configure the chat client:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. Under Default Config, locate the Chat Client field.
  4. From the Chat Client list, select a provider (for example, OpenAI or Bedrock).
  5. Configure the provider-specific fields, such as the model or inference profile.
  6. Click Save.

Guardrails​

The Bedrock Guardrail Chat Client wraps any chat client and applies Amazon Bedrock Guardrails to prompts before they are sent and to responses before they are returned. This allows guardrails to be used with any AI provider, not just Bedrock-hosted models.

To configure guardrails:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. Under Default Config, locate the Chat Client field.
  4. From the Chat Client list, select Bedrock Guardrail Chat Client.
  5. From the Guardrail list, select the Bedrock guardrail to apply.
  6. Under Delegate, select the underlying chat client (for example, OpenAI Chat Client) and configure it as usual. Bedrock Chat Client cannot be used as the delegate — Bedrock-hosted models apply guardrails natively through the Guardrail field on Bedrock Chat Client itself.
  7. Click Save.
note

The IAM role used by the environment must have permission to call bedrock:ApplyGuardrail. Guardrails are assessed against both the user prompt and the model response.

Create with Esca​

Create with Esca allows editors to query the AI client to generate content ideas or suggestions such as headlines, body text, and more. The enable toggle lives directly on Default Config; all other Create with Esca settings live on the Create with Esca Agent record in the Agents list.

Enabling Create with Esca​

To enable Create with Esca:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. Under Default Config, toggle on the Create with Esca Enabled setting.
  4. Click Save.

Adding the Create with Esca Agent​

The Create with Esca Agent record holds all Create with Esca–specific configuration: brand guidelines, prompt suggestions, author personas, generation timeout, and AI-generated content detectors.

To add the agent:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. Under Default Config, locate the Agents list and click Add Item.
  4. Select Create with Esca Agent.
  5. Configure the fields described in the following sections.
  6. Click Save.

Brand guidelines​

Brand guidelines are appended to the structural system prompt for every Create with Esca request, ensuring the LLM follows your organization's tone and style requirements without needing to repeat them in individual prompts.

In the Create with Esca Agent record, enter the desired text in the Brand Guidelines field.

note

Long brand guidelines increase cost and may require models with larger context windows.

Prompt suggestions​

Prompt suggestions appear when editors interact with Create with Esca, providing pre-written prompts that can be clicked instead of typed. They can be configured at three levels: site-wide, content-type, and field.

Site-wide prompt suggestions

Site-wide prompt suggestions are available whenever an editor interacts with Create with Esca, regardless of content type or field.

To configure site-wide prompt suggestions:

  1. From the left navigation, under Admin, click Plugins.

  2. Click on the desired AI plugin.

  3. Open the Create with Esca Agent record in the Agents list and expand the Prompt Suggestions cluster.

  4. Under Global Prompt Suggestions, click Add Item.

  5. Click Create New. Brightspot displays the New Prompt Suggestion content edit form.

    1. In the Title field, give the prompt suggestion a title.
    2. In the Prompt field, enter the prompt text.
    3. Click Save.
    4. Click Back.

  6. Under Global Prompt Suggestions, select the prompt suggestion you just created.

  7. Repeat steps 4–6 to add additional prompt suggestions.

  8. Click Save.

Content-level prompt suggestions

Content-level prompt suggestions are available on a specific content type. When an editor interacts with Create with Esca on an asset of the selected content type, the prompt suggestion appears.

To configure content-level prompt suggestions:

  1. From the left navigation, under Admin, click Plugins.

  2. Click on the desired AI plugin.

  3. Open the Create with Esca Agent record in the Agents list and expand the Prompt Suggestions cluster.

  4. Under Type Specific Prompt Suggestions, click Add Item.

  5. Click Create New. Brightspot displays the New Content Level Prompt Suggestion content edit form.

    1. In the Name field, enter a name for the content-level prompt. This is an internal name that helps differentiate this content-level prompt from others.

    2. Under Content Type, select the content type for which the prompt suggestion will appear. For example, if you only want the prompt suggestion to appear for articles, select Article from this list.

    3. Under Content Level Prompt Suggestions, click Add Item.

    4. Click Create New. Brightspot displays the New Prompt Suggestion content edit form.

      1. In the Title field, give the prompt suggestion a title.
      2. In the Prompt field, enter the prompt text.
      3. Click Save.
      4. Click Back.

    5. Under Content Level Prompt Suggestions, select the prompt suggestion you just created.

    6. Repeat steps 5c–5e to add additional prompt suggestions. To create prompt suggestions for a different content type, return to the plugin settings and begin at step 4.

    7. Click Save.

    8. Click Back.

  6. Under Type Specific Prompt Suggestions, select the content-level prompt suggestion you just created.

  7. Click Save.

Field-level prompt suggestions

Field-level prompt suggestions are the most granular type and are available on a specific field of a specific content type.

note

Field-level prompt suggestions are created within content-level prompt suggestions. See the steps below for details.

To configure field-level prompt suggestions:

  1. From the left navigation, under Admin, click Plugins.

  2. Click on the desired AI plugin.

  3. Open the Create with Esca Agent record in the Agents list and expand the Prompt Suggestions cluster.

  4. Under Type Specific Prompt Suggestions, click Add Item.

  5. Click Create New. Brightspot displays the New Content Level Prompt Suggestion content edit form.

    1. In the Name field, enter a name for the field-level prompt.

    2. Under Content Type, select the content type for which the prompt suggestion will appear.

    3. Under Field Level Prompt Suggestions, click Add Field Level Prompt Suggestion.

    4. Under Content Field, select the field for which the prompt suggestion will appear. For example, if you only want the prompt suggestion to appear for the Headline field on an article, select Headline from this list.

    5. Under Field Level Prompt Suggestions, click Add Item.

    6. Click Create New. Brightspot displays the New Prompt Suggestion content edit form.

      1. In the Title field, give the prompt suggestion a title.
      2. In the Prompt field, enter the prompt text.
      3. Click Save.
      4. Click Back.

    7. Repeat steps 5c–5f to add additional field-level prompt suggestions.

    8. Click Save.

    9. Click Back.

  6. Under Type Specific Prompt Suggestions, select the field-level prompt suggestion you just created.

  7. Click Save.

Author personas​

An author persona applies a preset tone and style to AI-generated responses. Personas can be AI-generated from reference content or manually defined. A default persona and additional personas can be configured; editors select which persona to use when generating content.

To create an author persona:

  1. From the left navigation, under Admin, click Plugins.

  2. Click on the desired AI plugin.

  3. Open the Create with Esca Agent record in the Agents list and expand the Personas cluster.

  4. Under Default Persona, do the following:

    1. Select the field and click Create New.

    2. In the Name field, enter a name for the author persona.

    3. Under Profile, select one of the following options:

      • AI Generated—AI generates the persona by referencing assets that you select. After selecting this option, do the following:

        1. Under Referenced Content, click Add Item and search for an existing asset for AI to reference. You may select up to five assets.
        2. Writing Style Profile is a read-only field. After saving, Brightspot uses the configured chat client to generate a summary of the persona's tone and style.

      • Manual—Define the persona by entering a description. After selecting this option, do the following:

        • Under Writing Style Prompt, enter a description of the persona you want. Add as much detail as possible (for example, "I want my persona to sound like a thought leader in the content management space").

  5. (Optional) Under Other Personas, follow steps 4a–4c to create additional personas.

  6. Click Save.

note

If you selected AI Generated for the persona, then after saving, the AI client analyzes the selected assets and generates a summary in the Writing Style Profile field. From that field, you can click Preview a sample to see a side-by-side comparison of text with and without the persona applied.

Advanced settings​

Open the Create with Esca Agent record and select the Advanced tab:

FieldDescriptionDefault
Generation TimeoutMaximum time allowed for a generation request.180 seconds
Generated Content DetectorsDetectors that compare AI-generated content with subsequent edits to determine whether content should still be flagged as AI-generated.None

Ask Esca​

Ask Esca lets editors converse with an agent that searches and summarizes CMS content. The agent calls semantic and textual search tools iteratively as the conversation requires, rather than performing a single fixed retrieval pass.

Enabling Ask Esca​

To enable Ask Esca:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. Under Default Config, toggle on the Ask Esca Enabled setting.
  4. Click Save.

Adding the Ask Esca Agent​

The Ask Esca Agent record is optional — Ask Esca works without it using built-in defaults. Add the record only if you need to layer additional instructions on top of the default agent behavior.

To add the agent:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. Under Default Config, locate the Agents list and click Add Item.
  4. Select Ask Esca Agent.
  5. (Optional) Under the Advanced tab, populate Additional Instructions with extra guidance appended to the structural prompt.
  6. Click Save.

Permissions​

The ability to use AI features is based on the permissions assigned to an editor's role. Without the appropriate permissions, the AI icons are not visible.

Create with Esca permissions​

To configure Create with Esca permissions for a role:

  1. From the left navigation, under Admin, click Users & Roles.
  2. In the Roles widget, locate the role for which you want to enable AI functionality.
  3. Click under Additional Permissions and select Create with Esca Permission.
  4. From the Content Types field, select the content types in which Create with Esca is enabled.
  5. Click Save.

Ask Esca permissions​

To configure Ask Esca permissions for a role:

  1. From the left navigation, under Admin, click Users & Roles.
  2. In the Roles widget, locate the role for which you want to enable Ask Esca functionality.
  3. Click under Additional Permissions and select Ask Esca Permission.
  4. Toggle on the Use Ask Esca? setting.
  5. Click Save.