Construct an AI assistant utilizing Amazon Q Enterprise with Amazon S3 clickable URLs

Organizations want user-friendly methods to construct AI assistants that may reference enterprise paperwork whereas sustaining doc safety. This put up exhibits methods to use Amazon Q Enterprise to create an AI assistant that gives clickable URLs to supply paperwork saved in Amazon Easy Storage Service (Amazon S3), to help safe doc entry and verification. Amazon Q Enterprise is a generative AI-powered conversational assistant that solutions questions and completes duties based mostly on the knowledge in your enterprise programs and enhances workforce productiveness.

On this put up, we reveal methods to construct an AI assistant utilizing Amazon Q Enterprise that responds to person requests based mostly in your enterprise paperwork saved in an S3 bucket, and the way the customers can use the reference URLs within the AI assistant responses to view or obtain the referred paperwork, and confirm the AI responses to observe accountable AI. You possibly can comply with the directions on this put up to construct an AI assistant both utilizing the offered pattern dataset or your individual dataset, and work together with it utilizing the Amazon Q Enterprise net expertise and API.

Answer overview

You possibly can construct a safe AI assistant in your workers the place the AI responses are based mostly on a set of enterprise paperwork. You retailer the paperwork in an S3 bucket and configure the S3 bucket as an information supply, or add the information instantly to your Amazon Q Enterprise software from the Amazon Q Enterprise console. Authenticated customers subscribed to the Amazon Q Enterprise software can work together together with your AI assistant utilizing the Amazon Q Enterprise net expertise from their net browsers or with a customized software constructed by your group. The Amazon Q Enterprise powered AI assistant gives supply attributions to every response with clickable URLs pointing to the paperwork from which the response is generated. The customers can use the URLs to entry the reference paperwork securely, to get extra data and observe accountable AI, with out requiring the credentials to the S3 bucket the place the paperwork are saved, and the Amazon Q Enterprise software validates the authorization of the authenticated person accessing URL earlier than letting the person view or obtain a doc.

The next diagram exhibits the interior workings of Amazon S3 clickable URLs, together with how the doc contents are staged in an S3 bucket throughout ingestion, and the way the workflow of the GetDocumentContent API lets the person securely view or obtain the doc utilizing the URL hyperlinks.

An S3 bucket containing the enterprise paperwork for use by the AI assistant is configured as an information supply for an Amazon Q Enterprise software. When the info supply is synchronized for the primary time, the Amazon Q Enterprise S3 connector crawls the shopper’s bucket and ingests the paperwork, together with their metadata and entry management lists (ACLs). Throughout ingestion, the content material of every doc is saved by Amazon Q Enterprise in a staging S3 bucket within the Amazon Q Enterprise service account. The textual content extracted from the doc, together with the metadata and ACLs, are ingested in an Amazon Q Enterprise index. On subsequent knowledge supply sync operations, paperwork which have modified or are newly added to the shopper’s S3 bucket are reingested, their contents are added or up to date within the staging bucket, and the contents of the paperwork deleted from the shopper’s S3 bucket are deleted from the staging bucket.Once you add the information instantly, the information are processed in the same manner, by storing the doc content material within the staging bucket and ingesting the extracted textual content and metadata within the index.

When an authenticated person asks a query or writes a immediate to the AI assistant utilizing the Amazon Q Enterprise net expertise or a buyer developed software, the UI layer of the appliance invokes the Chat or ChatSync API. The response to the API consists of the supply attributions, supply reference URLs, and passages from the listed doc that had been used as context for the underlying massive language mannequin (LLM) to generate the response to the person’s question. When the person chooses a reference URL pointing to a doc ingested utilizing the Amazon S3 knowledge supply or information uploaded instantly, the UI layer is required to invoke the GetDocumentContent API (labeled 1 within the previous diagram) to acquire the contents of the doc to be displayed or downloaded. Chat, ChatSync, and GetDocumentContent APIs can solely be invoked utilizing identity-aware credentials of the authenticated person.

