Skip to main content
Version: 4.0.x

Configuration

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

Default provider and models​

The plugin does not choose a provider or a model on its own. Ask Esca and Create with Esca need a chat client. Only semantic search needs a text embedding generator; without one, Ask Esca searches by keyword only. For the best blend of cost, performance, and reliability, Brightspot's recommended default configuration is to use Amazon Bedrock with the following models.

PurposeDefault modelID
Text embeddingsAmazon Titan Text Embeddings V2amazon.titan-embed-text-v2:0
ChatGPT-6 Lunaus.openai.gpt-6-luna (inference profile)

Use the default configuration unless you have a specific reason to use another provider or model, such as a requirement to run AI through your organization's own provider account. OpenAI, Azure OpenAI, and Google Vertex AI are also supported (see Chat client).

Example environment configuration​

A cloud environment sets the default configuration with environment properties, so the plugin is configured when the environment starts and nobody has to select a model in the CMS. The following properties select the default models and turn on Ask Esca and Create with Esca.

1
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.aws.bedrock.BedrockTextEmbeddingGenerator
2
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=amazon.titan-embed-text-v2:0
3
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.aws.bedrock.BedrockChatClient
4
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/inferenceProfile=us.openai.gpt-6-luna
5
com.brightspot.ai.AiPlugin/defaultConfig/askAiEnabled=true
6
com.brightspot.ai.AiPlugin/defaultConfig/createWithAiEnabled=true

The environment's IAM role must be allowed to call Amazon Bedrock (see Configuring Amazon Bedrock), and semantic search also needs a vector database (see Vector database configuration). Editors still need the role permissions described in Permissions. For the equivalent properties for other providers, see Provider configuration.

warning

Environment properties and the CMS configuration are not merged. As soon as the AI plugin is saved in the CMS, Brightspot uses the saved plugin and ignores every com.brightspot.ai.AiPlugin property, including the ones for fields you did not change. The CMS form does not show the values set by properties, and it cannot be saved without a chat client.

In an environment configured with properties, do not create or save the AI plugin in the CMS unless you intend to replace the whole configuration. If you do, get the current values from the team that operates the environment, and select the same text embedding generator, Model, and Dimension (see Text embedding generator).

Default values​

The following tables list the default for each setting. The first table applies whichever provider is used. Each provider then has its own table, starting with Amazon Bedrock, the default provider. In the Location column, Default Config is the section of the AI plugin whose settings apply to every site unless a site has its own AI plugin configuration (see Default Config).

SettingLocationDefault
Additional TypesAI pluginNone. Only types marked in code are indexed.
Text ChunkerAI plugin > AdvancedDefault (recursive JSON chunking)
Max TokensAI plugin > Advanced500
Create with Esca EnabledAI plugin > Default ConfigOff
Ask Esca EnabledAI plugin > Default ConfigOff
Multimodal Allowed MIME TypesAI plugin > Default ConfigPNG, JPEG, GIF, and WebP images, PDF, plain text, Markdown, and CSV
Multimodal Maximum File SizeAI plugin > Default Config2,500,000 bytes
Generation TimeoutCreate with Esca Agent > Advanced180 seconds
Generated Content DetectorsCreate with Esca Agent > AdvancedDefault Generated Text Detector at 80% similarity
Ask Esca response limitai/askAiTimeoutSeconds context property300 seconds

Amazon Bedrock​

Amazon Bedrock is the recommended provider. The first four rows are the default configuration, which you set with environment properties or in the CMS. The remaining rows are the values Brightspot uses when the field is left blank.

SettingLocationDefault
Text Embedding GeneratorAI pluginBedrock Text Embedding Generator
ModelBedrock Text Embedding GeneratorAmazon Titan Text Embeddings V2 (amazon.titan-embed-text-v2:0)
Chat ClientAI plugin > Default ConfigBedrock Chat Client
Inference ProfileBedrock Chat ClientGPT-6 Luna (us.openai.gpt-6-luna)
Max Output TokensBedrock Chat Client32,768
GuardrailBedrock Chat ClientNone
Prompt Caching DisabledBedrock Chat ClientOff, so prompt caching is on

