AI Agents

The Agents section is where you manage all of your CrafterQ agents — from their configuration and connected data sources to testing, usage, and deployment.

Clicking on the Agents menu item will give you a list of your agents. From here, you can click on the Create Agent button to create a new agent (assuming your Plan has unused agents available).

Creating New Agents

The Create Agent screen allows you to build a new AI agent from scratch. Here you’ll define its name, appearance, behavior, and user interface — everything needed to shape how your agent will interact with users once deployed.

When you click Create Agent from the Agents page, you’ll see configuration fields organized into two main sections: General and User Interface.

1. General

These fields define your agent’s basic information and are primarily for internal use within your organization.

Field	Description
Name	The internal name of your agent. This is how the agent will appear in your dashboard and project listings. Choose a name that clearly describes its function, such as Support Bot or Product Assistant.
Description	An optional short description to help you identify the agent’s purpose. Example: “Handles customer support queries and product FAQs.”

2. User Interface

This section customizes how your agent appears and behaves in the chat interface, shaping the user experience.

Field	Description
Display Name	The public-facing name shown to users during chat sessions. If left blank, the internal agent name will be used instead. Example: Ask CrafterQ or Virtual Assistant.
User Prompt Placeholder	Text displayed in the chat input field before the user types anything. This helps guide users on what to ask. Example: “Ask anything…” or “How can I help you today?”
Welcome Message	The initial message displayed when a user first opens the chat window and no messages have been sent. Example: “Hi there! I’m here to answer your questions.”
Quick Messages	Predefined buttons that appear below the chat input to help users start a conversation. Enter one message per line. Example: – “Show me pricing” – “What products do you offer?” – “Talk to support”
Collect Feedback	Toggle to display thumbs up/down buttons on each agent message. Enables users to rate responses, helping you measure satisfaction and improve performance.
Follow-Up Suggestions	Toggle to show dynamic follow-up prompts after each agent response. When enabled, CrafterQ automatically suggests related questions or next actions to keep the conversation flowing.
Theme	Controls the overall chat widget appearance. Options include: – System: Follows the user’s device theme (light or dark). – Light: Always displays the light theme. – Dark: Always displays the dark theme.
User Message Bubble Color (Light Theme)	Customizes the color of the user’s message bubbles in Light Mode. This helps differentiate messages and maintain visual consistency. Click Reset to revert to the default.
User Message Bubble Color (Dark Theme)	Customizes the color of the user’s message bubbles in Dark Mode. This helps differentiate messages and maintain visual consistency. Click Reset to revert to the default.

Pro Tip

Use your organization’s primary brand color to maintain consistency with your website or app design.

Saving and Next Steps

After completing the required fields:

1. Click Save to create your agent.

2. Once saved, CrafterQ will take you back to the Agents screen where your new agent will now be listed.

Note

You can edit any of these settings later from the AI Agents → Settings screen.

Create Agent Summary

The Create Agent screen is the starting point for building intelligent, branded conversational experiences. By defining both internal details and user-facing interface options, you lay the foundation for how your agent looks, sounds, and interacts — ready for testing, training, and deployment on your digital channels.

Managing Agents

Each agent has its own set of configurable screens accessible through the sidebar menu that you’ll see after clicking on an agent listed on the Agent screen:

• Usage – View chat and credit usage specific to this agent.

• Chat Logs – Review past user conversations for training and quality assurance.

• Settings – Configure your agent’s core parameters (identity, AI behavior, and interface).

• Sources – Connect or update the data sources your agent uses for knowledge.

• Playground – Interactively test your agent’s performance and tune its behavior.

• Embed & Share – Deploy or share your agent on websites and applications.

Usage Screen

The Usage screen provides detailed analytics on how your agent is performing over time. It helps you understand user engagement, monitor message quality, and identify geographic patterns of interaction.

All metrics on this screen reflect data for the time period selected using the calendar control at the top of the page.

Selecting a Time Period

At the top of the screen, use the date range selector to specify the time window for your usage data.

The dashboard will automatically refresh to show chat and message statistics for your selected timeframe.

1. Chat Detail Summary

This section summarizes your agent’s total activity and feedback within the chosen period.

