Build a Conversational Generative AI Assistant Using Amazon Q Business – A Step-by-Step Guide

Let’s empower your corporate team with a secure, permission-based conversational AI assistant created by Amazon Q Business.

This is a step-by-step guidance on how to create a conversational generative AI application for employees, powered by your own enterprise content. With Amazon Q Business application, you can ingest proprietary data through secure connectors and define access policies so the application only responds with information users are allowed to see – and confirm the response uses only content the user has permission to access.

This article also explores the generative AI models utilized by Amazon Q Business to power conversational experiences and generate tailored outputs, such as email responses, based on enterprise data.

At the end, there will be a bonus content on how to develop a Plugin for employee to ask tailored question and submit request to corporate system.

Amazon Q Business is a generative AI–powered assistant that can answer questions, provide summaries, generate content, and securely complete tasks based on data and information in your enterprise systems. It empowers employees to be more creative, data-driven, efficient, prepared, and productive. [1]

As enterprises grapple with fast technological change, the enterprise contents have been spiking to a new high level. As an employee, we may frequently interact with enterprise HR policies documents, retrieve payroll information, look for IT helpdesk contact, etc..

With an in-house generative AI assistant, you can quickly find accurate answers from your enterprise content, backed up with citations and references. You can brainstorm new ideas, generate content, or create summaries using Amazon Q Business based on your enterprise data.

Amazon Q Business ensures that users access enterprise content securely according to their permissions. You can quickly deploy Amazon Q Business with built-in connectors to popular enterprise repositories.

1. Control Flow Overview:

From the user making a request to receiving a response, Amazon Q Business acts as a powerful engine that processes queries, enforces access policies, and delivers accurate information securely from your enterprise data.

In this process:

1. User Query: The user initiates a request by entering a natural language query, such as “How to make a claim for flood damage?”
2. Semantic Retrieval: Amazon Q Business performs semantic search across all ingested content repositories to locate information most relevant to the query. It ensures access control by filtering results based on the user’s permissions, retrieving only authorized documents and data.
3. Query Contextualization and Prompt Construction: Amazon Q Business takes the user’s query along with the retrieved content and constructs a prompt to pass to the underlying large language model (LLM). The prompt is carefully designed to maintain relevance and provide sufficient context to the LLM, for instance, “Using the latest sales report, summarize key financial outcomes relevant to last quarter.”
4. LLM Processing and Response Generation: The LLM leverages both the prompt and the contextual data provided to generate a detailed yet succinct response.
5. Response Delivery: The system then sends this synthesized response back to the user, ensuring it is accessible in a user-friendly format, such as a concise text summary or a highlighted passage within the original document.

2. AWS tools and resources

The following AWS tools and resources will be used to configure an Amazon Q Business application that acts as the generative AI assistant for your company data:

Amazon Q Business Application Configuration:

• Use Amazon Q Business’s native retriever to upload documents and integrate external data sources.
• Connect a web crawler data source via Amazon Q Business’s built-in connector to automatically ingest content from approved web sources.

Amazon S3 Bucket Setup and Data Ingestion:

• Create an Amazon S3 bucket to store company contents and data.
• Configure an Access Control List (ACL) on the S3 bucket to enforce fine-grained permissions for data access.
• Use Amazon Q Business’s connector to ingest data from the S3 bucket, ensuring only authorized content is accessible based on the ACL settings.

User Authentication with AWS IAM Identity Center (IDC):

• Deploy the Amazon Q application’s web experience and set up AWS IAM Identity Center (IDC) as the Identity Provider (IdP).
• Configure user and group information in IDC, allowing Amazon Q Business to recognize each user’s access permissions and group memberships.

Secure Query Response Generation:

• Users access the Amazon Q web experience and submit natural language queries.
• Amazon Q Business retrieves relevant content, filtering responses based on the permissions defined by the S3 ACL and user/group data from IDC.
• Responses are generated based only on the content the logged-in user has permissions to access, ensuring data security and compliance with access policies.

3. Steps to configure and deploy an Amazon Q Business application

With Amazon Q Business, we’ll set up an Application, configure a Retriever, and deploy a Web Experience using AWS IAM Identity Center. Once deployed, you can share the web experience URL with users so they can securely access the application. Here’s how to get started:

• Create the Application.

AWS Management Console for Amazon Q Business has a full step-by-step guide for creating applications.

• Deploy the Web Experience.

Create a secure URL to share the application using AWS IAM Identity Center .

• Configure the Retriever:

Choose an appropriate retriever (e.g., a native retriever or an external retriever) based on your application's requirements. Configure it to optimize the retrieval process by selecting the indexing strategy, setting access policies, and ensuring the retriever aligns with your enterprise content structure.

• Set Up Data Sources:

Add company documents by uploading them directly, setting up a data source with sample documents, or connecting Amazon Q Business to the existing data sources using native connectors.

