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 publish reveals the way 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 primarily based on the knowledge in your enterprise techniques and enhances workforce productiveness.

On this publish, we reveal the way to construct an AI assistant utilizing Amazon Q Enterprise that responds to person 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 apply accountable AI. You may comply with the directions on this publish 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 may construct a safe AI assistant on your staff 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 information on 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 offers 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 apply 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 reveals 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 a knowledge 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.While you add the information instantly, the information are processed in the same approach, 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 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 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 id from the identity-aware credentials, retrieves the ACLs for the doc being requested, and validates that the person 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 net browser or obtain it to the person’s native pc. Requiring identity-aware credentials and authorization validation makes positive solely authenticated customers licensed 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 accessible 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 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 publish to create an AI assistant utilizing an Amazon Q Enterprise software, with an S3 bucket configured as a knowledge 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 alternative. You may then use the Amazon Q Enterprise net expertise to ask a couple of questions concerning 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 the way 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.

Issues for utilizing Amazon S3 clickable URLs

Contemplate 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 publish 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, protecting 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 a knowledge supply, check with Making a common function 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 Area, HR Information, and IT Assist folders to the S3 bucket.

The next screenshot reveals the checklist of uploaded information.

Create an Amazon Q Enterprise software

Relying in your alternative of person entry administration methodology, create an IAM Identification Heart built-in Amazon Q Enterprise software or an IAM federated Amazon Q Enterprise software. On the time of writing, Amazon S3 clickable URLs usually are not accessible for Amazon Q Enterprise purposes with nameless entry.

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

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

6. For Entry administration methodology, choose AWS IAM Identification Heart.

If IAM Identification Heart is accurately 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 concerning the software being linked to the IAM Identification Heart occasion.

7. Select the customers who could have entry to this software and their subscription tiers. For this publish, 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 Purposes within the navigation pane.
2. Open your software.
3. Underneath Enhancements within the navigation pane, select Information sources.
4. Select Add an index.

5. Choose create a brand new index.
6. For Index identify, hold the robotically generated identify.
7. For Index provisioning, choose your most popular provisioning methodology. For this publish, both Enterprise or Starter will work.
8. Depart 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, check 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 software.
3. Underneath 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 function, select Create a brand new service function.
8. For Function identify, hold the robotically generated identify.

9. Underneath Sync scope, enter the situation 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 reveals the standing of the info sources, as proven within the following screenshot.

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

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

3. Underneath Choose information, select Select information.
4. Open the situation 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 the way 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 online browser window to start out the net expertise on your AI assistant and sign up as one of many subscribed customers.

After the net expertise begins, enter a immediate primarily based on the info you listed. If you’re utilizing the pattern knowledge supplied with the publish, you need to use the immediate “What’s the eligibility standards for workers to obtain well being advantages?” as proven within the following screenshot. While 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 pc.

Take into account that though Amazon Q Enterprise checks the ACLs to substantiate that you’re licensed to entry the doc earlier than downloading, anybody who has entry to the pc the place you obtain the file will have the ability 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 on 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. While you select the file identify, the doc opens in a brand new tab.

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

Utilizing the Amazon Q Enterprise API

On this part, we present the way 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 primarily based on whether or not your Amazon Q Enterprise software person entry administration is configured with IAM Identification Heart or IAM federation. You may apply these credentials by setting atmosphere variables in your command line the place the AWS CLI is put in; for comfort, you possibly can select AWS CloudShell.

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

aws qbusiness chat-sync --region <YOUR-AWS-REGION> 
    --application-id <YOUR-AMAZON-Q-BUSINESS-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": "<YOUR-CONVERSATION-ID>",
    "systemMessage": "Staff are eligible for well being advantages if they've an appointment of greater than six months (no less than six months plus sooner or later) and a time base of half-time or extra. Eligible staff 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": "<YOUR-SYSTEM-MESSAGE-ID>",
    "userMessageId": "<YOUR-USER-MESSAGE-ID>",
    "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://<YOUR-S3-BUCKET-NAME>/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://<YOUR-S3-BUCKET-NAME>/DemoData/hr-data/Worker+well being+advantages+coverage.docx",
            "indexId": "<INDEX-ID-OF-YOUR-AMAZON-Q-BUSINESS-APPLICATION>",
            "datasourceId": "<DATA-SOURCE-ID-OF-YOUR-S3-DATA-SOURCE>"
        }
    ],
    "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 <YOUR-AWS-REGION> 
    --application-id <YOUR-AMAZON-Q-BUSINESS-APPLICATION-ID> 
    --document-id <THE-DOCUMENT-ID-FROM-THE-SOURCE-ATTRIBUTIONS> 
    --index-id <INDEX-ID-FROM-THE-SOURCE-ATTRIBUTIONS> 
    --data-source-id <DATA-SOURCE-ID-FROM-THE-SOURCE-ATTRIBUTIONS> 
    --output-format RAW

When Amazon Q Enterprise receives the GetDocumentContent API name, the ACLs, when current, are verified to substantiate that the person 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 need to use to obtain or view the doc:

{
    "presignedUrl": "<PRESIGNED-URL-TO-THE-STAGED-DOCUMENT-CONTENT>",
    "mimeType": "<MIME-TYPE-OF-THE-DOCUMENT>"
}

Troubleshooting

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

Confer with Troubleshooting your Amazon S3 connector for details about error codes you may see for the Amazon S3 connector and prompt 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 applying. To search out the frequent causes and the way to handle them, check with Troubleshooting Amazon Q Enterprise and id 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 may now not entry a doc referred within the dialog historical past – Whereas searching via dialog historical past, the person chooses a reference URL from an Amazon S3 knowledge supply and may’t view or obtain the file with the next error: “Error: You now 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 you need 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 now not licensed to entry the file, and the ACLs bought up to date within the Amazon Q Enterprise index in a knowledge 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 a knowledge supply sync.
• The doc you are attempting to entry now not exists – Whereas searching via dialog historical past, the person chooses a reference URL from an Amazon S3 or uploaded information knowledge supply, and may’t view or obtain the file with the next error: “Error: The doc you’re making an attempt to entry now 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 distinct location, and subsequently additionally bought deleted from the Amazon Q Enterprise index and staging bucket for the precise doc ID throughout a knowledge supply sync. This error may even 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 try to revive the doc and carry out a knowledge supply sync.
• You may’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 will’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 function for the Internet Expertise to incorporate permissions for the GetDocumentContent API. Please contact your admin to request this IAM function replace.” The administrator can try and resolve this error by updating the IAM function for the net expertise with permissions to invoke the GetDocumentContent API, as mentioned within the concerns part earlier on this publish.

Clear up

To keep away from incurring future costs and to scrub 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 Purposes web page, choose your software.
2. On the Actions drop-down menu, select Delete.
3. To verify 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 Identification Heart occasion.

Conclusion

On this publish, we confirmed the way to construct an AI assistant with Amazon Q Enterprise primarily based 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 apply accountable AI—a crucial 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.

In regards to the authors

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