OpenAI and Azure OpenAI​

These defaults apply only when you use OpenAI or Azure OpenAI in place of the default provider. Neither has a default model, so select one for the chat client and one for the text embedding generator.

SettingLocationDefault
ProviderOpenAI pluginOpenAI, as opposed to Azure OpenAI
Base URLOpenAI pluginhttps://api.openai.com/v1
API VersionOpenAI plugin, Azure OpenAI onlyThe SDK's latest stable version
URL Path ModeOpenAI plugin, Azure OpenAI onlyAUTO
APIOpenAI Chat ClientResponses
Reasoning EffortOpenAI Chat ClientThe model's default
Structured Output SupportedOpenAI Chat ClientOff
DimensionOpenAI Text Embedding GeneratorThe model's full size

Google Vertex AI​

These defaults apply only when you use Google Vertex AI in place of the default provider. It has no default model, so select one for the chat client and one for the text embedding generator.

SettingLocationDefault
LocationGoogle Gemini Chat Client and Google Gemini Text Embedding Generatorus-central1
DimensionGoogle Gemini Text Embedding GeneratorThe model's full size

Configuration levels​

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, the multimodal input settings, 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. A site's AI plugin configuration replaces Default Config as a whole. Configure its chat client, enable toggles, and agents explicitly; empty agent lists and disabled flags do not inherit the defaults. Sites without their own AI plugin configuration use Default Config.

note

In 4.0, legacy AI settings on the Integrations tab are no longer read or migrated automatically. Complete the 4.0 migration before upgrading an existing installation.

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.

Additional types​

Ask Esca's semantic search covers only assets whose type is indexed for AI. Keyword search and the content tools reach every type the editor can access. A type is indexed when developers mark it in code or when you select it in the Additional Types field. Types selected in this field are indexed in addition to those marked in code. The field lists only types that can be created as standalone assets.

To select the asset types indexed for semantic search:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. Expand the Additional Types list, and select an asset type. Repeat for each type you want to index.
  4. Click Save.
note

Brightspot generates embeddings when an asset is saved. Adding a type does not index assets that already exist. Those assets become searchable when they are next saved, or when a developer runs a bulk index (see Rebuild the vector index). A bulk index first deletes every embedding in the vector database, so semantic search returns incomplete results until it finishes.

Text embedding generator​

The text embedding generator converts content into vector representations for semantic search. This setting is optional. Without it, assets are not embedded when they are saved, semantic search is unavailable, and Ask Esca searches by keyword only. Embeddings already stored are left in place.

warning

Choose the text embedding generator once, before content is indexed, and do not change it, its Model, or its Dimension afterward. Embeddings from different models or of different sizes cannot be compared, and embeddings already stored are not regenerated. After a change of dimension, existing assets stop appearing in semantic search until they are saved again. After a change to a different model with the same dimension, semantic search returns unreliable results. Neither case reports an error.

Recovery requires a developer to rebuild the vector index (see Rebuild the vector index), which first deletes every stored embedding, so semantic search stays incomplete until the rebuild finishes.

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, Bedrock Text Embedding Generator).
  4. Configure the provider-specific fields, such as Model.
  5. Click Save.

OpenAI Text Embedding Generator and Google Gemini Text Embedding Generator have an optional Dimension field that sets the number of dimensions in each embedding, for models that support reduced dimensions such as text-embedding-3-small or gemini-embedding-001. Leave it blank to use the model's full size. For Google Gemini Text Embedding Generator, the Model list shows only models whose ID contains embedding at the configured Location.

note

A failure to generate embeddings does not block saving an asset. The server log records Can't update the embedding for <id>!, and the asset can drop out of semantic search until it is saved again with a working text embedding generator.

Chunker settings​