• Try the Web Experience:

Access the secure URL to test the web experience as an end user. Submit a variety of queries to ensure the application retrieves accurate and permission-filtered responses, validating that the data ingestion and access policies are correctly implemented.

4. Step-by-Step Configuration Guidance

4.1 Infrastructure setup

As our focus is going to be Amazon Q application, for the convenience, the infrastructure i.e. the S3 bucket containing the sample data to be used as the data source, and AWS IAM Identity Center (IDC) with sample users and groups were already created in advance.

4.2 Configure Amazon Q Business

In AWS Management Console, you may follow the steps with detailed instructions.

4.2.1 Create Application

• Create the application with the name “Generative-AI-Assistant”.
• Select Create and use a new service-linked role (SLR).
• Click Create.

A Service-Linked Role (SLR) is a special type of IAM role directly associated with an AWS service—in this case, Amazon Q Business. 

When you create a new SLR, it simplifies permission management by linking the role specifically to Amazon Q Business, allowing the service to access resources securely and as needed for your application to function properly.

Amazon Q Business will use this role to access and manage resources like document storage, retrieval processes, and data source connections, without requiring manual setup for each task.

4.2.2 Select Retriever

• Select Use native retriever, leave the other selections as they are and click Next.

The native retriever is Amazon Q Business’s built-in tool for searching and retrieving relevant information from your ingested documents and data sources. 
This option is ideal for users who don’t require advanced search features or external indexing (like Amazon Kendra). The native retriever is simple to configure and is designed to handle typical search and retrieval needs within Amazon Q Business.

4.2.3 Connect Data Source

• On the Connect data sources screen, scroll to the bottom of the screen and click Next.

4.2.4 Add groups and users

• For Web experience service access select Use an existing service role.
• Click the pull down menu Service role name and then search for the pre-configured role.

• Next click on Add Groups and users, select Assign existing users and groups, click Next and click Get Started.

• In the Assign users and groups window use the search box to find users and groups by name.

• After finishing all steps, click Create, and ensure the application is successfully created.

4.3 Configure data sources

4.3.1 Upload files connector

• In the Add data source page, upload all relevant corporate documents. We will be using a couple of corporate insurances policies html files.

Start conversation

• Now we can start the conversation in Amazon Q Business, by asking questions, such as “How to make a claim on flood damage?”

• We may further ask Amazon Q Business to generate an email using the results from previous conversation.

Amazon Q Business leverages generative AI models, such as those based on Amazon Bedrock or proprietary large language models (LLMs) provided by AWS, to generate emails from the results of a previous conversation.

Here's how it works:

Understanding the Context:

The generative AI model processes the previous conversation's context, extracting relevant details such as the user's queries, retrieved responses, and any instructions provided.

Template and Formatting:

Amazon Q Business can apply pre-defined email templates or formatting rules specified by the organization. The system ensures the generated email adheres to the tone, style, and branding requirements.

Generating the Email:

Using a foundation model such as GPT (via Amazon Bedrock) or other proprietary LLMs, the system creates a draft email. These models are fine-tuned for enterprise-specific tasks, ensuring the content is accurate and concise.

Incorporating Permissions:

The model respects access policies and includes only information the user is authorized to see, ensuring secure and compliant email generation.

Review and Delivery:

The generated email can either be sent directly to recipients or reviewed by a human for final approval before delivery.

This process ensures the generated email is contextually accurate, secure, and aligned with the enterprise’s communication standards.

4.3.2 Web crawler connector

In addition to existing corporate data, we can add Web contents as our data source to enrich the existing content.

• Select Source URLs and provide Source URLs

For the purpose of testing, in the scope section, we will reduce the scope to index fewer number of documents to complete the ingestion quickly.
Setting the Crawl depth to 0 means that only the initial page or entry point of each document will be indexed. Amazon Q Business won’t follow any internal links within the document, reducing the amount of content to ingest and further speeding up the process.
With Maximum links per page set to 1, Amazon Q Business will only index a single link from each page, minimizing the amount of content being retrieved. This setting helps to limit the scope of the sync to just a few essential links, which is useful for a quick test ingestion.
In actual deployment, you may select appropriate numbers for maximum links and throttling.

• For Sync run schedule set the Frequency to Run on demand from the pull down menu.

• Once it’s been deployed successfully, you should see the ‘Active’ status from the Console.

Start conversation

Now try to ask some questions relevant to the contents of the website:

“What are some fun and unusual things to do in Yosemite?”

Key Benefits of Using a Web Crawler in Amazon Q Business:

• Broader Information Base: By crawling selected web sources, Amazon Q Business can pull in valuable external information to answer questions more comprehensively.
• Up-to-Date Content: The web crawler can be configured to re-scan sources regularly, keeping the content fresh and current for more accurate responses.
• Automated Retrieval: The web crawler continuously gathers information without requiring manual input, providing a reliable and scalable way to expand the knowledge base Amazon Q Business draws from.