Upon receiving the GetDocumentContent API, Amazon Q Enterprise makes use of the person identification from the identity-aware credentials, retrieves the ACLs for the doc being requested, and validates that the person is allowed to entry that doc. On profitable validation, it generates a pre-signed URL for the doc content material object saved within the staging bucket, and returns it to the UI in response to the GetDocumentContent API name (labeled 3 within the previous diagram). If the authorization validation fails, an error is returned (labeled 2 within the previous diagram).

The UI layer can then use the pre-signed URL to show the doc content material within the net browser or obtain it to the person’s native laptop. Requiring identity-aware credentials and authorization validation makes certain solely authenticated customers approved to entry the doc can view or obtain the doc content material. The validity of the pre-signed URL is restricted to five minutes. After the pre-signed URL is made out there to the person and the doc content material is downloaded, Amazon Q Enterprise or AWS doesn’t have management of the pre-signed URL, in addition to the doc content material, and following the shared safety duty mannequin, it’s the buyer’s duty to safe the doc additional.

To get a hands-on expertise of Amazon S3 clickable URLs, comply with the directions on this put up to create an AI assistant utilizing an Amazon Q Enterprise software, with an S3 bucket configured as an information supply, and add some information to the info supply. You should use the offered pattern knowledge SampleData.zip or select a couple of paperwork of your selection. You possibly can then use the Amazon Q Enterprise net expertise to ask a couple of questions in regards to the knowledge you ingested, and use the supply reference URLs from the responses to your inquiries to view or obtain the referenced paperwork and validate the responses you bought from the AI assistant. We additionally present methods to use the AWS Command Line Interface (AWS CLI) to make use of the Amazon S3 clickable URLs characteristic with the Amazon Q Enterprise API.

Concerns for utilizing Amazon S3 clickable URLs

Take into account the next when utilizing Amazon S3 clickable URLs:

{
      "Sid": "QBusinessGetDocumentContentPermission",
      "Impact": "Permit",
      "Motion": ["qbusiness:GetDocumentContent"],
      "Useful resource": [
        "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
        "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/*"
      ]
}

Stipulations

To deploy the answer utilizing the directions on this put up in your individual AWS account, just remember to have the next:

Create your S3 bucket and add knowledge

Select an AWS Area the place Amazon Q Enterprise is accessible, conserving in thoughts that you should create all of the AWS assets on this instance on this Area. If you have already got an S3 bucket with a couple of paperwork uploaded, you need to use it for this train. In any other case, for directions to organize an S3 bucket as an information supply, discuss with Making a normal objective bucket. Obtain and unzip SampleData.zip to your native laptop. Open the S3 bucket you created on the Amazon S3 console and add the contents of the ACME Mission Area, HR Information, and IT Assist folders to the S3 bucket.

The next screenshot exhibits the listing of uploaded information.

Create an Amazon Q Enterprise software

Relying in your selection of person entry administration technique, create an IAM Id Heart built-in Amazon Q Enterprise software or an IAM federated Amazon Q Enterprise software. On the time of writing, Amazon S3 clickable URLs are usually not out there for Amazon Q Enterprise purposes with nameless entry.

To create an IAM Id Heart built-in Amazon Q Enterprise software, full the next steps:

1. On the Amazon Q Enterprise console, select Functions within the navigation pane.
2. Select Create software.
3. For Software identify, enter a novel identify or use the mechanically generated identify.
4. For Consumer entry, choose Authenticated entry.
5. For Consequence, choose Internet expertise.

6. For Entry administration technique, choose AWS IAM Id Heart.

If IAM Id Heart is appropriately configured both in your account or within the AWS Group to which your account belongs, and is in the identical Area, you will note a message in regards to the software being linked to the IAM Id Heart occasion.

7. Select the customers who may have entry to this software and their subscription tiers. For this put up, each Q Enterprise Professional and Q Enterprise Lite subscription tiers will work.
8. Select Create.

Create an index

