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 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 primarily based on the data in your enterprise programs and enhances workforce productiveness.

On this put up, we display construct an AI assistant utilizing Amazon Q Enterprise that responds to consumer requests primarily based 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 follow accountable AI. You possibly can comply with the directions on this put up to construct an AI assistant both utilizing the supplied pattern dataset or your individual dataset, and work together with it utilizing the Amazon Q Enterprise internet expertise and API.

Answer overview

You possibly can construct a safe AI assistant in your workers the place the AI responses are primarily based on a set of enterprise paperwork. You retailer the paperwork in an S3 bucket and configure the S3 bucket as a knowledge supply, or add the recordsdata straight to your Amazon Q Enterprise utility from the Amazon Q Enterprise console. Authenticated customers subscribed to the Amazon Q Enterprise utility can work together together with your AI assistant utilizing the Amazon Q Enterprise internet expertise from their internet browsers or with a customized utility constructed by your group. The Amazon Q Enterprise powered AI assistant supplies 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 info and follow accountable AI, with out requiring the credentials to the S3 bucket the place the paperwork are saved, and the Amazon Q Enterprise utility validates the authorization of the authenticated consumer accessing URL earlier than letting the consumer 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 consumer 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 a knowledge supply for an Amazon Q Enterprise utility. 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.If you add the recordsdata straight, the recordsdata 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 consumer asks a query or writes a immediate to the AI assistant utilizing the Amazon Q Enterprise internet expertise or a buyer developed utility, the UI layer of the applying invokes the Chat or ChatSync API. The response to the API contains 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 consumer’s question. When the consumer chooses a reference URL pointing to a doc ingested utilizing the Amazon S3 knowledge supply or recordsdata uploaded straight, 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 consumer.

Upon receiving the GetDocumentContent API, Amazon Q Enterprise makes use of the consumer identification from the identity-aware credentials, retrieves the ACLs for the doc being requested, and validates that the consumer is permitted 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 internet browser or obtain it to the consumer’s native pc. 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 obtainable to the consumer 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 accountability mannequin, it’s the buyer’s accountability 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 utility, with an S3 bucket configured as a knowledge supply, and add some recordsdata to the info supply. You should utilize the supplied pattern knowledge SampleData.zip or select a number of paperwork of your alternative. You possibly can then use the Amazon Q Enterprise internet expertise to ask a number 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 use the AWS Command Line Interface (AWS CLI) to make use of the Amazon S3 clickable URLs function with the Amazon Q Enterprise API.

Concerns for utilizing Amazon S3 clickable URLs

Think about the next when utilizing Amazon S3 clickable URLs:

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

Conditions

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 offered, retaining in thoughts that you could create all of the AWS sources on this instance on this Area. If you have already got an S3 bucket with a number of paperwork uploaded, you should use it for this train. In any other case, for directions to organize an S3 bucket as a knowledge supply, consult with Making a normal objective bucket. Obtain and unzip SampleData.zip to your native pc. Open the S3 bucket you created on the Amazon S3 console and add the contents of the ACME Venture House, HR Knowledge, and IT Assist folders to the S3 bucket.

The next screenshot exhibits the listing of uploaded recordsdata.

Create an Amazon Q Enterprise utility

Relying in your alternative of consumer entry administration methodology, create an IAM Id Middle built-in Amazon Q Enterprise utility or an IAM federated Amazon Q Enterprise utility. On the time of writing, Amazon S3 clickable URLs should not obtainable for Amazon Q Enterprise functions with nameless entry.

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

1. On the Amazon Q Enterprise console, select Purposes within the navigation pane.
2. Select Create utility.
3. For Utility identify, enter a singular identify or use the routinely generated identify.
4. For Person entry, choose Authenticated entry.
5. For Consequence, choose Net expertise.

6. For Entry administration methodology, choose AWS IAM Id Middle.

If IAM Id Middle 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 notice a message in regards to the utility being related to the IAM Id Middle occasion.

7. Select the customers who can have entry to this utility 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 could first create an index. Full the next steps:

1. On the Amazon Q Enterprise console, select Purposes within the navigation pane.
2. Open your utility.
3. Beneath Enhancements within the navigation pane, select Knowledge sources.
4. Select Add an index.

5. Choose create a brand new index.
6. For Index identify, preserve the routinely generated identify.
7. For Index provisioning, choose your most well-liked provisioning methodology. For this put up, both Enterprise or Starter will work.
8. Go away Variety of models 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, consult with Connecting Amazon Q Enterprise to Amazon S3 utilizing the console.

1. On the Amazon Q Enterprise console, select Purposes within the navigation pane.
2. Open your utility.
3. Beneath Enhancements within the navigation pane, select Knowledge sources.
4. Select Add knowledge supply.

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

