How to Build Your First AI Agent with Heeya: Step-by-Step Tutorial (2026)

Step 1: Create Your Heeya Account

Go to heeya.fr/register to create your free account. Sign-up takes under a minute: enter your email, choose a password, and you are redirected straight to your dashboard. No credit card required to get started.

The free plan lets you create a first agent and test every feature — RAG, tools, web embed. The plan limits and quotas are detailed on the pricing page if you want to compare before you begin.

Step 2: Create Your First AI Assistant

From your dashboard (URL: /dashboard), you will see a dashed-border card with a "Create an assistant" button at the top of the page. Click it — a modal opens with three fields to fill in.

The three fields in the creation form

1. Assistant name (required)

Choose a clear, descriptive name. This name appears in your dashboard and, if you configure it, in the widget on your site. Examples: "FAQ Assistant", "Customer Support", "Product Advisor", "HR Bot".

2. Description (optional)

This field helps you identify the agent in your dashboard when you manage several. It has no effect on how the agent behaves — it is an internal note. Example: "E-commerce FAQ — returns, shipping, products".

3. Instructions for the AI (required — this is the system prompt)

This is the most important field. These instructions define your agent's behavior, tone, scope, and rules. The AI reads them before every conversation. A well-written system prompt transforms a generic LLM into a domain expert. To go deeper, our system prompt engineering guide covers advanced techniques.

3 copy-ready system prompt templates

Here are three ready-to-use templates covering the most common use cases. Copy the one closest to your needs, then customize the bracketed placeholders.

Template 1 — E-commerce customer support

You are the AI assistant for [Store Name], an online store specializing in [product category].

Your role:
- Answer questions about products, sizing, materials, and delivery timelines
- Help customers with return and exchange requests (return window: 30 days)
- Explain payment options and current promotions

Your behavior:
- Be warm, concise, and professional
- Answer only based on information available in your knowledge base
- If you don't know something, say so clearly and offer to connect the customer with the team

Scope:
- Do not discuss topics unrelated to the store
- Never quote a price without verifying it in your knowledge base
- If the customer wants a callback or a custom quote, offer them the contact form

Template 2 — Company FAQ / HR

You are the internal HR assistant for [Company Name]. You help employees quickly find answers to their everyday HR questions.

Topics you cover:
- Time off and absences (procedures, request deadlines, balances)
- Payroll and expense reimbursements (payment dates, forms to use)
- Employee benefits (health insurance, meal vouchers, remote work policy)
- Training and professional development

Your behavior:
- Answer precisely and directly
- Cite the relevant policy or internal document when appropriate
- If a question is outside your scope or requires an HR decision, direct the employee to the right contact

Limits:
- Do not handle sensitive individual matters (disciplinary actions, terminations)
- Do not give legal advice — refer to the legal or HR team in those cases

Template 3 — Product advisor / recommendation

You are the AI product advisor for [Company Name]. Your role is to help visitors find the product or solution that precisely fits their needs.

Your method:
1. Understand the customer's need by asking 1–2 qualifying questions if needed
2. Recommend 1–3 options and explain why each matches the stated need
3. Highlight the key differentiators of each option
4. If the customer is undecided, offer to connect them with a human expert via the contact form

Your tone:
- Expert but accessible — explain clearly without being condescending
- Do not oversell: if a less expensive product meets the need, say so
- Be honest about the limitations of a solution

Available information:
- Full product catalog in your knowledge base
- Spec sheets, comparison guides, customer use cases

Once you have filled in all three fields, click "Create". The agent is created instantly with a dedicated Qdrant vector collection — the technical layer that powers semantic search across your documents. You are automatically redirected to your agent's configuration page.

Step 3: Build the RAG Knowledge Base

Without a knowledge base, your agent answers only from its general training data — which can be useful, but is rarely sufficient for professional use. Feeding the RAG means giving your agent access to your specific content: product documentation, return policies, terms of service, employee handbooks, catalogs, and more.

Inside your agent's page, click the "Files" tab.

What file formats are accepted?

• PDF: the most common format. Compatible with all document types — brochures, contracts, guides, catalogs.
• DOCX: Word files. Ideal for internal procedures, policies, and HR documents.
• PPTX: PowerPoint presentations. Slide content is extracted and indexed.
• TXT: plain text files. Perfect for pre-written FAQs, call scripts, or product lists.

Best practices for organizing your documents

The quality of your knowledge base directly determines the quality of your agent's responses. A few rules to follow before uploading:

• Prefer topic-focused documents: one file = one subject. A "return policy" PDF is more effective than a single PDF mixing returns, shipping, legal notices, and payment terms all together.
• Use clear headings and subheadings inside your documents. Chunking relies on document structure — clear headings produce more coherent chunks.
• Avoid scanned PDFs without OCR: a PDF image without a text layer cannot be read by the system. Verify that your PDF contains selectable text.
• Remove unnecessary pages: blank cover pages, generic legal boilerplate, lengthy tables of contents — they consume tokens without adding value.
• Update documents rather than accumulating them: if your catalog has changed, delete the old version before uploading the new one.