Metric	Description
Chats	The total number of chat sessions initiated by users, shown along with the number of countries where they originated. Example: 24 chats across 2 countries.
Messages	The total number of messages exchanged between users and your agent during the selected timeframe. This includes both user messages and AI responses. Example: 509 messages.
Thumbs Up	The number of agent messages that users rated positively. This indicates user satisfaction and helps assess agent quality.
Thumbs Down	The number of agent messages that users rated negatively. Use this to identify responses that need improvement or retraining.

Pro Tip

A high ratio of chats to thumbs-up feedback suggests users are engaging frequently but not rating responses — consider prompting for feedback in your Agent Instructions.

2. Chats Started (Line Graph)

Below the summary metrics, a line graph visualizes the number of chat sessions started per day during the selected period.

Use this chart to:

• Identify daily or weekly engagement trends.

• Measure how product launches, content updates, or campaigns impact chat volume.

• Spot peaks or drops that may indicate seasonal changes or performance issues.

Hovering over a data point shows:

• Date

• Number of chats started on that day

  Example: You might see a spike of 15 chats on October 12 following a new website update, indicating higher user interest or discovery.

3. Chats by Country (Global Map)

This interactive world map shows where your chats are coming from, with countries shaded according to their chat volume.

The darker the color, the higher the engagement from that region.

How to use:

• Hover over any country to view the exact number of chats and percentage of total sessions.

• Use this data to identify where your audience is most active.

• Combine with chat language settings to localize responses or add multilingual agents.