6. For Knowledge supply identify, enter a reputation.
7. For IAM position, select Create a brand new service position.
8. For Position identify, preserve the routinely generated identify.

9. Beneath 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 begin the info supply sync.

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

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

Now let’s create a knowledge supply with uploaded recordsdata.

1. On the Knowledge sources web page, select Add knowledge supply.
2. Select Add recordsdata.

3. Beneath Choose recordsdata, select Select recordsdata.
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 display use the Amazon Q Enterprise internet expertise and the API to work together together with your AI assistant.

Utilizing Amazon Q Enterprise internet expertise

Open the deployed URL of your Amazon Q Enterprise utility in an internet browser window to begin the online expertise in your AI assistant and sign up as one of many subscribed customers.

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

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

Needless to say though Amazon Q Enterprise checks the ACLs to substantiate 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 of 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 take a look at the instance of a PDF doc, which on this case is the info supply containing the recordsdata you uploaded, in response to the immediate “What number of parks are ruled by the Nationwide Parks Service?” As a result of most internet browsers can open the PDF file on a brand new tab, discover the file open icon subsequent to the supply file identify—that is completely different from the file obtain icon within the earlier case of a .docx file. If 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 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 consumer ID and group-based sources, 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 consumer on whose behalf the API name is being made. You could use the suitable process to get identity-aware credentials primarily based on whether or not your Amazon Q Enterprise utility consumer entry administration is configured with IAM Id Middle or IAM federation. You possibly can apply these credentials by setting surroundings variables in your command line the place the AWS CLI is put in; for comfort, you’ll be able to select AWS CloudShell.

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

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 (not less than six months plus at some point) 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 data from the supply attributions within the ChatSync API response to obtain and show the doc to the consumer:

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 substantiate that the consumer making the API name is permitted 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 should use to obtain or view the doc:

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

Troubleshooting

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

Discuss with Troubleshooting your Amazon S3 connector for details about error codes you would possibly see for the Amazon S3 connector and prompt troubleshooting actions. Should you encounter an HTTP standing code 403 (Forbidden) error while you open your Amazon Q Enterprise utility, it signifies that the consumer is unable to entry the applying. To search out the widespread causes and tackle them, consult with Troubleshooting Amazon Q Enterprise and identification supplier integration.

• Full sync required – Whereas trying to entry referenced URLs from an Amazon S3 or uploaded recordsdata knowledge supply, the consumer will get the next error message: “Error: This doc can’t be downloaded as a result of the uncooked doc obtain function 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 may be resolved after performing a full sync of the Amazon S3 knowledge supply, or deleting the recordsdata from the uploaded recordsdata knowledge supply and importing them once more.
• You possibly can not entry a doc referred within the dialog historical past – Whereas searching by dialog historical past, the consumer 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 if you happen to consider it’s 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 consumer not approved to entry the file, and the ACLs received up to date within the Amazon Q Enterprise index in a knowledge supply sync. If the consumer believes that they need to have entry to the doc, they have to contact the administrator to deal with the ACLs and carry out a knowledge supply sync.
• The doc you are attempting to entry not exists – Whereas searching by dialog historical past, the consumer chooses a reference URL from an Amazon S3 or uploaded recordsdata knowledge supply, and might’t view or obtain the file with the next error: “Error: The doc you’re attempting to entry not exists within the knowledge supply. It might have been deleted or moved because it was final referenced. Please examine with the admin if you happen to want entry to this doc.” This error implies that the doc is deleted from the S3 bucket or moved to a special location, and due to this fact additionally received deleted from the Amazon Q Enterprise index and staging bucket for the particular doc ID throughout a knowledge supply sync. This error can even manifest when a doc from the uploaded recordsdata knowledge supply is deleted by the administrator subsequent to the dialog. If the consumer believes that the doc shouldn’t be deleted, they need to contact the administrator to try to revive the doc and carry out a knowledge supply sync.
• You possibly can’t obtain this doc as a result of your internet expertise lacks the required permissions – When the consumer chooses a reference URL from an Amazon S3 or uploaded recordsdata 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 Net Expertise lacks the required permissions. Your admin must replace the IAM position for the Net 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 issues part earlier on this put up.

Clear up

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

1. To delete the Amazon Q utility, go to the Amazon Q console and, on the Purposes web page, choose your utility.
2. On the Actions drop-down menu, select Delete.
3. To substantiate deletion, enter delete within the discipline 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 Middle occasion.

Conclusion

On this put up, we confirmed construct an AI assistant with Amazon Q Enterprise primarily based in your enterprise paperwork saved in an S3 bucket or by straight 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 follow accountable AI—a vital success issue for an enterprise AI assistant resolution.

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 crew at AWS. Abhinav works with AWS clients and companions to assist them construct generative AI options on AWS.