Web scraping: when to use it

The "Files" tab also offers a web URL scraping option. Instead of uploading a document, you enter a URL and Heeya automatically extracts the page content for indexing.

Use scraping when:

• Your reference content is already online and maintained (product pages, public FAQ, online documentation)
• You want to avoid managing file exports with every update
• Your site is publicly accessible without authentication

Avoid scraping when content is behind a login, when pages are highly dynamic (SPAs without static HTML), or when your site uses a captcha. In those cases, export your content as PDF or TXT.

Example: 5 documents to upload for an e-commerce agent

1. product-catalog.pdf — Full product list with descriptions, SKUs, prices, and availability
2. return-exchange-policy.pdf — Return process, timelines, eligibility conditions, refund terms
3. shipping-faq.txt — Carrier timelines, coverage areas, order tracking, what to do if a package is lost
4. size-materials-guide.pdf — Size charts, care instructions, fabric composition
5. current-promotions.txt — Active promo codes, conditions, expiration dates

To understand the chunking and indexing mechanisms running in the background, our RAG expertise page details the technical architecture.

Step 4: Test Your Agent in the Conversations Tab

Before embedding your agent on your site, test it thoroughly. The "Conversations" tab gives you a direct chat interface with your agent — exactly what your end users will see.

How to write good test questions

Do not test with easy or generic questions. Simulate the real questions your visitors will ask:

• Substantive questions: "Do you ship to Canada?" / "What is the composition of the XP-200 model?" / "How long does a return refund take?"
• Ambiguous questions: "How does your return thing work?" / "When does it arrive?" — verify that the agent asks for clarification rather than making something up.
• Out-of-scope questions: "What is the weather in New York?" / "Translate this text for me." — verify that the agent politely declines and stays in its role.
• Questions about missing information: ask about a topic you have not indexed — the agent must say it does not know, not invent an answer.

How to evaluate response quality

For each response, evaluate three criteria:

• Relevance: does the response directly address the question without unnecessary tangents?
• Faithfulness to sources: is the information present in your documents? The agent should not fill gaps with invented content.
• Tone: does the response style match the system prompt? An agent configured as "warm and concise" should not respond in a cold, lengthy way.

Iterating on the system prompt when needed

If responses do not meet your expectations, go back to the agent's settings and update the instructions. The most common adjustments:

• The agent is too verbose: add "Your responses are no longer than 3–4 sentences, unless the user explicitly asks for more detail."
• The agent invents information: add "You answer ONLY based on documents available in your knowledge base. If the information is not available, say so clearly."
• The agent goes off-topic: specify excluded subjects in your prompt — "Do not answer any question outside the scope of [X]."
• The tone is off: describe exactly what you expect — "Use bullet points for responses with multiple elements." / "Address the user by first name when it is known."

Expect 3–5 test-and-adjust cycles for a well-calibrated agent. It is an investment that pays off quickly. For advanced prompt writing techniques, see our chatbot system prompt engineering guide.

Step 5: Configure Tools

The "Tools" tab lets you enable additional features that extend your agent's capabilities beyond simple text responses.

The contact form — built-in lead capture

When a user expresses a desire to be contacted, called back, or to receive a quote, the agent can automatically trigger a contact form. This is the most powerful tool for turning your chatbot into a lead generation engine.

To enable it: in the "Tools" tab, activate the contact form. You can configure which fields to collect — name, email, phone, message — based on your needs.

Once enabled, the agent automatically detects contact intent signals in the conversation ("I'd like to be called back", "Can you send me a quote?", "I'd like to speak with someone") and surfaces the form at the right moment — with no manual intervention on your part.

For more on lead capture and qualification logic with chatbots, our article on AI chatbot lead generation covers best practices in depth.

Testing form triggers

In the "Conversations" tab, test phrases that should trigger the form:

• "I would like to be contacted by your team."
• "Can someone give me a call?"
• "I would like a custom quote."

Verify that the form appears in these cases, and that it does not appear for simple informational questions ("What are your shipping timelines?"). If triggering is too frequent or too rare, adjust the system prompt by specifying the exact conditions under which the form should appear.

A note on plans and limits

Some advanced features depend on your plan. The free plan lets you test all tools, but with a limited message quota. The exact per-plan limits are available on the pricing page. You do not need to upgrade to create your first agent and validate the concept.

Step 6: Embed the Agent on Your Website

Your agent is configured and tested. Time to deploy it. Go to the "Connect" tab inside your agent.

Get the embed code

You will find a ready-to-use JavaScript snippet. It looks like this:

<script
  async
  src="https://heeya.fr/agent/{your-agent-uuid}/embed.js"
  data-agent-name="Your Assistant Name"
  data-position="bottom-right"
  data-color="#0d9488"
  data-text="How can I help you today?"
></script>

Available customization options

