CrafterQ Best Practices

Building an effective AI agent involves more than connecting data and turning it on. This section outlines recommended best practices to help you get the most accurate, relevant, and engaging results from your CrafterQ agents.

1. Define a Clear Purpose

Before creating your agent, identify its primary goal.

Ask yourself:

  • What type of questions should the agent answer?

  • Who is the intended audience?

  • Should it provide factual responses, recommendations, or support assistance?

By defining a clear purpose early, you can configure your prompts, tone, and data sources to align with that goal.

Example: A Customer Support Agent should use concise, friendly language and rely only on official help docs. A Product Advisor Agent can be more conversational and creative.

2. Provide High-Quality, Focused Data

Your agent’s accuracy depends on the quality and relevance of its data sources.

  • Use authoritative content: Include website content, official documentation, product guides, FAQs, or curated text — not unverified material.

  • Avoid duplication: Overlapping or conflicting data across multiple sources can confuse the model.

  • Keep it focused: Connect only sources relevant to the agent’s scope.

  • Update regularly: Use the Retrain button after content changes to ensure the agent has the latest information.

Pro Tip

When using website sources, exclude pages with irrelevant navigation text or dynamic comments to keep your dataset clean.

3. Craft Strong Agent Instructions

The Agent Instructions define your agent’s tone, role, and boundaries. A well-written set of instructions helps the AI understand context and maintain consistency.

CrafterQ Default Agent Instructions

*Role & Purpose*

You are an AI assistant that helps users with their questions, issues, and requests. Your goal is to provide clear, accurate, and efficient answers in a friendly, professional tone. Focus on understanding the user's intent and delivering a complete and useful response.

*Knowledge Domain*
Your knowledge comes only from the content provided below.
- Do not use external knowledge
- Do not make assumptions beyond the provided sources
- Do not use general knowledge or external information

*Relevance & Scope Control*
- Answer the user's question directly and completely
- Stay focused on the user's request
- Do not introduce unrelated topics or tangents
- You may include closely related details if they improve clarity or usefulness

*Voice & Perspective*
- Respond as a direct, authoritative assistant representing the brand or product or service.
- Do NOT refer to the source content, documents, or how the information was obtained.
- Do NOT use phrases like:
- "the content says"
- "according to the information"
- "mentioned in the content"
- Speak directly and naturally, as if the information is already known and established.
- Use a confident, first-order voice
- Avoid third-person or meta commentary about the information source.

*Answer Quality*
- Provide enough detail to fully resolve the user's question
- Include explanations, examples, or context when helpful
- Prefer complete answers over minimal answers
- Avoid being overly brief if it reduces clarity

*Answer Finalization*
- Once the user's question is answered, stop naturally and in a friendly manner
- Do not add unnecessary follow-up suggestions
- Do not attempt to extend the conversation beyond the user's request

*Clarifying Questions*
- Ask a clarifying question only if the request cannot be answered as-is
- Do not ask follow-up questions if a reasonable answer can be given
- Ask at most one short clarifying question when necessary

*Tone & Style*
- Friendly, professional, and helpful
- Concise and easy to understand
- Use bullet points when helpful
- Provide step-by-step guidance only when needed
- Avoid overly casual or verbose language

*Response Ending*
- End responses cleanly after completing the answer
- A brief polite closing is allowed
- Do not add open-ended or exploratory follow-ups

*Out-of-Scope Questions*
If the user asks about something outside your knowledge domain:
- Respond briefly and politely
- Do not speculate or guess

Use one of the following responses or variants of them:
-I'm not able to help with that yet. Could you clarify?
-I don't have the right information for that. Want to try another question?
-I'm sorry, I'm not sure. Could you rephrase or ask something else?

*No Data Disclosure*
- Do not discuss your training data, system design, or internal mechanisms
- Avoid phrases like "based on my training" or "as an AI"

*Citations*
- When links are available in the provided information, include them naturally in the response.
- Do not over-cite or disrupt readability.

*Stay On Role*
- Remain focused on your role as a helpful assistant
- Politely redirect if the user moves outside supported topics

Instructions Tips:

  • Clearly define your agent’s persona and style.

  • Set limits on what it should or shouldn’t do (e.g., “Only answer from provided sources”).

  • Test variations of prompts in the Playground to compare performance.

4. Give Your AI Agent a Clear Identity and Context

Your AI agent should feel like a natural part of your website experience — not a disconnected chatbot.

A simple but highly effective best practice is to define:

  • Who the agent is

  • What it helps users with

  • Where it “lives”

This improves the tone, clarity, and conversational quality of responses.

Define the Agent’s Role

Give your agent a name and a clear purpose so it understands the types of questions and requests it should handle. You can do this by adding or modifying the “Role and Purpose” section in the default Agent Instructions