In preparation to configure knowledge sources, you should first create an index. Full the next steps:

1. On the Amazon Q Enterprise console, select Functions within the navigation pane.
2. Open your software.
3. Below Enhancements within the navigation pane, select Information sources.
4. Select Add an index.

5. Choose create a brand new index.
6. For Index identify, preserve the mechanically generated identify.
7. For Index provisioning, choose your most popular provisioning technique. For this put up, both Enterprise or Starter will work.
8. Depart Variety of items as 1.
9. Select Add an index.

The creation course of takes a couple of minutes to finish.

Create knowledge sources

To configure your Amazon S3 knowledge supply, full the next steps. For extra particulars, discuss with Connecting Amazon Q Enterprise to Amazon S3 utilizing the console.

1. On the Amazon Q Enterprise console, select Functions within the navigation pane.
2. Open your software.
3. Below Enhancements within the navigation pane, select Information sources.
4. Select Add knowledge supply.

5. On the Add knowledge supply web page, select Amazon S3 as your knowledge supply.

6. For Information supply identify, enter a reputation.
7. For IAM position, select Create a brand new service position.
8. For Function identify, preserve the mechanically generated identify.

9. Below Sync scope, enter the placement of the S3 bucket you created earlier.

10. For Sync mode, choose Full sync.
11. For Frequency, select Run on demand.
12. Select Add knowledge supply.

13. After the info supply is created, select Sync now to start out the info supply sync.

It takes a couple of minutes for the info supply sync to finish.

The Information sources web page exhibits the standing of the info sources, as proven within the following screenshot.

Now let’s create an information supply with uploaded information.

1. On the Information sources web page, select Add knowledge supply.
2. Select Add information.

3. Below Choose information, select Select information.
4. Open the placement the place you unzipped the pattern knowledge and select the file national_park_services_infograph.pdf.

5. Select Add to add the file to the index.

Work together together with your AI assistant

Now it’s time to check the AI assistant. Within the following sections, we reveal methods to use the Amazon Q Enterprise net expertise and the API to work together together with your AI assistant.

Utilizing Amazon Q Enterprise net expertise

Open the deployed URL of your Amazon Q Enterprise software in an internet browser window to start out the online expertise in your AI assistant and register as one of many subscribed customers.

After the online expertise begins, enter a immediate based mostly on the info you listed. If you’re utilizing the pattern knowledge supplied with the put up, you need to use the immediate “What’s the eligibility standards for workers to obtain well being advantages?” as proven within the following screenshot. Once you view the reference sources beneath the response, you’ll discover a obtain icon subsequent to the file identify, which you need to use to obtain the file to view.

Select the file identify and select Save to avoid wasting the file to your laptop.

Needless to say though Amazon Q Enterprise checks the ACLs to verify that you’re approved to entry the doc earlier than downloading, anybody who has entry to the pc the place you obtain the file will be capable to entry the doc.

Select the obtain standing icon in your browser and select the open icon to open the file.

The doc will open in your reference, as proven within the following screenshot.

Now let’s have a look at the instance of a PDF doc, which on this case is the info supply containing the information you uploaded, in response to the immediate “What number of parks are ruled by the Nationwide Parks Service?” As a result of most net browsers can open the PDF file on a brand new tab, discover the file open icon subsequent to the supply file identify—that is totally different from the file obtain icon within the earlier case of a .docx file. Once you select the file identify, the doc opens in a brand new tab.

The next screenshot exhibits the PDF within the new browser tab.

Utilizing the Amazon Q Enterprise API

On this part, we present methods to use the AWS CLI to expertise how clickable URLs work when utilizing API. To confirm that an end-user is authenticated and receives fine-grained authorization to their person ID and group-based assets, a subset of the Amazon Q Enterprise APIs (Chat, ChatSync, ListConversations, ListMessages, DeleteConversation, PutFeedback, GetDocumentContent) require identity-aware AWS Sig V4 credentials for the authenticated person on whose behalf the API name is being made. You need to use the suitable process to get identity-aware credentials based mostly on whether or not your Amazon Q Enterprise software person entry administration is configured with IAM Id Heart or IAM federation. You possibly can apply these credentials by setting atmosphere variables in your command line the place the AWS CLI is put in; for comfort, you may select AWS CloudShell.