Each asset is split into chunks before it is embedded. To change how assets are split, select the Advanced tab and expand Chunker Settings:

FieldDescriptionDefault
Text ChunkerThe strategy used to split an asset into chunks.Default (recursive JSON chunking)
Max TokensThe maximum number of tokens per chunk. Keep it within the embedding model's context window. Applies when an asset is saved; a bulk index splits assets by the text embedding generator's own token limit instead.500
warning

A Max Tokens value larger than the embedding model accepts can make embedding requests fail. Brightspot removes an asset's stored embeddings before it generates new ones, so every asset saved while the value is too high drops out of semantic search until it is saved again with a working value.

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. Add each agent once; if the list holds two of the same kind, only the first is used.

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 (Bedrock Chat Client, OpenAI Chat Client, Google Gemini Chat Client, or Bedrock Guardrail Chat Client).
  5. Configure the provider-specific fields, such as the model or inference profile.
  6. Click Save.
note

For OpenAI, the API list selects which OpenAI API the chat client calls. Leave it blank to use Responses, which supports reasoning together with tools; a chat client saved before this field existed also uses Responses. Select Chat Completions only for an Azure deployment or an OpenAI-compatible endpoint that does not serve the Responses API. Such an endpoint returns a 404 error whose message says to make this change. Both APIs support image and PDF inputs automatically, subject to file type and size limits. Responses requests are sent with store set to false, so Brightspot replays reasoning and tool calls with each request rather than relying on responses stored by OpenAI.

The Reasoning Effort list sets the reasoning effort sent with either API. Leave it blank to use the model's default; supported levels depend on the model. Select NONE to turn off reasoning, which some models require for tool calls with Chat Completions.

note

For Bedrock, the Max Output Tokens field caps each response, including the model's thinking. Leave it blank to send 32,768. Bedrock rejects a value above the selected model's limit and names the limit in the error, so set the field to that limit for a model with a lower limit, or raise it (for example, 128,000 for Claude Opus 5) when responses or tool calls are cut off.

note

Google Gemini Chat Client has no output token field. A response cut off at the output token limit is returned as complete, and the server log records the warning Response truncated at the token limit for model [<model>]. Its Model list shows only models whose ID starts with gemini- followed by a digit, excluding TTS, image, computer-use, embedding, and live models, at the configured Location. The list is cached for one day per location, so a newly available model can take up to a day to appear.

note

Bedrock chat clients send prompt-cache checkpoints by default, so repeated instructions, tool definitions, and conversation history are billed at the cached rate on models that support caching. Models that do not support caching are detected automatically and run unchanged. Select Prompt Caching Disabled to stop sending checkpoints. Which models cache, and from what prompt size, is listed in the Amazon Bedrock prompt caching documentation.

Configuring OpenAI​

OpenAI Chat Client and OpenAI Text Embedding Generator use the API key and endpoint configured on the separate OpenAI plugin, not on the AI plugin.

To configure OpenAI:

  1. From the left navigation, under Admin, click Plugins.
  2. Click OpenAI.
  3. From the Provider list, select OpenAI.
  4. In the API Key field, type the OpenAI API key.
  5. (Optional) In the Base URL field, type the base URL of an OpenAI-compatible endpoint. Leave it blank to use https://api.openai.com/v1.
  6. Click Save.

Configuring Azure OpenAI​

Azure OpenAI uses the same plugin as OpenAI. Selecting Azure OpenAI from the Provider list reveals the Azure-only fields.

To configure Azure OpenAI:

  1. From the left navigation, under Admin, click Plugins.
  2. Click OpenAI.

  3. From the Provider list, select Azure OpenAI.

  4. In the API Key field, type the resource's API key.

  5. In the Endpoint field, type the resource's endpoint URL.

  6. (Optional) In the API Version field, type a dated API version. Leave it blank to use the SDK's latest stable version.

  7. In the Chat Model Deployments and Embedding Model Deployments fields, add the chat and embedding deployment names for the resource.

  8. (Optional) Using the following table as a reference, complete the remaining fields as needed.

    FieldDescription
    URL Path ModeWhich Azure API surface the endpoint serves. AUTO detects it from the endpoint; LEGACY forces the dated API paths; UNIFIED forces the v1 API paths.
    Additional HeadersExtra headers sent with every request, for gateways that require their own key. Each header has a Name and a secret Value.
  9. Click Save.