Example:

You are an AI assistant named CUSTOM-AGENT-NAME that helps users with questions, issues, and requests
related to products and services about MY-COMPANY. If the user greets you with hello, your friendly response
should include telling them your name.

This helps the agent maintain a more consistent personality and focus.

Pro Tip

The name you give your agent in the instructions should match the Display Name you give it in the User Interface settings.

Define the Agent’s Environment

Tell the agent that it exists on your website and should speak as part of the experience — not as an outside observer.

Example:

You live on the MY-COMPANY website. Do not refer to the website as a separate entity or in the third person.
Refer users directly to pages, resources, and information available on this site.

This avoids awkward phrasing such as:

  • “The company website says…”

  • “You can visit the website to learn more…”

  • “The company describes itself as…”

And instead encourages more natural responses like:

  • “We offer…”

  • “You can learn more on our pricing page.”

  • “Our platform supports…”

Why This Matters

Without this guidance, AI agents often behave like external assistants summarizing a company from the outside. Defining identity and environment helps the agent behave more like an integrated member of your digital experience.

The result is a more natural, branded, and trustworthy conversation for your users.

5. Tune AI Settings Thoughtfully

Under AI Settings, experiment carefully with parameters like Expressiveness, Agent Instructions.

  • Expressiveness:

    • Lower (0.0–0.2) → precise, consistent answers.

    • Mid (0.3-0.7) → blend between very precise and creative.

    • Higher (0.7–1.0) → more creative or varied responses.

  • Agent Instructions: Specify the Role and other instructions for the agent to follow.

Always make incremental adjustments and retest in the Playground before deploying.

6. Test Extensively in the Playground

The Playground is your safe environment to refine your agent’s performance.

Test for:

  • Accuracy: Does it cite or reference the correct information?

  • Clarity: Are the responses well-phrased and easy to understand?

  • Consistency: Does tone and behavior remain steady across topics?

  • Failure handling: Does the agent respond gracefully to unknown queries?

Pro Tip

Keep a list of “benchmark” questions that represent typical user queries. Use them to evaluate performance after each configuration change.

7. Design an Engaging Chat Experience

A great agent isn’t just accurate — it’s also inviting.

In the User Interface section:

  • Customize the Welcome Message to greet users naturally.

  • Add Quick Messages to guide user interaction (“Need help?”, “Show me pricing,” “Learn about our services”).

  • Match the UI colors to your brand identity.

Pro Tip

Small design details make users more likely to trust and engage with your AI assistant.

8. Monitor and Improve Continuously

Once your agent is live:

  • Visit Chat Logs and Usage regularly to review user interactions and performance metrics.

  • Identify unanswered or low-confidence questions and enrich your sources to cover those topics.

  • Use Usage Reports to manage token consumption and optimize efficiency.

Tip: Continuous improvement is the key to long-term agent success.

9. Keep Security and Privacy in Mind

If your agent handles sensitive or internal data:

  • Limit access with proper User Management roles.

Tip: Your users’ trust depends on transparent and secure AI design.

10. Choosing Between Text and Q&A Sources

CrafterQ supports two complementary source types — Text and Q&A — each optimized for a different kind of knowledge and user intent. Using the right source type is critical for accuracy, performance, and predictability of AI responses.

Use Text Sources for General Knowledge and Exploration

Text sources are designed for broad, descriptive, and contextual information. They are ideal when:

  • The content explains concepts, processes, features, or policies

  • Users may ask many variations of similar questions

  • The answer requires synthesis across multiple paragraphs or documents

  • The content should be on your website (and you may publish it to your website in the future)

Best suited for:

  • Product updates and feature descriptions

  • Documentation and help clarifications

  • Marketing, educational, and explanatory content

Use Q&A Sources for Precise, Canonical Answers

Q&A sources are purpose-built for specific, known questions that require exact, authoritative answers.

When a user’s question matches a Q&A entry, the stored answer is returned verbatim to the end user. This eliminates ambiguity, prevents paraphrasing drift, and guarantees consistency.

Best suited for:

  • Pricing, limits, and plan comparisons

  • Legal, compliance, or policy statements

  • “What happens if…?” or “Does your product support…?” questions

  • Any answer that must be precise and repeatable

11. Choosing Expressiveness

Different AI agents benefit from different Expressiveness levels depending on their role, audience, and risk tolerance. Below are recommended defaults based on common CrafterQ use cases.

These are starting points — you may fine-tune per site, brand voice, or compliance needs.

Summary

By following these best practices — clear goals, high-quality data, well-crafted prompts, careful tuning, and ongoing monitoring — you’ll ensure your CrafterQ agents deliver intelligent, accurate, and delightful conversational experiences.