Example: If you see most chats originating from the U.S. and Germany, you might consider training your agent on support content for those markets (the agent will automatically translate the language for its responses based on the language of user queries.

4. Insights and Next Steps

Regularly reviewing your Usage screen helps you:

• Track agent adoption and engagement growth.

• Identify underperforming regions or timeframes.

• Evaluate the quality of interactions using user feedback metrics.

Next Steps:

• Visit the Chat Logs screen to view individual conversations and assess specific responses.

• Revisit the Sources or AI Settings screens to retrain or fine-tune your agent based on insights from usage data.

Chat Logs Screen

The Chat Logs screen provides a detailed record of all conversations between users and your agent. Use this screen to review real user interactions, understand how your agent is performing in the field, and identify areas where responses can be improved.

Overview

Each chat session is automatically logged by CrafterQ and displayed in a searchable, filterable list.

Logs include key information such as:

• The date and time of the chat

• The number of messages exchanged

• Feedback (Thumbs Up / Down) received from users

• The country or region where the chat originated

This screen is essential for training and continuous improvement — it gives you direct visibility into what your users are asking and how your agent is responding.

Selecting a Time Period

At the top of the page, use the calendar widget to choose the date range for the logs you want to view.

Once selected, the chat list will automatically update to show only the sessions that occurred within the chosen timeframe.

Filtering by Feedback

You can narrow down your logs by user feedback type, allowing you to focus on either successful or problematic interactions.

Filter options:

• All Chats: Displays every recorded chat session.

• Thumbs Up: Shows only chats containing messages that received positive feedback.

• Thumbs Down: Shows only chats containing messages that received negative feedback.

Pro Tip

Use the “Thumbs Down” filter regularly to identify conversations where your agent underperformed. Reviewing these chats helps pinpoint missing data or prompt issues.

Chat Log List

Each entry in the list represents one chat session and includes the following columns:

Field	Description
Date/Time	The timestamp when the chat session started.
User Location	The country or region from which the chat originated, based on IP data.
Messages	The total number of messages exchanged in the session (user + agent).
Feedback	Displays a thumbs-up or thumbs-down icon if any message in that chat received feedback. If no feedback was given, this column remains blank.
Agent Used	The name of the agent that handled the chat session (useful if multiple agents are active).
Actions	Click View to open the full transcript of that chat session.

Viewing a Chat Transcript

Click the View button on any chat entry to open the full conversation log.

Within the transcript view, you’ll see:

• User messages and AI responses, displayed in chronological order.

• Any feedback icons beside specific responses (👍 or 👎).

• Message-level metadata such as timestamps and token usage (if applicable).

Use this view to:

• Analyze how well the agent understood the user’s intent.

• Identify gaps in your content or training data.

• Refine prompts and AI settings for improved responses.

Pro Tip

Combine feedback filtering with the transcript view to create a targeted quality review workflow — for example, reviewing only the “Thumbs Down” sessions from the past week.

Exporting Chat Logs (if available)

If your plan supports it, you can export logs for further analysis.

Look for the Export button at the top-right corner of the Chat Logs screen to download data in CSV or JSON format for reporting, auditing, or external analytics.

Chat Logs Summary

The Chat Logs screen is your direct window into how users are engaging with your agent:

• Use time filters to focus on recent or historical sessions.

• Use feedback filters to identify high- or low-performing conversations.

• Review transcripts to guide prompt updates and retraining decisions.

Next Steps

After reviewing chat logs:

• Visit the Sources screen to add or refine data for poorly answered questions.

• Adjust your System Prompt or Temperature in AI Settings to improve tone or precision.

• Re-test improvements in the Playground before redeploying.

Settings Screen

The Settings screen defines your agent’s personality, configuration, and user experience. It is divided into three main sections:

1. General

2. User Interface

3. AI Settings

Each section controls a different aspect of how your agent operates and interacts with users.

1. General

This section defines the basic information used to identify and describe your agent within CrafterQ.

Field	Description
Name	The display name for your agent. This appears in the dashboard, Playground, and embed interfaces. Example: Support Assistant or Product Recommender.
Description	A short summary of the agent’s purpose. This is for internal use to help your team distinguish between multiple agents. Example: “Provides instant answers to customer FAQs.”

Pro Tip

Use clear, descriptive names if you manage multiple agents — e.g., “Website Chatbot – English,” “E-Commerce Assistant,” etc.

2. User Interface

These controls customize the look and feel of your chat experience, ensuring the agent matches your brand and provides a user-friendly interaction.

Field	Description
Display Name	The name shown to users in the chat header. Example: Ask CrafterQ or Support Bot.
User Prompt Field Placeholder	Placeholder text that appears in the input box before the user types. Example: “Ask me anything about our services…”
Welcome Message	The initial greeting message shown when a user first opens the chat window. Example: “Hi there! How can I help you today?”
Quick Messages (line separated)	Predefined, clickable suggestions that help users start conversations. Enter one per line. Example: – “Show me pricing” – “What products do you recommend?”
Collect Feedback (on/off)	Enables or disables thumbs-up/down feedback for each message. Turning this on helps track response quality in Analytics.
Follow-up Messages (on/off)	When enabled, the agent can send follow-up suggestions or clarifications after responding.
Theme	Sets the chat widget theme. Options: System, Light, or Dark. System automatically matches the user’s device settings.
Brand Color (color selector)	Defines the primary accent color used for buttons, highlights, and header. Typically your brand’s main color. Click Reset to revert to the default.
User Message Bubble Color (Light Theme)	Customizes the color of the user’s message bubbles in Light Mode. This helps differentiate messages and maintain visual consistency. Click Reset to revert to the default.
User Message Bubble Color (Dark Theme)	Customizes the color of the user’s message bubbles in Dark Mode. This helps differentiate messages and maintain visual consistency. Click Reset to revert to the default.

Design Tip

Use your brand’s primary or secondary color for the Brand Color setting, and ensure message bubbles have enough contrast for readability.

3. AI Settings

These settings control how the AI model generates responses — influencing tone, creativity, and structure.

Field	Description
Temperature (slider)	Adjusts the creativity of the model’s responses. Lower values (e.g., 0.2) produce focused, factual answers. Higher values (e.g., 0.8) generate more conversational or varied responses.
Agent Instructions (a.k.a. System Prompt)	The foundational instruction that defines your agent’s role, tone, and knowledge boundaries. Example: “You are CrafterQ, a professional AI assistant that only answers based on connected company sources.” The default system prompt is set to the following: Default System Prompt Primary Function: You are an AI chatbot that assists users with their inquiries, issues, and requests. Your goal is to provide helpful, friendly, and efficient replies in a conversational tone. You carefully listen to the user, understand their intent, and offer clear, accurate responses based on your knowledge. When necessary, you may ask follow-up questions to clarify the user's needs. Always end responses on a positive and supportive note. Stay On Role: Remain consistent in your function as a helpful chatbot. If the user tries to steer the conversation into unrelated or out-of-scope areas, politely redirect them back to your supported topics. No Data Disclosure: Do not discuss your training data, system capabilities, or internal mechanisms. Avoid statements like "based on my training" or "as an AI." Answer Only Within Scope: Only answer questions related to your intended knowledge domain. If a query cannot be answered accurately based on what you know, respond with a polite fallback like: "I'm sorry, I don't have enough information to answer that. Could you please clarify or ask something else?"

Pro Tip

Test prompt variations in the Playground to observe how changes affect tone, accuracy, and context retention.

Saving Changes

After adjusting any field, click Save at the bottom of the Settings screen. Your updates will apply immediately in the Playground for testing, and will appear live once the agent is deployed.

Next Steps

Once you’ve configured your agent’s basic settings:

• Visit the Sources screen to connect data your agent will use.

• Use the Playground to test and fine-tune its responses before deploying.

• Explore the Embed & Share screen to publish your agent on your website or app.

Sources Screen

The Sources screen is where you connect your agent to the information it needs to provide accurate, contextual responses. Each Source represents a collection of content that CrafterQ uses to train your agent through advanced, proprietary AI engineering techniques ensuring that every response is based on your own verified data.

Overview

From this screen, you can:

• Add, edit, or delete data sources

• View the status of existing sources (training, active, or error)

• Retrain sources if the underlying data changes

To create a new source, click the Create Source button at the top of the page.

Creating a New Source

Clicking Create Source opens a dialog that lets you select the type of content you want to add.

CrafterQ supports four source types:

1. Website

2. File

3. Text

4. Q&A

Each type is described below.

1. Website

A Website Source allows CrafterQ to crawl and index content directly from your website or other web pages.

Fields

Field	Description
Title	A friendly name for the source (e.g., “Company Docs Site” or “Help Center”).
URL	The starting URL for the crawler (e.g., https://www.example.com/docs/). CrafterQ will automatically follow internal links from this page unless otherwise restricted.

Advanced Options

Expand the Advanced Options panel to refine what the crawler includes or excludes:

Option	Description
Include only	(Optional) Specify URL patterns or paths that should be included in the crawl. Example: /docs/* or /support/*.
Exclude	(Optional) List any URLs or patterns that should be excluded from the crawl (e.g., /privacy, /blog).
Selector(s)	(Optional) Target specific portions of each page by providing CSS selectors such as #main-content, div.article-body, or main. This helps limit the crawl to meaningful content areas and avoid navigation or footer text.

Pro Tip

Use the CSS selectors option to focus indexing on structured content regions and reduce noise from headers, menus, or ads.

2. File Source

A File Source lets you upload documents directly into CrafterQ for indexing.

Upload Box

Use the drag-and-drop area labeled “Drop files here or browse files” to upload your content.

Supported file formats typically include:

• .pdf

• .docx

• .txt

• .csv

• and other common text-based formats.

Once uploaded, CrafterQ automatically extracts and indexes the file text so your agent can use it during conversations.

Pro Tip

Group related documents together in a single source (e.g., Product Manuals) to simplify management.

3. Text Source

A Text Source allows you to add raw text content manually — perfect for concise policies, team FAQs, or short reference material.

Fields

Field	Description
Title	The internal name for this text source (e.g., “Return Policy”).
Content	The body text you want your agent to learn from. Paste or type any content here, such as plain text, bullet points, or short paragraphs.

This option is ideal for quick knowledge additions without uploading files or web links.

4. Q&A Source

A Q&A Source defines one or more question-and-answer pairs that your agent can recall exactly as provided.

This is useful for specific responses that require precise wording or compliance-approved language.

Fields

Field	Description
Title	A descriptive name for the Q&A group (e.g., “Pricing FAQs”).
Question(s)	One or more related questions that users might ask. You can enter multiple variations separated by new lines.
Answer	The response your agent should give for the questions listed above. This text is indexed verbatim.

Example:

Question: “What are your business hours?”

Question: “Business hours?”

Answer: “Our offices are open Monday through Friday, 9 AM to 5 PM EST.”

Saving and Training

Once you’ve filled in the required fields for any source type, click Save.

After saving:

1. CrafterQ automatically begins a training step, where the content is indexed and vectorized for retrieval.

2. The status indicator under the source will show progress (e.g., “Crawling,” “Training,” or “Trained”).

3. Once training completes, the data becomes immediately available for your agent to use in chat responses.

   Note

   If you later update or replace the source data, your agent will automatically be retrained. If you update your website content through your CMS, then your agent will automatically find the new content and retrain itself on a schedule based on your Billing Plan; you can also hit the Retrain button to force a retraining operation as well.

Managing Existing Sources

Each listed source displays:

• Title

• Type (Website, File, Text, or Q&A)

• Created Date

• Status (e.g., Trained)

• Actions (drop down on right side): Edit, Delete

Use these controls to maintain your agent’s knowledge base and ensure accuracy over time.

Best Practices

• Keep each source focused (one topic or type of document per source).

• Use Advanced Options on website sources to filter out irrelevant content.

• Combine multiple source types for a well-rounded dataset (e.g., website + PDF + Q&A).

Sources Summary

The Sources Screen is where your agent’s intelligence begins. By connecting relevant and high-quality data here, you enable CrafterQ to generate accurate, context-aware responses tailored to your organization’s knowledge.

Playground Screen

The Playground screen is where you can test your AI agent in real time — just as your users would experience it on your website or app. It provides an interactive chat environment to evaluate how well your agent performs based on its Settings, Sources, and AI configurations.

Overview

The Playground is a single, live instance of your selected agent.

You can use it to:

• Experiment with different types of user queries

• Evaluate how your agent responds based on its data sources and system prompt

• Adjust the Settings (prompt, temperature, etc.) and retest to fine-tune results

Note

In future releases, the Playground will support multiple side-by-side testing instances, allowing you to compare different configurations (e.g., varying prompts, temperatures, or models) for more advanced optimization.

How It Works

When you open the Playground, you’ll see:

• A chat interface identical to the deployed chat widget

• An input field to type your messages

• The conversation history displaying your queries and the agent’s responses

This environment uses the exact same parameters you configured under the Settings screen — including:

• System Prompt

• Temperature

• User Interface options (welcome message, placeholder text, etc.)

That means the Playground replicates the live user experience, ensuring your tests reflect how the agent will behave once deployed.

Testing Your Agent

1. Type a query or request in the input field (e.g., “What products do you offer?” or “Summarize our privacy policy.”)

2. Observe the agent’s response.

3. Evaluate for:

   • Accuracy — Does the response correctly reflect your content sources?

   • Tone — Is it aligned with your intended personality or brand voice?

   • Structure — Is the message clear, concise, and complete?

If the agent’s answers need improvement:

• Go back to the Settings screen to adjust prompts, temperature, or model options.

• Retrain your Sources if content has changed or needs refinement.

• Return to the Playground and test again.

Pro Tip

Keep a short list of benchmark questions to test consistency after making configuration changes.

Quota and Billing Usage

All interactions within the Playground use live API calls and therefore count toward your organization’s quota and billing plan.

Specifically:

• Each message exchange consumes credits under your agent’s Usage plan.

• These credits are reflected in both the Usage screen (per agent) and your Dashboard totals.

Important

Treat Playground testing as production usage. While it’s a safe space for experimentation, frequent testing will consume your plan’s credit allowance.

When to Use the Playground

Use the Playground whenever you:

• Create a new agent and want to confirm it’s working correctly

• Add or update sources and want to validate the new knowledge

• Modify prompts or temperature settings and want to observe behavioral changes

• Need to demonstrate your agent’s functionality before deployment

Playground Summary

The Playground gives you an accurate preview of how your agent will perform in the real world — using the same configuration, data, and tone defined in its settings. It’s the best place to refine your agent before embedding it live.

Embed & Share Screen

The Embed & Share screen provides everything you need to deploy your CrafterQ agent to a live environment.From here, you can share your agent as a standalone chat page or embed it directly into your website or web application using a lightweight JavaScript snippet.

Overview

Your CrafterQ agent can be shared or embedded in three main ways:

1. Standalone Share Link – Instantly share a hosted chat page.

2. Website Embed Code – Add the agent to your own website using a simple script tag.

3. Advanced Initialization – Customize behavior with optional JavaScript parameters.

Each deployment method references your agent’s unique Agent ID, which connects the chat widget to your configured AI agent.

1. Agent ID

Every CrafterQ agent has a unique Agent ID that identifies it across the platform.

Example:

Your agent ID is 0198ed35-9f87-7711-8a93-2dfdc027e007

You’ll use this ID when embedding or configuring your agent.

2. Shareable Standalone Page

You can instantly share your agent using a hosted CrafterQ chat page. This option is ideal for quick demos, internal testing, or customer support links.

Example:

https://chat.crafterq.ai/0198ed35-9f87-7711-8a93-2dfdc027e007

Simply copy and share this URL with anyone you’d like to access your agent directly. The standalone page includes the full CrafterQ chat interface, styled according to your User Interface settings.

Pro Tip

Use this hosted link in marketing emails, help center pages, or Slack channels to provide easy access to your agent without embedding code.

3. Embed on Your Website

To embed your agent into your own website, copy and paste the provided script tag into the bottom of your site’s HTML layout — ideally before the closing </body> tag.

Example Embed Code:

<script src=”https://chat.crafterq.ai/embed.js” data-q-id=”0198ed35-9f87-7711-8a93-2dfdc027e007”></script>

When users visit your site, this script automatically loads the CrafterQ chat widget connected to your agent.

Placement Recommendation:

• Add this code to your site’s global footer or layout template so it appears on all pages.

• For single-page apps or specific sections, include it only where chat functionality is desired.

Note

The data-q-id attribute must contain your Agent ID. Without it, the widget cannot connect to your agent.

4. Advanced Initialization (Optional)

For developers who want more control over widget behavior, CrafterQ supports advanced initialization through JavaScript.

Use the following template for custom setup:

<script src="https://chat.crafterq.ai/embed.js"></script>
<script>
window.crafterq.init({
  /** agentKey {string} - Required. Your agent key. */
  agentKey: '0198ed35-9f87-7711-8a93-2dfdc027e007',

  /** chatUnavailableMessage {string} - Optional.
   *  Message displayed when the chat service is unavailable.
   */
  chatUnavailableMessage: 'Chat is currently unavailable. Please try again later.',

  /** onMount {function} - Optional.
   *  Function executed after the chat widget is fully mounted.
   */
  onMount() {
    // Custom logic here
  },

  /** openLinksInNewTab {boolean | function} - Optional.
   *  Determines how external links are handled.
   *  - true: always open links in a new tab
   *  - false: open links in the same window
   *  - function: provides fine-grained control
   */
  openLinksInNewTab(e) {
    const href = e.currentTarget.getAttribute('href');
    if (!href) return;
    try {
      const url = new URL(href);
      if (window.location.hostname !== url.hostname) {
        e.preventDefault();
        window.open(href, '_blank', 'noopener noreferrer');
      }
    } catch {
      // Invalid URL - ignore
    }
  }
});
</script>

Available Options

Option	Type	Required	Description
agentKey	String	✅ Yes	The unique identifier for your CrafterQ agent.
chatUnavailableMessage	String	❌ No	Custom message shown if the chat cannot connect.
onMount()	Function	❌ No	Runs after the chat widget mounts. Use for analytics, UI tweaks, or logging.
openLinksInNewTab	Boolean / Function	❌ No	Controls how the widget handles links. Accepts true, false, or a custom function.

Pro Tip

The onMount callback can be used to automatically open the chat when a user lands on a page, track widget engagement, or log initialization events to your analytics system.

5. Testing Your Embed

After embedding:

1. Load your website in a browser.

2. Confirm that the CrafterQ chat icon or panel appears as configured.

3. Click the widget and test a short conversation to verify connectivity.

Summary

The Embed & Share screen gives you flexible options to deploy your CrafterQ agent:

• Share instantly using a hosted standalone chat link

• Embed anywhere with a simple script tag

• Customize behavior through advanced initialization for developers

Once embedded, your agent is live and ready to engage users — bringing AI-driven conversation directly into your digital experiences.