> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Your MerchantAI Agent: A Complete Guide

> A complete walkthrough for creating your MerchantAI workspace, connecting knowledge sources, configuring guardrails, and deploying your agent.

Getting your MerchantAI agent live involves a handful of deliberate steps — from creating your workspace and connecting your content, through to tuning guardrails and dropping the widget onto your site. This guide walks you through every stage in order, so you arrive at a tested, production-ready agent rather than one that surprises you in front of real customers.

<Steps>
  <Step title="Create your workspace">
    Sign up at [merchantai.io](https://merchantai.io) and create your first workspace. Each workspace maps to a single website or Shopify store — it holds the agent's knowledge base, brand voice settings, handover configuration, and analytics for that property. If you run multiple stores or brands, you create a separate workspace for each one.
  </Step>

  <Step title="Connect your site">
    Enter your website URL in the **Sources** panel. MerchantAI's crawler indexes your public pages automatically — product pages, policy documents, blog posts, and general content — so the agent can answer questions grounded in your actual site content. The crawler re-runs whenever you trigger a manual sync or (for Shopify) when a product or policy update is detected.
  </Step>

  <Step title="Add knowledge sources">
    Supplement the crawled content with any additional material your agent needs to know:

    * **PDFs and DOCX files** — upload sizing guides, specification sheets, warranty documents, or internal FAQs.
    * **Q\&A pairs** — add discrete question-and-answer entries for questions you know visitors ask but that aren't covered well by your existing pages.
    * **Shopify catalogue** — if your workspace is connected to a Shopify store, install the MerchantAI Shopify app to sync products, variants, collections, policies, and blog posts automatically. The sync updates on store changes via webhooks, so pricing and inventory stay current.

    All sources you add are scoped to this workspace only and are never shared across agents.
  </Step>

  <Step title="Set your brand voice">
    Navigate to **Configuration → Brand Voice**. You can either select one of the built-in presets (Friendly, Professional, Concise, Warm) as a starting point, or write a fully custom system prompt. The system prompt is the core instruction document that governs how your agent introduces itself, what tone it uses, what it should never say, and when it should escalate to a human. See the [Brand Voice guide](/configuration/brand-voice) for a full walkthrough.
  </Step>

  <Step title="Configure guardrails">
    In **Configuration → Guardrails**, set the confidence threshold that determines when the agent answers versus when it hands over to a human. A lower threshold means the agent is more cautious and escalates more often; a higher threshold means it attempts to answer in more ambiguous situations. You can also add topic blocklists — specific subjects (for example, medical advice, legal questions, or competitor comparisons) that the agent should always decline and redirect to your team.
  </Step>

  <Step title="Set up handover">
    Decide how you want unanswered or escalated conversations to reach your team:

    * **Email handover** — enter an email address under **Configuration → Handover**. When handover is triggered, MerchantAI sends a notification with the full conversation transcript, visitor contact details, source pages referenced, and a timestamp.
    * **Contacts inbox** — every handover conversation also appears in the **Contacts** inbox in your dashboard, where a team member can review history or take over the conversation live.

    See the [Handover guide](/configuration/handover) for detailed setup instructions.
  </Step>

  <Step title="Preview your agent">
    Before you send a single real visitor to your agent, use the **Preview** chat in the dashboard. Ask the kinds of questions your customers actually ask — product questions, delivery questions, edge cases, and anything you'd be embarrassed to see a bad answer to. Adjust the system prompt, knowledge sources, or guardrail settings based on what you observe. The preview runs against your live configuration, so what you see is exactly what visitors will get.
  </Step>

  <Step title="Deploy">
    When you're satisfied with the preview, deploy the widget:

    * **Shopify** — install the MerchantAI app from the Shopify App Store. The chat widget appears on your storefront automatically. Custom themes can paste the single `<script>` tag instead.
    * **Any other website** — copy the JS widget snippet from **Configuration → Deploy** and paste it before the closing `</body>` tag on your site.

    Your agent is now live and answering visitor questions.
  </Step>
</Steps>

## Workspace settings

A few workspace-level settings are worth reviewing once your agent is up and running:

* **Workspace name** — used internally to identify this property in your dashboard. Useful if you manage multiple workspaces.
* **Agent name** — the display name visitors see in the chat header (for example, "Mia" or "Support"). You can update this at any time without redeploying.
* **Language and locale** — set the primary language your agent responds in. MerchantAI will match the agent's default language to this setting, though it can detect and respond to visitor messages in other languages where content is available.

<Tip>
  Don't rush through the preview step. Spending 20–30 minutes testing real customer phrasing before going live is the single best way to catch gaps in your knowledge sources and awkward responses in your system prompt — before visitors do.
</Tip>

## Multiple agents

If you operate more than one website, brand, or Shopify store, you can create additional agents within your account:

* **Pro plan** — supports up to 3 agents, each in its own workspace with independent knowledge bases, brand voice, and handover settings.
* **Business plan** — supports up to 5 agents, suited to multi-brand retailers or agencies managing several properties.

Each agent is fully isolated — knowledge, configuration, contacts, and analytics never cross workspace boundaries.