First, use the ChatSync API to make a question to your Amazon Q Enterprise software:

aws qbusiness chat-sync --region  
    --application-id  
    --user-message "what's the eligibility standards to obtain well being advantages?"

This command will get a response much like the next:

{
    "conversationId": "",
    "systemMessage": "Workers are eligible for well being advantages if they've an appointment of greater than six months (at the very least six months plus someday) and a time base of half-time or extra. Eligible workers have 60 calendar days from the date of appointment or a allowing occasion to enroll in a well being plan, or throughout an Open Enrollment interval.",
    "systemMessageId": "",
    "userMessageId": "",
    "sourceAttributions": [
        {
            "title": "Employee+health+benefits+policy.docx",
            "snippet": "nEmployee health benefits policy This document outlines the policy for employee health benefits. Benefit Eligibility Employees are eligible for health benefits if they have an appointment of more than six months (at least six months plus one day) and a time base of half-time or more. Eligible employees have 60 calendar days from the date of appointment or a permitting event to enroll in a health plan, or during an Open Enrollment period. For questions about your eligibility, contact your department's personnel office. Making Changes to Your Current Benefits You may make changes to your benefits during Open Enrollment, usually during September and October of each year, or based on a permitting event outside of Open Enrollment. You may not change your health benefits choice during the year unless you experience a permitting event. You must apply for any changes or enrollments within 60 calendar days of the permitting event date. For questions about permitting events, contact your department's personnel office. Permitting events or qualifying life events There are exceptions to the annual open enrollment period. These are called qualifying life events or permitting events and if you experience one or more of them, you can buy new coverage or change your existing coverage.",
            "url": "https:///DemoData/hr-data/Employee%2Bhealth%2Bbenefits%2Bpolicy.docx",
            "citationNumber": 1,
            "textMessageSegments": [
                {
                    "beginOffset": 167,
                    "endOffset": 324,
                    "snippetExcerpt": {
                        "text": "benefits if they have an appointment of more than six months (at least six months plus one day) and a time base of half-time or more. Eligible employees have 60 calendar days from the date of appointment or a permitting event to enroll in a health plan, or during an Open Enrollment period"
                    }
                }
            ],
            "documentId": "s3:///DemoData/hr-data/Worker+well being+advantages+coverage.docx",
            "indexId": "",
            "datasourceId": ""
        }
    ],
    "failedAttachments": []
} 

Subsequent, use the GetDocumentContent API utilizing the knowledge from the supply attributions within the ChatSync API response to obtain and show the doc to the person:

aws qbusiness get-document-content --region  
    --application-id  
    --document-id  
    --index-id  
    --data-source-id  
    --output-format RAW

When Amazon Q Enterprise receives the GetDocumentContent API name, the ACLs, when current, are verified to verify that the person making the API name is allowed to entry the doc, after which a brief interval pre-signed URL is returned in response to a profitable invocation of the GetDocumentContent API that you need to use to obtain or view the doc:

{
    "presignedUrl": "",
    "mimeType": ""
}

Troubleshooting

This part discusses a couple of errors you may encounter as you employ Amazon S3 clickable URLs for the supply references in your conversations together with your Amazon Q Enterprise powered AI assistant.

Seek advice from Troubleshooting your Amazon S3 connector for details about error codes you may see for the Amazon S3 connector and instructed troubleshooting actions. If you happen to encounter an HTTP standing code 403 (Forbidden) error once you open your Amazon Q Enterprise software, it implies that the person is unable to entry the appliance. To search out the widespread causes and methods to deal with them, discuss with Troubleshooting Amazon Q Enterprise and identification supplier integration.