note

The deployment lists are added to what the resource's models endpoint reports, so a deployment stays selectable even when that endpoint is unavailable.

With Azure OpenAI selected, the chat client's Model field is labeled Deployment and lists the chat model deployments. To use native structured output, open the AI plugin's OpenAI Chat Client under Default Config and toggle on Structured Output Supported. Turn it on only when the deployment's model and the selected API version both support it; on the dated API that means 2024-08-01-preview or later.

Configuring Amazon Bedrock​

Amazon Bedrock uses a chat client for generation and a separate text embedding generator. Both use the credentials configured on the AWS plugin, and both fields list only the models that those credentials can reach. The following values are the defaults (see Default provider and models).

SettingDefault selection
Text Embedding Generator > ModelThe Amazon Titan Text Embeddings V2 model (amazon.titan-embed-text-v2:0)
Chat Client > Inference ProfileThe GPT-6 Luna inference profile (us.openai.gpt-6-luna)

Before configuring the plugin, ensure the following:

  • The AWS plugin is configured with credentials for the account that hosts the models.
  • Model access is enabled in Amazon Bedrock for both models.
  • The IAM role or user has permission to call, at a minimum, bedrock:ListFoundationModels, bedrock:ListInferenceProfiles, bedrock:InvokeModel, and bedrock:InvokeModelWithResponseStream. The first two populate the Model and Inference Profile lists. The others run embedding and chat requests. To select a guardrail, also allow bedrock:ListGuardrails, which populates the Guardrail list. Optionally, allow bedrock:GetFoundationModelAvailability, which converts a listed embedding model ID such as amazon.titan-embed-text-v2:0:8k into one that bedrock:InvokeModel accepts; without it, the listed ID is used as is. Your account's policies might require additional permissions, such as access to specific model and inference profile resources. For details, see the Amazon Bedrock actions reference in the AWS documentation.
  • The AWS Region offers the selected models. An inference profile with a us. prefix routes requests across US Regions.

To configure Amazon Bedrock:

  1. From the left navigation, under Admin, click Plugins.
  2. Click on the desired AI plugin.
  3. From the Text Embedding Generator list, select Bedrock Text Embedding Generator.
  4. From the Model list, select the Titan Text Embeddings V2 model.
  5. Under Default Config, from the Chat Client list, select Bedrock Chat Client.
  6. From the Inference Profile list, select the GPT-6 Luna profile.
  7. Click Save.

The Model and Inference Profile lists show the models and profiles that the AWS plugin's credentials can reach. Each entry shows the model name with its ID beneath it, so match the entry to the ID in the preceding table. Bedrock Text Embedding Generator supports only Amazon Titan, Cohere, and Amazon Nova embedding models, whose IDs start with amazon.titan-, cohere., or amazon.nova-. Other embedding models can appear in the Model list, but embedding with one fails with the error Bedrock model <ID> not supported.

note

The optional Guardrail field applies an Amazon Bedrock guardrail to Bedrock Chat Client requests. Leave it blank unless the account has a guardrail to apply. Bedrock Guardrail Chat Client is a separate option that wraps another chat client, such as one for a different provider, and applies a guardrail to its prompts and responses.

If a list is empty or a request fails, check the AWS plugin credentials, model access, and IAM permissions first.

tip

To give every environment the same baseline, set these values with environment properties instead. See Example environment configuration.

Guardrails​

The Bedrock Guardrail Chat Client wraps any chat client and applies Amazon Bedrock Guardrails to prompts before they are sent and to each response once the wrapped client has finished it. 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.