• data-agent-name: the name displayed in the widget on your site
• data-position: widget position — bottom-right or bottom-left
• data-color: primary widget color in hex format — match your brand palette
• data-text: welcome message shown in the bubble before the user opens the chat

Embedding on a standard HTML site

Paste the snippet just before the closing </body> tag on your page. The widget loads asynchronously and will not block your page render.

Embedding on WordPress

Several methods work on WordPress:

• Via the theme: add the snippet to your theme's footer.php file, just before </body>.
• Via a plugin: use an "Insert Headers and Footers" plugin (e.g., WPCode) to paste the script without touching theme code.

Embedding on Shopify

In your Shopify admin, go to Online Store → Themes → Actions → Edit code. Open the theme.liquid file and paste the snippet just before </body>. Save — the widget is now active on every page of your store.

Our full guide on Shopify AI chatbot integration covers the platform in detail with step-by-step instructions.

Step 7: Monitor Performance with Analytics

Once your agent is live, the "Analytics" tab gives you an overview of activity: number of conversations, messages exchanged, distribution over time.

What to monitor first

• Conversation volume: how many users start a conversation? A low volume may indicate a widget visibility issue (position, color, or an uninviting welcome message).
• Conversation depth: how many exchanges per session on average? A low depth may signal that first responses are not satisfying users.
• Recurring questions without satisfying answers: read through conversations. If the same type of question keeps coming up with poor responses, that is a signal to enrich your knowledge base on that specific topic.
• Contact form submissions: how often is the form submitted? This is your direct conversion indicator.

Using conversations to improve the agent

Real conversations are the best source of improvement. Spend 15 minutes per week reading recent exchanges. You will quickly identify:

• Knowledge base gaps (questions the agent cannot answer due to missing documents)
• System prompt phrasing to refine (the agent is too formal, not precise enough)
• New user needs to address (topics that are not covered but come up repeatedly)

For a deeper look at which metrics to track, our article on AI chatbot KPIs and performance metrics covers the key indicators and how to interpret them.

Common Mistakes and How to Avoid Them

Mistake 1 — A system prompt that is too vague

Symptom: the agent responds generically, shifts tone between replies, or drifts outside its scope.
Fix: be explicit about the role, tone, covered topics, and especially the limits. "You are a customer service assistant" is not a system prompt — it is a job title. Describe expected behaviors with concrete examples.

Mistake 2 — Uploading large, unstructured documents

Symptom: the agent struggles to surface precise information from a long document; responses are vague.
Fix: split documents by topic. A single 200-page mixed document is less effective than five focused 40-page files. Clear internal structure (headings, sections) also improves chunking quality.

Mistake 3 — Not testing with difficult questions

Symptom: the agent seems fine during testing but disappoints real users.
Fix: always test with ambiguous, out-of-scope, or knowledge-gap questions. A robust agent knows how to say "I don't know" without inventing.

Mistake 4 — Ignoring Analytics after launch

Symptom: agent quality stagnates despite growing usage.
Fix: schedule a 15-minute weekly slot to read recent conversations and identify improvements. An AI agent improves continuously — not just at launch.

Mistake 5 — Enabling the contact form without conditions

Symptom: the form triggers too often, even for simple questions, frustrating users.
Fix: in your system prompt, explicitly define the signals that should trigger the form. Example: "Only offer the contact form when the user explicitly expresses a desire to speak with a human or to receive a custom quote."

Mistake 6 — Copy-pasting a generic prompt found online

Symptom: the agent feels impersonal and inconsistent with your brand.
Fix: use the templates in this guide as a starting point, but always customize. Your company name, specific products, brand voice — these details are what separate a generic chatbot from a true brand representative.

Mistake 7 — Ignoring free plan limits

Symptom: the agent stops responding mid-month with no apparent explanation.
Fix: check the pricing page for free plan quotas. If your usage exceeds these limits, upgrade to the right plan before the quota is reached. The "Settings" tab of your agent shows your current consumption.

FAQ — Building Your First AI Agent with Heeya

Conclusion

Building a functional AI agent is no longer the exclusive domain of technical teams. In 10 minutes with Heeya, you have everything you need to deploy a chatbot that answers your users precisely, captures qualified leads, and improves continuously based on real conversations.

The key to success is not in the initial setup — it is in the iteration cycles that follow. Read your conversations, enrich your knowledge base, refine your system prompt. An AI agent is a living tool, not a static deployment.

If you want to explore the platform's full capabilities, our custom AI chatbot page covers advanced use cases and integration options with your existing tools. And if you are starting without a structured knowledge base yet, our guide on how to build an AI chatbot with no code walks you through every step.

Further reading

• What Is RAG? The Complete Business Guide
• Chatbot System Prompt Engineering: Master Your AI Instructions
• How to Build an AI Chatbot with No Code: Complete Guide
• Shopify AI Chatbot Integration Guide
• AI Chatbot KPIs: How to Measure Your Agent's Performance
• Our RAG Expertise — Architecture and Implementation