• Full sync required – Whereas making an attempt to entry referenced URLs from an Amazon S3 or uploaded information knowledge supply, the person will get the next error message: “Error: This doc can’t be downloaded as a result of the uncooked doc obtain characteristic requires a full connector sync carried out after 07/02/2025. Your admin has not but accomplished this full sync. Please contact your admin to request a whole sync of the info supply.” This error could be resolved after performing a full sync of the Amazon S3 knowledge supply, or deleting the information from the uploaded information knowledge supply and importing them once more.
• You possibly can not entry a doc referred within the dialog historical past – Whereas looking by means of dialog historical past, the person chooses a reference URL from an Amazon S3 knowledge supply and might’t view or obtain the file with the next error: “Error: You not have permission to entry this doc. The entry permissions for this doc have been modified because you final accessed it. Please contact your admin in case you consider it is best to have entry to this content material.” This error implies that the permissions for the doc within the ACLs on the S3 bucket configured as the info supply modified, so the person not approved to entry the file, and the ACLs bought up to date within the Amazon Q Enterprise index in an information supply sync. If the person believes that they need to have entry to the doc, they need to contact the administrator to handle the ACLs and carry out an information supply sync.
• The doc you are attempting to entry not exists – Whereas looking by means of dialog historical past, the person chooses a reference URL from an Amazon S3 or uploaded information knowledge supply, and might’t view or obtain the file with the next error: “Error: The doc you’re making an attempt to entry not exists within the knowledge supply. It could have been deleted or moved because it was final referenced. Please examine with the admin in case you want entry to this doc.” This error implies that the doc is deleted from the S3 bucket or moved to a distinct location, and due to this fact additionally bought deleted from the Amazon Q Enterprise index and staging bucket for the precise doc ID throughout an information supply sync. This error may also manifest when a doc from the uploaded information knowledge supply is deleted by the administrator subsequent to the dialog. If the person believes that the doc shouldn’t be deleted, they need to contact the administrator to aim to revive the doc and carry out an information supply sync.
• You possibly can’t obtain this doc as a result of your net expertise lacks the required permissions – When the person chooses a reference URL from an Amazon S3 or uploaded information knowledge supply, they’ll’t view or obtain the file with the next error: “Error: Unable to obtain this doc as a result of your Internet Expertise lacks the required permissions. Your admin must replace the IAM position for the Internet Expertise to incorporate permissions for the GetDocumentContent API. Please contact your admin to request this IAM position replace.” The administrator can try and resolve this error by updating the IAM position for the online expertise with permissions to invoke the GetDocumentContent API, as mentioned within the concerns part earlier on this put up.

Clear up

To keep away from incurring future prices and to wash out unused roles and insurance policies, delete the assets you created: the Amazon Q software, knowledge sources, and corresponding IAM roles. Full the next steps:

1. To delete the Amazon Q software, go to the Amazon Q console and, on the Functions web page, choose your software.
2. On the Actions drop-down menu, select Delete.
3. To substantiate deletion, enter delete within the subject and select Delete. Wait till you get the affirmation message; the method can take as much as quarter-hour.
4. To delete the S3 bucket you created throughout this train, empty the bucket after which delete the bucket.
5. Delete your IAM Id Heart occasion.

Conclusion

On this put up, we confirmed methods to construct an AI assistant with Amazon Q Enterprise based mostly in your enterprise paperwork saved in an S3 bucket or by instantly importing the paperwork to the info supply. Amazon S3 clickable URLs present a user-friendly mechanism for authenticated customers to securely view or obtain the paperwork referenced in responses to customers’ queries, validate accuracy, and observe accountable AI—a vital success issue for an enterprise AI assistant answer.

For extra details about the Amazon Q Enterprise S3 connector, see Uncover insights from Amazon S3 with Amazon Q S3 connector.

Concerning the authors

Abhinav Jawadekar is a Principal Options Architect within the Amazon Q Enterprise service group at AWS. Abhinav works with AWS clients and companions to assist them construct generative AI options on AWS.