# Admin controls and guardrails in Amazon Q Business
With Amazon Q Business, you can customize your application environment to your organizational needs. Amazon Q Business offers application environment *guardrails* or *chat controls* that you can configure to control the end user chat experience.
Using the guardrails feature, you can define global controls and topic-level controls for your application environment like the following:
+ Control whether end users can upload files in chat to generate responses from uploaded files.
+ Control whether chat responses will be personalized to end users based on information (address and job related information) associated with them in your IAM Identity Center instance.
+ Specify whether all Amazon Q Business chat responses will be generated using only enterprise data or whether your application environment can also use its underlying large language model (LLM) to generate responses when it can’t find answers in your enterprise data.
+ Allow Amazon Q Business to automatically orchestrate end user chat requests across any Amazon Q Business plugins and data sources you’ve configured.
+ Allow Amazon Q Business to check its responses for hallucinations.
+ Control how Amazon Q Business responds to specific topics in chat.
+ Customize which users and groups Amazon Q Business topic-level controls apply to.
**Topics**
+ [Key terms for Amazon Q Business guardrails and chat controls](guardrails-concepts.md)
+ [Using global controls in Amazon Q Business](guardrails-global-controls.md)
+ [Using topic-level controls in Amazon Q Business](guardrails-topic-controls.md)
+ [Managing Amazon Q Business admin controls and guardrails](guardrails-management.md)
# Key terms for Amazon Q Business guardrails and chat controls
The following are key terms to understand guardrails in Amazon Q Business:
+ **Enterprise data** – Data connected to your application environment using either an Amazon Q Business connector, direct document upload, or through an Amazon Kendra retriever.
+ **Model knowledge** – The underlying knowledge outside your enterprise data that your large language model (LLM) is trained on.
+ **Topic** – An admin user defined natural language topic.
+ **Global controls** – application environment level controls for controlling the sources that your application environment uses to generate responses (model knowledge and enterprise data, or enterprise data only). Global controls also define and control blocked phrases within your application environment.
+ **Topic controls** – Topic-specific controls to determine the web application environment's behavior when it encounters a mention of a blocked topic by an end user.
+ **Rules** – An application environment behavior logic configured to manage a controlled topic for a particular group of users.
# Using global controls in Amazon Q Business
You can use Amazon Q Business global controls to configure settings that apply to conversations in your application environment.
**Note**
You can't create or delete guardrail global controls. You can only update existing global controls in your application environment.
The following are the global features that you can customize:
**Topics**
+ [Response settings](#guardrails-global-response)
+ [Chat orchestration settings](#guardrails-global-orchestration)
+ [Feature settings](#guardrails-global-feature)
+ [Blocked phrases](#guardrails-global-blocked)
+ [Customizing global controls](#guardrails-global-controls-customizing)
## Response settings
**Important**
If you're changing response settings for an Amazon Q Business application environment created and deployed before 16 April, 2024, you need to update your web experience service role. For information on service role permissions needed, see [IAM role for an Amazon Q Business web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#deploy-experience-iam-role). For information on how to update your web experience service role, see [Updating a web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#update-web-experience).
**Note**
Displaying sample prompts to your end user using the Amazon Q Business [Quick prompts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quick-prompts.html) feature might not work if you choose to restrict response generation to enterprise data.
When you update your application environment guardrails, you can use **Response settings** to change this behavior in the following ways:
+ **Allow end users to send queries directly to the LLM** – Give end users the option to either generate LLM-only responses or only generate responses from connected data sources. If you choose to activate this option, end users will be able to toggle between generating responses from either the data sources you have connected to your application environment or use only the LLM to generate responses.
If you choose to activate this feature for your end users, they will see the option to turn **All data sources off** or **Respond from approved sources** in their web experience. If you turn this feature off, then this option won't be available—or displayed—to end users in a web experience.
**Note**
As of Oct 31, 2024, once you have created a new Amazon Q Business application environment, this setting will be *enabled by default*, even if the Admin has not yet connected any enterprise data sources.
For existing application environments, this setting will *remain as previously configured*.
+ **Allow Amazon Q Business to fall back to LLM knowledge** – Allow Amazon Q Business to use its LLM knowledge to generate responses when it can’t find responses from your connected data sources. If you choose to activate this mode, and haven't given your end users the option to choose how responses are generated, your application environment will default to producing responses using the LLM when it can't find information in your data sources.
+ **Personalize responses** – Allow Amazon Q Business to customize chat responses to end users using metadata associated with them—specifically address and job related information—in your IAM Identity Center instance.
You must have already added this information in IAM Identity Center for response personalization to work as intended. For more information on how to configure your IAM Identity Center instance for personalization see [Personalizing chat responses](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/personalizing-chat-responses.html).
+ **Enable hallucination mitigation** – Allow Amazon Q Business to check the chat responses it generates for [hallucinations](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/concepts-terms.html#hallucination). If a hallucination is detected with high confidence, Amazon Q Business corrects the inconsistencies in its response real-time during chat and generates a new, edited message.
The hallucination mitigation feature is only available for retrieval augmented generation (RAG) responses from data connected to the application—either through connected data sources, or files uploaded during chat (up to 100,000 characters).
Hallucination mitigation isn't supported for the following use cases:
+ Applications where [chat orchestration](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-global-controls.html#guardrails-global-orchestration) is enabled.
+ [Plugin](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html) workflows.
+ Responses generated from tabular data, or from transcripts of images, audio and video. Hallucination mitigation applies only to responses generated from textual data.
**Important**
Activating hallucination mitigation will increase chat response latency.
Global controls apply to all supported conversation interactions, except when it conflicts with a specific topic-level control. In that case, a topic-level control takes precedence.
## Chat orchestration settings
You can use **Chat orchestration settings** to automatically manage chat requests across configured plugins and data sources in your Amazon Q Business application. If you activate chat orchestration, Amazon Q Business automatically routes chat requests to [plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html), integrating enterprise data and relevant actions within a single chat response. Users get direct responses without manual plugin selection.
**Note**
Chat orchestration is optimized to work for English language content. For more details on language support in Amazon Q Business, see [Supported languages](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-languages.html). Additionally, the [hallucination mitigation](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/hallucination-reduction.html) feature won't work if chat orchestration controls are enabled for your application.
The following are the key features of chat orchestration:
+ **Unified response integration** – Lets Amazon Q Business combine its [retrieval augmented generation (RAG) workflow](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/concepts-terms.html#retrieval-augmented-generation) with plugin actions. This allows Amazon Q Business to provide comprehensive answers in natural language during conversations. For example, Amazon Q Business can explain paid time-off (PTO) policy from company data and create a time-off request at the same time.
+ **Intelligent action detection** – Allows Amazon Q Business to automatically identify read-only chat requests (like checking ticket counts) and write actions (like creating a ticket) and present forms for user validation.
+ **Smart plugin management** – Allows Amazon Q Business to automatically select appropriate plugins without manual user selection while managing multiple complex plugin interactions.
+ **User driven experience** – Enables Amazon Q Business to ask for user clarification when multiple actions are possible, validating actions before taking them, and guiding the user through the information needed to perform an action.
If you deactivate chat orchestration, Amazon Q Business won't relay queries across data sources and plugins. Users must manually select to use plugin mode to invoke a plugin action from chat.
If you're using an [Quick plugin](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quicksight-plugin.html) (fully-integrated with Amazon Q Business and not available for manual selection by users during chat), activating chat orchestration affects its behavior. With chat orchestration enabled, an Quick plugin only activates if:
+ No other plugin actions (read or write requests requiring additional end user input through forms) are detected, or, in progress.
+ No end user authentication requests are pending.
## Feature settings
You can control whether end users can upload files during chat to ask questions based on the uploaded document. By default, your application environment allows your end users to directly upload files in chat.
You can also choose whether to allow end users in a web experience to create and use Amazon Q Apps. Amazon Q Apps relies on LLM knowledge to work.
## Blocked phrases
You can define blocked phrases for your application environment. Amazon Q Business ensures that chat responses don't include these words. You can choose up to 20 words.
Additionally, you can optionally configure a custom message to be displayed to your end users in response to any mention of blocked phrases during chat. You can use this message to inform them that word is blocked and provide them with further guidance on next steps.
By default, your application environment doesn't define any blocked words. You can choose to add these words when you edit and update your global control guardrails.
## Customizing global controls
When you create an Amazon Q Business application environment, it's assigned the following default global controls:
+ An option to generate responses from either enterprise data or LLMs.
+ Response personalization is activated.
+ Automatic orchestration of end user chat requests across any Amazon Q Business plugins and data sources you’ve configured.
+ File upload by end user during chat is activated.
+ Q Apps creation is activated.
+ Hallucination mitigation is deactivated. To turn hallucination mitigation on, you must first deactivate chat orchestration.
To update global topic controls for your web experience chat, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateChatControlsConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateChatControlsConfiguration.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
**Note**
You can't create or delete guardrail global controls. You can only update existing global controls in your application environment.
------
#### [ Console ]
**To update a global control guardrail**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your application environment from the list of applications.
1. From the left navigation menu, choose **Enhancements**, and then choose **Guardrails**.
1. In **Guardrails**, from **Global controls**, choose **Edit**.
1. In **Application guardrails**, do the following:
+ For **Response settings** do the following:
+ **Allow end users to send queries directly to the LLM** – If you choose to activate this option, end users will be able to toggle between generating responses from either the data sources you have connected to your application environment or use only the LLM to generate responses.
**Note**
If you choose to enable this option, your end users will have the option to generate LLM-only responses even if you don't allow Amazon Q to user LLM knowledge to generate responses.
For more information, see [Using global controls in Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-global-controls.html).
+ **Allow Amazon Q Business to fall back to LLM knowledge** – Choose this option if you want to generate responses from your application environment's LLM world knowledge when it can't find information in your connected data sources. The default is to restrict responses to enterprise data. For more information, see [Using global controls in Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-global-controls.html).
+ **Personalize responses** – Allow Amazon Q Business to customize chat responses to end users using metadata associated with them—specifically address and job related information—in your IAM Identity Center instance.
**Note**
You must have already added this information in IAM Identity Center for response personalization to work as intended. For more information on how to configure your IAM Identity Center instance for personalization see [Personalizing chat responses](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/personalizing-chat-responses.html).
+ **Enable hallucination mitigation** – Allow Amazon Q Business to check the chat responses it generates for [hallucinations](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/concepts-terms.html#hallucination). If a hallucination is detected with high confidence, Amazon Q Business corrects the inconsistencies in its response real-time during chat and generates a new, edited message.
**Note**
You must deactivate **Chat orchestration settings** before you can activate hallucination mitigation.
1. For **Chat orchestration settings**, activate to automatically manage chat requests across configured plugins and data sources in your Amazon Q Business application. If you activate chat orchestration, Amazon Q Business automatically routes chat requests to [plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html), integrating enterprise data and relevant actions within a single chat response. Users get direct responses without manual plugin selection.
**Note**
You must deactivate **Enable hallucination mitigation** before you can activate chat orchestration.
1. For **Feature settings**, choose whether your end users will be allowed to upload files directly in chat to ask questions based on file content and whether Amazon Q Apps will be enabled for your application environment.
1.
+ For **Blocked words** – Define blocked words for the application environment. The application environment will not respond to questions that contain these words or mention them in any responses.
+ For **Messaging shown for blocked words** – Choose to create a custom response for your end users informing them of blocked word usage and any next steps to take.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To update a global control guardrail**
```
aws qbusiness update-chat-controls-configuration \
--application-id application-id \
--blocked-phrases-configuration-update '{"blockedPhrasesToCreateOrUpdate":["example phrase 1", "example phrase 2"],"blockedPhrasesToDelete":["example phrase 1", "example phrase 2"],"systemMessageOverride":"user facing message when blocked phrase encountered"}' \
--client-token clientToken \
--response-scope ENTERPRISE_CONTENT_ONLY | EXTENDED_KNOWLEDGE_ENABLED \
--creator-mode-configuration creatorModeControl=ENABLED | DISABLED \
--orchestration-configuration orchestrationControl=ENABLED | DISABLED \
--hallucination-reduction-configuration '{"hallucinationReductionControl": "ENABLED" | "DISABLED"}'
```
------
# Using topic-level controls in Amazon Q Business
You can use topic-level controls to specify special topics within your application environment. You can configure rules to customize how Amazon Q Business should respond when a chat message matches a special topic. To streamline your application environment's response, you provide a name and a short description for how the large language model (LLM) should respond based on the topic-specific guardrail you're building. You can configure up to 2 topic-level controls.
Topic-level controls provide fine-grained customization for your application environment. For example, you can define a global control guardrail that allows your application environment to generate responses using model knowledge. You can also use a content retrieval rule to limit response generation for specific topics to enterprise content.
The following are the topic-level guardrails that you can customize:
**Topics**
+ [LLM prompt control](#guardrails-topic-controls-messages)
+ [Application behavior rules](#guardrails-topic-controls-app-rules)
+ [Creating topic controls](#guardrails-topic-controls-customizing)
## LLM prompt control
You can add up to 5 representative messages that you expect end users to submit about this topic. You can also configure natural language descriptions to define the boundaries of the topic. Amazon Q Business uses these messages to check the responses that it generates for restricted content.
## Application behavior rules
You can configure behavior rules that control how Amazon Q Business responds for each special topic that you specify.
**Note**
You can specify up to 5 rules per special topic.
**Topics**
+ [Answer using enterprise data](#guardrails-topic-controls-rules-data)
+ [Blocking special topics](#guardrails-topic-controls-rules-block)
### Answer using enterprise data
When your application environment encounters a special topic, you can choose to allow it to answer from your enterprise data. If you allow responses from your enterprise data, you can further restrict which data sources in your application environment that your responses are generated from.
You can also choose to specify the specific users or groups within your application environment to apply this rule to, using either an inclusion logic or an exclusion logic. You can’t use both kinds of logic at once. If a user is a member of a group with conflicting rules defined, Amazon Q Business will apply the more restrictive rule to that user.
### Blocking special topics
When your application environment encounters a special topic, you can choose to block responses completely. If you do so, you can configure a custom message to display to your end users in response to any mention of blocked topics during chat. Use this message to inform your end users that the topic is blocked and provide them with further guidance on next steps.
You can also choose to specify the specific groups within your application environment to apply this rule to, using either an inclusion logic or an exclusion logic. You can’t use both kinds of logic at once. If a user is a member of a group with conflicting rules defined, Amazon Q Business will apply the more restrictive rule to that user.
Not specifying an inclusion or exclusion logic will result in the rule being applied to all users.
**Note**
User level rule creation is not currently supported for the following IAM Identity Provider access management methods: SAML and OIDC.
## Creating topic controls
To create an Amazon Q Business topic-level control for your web experience chat, you can use AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateChatControlsConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateChatControlsConfiguration.html) operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To create a topic control**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your application environment from the list of applications.
1. From the left navigation menu, choose **Enhancements**, and then choose **Guardrails**.
1. For **Guardrails**, from **Topic specific controls**, choose **Create topic control**.
1. For **Create topic specific controls**, enter the following information:
+ **Name** – Enter a name for your topic-specific control.
+ **Description** – A natural language description for your topic control configuration. Use this to help the LLM better identify queries associated with the topic control you're configuring.
1. For **Example chat messages**, enter representative phrases that you expect a user to type to invoke this topic. You can add up to 5 messages.
1. (Optional) To configure a rule, choose **Add new rule**.
1. For **Rule 1**, enter the following information:
+ In **Behavior in response to guardrail**, for **Behavior** – Choose how Amazon Q Business will respond to blocked topics: **Answer using enterprise data** or **Block completely**.
+ If you choose **Block completely** – Choose to include a custom message to inform your end user of restricted topics from chat and suggest follow up actions.
+ If you choose **Answer using enterprise data**, **Data source requirements** – Choose data sources that Amazon Q Business will use to generate responses.
1. For **User handling**, specify the users or groups that this topic control rule applies to and any users or groups that are exempt from this rule.
1. Choose **Save**.
------
#### [ AWS CLI ]
**To create a topic control**
```
aws qbusiness update-chat-controls-configuration \
--application-id application-id \
--client-token clientToken \
--topic-configurations-to-create-or-update '[{"name":"name","description":"description","exampleChatMessages":["message1", "message2"],"rules":[{"includedUsersAndGroups":{"userIds":["userId1","userId2"],"userGroups":["userGroup1","userGroup2"]},"ruleType": "CONTENT_BLOCKER_RULE","ruleConfiguration":{"contentBlockerRule":{"systemMessageOverride":"custom_message"}}},{"excludedUsersAndGroups":{"userIds":["id1", "id2"],"userGroups":["group1", "group2"]}, "ruleType": "CONTENT_RETRIEVAL_RULE", "ruleConfiguration":{"contentRetrievalRule":{"eligibleDataSources":[{"indexId":"index-id1","dataSourceId":"data-source-id1"},{"indexId":"index-id2","dataSourceId":"data-source-id2"}]}}}]}]' \
--topic-configurations-to-delete '{"name":"existing-topic-name"}'
```
**Note**
The user IDs you add to configure topic controls must already exist in your Identity Provider (IdP). You are responsible for validating any user groups you add.
------
# Managing Amazon Q Business admin controls and guardrails
To manage Amazon Q Business admin controls and guardrails, you can take the following actions:
**Note**
You can't create or delete guardrail global controls. You can only update existing global controls in your application environment.
**Topics**
+ [Deleting topic controls](#guardrails-update)
+ [Getting topic control properties](#topic-control-properties)
## Deleting topic controls
To delete configured chat controls, you can use AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteChatControlsConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteChatControlsConfiguration.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To delete topic controls**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your application environment from the list of applications.
1. From the left navigation menu, choose **Enhancements**, and then choose **Guardrails**.
1. In **Guardrails**, from **Topic specific controls**, choose the topic control you want to delete, and then choose **Delete**.
1. In the dialog box, type **delete** to confirm your action.
The console displays a successful deletion message when the plugin deletion process is finished.
------
#### [ AWS CLI ]
**To delete a topic specific control**
```
aws qbusiness delete-chat-controls-configuration \
--application-id application-id
```
------
## Getting topic control properties
To get the details of Amazon Q Business topic controls, you can use either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetChatControlsConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetChatControlsConfiguration.html) API operation. The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To get configured details for admin controls and guardrails**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the Amazon Q Business console, in **Applications**, select the name of your application environment from the list of applications.
1. From the left navigation menu, choose **Enhancements**, and then choose **Admin controls and guardrails**.
You will find the details of your configured **Global controls** and **Topic specific controls** on the page.
------
#### [ AWS CLI ]
**To get admin controls and guardrails details**
```
aws qbusiness get-chat-control-configuration \
--application-id application-id
```
------