note

When a guardrail intervenes, the request ends with an error instead of a response. Create with Esca shows Create with Esca is temporarily unavailable because the AI Guardrails service is not responding. Contact an administrator for more information.; despite its wording, this message means a guardrail blocked the prompt or response. Ask Esca shows Something went wrong while generating the response. Please try again. The response check runs only after the wrapped client finishes, so text streamed before an intervention can already be visible to the editor. The same errors appear when the Guardrail field on Bedrock Chat Client intervenes, or when Google Gemini blocks a response, for example for safety or recitation. Google Gemini Chat Client has no safety settings field; a developer can apply safety settings by overriding AbstractGeminiChatClient#buildConfig.

Bedrock credentials​

By default, Bedrock clients use the credentials and region configured in the AWS plugin. To route Bedrock through a different IAM role, for example a role in the customer's own account, name a client config in the environment's settings. When one is named, it is used for every Bedrock client and the AWS plugin is ignored for Bedrock, except for the optional bedrock:GetFoundationModelAvailability call that resolves embedding model IDs, which still uses the AWS plugin's credentials.

1
aws/defaultBedrockClientConfig: customer
2
aws/bedrockClientConfig/customer/class: com.brightspot.aws.bedrock.AssumeRoleBedrockClientConfig
3
aws/bedrockClientConfig/customer/roleArn: arn:aws:iam::123456789012:role/BedrockAccess
4
aws/bedrockClientConfig/customer/roleSessionName: my-tenant
5
aws/bedrockClientConfig/customer/region: us-east-1
SettingDescription
roleArnARN of the role to assume. Required.
roleSessionNameSession name recorded in CloudTrail. Defaults to brightspot.
externalIdExternal ID, if the role's trust policy requires one.
regionRegion for the STS and Bedrock clients. Defaults to the SDK's region.

The role is assumed with the SDK's default credentials, such as the environment's IAM role, and the session is refreshed automatically before it expires.

Configuring Google Vertex AI​

Google Gemini Chat Client and Google Gemini Text Embedding Generator always call Gemini through Vertex AI; there is no API key option. Both use the project and credentials configured on the separate GCP Plugin, and send requests to the Location set on the client or generator, us-central1 when blank. On the GCP Plugin, select Static GCP Client Config under Client Config, then type the Google Cloud project ID in Project and paste the JSON contents of a service account key in Credentials Json. Without a project, the GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT environment variable is used; without a key, Application Default Credentials are used. The credentials must be able to list models and call Vertex AI in that project, because the Model lists come from Vertex AI.

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. Field-level suggestions are listed first, then content-level, then site-wide, and a prompt suggestion selected at more than one level is listed once.

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.

note

The legacy Default Author Persona and Other Author Personas fields under a site's Integrations > AI remain visible, but Create with Esca no longer reads them. Configure Default Persona and Other Personas on the Create with Esca Agent instead. User-level default persona preferences remain supported.

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:

        • In the Writing Style Profile field, 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.

While analysis is in progress, the field's note offers Refresh to view latest results, which reloads the persona, and You can also force a restart, which starts a new analysis. If analysis fails, the note shows the first recorded error; click regenerate to try again.

Brightspot generates the Writing Style Profile only when a new AI Generated persona is first saved with Referenced Content selected. After changing Referenced Content on an existing persona, save it, then click regenerate in the note under Writing Style Profile. If the referenced assets do not hold enough writing to form a persona, the model's reply that additional writing samples are needed is saved as the Writing Style Profile and no sample is generated; add more assets to Referenced Content and regenerate.

Saving a new AI Generated persona with Referenced Content selected, or clicking regenerate, fails with the error No Esca client is configured. Set one in the AI plugin settings to generate this persona. when the chat client is missing or misconfigured. Generation itself runs in the background with the chat client in Default Config, even for a persona on a site with its own AI plugin configuration, so Default Config must have a working chat client.

