# Build your first agent

> A step-by-step walkthrough. Create an agent from your website, test it, and add a chat bubble to your site in about 15 minutes.

This guide walks you through building a working agent from scratch and putting it on your website as a chat bubble. You'll answer a few setup questions, check the agent's first answers, and then go live. Plan on about 15 minutes, plus a few minutes to add a small piece of code to your website.

**Where to start:** go to your list of agents and select **New AI agent**.

> [!NOTE] Before you begin
> Have these ready:
> - Your **website address**, or a few documents that answer common questions (a returns policy, a shipping page, an FAQ).
> - **Five to ten real questions** your customers ask. You'll use them to test the agent.
> - **A way to edit your website**, or the contact details of the person who does.

1. **Create**: Answer four short questions in the setup assistant.
2. **Check**: Wait for training, then review the instructions.
3. **Test**: Chat with your agent in the Playground.
4. **Go live**: Publish the chat bubble and add it to your website.

## Step 1: Create the agent

When you select **New AI agent**, a setup assistant opens. It asks you one thing at a time, like a chat. The steps along the top show where you are: **Knowledge**, **Personality**, and **Channels**, plus **Website pages** when you add a website.

![The agent setup assistant asking "What should your agent know?" with acme.com entered and a returns policy PDF added](https://hourzero.dev/marketing/app/onboarding-knowledge-light.webp "The first question: what should your agent know? Here, Acme adds its website and a returns policy PDF.")

> [!TIP]
> Changed your mind about an earlier answer? Select **Edit** under that answer to go back to that step.

### Tell it what to know

1. Under **Your website (recommended)**, type your website address, for example `acme.com`. You don't need to type `https://`.
2. To add more information, select **Add files, text, Q&A and more**. You'll see three tabs:
   - **Files**: drop files in, or click to browse. You can add PDF, DOC, DOCX, XLSX, PPTX, CSV, TXT, and MD files.
   - **Text**: give it a **Title** and paste the **Content**. Handy for things that aren't on your website, like holiday opening hours.
   - **Q&A**: select **Add pair**, then type a **Question** and the exact **Answer** you want customers to get.
3. Select **Continue**. Hourzero gets to know your business the way you'd brief a new employee. It reads your homepage, about, contact, terms, and policy pages in full, looks up what reviews and articles on other websites say about you, lists the questions your customers ask, and checks which of your pages answer them. Then it picks the pages your agent should learn from. Its thinking and each step it takes, like reading a page or searching the web, appear in the conversation as it works; select a step to see its details. When it's done, the steps fold into a **Worked for** line you can open again. Small websites take under a minute; large online stores can take up to four. To stop it, select **Stop**.

Have a sitemap file? Select **Upload sitemap.xml** under the website field and choose the file. Hourzero lists the pages in it, so you don't have to type them. The file is read in your browser and isn't stored.

No website? Leave the field empty and the button changes to **Continue without website**. You can build an agent from files, text, and Q&A alone, or even start empty and add knowledge later.

### Review your website pages

Hourzero tells you what it learned about your business and what others say about it, and how many of your customers' questions the pages it picked answer. Select **Show questions** to see them.

Some questions your website doesn't answer, or only answers in part, like how to cancel an order. They're listed under **Your website doesn't fully answer**. Select **Answer** next to one and type the answer your agent should give. Your answers are added to the agent as Q&A.

Below that are the pages Hourzero picked, grouped like folders on your computer, each with a short note on what it tells customers. It picks the pages customers ask about, like help, FAQ, pricing, shipping, returns, and contact pages. On a large store it doesn't list every product: it picks your categories and collections, which show many products and their prices, plus your featured products.

To see every page Hourzero found, including the ones it didn't pick, select **All pages**. Select **Selected** to go back to its picks.

![The page picker showing pages found on the website, grouped by section, with checkboxes](https://hourzero.dev/marketing/app/onboarding-pages-light.webp "Uncheck the pages that won't help customers. Unchecking a folder unchecks every page in it.")

1. Uncheck pages that won't help customers, such as job listings, old blog posts, login pages, or long legal text.
2. Use **Search** to find a page quickly in a long list.
3. Missing a page? Type its address under **Add another URL**, for example `/shipping`, and select **Add URL**. It must be on the same website.
4. Missing a lot of pages? Select **Upload sitemap** and choose your sitemap file to add every page it lists.
5. Select **Continue**.

You can include up to 100 pages during setup. You can add more later from **Build → Data Sources**.

> [!TIP]
> Fewer, better pages beat lots of pages. Your shipping, returns, pricing, FAQ, and product pages usually matter most.

### Give it a role

If you added a website, Hourzero has already chosen a role and written what your agent will do, based on your website and what others say about your business: who it talks to, what it recommends, how it presents your business against the alternatives, and when to hand over to your team. It's written in the language your website uses with customers.

1. Check the role in the corner of the text box: **Customer support**, **Sales agent**, or **Shopping assistant**. Change it if it's not right.
2. Under **What will your agent do?**, edit the text in your own words. Say who it helps, what it should help with, and anything it must not do. To go back to Hourzero's text, select **Use my suggestion**.
3. Select **Continue**.

Here's an example for an online clothing store:

```text
Help Acme customers with orders, shipping, returns, and sizing.
Be friendly and brief: answer first, then give the next step.
Never promise refunds or delivery dates that aren't in our policies.
If someone has a billing problem, offer to connect them with our team.
```

Hourzero combines this description with your website to write the agent's full instructions and guardrails. You can change everything afterwards.

> [!NOTE]
> If you've already edited the text and then switch roles, Hourzero keeps your words. Only the untouched default suggestion is replaced.

### Choose where it appears

Pick the places you'd like to use this agent. **Chat Bubble** is already selected. For this guide, keep **Chat Bubble**; you can add WhatsApp, Instagram, and other channels any time later.

![The channel picker with Chat Bubble selected among website and messaging channels](https://hourzero.dev/marketing/app/onboarding-channels-light.webp "Pick one or more channels. You can change this later.")

Select **Create agent**.

### What happens next

Hourzero saves your agent and opens **Build → Data Sources**. A box at the top says **Preparing your agent in the background**. During this time Hourzero:

1. Reads the pages and files you chose.
2. Trains the agent on them.
3. Writes the agent's instructions and guardrails from your description.

This usually takes a few minutes. You can leave the page and come back. Your agent is named after your website (for example `acme.com`); rename it any time under **Settings → Agent details**.

## Step 2: Check that training finished

Stay on **Build → Data Sources**. Each source shows a status: **Pending**, **Processing**, **Ready**, or **Failed**.

![The Data Sources page listing a help center website, a returns policy PDF, Q&A pairs, and text notes, each with a status](https://hourzero.dev/marketing/app/data-sources-light.webp "Each source shows its status. When you change sources later, the box at the top reminds you to retrain.")

You're ready to continue when the box at the top says **Agent is trained**.

- **Setup needs attention?** Select **Retry setup**. Your agent and sources are already saved, so nothing is lost.
- **A source says Failed?** Add it again with **Add new file** or **Add new webpage**, or try a different page or file. Archive the failed one so it stays out of training.

> [!IMPORTANT] Retrain after every knowledge change
> Whenever you add, edit, archive, or restore a source later, select **Train agent** (or **Retrain agent**) on this page. Until you do, the agent keeps using what it learned last time.

## Step 3: Review the instructions

When setup finishes, open **Build → Instructions**. If you're still on the Data Sources page, a message tells you **Instructions and guardrails are ready**.

![The Instructions page with General Instructions for role, tone, and escalation, and a short list of guardrails](https://hourzero.dev/marketing/app/instructions-light.webp "General Instructions describe the agent's job. Guardrails are the rules it must always follow.")

You'll see two boxes:

- **General Instructions**: the agent's job description. Who it works for, what it helps with, how it should sound.
- **Guardrails**: the rules it must never break.

Read both and check that:

- your business name and what you sell are correct;
- the topics it should help with are listed;
- the tone sounds like your brand;
- it knows when to offer a person, and how customers can reach your team.

Want a second opinion? Select **Improve with AI**. Hourzero reviews the text and suggests improvements. You read the suggestions and choose whether to use them.

When you're happy, select **Save changes**.

## Step 4: Test it in the Playground

Select **Playground** in the sidebar. Settings are on the left, and a working chat is on the right. Make sure **Preview channel** at the top left says **Chat Bubble**.

Now chat with it as if you were a customer. Try a mix of questions:

| Try this | Example | A good agent… |
| --- | --- | --- |
| A common question | "How long does shipping to Canada take?" | Answers correctly from your information. |
| The same question, worded differently | "when will my order get to toronto" | Still gets it right. |
| Something your information doesn't cover | "Do you sell gift cards?" | Says it doesn't know, instead of guessing. |
| Something off-topic | "Write me a poem about cats." | Politely steers back to how it can help. |
| Something that needs a person | "I was charged twice for my order." | Offers a clear next step. |

![The Playground with the Acme Support agent helping a customer return a jacket](https://hourzero.dev/marketing/app/playground-chat-light.webp "The Playground chat talks to your draft. Customers can't see any of this.")

If an answer isn't right, here's what to change:

- **A fact is wrong or missing**: fix or add a data source, then retrain.
- **The behavior or tone is off**: edit the instructions, then select **Save changes**.
- **Answers are too long**: add a line to the instructions such as "Keep answers to two or three sentences."

Then test again. Use **Start over** (the circular arrow at the top of the chat) to begin a fresh conversation.

> [!TIP]
> Your Playground chats are saved. Find them later under **Activity → Conversations** with the **Playground** filter.

## Step 5: Make it look like your brand

Still in the Playground, open the **Display** tab. Here you can change:

- **Display name**: the name shown at the top of the chat, like "Acme Support".
- **Welcome message**: the first thing visitors see, for example "Hi! I can help with orders, returns, and shipping."
- **Colors and style**: pick a ready-made style or set your own accent color and avatar.
- **Suggested prompts**: up to four questions visitors can tap to get started, one per line.
- **Launcher position**: put the bubble at the **Bottom right** or **Bottom left** of your page.

The preview updates as you type. When you're done, select **Save draft** at the bottom left.

> [!NOTE]
> These settings are per channel. Styling the Chat Bubble doesn't change how your agent looks on other channels.

## Step 6: Put it on your website

1. Make sure you've saved everything. The bottom left of the Playground should say **Draft saved. Publish this channel to apply your changes.**
2. At the top right, select **Publish**, then **Website widget**. A window called **Deploy to your website** opens.
3. Under **Allowed domains**, type the website address where the bubble should appear, one per line. It saves automatically; wait until it says **Saved to draft**.
4. Select **Publish saved draft**. You'll see a message that the Chat Bubble was published.
5. Under **Install the widget**, select **Copy code**.
6. Paste the code into your website, just before the closing `</body>` tag, on every page where the bubble should appear. Then save or publish the change on your website.

![The Deploy to your website window with allowed domains, the embed code, and the publish button](https://hourzero.dev/marketing/app/playground-publish-light.webp "Allowed domains, the code to paste into your website, and the publish button, all in one place.")

The code looks something like this. Always copy yours from the window, because it contains your own agent's ID:

```html
<script
  src="https://hourzero.dev/embed.js"
  data-agent-id="acme-support"
  data-channel="chat-bubble"
  defer
></script>
```

Most website builders have a setting for code that should load on every page, often called "custom code", "footer code", or "code injection". If you're not sure where it goes, send the code to whoever manages your website.

### Getting allowed domains right

Allowed domains are a safety lock: the bubble only works on the websites you list. Type just the address to show it on every page.

| You type | The bubble works on |
| --- | --- |
| `acme.com` | `acme.com` only |
| `www.acme.com` | `www.acme.com` only |
| `*.acme.com` | Every subdomain, like `www.acme.com` and `shop.acme.com`, but not `acme.com` itself |
| `acme.com` and `*.acme.com` on two lines | All of the above |

> [!WARNING]
> If the list is empty, the bubble won't work on any website. A line like `acme.com/help` shows the bubble on that one page only. See [Show the widget on certain pages](https://hourzero.dev/docs/integrations/website-widget#show-the-widget-on-certain-pages).

## Step 7: Check that it's live

1. Open your website in a browser and refresh the page. The chat bubble appears in the corner.
2. Ask one of your test questions.
3. Back in Hourzero, open **Activity → Conversations** and select the **Visitors** filter. Your test chat is there.

Congratulations, your first agent is live.

### The bubble doesn't appear?

Check these in order:

1. **Did you publish?** Saving isn't enough. Open **Publish → Website widget** and check the message above the publish button.
2. **Is the exact domain listed?** If your site is `www.acme.com`, then `acme.com` alone isn't enough. Add `www.acme.com` or `*.acme.com`.
3. **Is the code on that page, and is your website change published?** Some website builders need you to publish the site after adding code.
4. **Are replies turned on?** In the Playground **Overview** tab, **Agent replies** should say **Replies on after publishing**. If you change it, save and publish again.

Still stuck? See [Troubleshooting](https://hourzero.dev/docs/help-and-support/troubleshooting).

## Making changes later

From now on, every improvement follows the same short loop. Customers keep getting the current live version until you publish again.

1. **Change**: Edit knowledge, instructions, or channel settings.
2. **Save**: Retrain if you changed knowledge.
3. **Test**: Try your questions in the Playground.
4. **Publish**: Select Publish, then Publish latest draft.

## Next steps

- [Tips for a great agent](https://hourzero.dev/docs/quick-start/best-practices): Simple habits that make answers more accurate.
- [Add more knowledge](https://hourzero.dev/docs/ai-agent-management/data-sources): Everything about files, website pages, text, and Q&A.
- [Connect WhatsApp](https://hourzero.dev/docs/integrations/whatsapp): Answer customers on your WhatsApp business number too.
- [Let your agent do things](https://hourzero.dev/docs/ai-agent-management/actions/overview): Collect leads, show buttons and forms, and hand chats to your team.