4.3.3 Amazon S3 connector

In this example, we ensure that an authenticated user interacts with the Amazon Q Business application, receiving responses generated exclusively from documents the user is authorized to access.

• Go to the S3 bucket with pre-setup buckets and documents. Each folder contain documents that are only accessible to certain groups of employees.

• Copy the json url link of the whitepapers_acl, we will need it in a later step.

• Name the data source ‘S3-Generative-AI-Assistant’ and select relevant IAM role.

• In Sync scope, in the field Enter the data source location, enter the name of S3 data source and bucket name
• In Access control list configuration file location - optional, paste the S3 URI of whitepapers_acl.json you copied in the previous step.

• For Sync mode leave the default setting of Full sync, and for Sync run schedule select the Frequency as Run on demand from the pull down menu.

Configuring the synchronization settings when connecting Amazon Q Business to an Amazon S3 bucket using Access Control Lists (ACLs) for managing permissions.

• Sync Mode - Full Sync:

In "Full Sync" mode, the system fetches and synchronizes the entire set of data from the specified S3 bucket. This ensures all the documents in the bucket are available for retrieval and processing. Leaving this as the default ensures that no data is missed during synchronization.

• Sync Run Schedule - Run on Demand:

Choosing "Run on Demand" means the synchronization will only occur manually when triggered by the user. This setting is useful for cases where updates to the data source are infrequent or where the admin wants more control over when the sync process occurs, instead of scheduling it at regular intervals.

We have pre-determined the following employee access with their roles:

• pat_candella - SA (group of solutions architects)
• mateo_jackson - DB_SME_SA (group of database subject matter expert solutions architects)
• john_doe - ML_SME_SA (group of machine learning subject matter expert solutions architects)
• mary_major - (does not belong to any of these groups)
• martha_rivera - Admins (group of administrators)

Start conversation

Now login as Mary_major (Note that all of these will need to be accessible by the user mary_major who is not a member of any group)

Ask a question:

“How to develop a well architected serverless application on AWS?”

The answer is sourced from the documents microservices-on-aws.pdf, aws-overview.pdf, and overview-aws-cloud-adoption-framework.pdf.

In the sample data, microservices-on-aws.pdf is located in the Best_Practices folder, while aws-overview.pdf and overview-aws-cloud-adoption-framework.pdf are in the General folder.

It is important to note that neither the Best_Practices nor the General folder has any ACLs defined in the ACL file configured for the data source. As a result, these folders are accessible to anyone, including the user mary_major.

In another attempt, login as pat_candella, and ask the same question.

Note that pat_candella is a member of the SA group, and in the ACL file, the Well_Architected folder is configured with an ACL allowing access to the SA group.

5. Bonus Content: Amazon Q Business Plugin

Discover how to build a plugin that interprets user requests, populates dialogue windows, and completes tasks seamlessly within Amazon Q Business.

• Identify the plugin URL by navigating to the plugin settings in Amazon Q Business, where you can configure the endpoint URL that the plugin will use to process user requests and interact with the application.

• Create a new custom Plugin

• The plugin will be an interactive tool to understand your leave balances, and for use to apply leaves.

• Provide API Schema in YAML (with example code)

openapi: 3.0.0
info:
  title: Employee Management API
  description: API for managing employee leave balances using DynamoDB
  version: 1.0.0
servers:
  - url: https://61xuduba0d.execute-api.us-west-2.amazonaws.com/Prod
paths:
  /leaves:
    get:
      summary: Retrieve leave balance
      description: Retrieve the leave balance for the employee with a constant employee ID.
      operationId: getLeaveBalance
      responses:
        "200":
          description: A JSON object containing the employee's leave balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Balance:
                    type: string
                    description: The leave balance of the employee.
                example:
                  Balance: "10"
        "404":
          description: Employee not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    description: Error message indicating employee not found.
                example:
                  Error: Employee not found
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    description: Detailed error message.
                example:
                  Error: Internal server error
  /apply-leave:
    post:
      summary: Apply for leave
      description: Submit a leave request for the employee with a constant employee ID.
      operationId: applyForLeave
      requestBody:
        description: Details of the leave request.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from_date:
                  type: string
                  format: date
                  description: The start date of the leave.
                to_date:
                  type: string
                  format: date
                  description: The end date of the leave.
                time_off_type:
                  type: string
                  description: The type of time off.
                  enum:
                    - sick
                    - vacation
              required:
                - from_date
                - to_date
                - time_off_type
              example:
                from_date: "2024-07-01"
                to_date: "2024-07-10"
                time_off_type: "vacation"
      responses:
        '200':
          description: A JSON object indicating success and the updated leave balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    type: string
                    description: Success message with the leave approval details.
                  new_balance:
                    type: number
                    description: The new leave balance after the leave is applied.
                example:
                  Message: "Success! Your leave from 2024-07-01 to 2024-07-10 is auto-approved. Your new balance is 5."
        '400':
          description: Bad request due to insufficient leave balance or invalid input.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    description: Error message indicating the reason for failure.
              examples:
                InsufficientBalance:
                  value:
                    Error: "Insufficient leave balance"
                InvalidInput:
                  value:
                    Error: "Invalid input data"
        '404':
          description: Employee not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    description: Error message indicating employee not found.
                example:
                  Error: "Employee not found"
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    description: Detailed error message.
                example:
                  Error: "Internal server error"