Each user can also choose a personal default that the Create with Esca pop-up preselects. In the header, click the user avatar > Profile, then from the Integrations tab, expand the AI cluster and select a Default Author Persona.

Advanced settings​

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

FieldDescriptionDefault
Generation TimeoutMaximum time allowed for a generation request. A positive ai/createWithAiTimeoutSeconds context property overrides this value.180 seconds
Generated Content DetectorsDetectors that compare AI-generated content with subsequent edits to determine whether content should still be flagged as AI-generated. Default Generated Text Detector keeps the flag while the field stays at least Similarity Threshold percent similar to the generated text (default 80). Detectors do not apply to a rich-text field filled by Create with Esca; that field stays flagged while any text Create with Esca marked as AI content remains in it.Default Generated Text Detector (80% similarity)

Ask Esca​

Ask Esca lets editors converse with an agent that finds, creates, edits, and deletes CMS content from natural-language requests. The agent calls search and content tools iteratively as the conversation requires, rather than performing a single fixed sequence.

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.

Ask Esca is offered only when the configuration that applies to the current site (the site's own AI plugin configuration, or Default Config) has Ask Esca Enabled toggled on and a Chat Client selected, and the editor's role grants Use Ask Esca? (see Ask Esca permissions). Otherwise the Ask Esca launcher is hidden.

note

An Ask Esca response is limited to 300 seconds. To change the limit, set the ai/askAiTimeoutSeconds context property to a number of seconds; a value of zero or less uses 300. When the limit is reached, the editor sees The response timed out. Please try again. and the turn is recorded in AI Audit with the Error completion type.

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.

Multimodal input​

Multimodal input lets an agent send files attached to CMS content to the model, so it can look at a diagram or read a PDF rather than work from a description of it. It is available automatically.

An agent can read files only from assets the editor can access.

File types and size​

Two settings control what an agent may send. Both are under Default Config, or under a site's AI plugin configuration on its Plugins tab. Both are optional, and both apply per site: an agent in the CMS uses the settings for the site the editor is working in. Over MCP, the site argument of Content_read does not select these settings, so do not rely on a site's own values to restrict MCP reads.

Multimodal Allowed MIME Types lists the file types an agent may send, one entry per type or pattern. Each entry uses the same syntax as file fields elsewhere in Brightspot: * matches any subtype, and a leading - denies rather than allows. A denial always wins whatever order the entries are in, so image/* and -image/svg+xml together mean every image format except SVG.

Leave the list empty to allow PNG, JPEG, GIF and WebP images, PDF, plain text, Markdown, and CSV. Word and Excel files require an explicit allowance and a model that supports their formats. Any entry replaces the default set rather than adding to it, and a list of denials alone allows nothing, so pair a denial with the types to allow, such as image/* with -image/svg+xml.

Multimodal Maximum File Size is the largest file an agent may send, in bytes, defaulting to 2,500,000. Keep it below the limit published by the AI provider in use, allowing roughly a third for encoding overhead.

A file must satisfy both these settings and whatever the provider itself accepts. When a file is refused, the agent is told which file, why, and what the site does allow, so it can try a different one.

Bedrock Chat Client accepts PNG, JPEG, GIF, and WebP images up to 3,750,000 bytes, and PDF, CSV, Word, Excel, HTML, plain text, and Markdown documents up to 4,500,000 bytes, and refuses any other file. Google Gemini Chat Client does not check files itself, so a file the model does not accept fails the whole request at the provider instead of being refused. With Gemini, keep Multimodal Allowed MIME Types to formats the selected model accepts.

note

Each Content_read includes at most three files and 10 MiB of file data, subject to the per-file site limit. The AI provider applies its own limits to the model request, which can include files from more than one read.

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. The server also refuses Ask Esca and Create with Esca requests with HTTP status 403 when the role lacks the matching permission or the feature is not enabled for the site. To let a role view the AI Audit widget, see Enabling permissions.

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. Leave the field empty to enable Create with Esca on all content types.
  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.