> ## Documentation Index > Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt > Use this file to discover all available pages before exploring further. # Conversational Q&A agent > Set up an Agent Studio chat agent that answers natural-language questions about a product, grounded in its documentation. > **Key questions to get you started** > > Powered by Lucidworks Agent Studio The **Conversational Q\&A** agent is an AI-powered chat agent that lives on your product detail pages. Customers ask natural-language questions about a product, and the agent responds with accurate, real-time answers grounded in that product's own documentation, such as datasheets, manuals, specifications, and other supporting PDF technical content. The agent answers follow-up questions in the same session. ## Use cases **B2B** If you are a B2B organization that provides computer components for enterprise organizations, your customers may ask questions about the specifications and compatibility documents for your products prior to purchase. The Conversational Q\&A agent can interpret user questions, analyze the documentation, and quickly provide accurate, factually-based answers. Any follow-up questions are answered based on the information on your site. This saves your customers time-consuming and difficult research to obtain the information they need to help make a purchasing decision. This agent enhances customer satisfaction, increases the potential for conversions, and improves the long-term relationship between your customers and your organization. **B2C** The Conversational Q\&A agent is most effective for B2C organizations that offer products with complex documentation such as technical specifications and requirements. For example, a customer asks about the installation and warranty for an uninterruptible power supply for their office computer. The agent interprets the user's questions and returns relevant, concise information derived from the documents on your site. As the customer enters additional questions, the agent responds with answers to those inquiries. This enhances the potential for sales, and minimizes customer support calls or product returns. **Knowledge management** The Conversational Q\&A agent excels at knowledge management use cases, helping employees and stakeholders quickly surface institutional knowledge from internal documentation, policies, and procedures. For example, an HR team member asks about the company's parental leave policy and accrual rules. Instead of searching through multiple documents, the agent interprets the question and returns a clear, accurate summary drawn from official HR documentation. As the employee asks follow-up questions such as eligibility criteria or how to submit a request, the agent continues the conversation with contextually relevant answers. This reduces time spent searching for information and keeps teams aligned on internal processes. ## Set up the agent This section details how to create, configure, and test the Conversational Q\&A agent. > **Prepare your data** > > Agent Studio reads your data from a Google Cloud Storage (GCS) bucket outside of Lucidworks Platform. > You enter the bucket details when you create the agent. > If your organization doesn't have a GCS bucket to use as a datasource, see [Create a GCS bucket](https://cloud.google.com/storage/docs/creating-buckets). > > Your data must be in JSONL *and* PDF format. > > In a JSONL file, each line is a complete JSON expression representing a single document, as in the example below: > > ```json wrap theme={"dark"} > {"name": "Puffy Winter Jacket", "product_id": "7a45q835", "description": "This classic down-filled jacket provides maximum insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > {"name": "Extra Puffy Winter Jacket", "product_id": "9b82c222", "description": "This classic down-filled jacket provides even more insulation combined with lightweight comfort.", "documents": ["https://storage.googleapis.com/my-storage/puffy-winter-jacket.pdf"]} > ``` > > * All fields are required. > * Each `product_id` must be unique. > * JSONL lines are not separated by commas. > * Enter multiple PDF files as an array of strings. > * If a document doesn't have an associated PDF file, a blank PDF file is accepted. > **Create the agent** > > 1. From the **Agent Studio** screen, select **Agents** and click **+ Create New**. > > ![Create a custom agent](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-qna-name-select-agent.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=eebd5386b880170223fa66a5106d58c7) > > 2. Enter a descriptive **Name** for the agent, select **Conversational Q\&A**, and then click **Next**. > > ![Select an industry domain and model](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-conv-qna-select-domain-model.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=fa48cf2f1cda5824b3b854affdc8769c) > > 3. From the **Industry Domain** list, select the industry that best matches your business. > > 4. In the **Tasks** field, select the AI model to execute for the agent. > The recommended model for your industry is selected by default, but you can select a different model. > Click **Next**. > > 5. On the **Select a data connector** screen, click **GCS Bucket** and then click **Next**. > > 6. On the **Configure GCS bucket to import data** screen, fill out all required fields. > > ![GCS bucket configuration](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-create-agent-gcs-bucket.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=a7a011d209a6519f93b07efa27fe50d7) > > * In the **Name** field, enter the name of your datasource as you want it to display in Lucidworks Platform. > * In the **Processing Region** field, select the region for Lucidworks to process your data. This is not necessarily the region you created your GCS bucket in. The default value is `us-southcarolina`. > * In the **Bucket Name** field, enter the name of your GCS bucket as it displays in GCS. > * In the **Service Account JSON Key** field, enter your Google Cloud Platform (GCP) key in JSON format to allow access to your GCS bucket. > > 7. Click **Verify Connection** to verify the connection to the GCS bucket. > > > [!NOTE] > > > > You can add multiple GCS buckets to expand the information the model uses for responses. > > To add another bucket, click **Add New** on the **Configure GCS bucket** screen. > > To remove a bucket, select it and click **Remove**. > > 8. When the agent is created, choose what to do next: > > * **Preview Agent** opens the agent preview, where you enter a product ID and test the agent's responses in Agent Studio before you add it to your site. > See [Preview and test the agent](#preview-and-test-the-agent). > * **Get Agent Code** displays the code snippets to add the agent to your website. > See [Embed the agent](#embed-the-agent). > > You can also click **Exit** and do either later from the agent details. > Verify the agent displays on the **Agents** screen. > > ![Preview Agent or Get Agent Code](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-select-preview-or-get-agent-code.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=fa7c34cf15be1dd441426fd5eaab6924) > > > [!WARNING] > > > > Major changes to an agent, such as updating the model or changing datasources, generate a new `template-id`. > > The old `template-id` still works, but it may not reflect your changes. > > Update your frontend code with the new `template-id` from the agent's **Details** tab to use the latest configuration. > **Preview and test the agent** > > Preview an agent in Agent Studio to test its responses before you add it to your website. > The preview displays the same component your customers see, using live data from your datasource for the product ID you enter. > You don't need to embed the agent or configure the **Agent Code** section to use the preview. > > 1. Navigate to Agent Studio, click the **Agents** tab, and then select the agent you want to preview or test. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > The agent details display the following sections: > > * **Agent Information**, such as the name, type, and model for the agent. > * **Agent Preview**, to test whether the responses accurately reflect the information on your website. > * **Agent Code**, to embed the agent in your web page. > > 2. In the **Agent Preview** section, enter the ID of a product from your datasource. > The agent loads using the data for that product. > If the product ID isn't found, check the ID and try again. > > What the preview displays depends on the agent type: > > * **Product Q\&A** displays the questions and answers generated for the product. Select a question to view its answer. > * **Conversational Q\&A** opens a chat. Enter questions about the product, including follow-up questions. > * **Conversational Q\&A FAQ** opens a chat for your questions and displays generated questions a customer is likely to ask. > > 3. Test the agent's responses and verify they accurately reflect the information about that product. > > > [!NOTE] > > > > If the preview reports that no data is available, your datasource is still processing or contains no documents. > > Wait for the initial processing to finish, and then try again. > **Embed the agent** > > After you create an agent, the agent details screen provides the code to embed the agent on your website. > Embedding an agent involves two decisions: > > * Where you [place the script](#add-the-script) that loads the agent. > > * How the agent [obtains the product ID](#specify-the-product-id) so it provides accurate information. > > > [!NOTE] > > > > The script, component markup, and CSS are unique to each agent. > > Always copy the code from the **Agent Details** section of the agent you're embedding. > > ### Add the script > > 1. Navigate to Agent Studio, click **Agents**, and then click the agent you want to implement. > > ![Agent Studio Agents screen](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-my-agents.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=f4b2feb15bb1ed6c37c4ad857d780863) > > 2. In the **Agent Details** section, scroll to the **Agent Code** section, and in the **Add the Script Tag** area, click **Copy**. > > ![Agent Code section](https://mintcdn.com/lucidworks/MyaJz9oMpKsO3BEa/assets/images/lw-platform/ai-agent-studio/ai-agent-studio-implement-markup-attribute.png?fit=max\&auto=format\&n=MyaJz9oMpKsO3BEa\&q=85\&s=1242f69e5a73f29b11cd8b7cf715e5e6) > > 3. Paste the script into the `` or `` of your website's HTML. > > No matter where you place the script, the `` snippet must be in the `` of a page for the agent to display there. > > **In the \ (recommended)** > > For best performance, place the script in the ``. > The script loads before the page body, along with any other scripts in your ``. > The agent displays only on pages where you also place the `` snippet in the ``. > > ```html theme={"dark"} > > > > > > > > > ``` > > **In the \** > > If you place the script in the `` of specific pages, it loads only on those pages, after the scripts in your ``. > The order of the script and snippet relative to other items on the page can affect the order in which other page elements load, so this placement isn't recommended. > > ```html theme={"dark"} > > > > > > > > > > ``` > > > [!NOTE] > > > > If your site uses a Content Security Policy (CSP), add `https://storage.googleapis.com` to your `script-src` directive (the agent script is served from Google Cloud Storage) and add the App Studio API URL to your `connect-src` directive. > > > [!NOTE] > > > > To use the Signals beacon on the same page as your agent, you need additional script configuration. > > See [Configure the beacon with Agent Studio or UI Studio](/docs/lw-platform/lw-analytics/signals/signals-beacon#configure-the-beacon-with-agent-studio-or-ui-studio). > > ### Specify the product ID > > The agent answers questions about a specific product. > It identifies the product by its unique ID, which it gets from the `` snippet in the `` of your page. > > Choose one of the following methods, and use it with the script placement you chose in [Add the script](#add-the-script). > > #### URL query parameter > > Use this method when the product ID is consistently in the page URL as a query parameter, or when you want to avoid manually injecting it into the HTML snippet. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > 3. In the **Specify the Product ID** section, enter the **URL Query Parameters** value for the product ID. > For example, if your URL is `https://www.example.com/sale?q=solvents&product=1234` and your product ID is `1234`, enter `product`. > 4. Verify the agent displays on the appropriate pages of your website. > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### CSS selector > > Use this method when the product ID isn't in a URL query parameter, you don't want to inject it into the HTML snippet, and the product ID is already on the page in an element you can isolate with CSS selectors. > > > [!NOTE] > > > > You must be able to extract the exact product ID through CSS selectors. > > For example, if the product ID is `1234`, you must be able to extract `1234` without any additional text, such as `product-id: 1234`. > > 1. Scroll to the **Add Component Markup** section, and then in the **Automatic Extraction** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > > 3. In the **Specify the Product ID** section, enter the **CSS Selector** that contains the product ID. > The following example uses `.product .product-name @data-value` to extract a product ID of `1234`: > > ```html theme={"dark"} > > > > > >
>
> Product Name >
>
> > > > > ``` > > 4. Verify the agent displays on the appropriate pages of your website. > > 5. Test the agent by entering various queries to determine if it returns appropriate responses. > > #### Markup attribute > > Use this method when the product ID exists on the product detail page but isn't available in the HTML or as a query parameter. > You inject the product ID dynamically into the markup. > > 1. Scroll to the **Add Component Markup** section, and then in the **Markup Attribute** area, click **Copy**. > > 2. Paste the `` snippet in the `` of every page where you want the agent to display. > The following example uses `https://www.example.com/sale/1234` and `product-id` in the snippet. > If your product ID attribute name is different from the one in the copied snippet, change the attribute name manually. > > ```html theme={"dark"} > > > > > > > > > ``` > > 3. Verify the agent displays on the appropriate pages of your website. > > 4. Test the agent by entering various queries to determine if it returns appropriate responses. > > ### Customize the layout with CSS > > The agent details screen also contains a CSS code block. > Use it to customize the appearance of the agent to match your website's existing layout. > > The following example shows some custom styling options. > Styling options vary by agent type. > > > [!NOTE] > > > > All agent customizations must be contained within the `.lw-template` properties. > > ```css theme={"dark"} > /* Custom styling for the agent template */ > .lw-template { > /* Container dimensions */ > min-height: 300px; > max-height: 800px; > min-width: 300px; > max-width: 600px; > > /* Optional styling examples: */ > --qna-font-family: Arial, sans-serif; > --qna-container-border-radius: 10px; > --qna-header-font-size: 32px; > --qna-header-icon-color: #a19eff; > --qna-answer-bubble-bg-color: #add8e6; > } > ``` ## Manage the agent > **[Manage agents](/docs/lw-platform/lw-agent-studio/manage-agents)** > > Preview, edit, and delete agents. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.