components:
  schemas:
    LeaveRequest:
      type: object
      properties:
        from_date:
          type: string
          format: date
          description: The start date of the leave.
        to_date:
          type: string
          format: date
          description: The end date of the leave.
        time_off_type:
          type: string
          description: The type of time off.
          enum:
            - sick
            - vacation
      required:
        - from_date
        - to_date
        - time_off_type
      example:
        from_date: "2024-07-01"
        to_date: "2024-07-10"
        time_off_type: "vacation"

YAML Code Explanation:

API Metadata

• openapi: Specifies the version of OpenAPI used (3.0.0).
• info: Contains basic information about the API, such as:
  • title: "Employee Management API"
  • description: Describes that this API is for managing employee leave balances with DynamoDB.
  • version: The version of the API (1.0.0).

Server Information

• servers: Specifies the base URL for the API endpoints:
  • The API is hosted at https://61xuduba0d.execute-api.us-west-2.amazonaws.com/Prod.

API Endpoints

The API has two primary endpoints:

/leaves (GET)

• summary: Retrieves the leave balance of an employee.
• operationId: getLeaveBalance
• responses:
  • 200: Returns the employee's leave balance in JSON format. Example: {"Balance": "10"}.
  • 404: If the employee is not found, returns a message like {"Error": "Employee not found"}.
  • 500: For internal server errors, returns a detailed error message.

/apply-leave (POST)

• summary: Allows an employee to submit a leave request.
• operationId: applyForLeave
• requestBody: The body of the request contains details about the leave, including:
  • from_date: Start date of the leave.
  • to_date: End date of the leave.
  • time_off_type: Type of leave (either sick or vacation).
  • These fields are required.
• responses:
  • 200: Success message, and the new leave balance is returned.
    • Example: {"Message": "Success! Your leave from 2024-07-01 to 2024-07-10 is auto-approved. Your new balance is 5.", "new_balance": 5}.
  • 400: Bad request (e.g., insufficient leave balance or invalid input). Example errors include "Insufficient leave balance" or "Invalid input data".
  • 404: If the employee is not found, returns an error like {"Error": "Employee not found"}.
  • 500: For internal errors, returns a general error message.

Components

• schemas: Defines the LeaveRequest schema, which is used in the /apply-leave endpoint:
  • from_date: A string in date format specifying the start date of the leave.
  • to_date: A string in date format specifying the end date of the leave.
  • time_off_type: A string that can either be sick or vacation.

Summary

This OpenAPI specification defines two operations:

1. GET /leaves: Retrieves an employee's leave balance.
2. POST /apply-leave: Submits a leave request and updates the leave balance.

The responses and request formats are structured in JSON, and various success and error responses are defined for each endpoint.

Start conversation

Click the three dots besides the chatbox, and select the EmployeeTimeOff Plugin.

Ask the question “How many leaves do I have?”. Note that the Plugin is included in the chatbox.

Confirm the answer provided by Amazon Q Business Plugin.

Now simply input your request in natural language. Amazon Q Business will populate the form with the detailed filled in.

Click Submit, and the request will be submitted to the corporate system.

6. Conclusion

In this walkthrough, we have:

1. Create Amazon Q Business applications.
2. Ingest documents by uploading files, using web crawler data source connector and Amazon S3 data source connector.
3. Use Amazon Q Business application as a generative AI assistant using web experience.
4. Deploy the Amazon Q Business application web experience using AWS IAM Identity Center as identity provider.
5. Use the deployed Amazon Q Business application web experience as a generative AI assistant logged in as different users to experience how the responses are generated securely, based only on the content the logged in user has permissions to access.
6. Created a plugin using APIs to extend the functionality of the application, allowing seamless interaction with external services and systems for enhanced performance.

Reference and further readings:

[1] Amazon Q Business. https://aws.amazon.com/q/business/

[2] Amazon Q Business, now generally available, helps boost workforce productivity with generative AI. https://aws.amazon.com/blogs/aws/amazon-q-business-now-generally-available-helps-boost-workforce-productivity-with-generative-ai