# Build your agent

Twenty steps in the order they depend on each other, from an empty workspace to an agent that answers your website, your WhatsApp and your phone.

Source: https://docs.omazy.ai/guides/build-your-agent/

import Figure from '../../../components/Figure.astro'
import Screen from '../../../components/Screen.astro'
import { Steps, Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'

Rina runs Nordwell, a furniture shop with two showrooms and about four hundred
products online. They deliver across the city. Every day the same four questions
arrive: is this in oak, where is my delivery, do you come out to my area, and
can I see it before I buy. Some arrive by web chat, most by WhatsApp, and the
awkward ones by phone at eight in the evening.

Rina and Nordwell are invented, a stand-in business so that every step has a
real problem attached to it, while the console screens, journeys and channels
described are the actual ones.

Rina has no engineers. What follows is what they did, in order, and what each
step gave them. Twenty steps across eight stages, spread over about two weeks
without rushing.

The order matters more than the speed. Several steps are meaningless until the
one before them is decided, and two of them are the reason a later step works at
all.

## The eight stages

| Stage | What happens | Steps |
|---|---|---|
| 1. Set it up | A workspace, and an agent that already looks like your business | 1 to 3 |
| 2. Teach it | The brief, your knowledge, your help articles, your products | 4 to 7 |
| 3. Shape how it talks | Shortcuts, exact wording, and knowing who is on the other end | 8 to 10 |
| 4. Give it hands | Journeys, your existing tools, and where the work lands | 11 to 13 |
| 5. Choose the engine and prove it | Pick the model, then score it before a customer does | 14 to 16 |
| 6. Put it on your site | The widget, and the moment a human takes over | 17 to 18 |
| 7. Give it a phone | Languages, a voice, a greeting, a number | 19 |
| 8. Run it | Reports, budgets, your team, and what to fix next | 20 |

---

## Stage 1: set it up

The goal today is not a good agent. It is an agent that exists, has your logo on
it, and says your company name back to you.

### 1. Create the workspace and the app

Two words carry all the structure, so they are worth thirty seconds.

**Workspace** is your company. Your team, your billing and your usage sit at
this level. **App** is one brand inside it, with its own agent, its own
knowledge and its own inbox.

Nordwell is one company selling one thing, so Rina needs one of each. Signing up
creates both, so in practice this step is done before you first see the console.
A second app only earns its place when there is genuinely a second brand that
would give different answers to the same question.

> **What this gives you.** A home for everything that follows, with your team
> and your billing already attached to it.

### 2. Let it read your website

The setup wizard offers two doors. Behind the first you paste your website
address and the platform reads your homepage. Behind the second, for businesses
with no site worth reading, you answer a few short questions instead.

Rina pastes the Nordwell address. A minute later the review screen comes back
with a proposed name, the brand colour found in the page, the logo picked out of
the markup, a first draft of how the assistant should introduce itself, and a
set of questions and answers pulled from the site copy.

<Screen
  path="Agent  /  Set up from my website"
  label="The setup review screen, with each proposed change on its own switch"
  caption="Nothing is applied until you press Apply. Every proposal has its own switch, so you keep the logo and drop the two FAQ entries that were marketing rather than fact."
>
  <div class="screen-head">
    <span class="t">Review what we found</span>
    <span class="ui-btn primary">Apply selected</span>
    <span class="d">Turn off anything you would rather write yourself.</span>
  </div>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Name</b><span class="sub">Nordwell</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Brand color</b><span class="sub">Read from the page theme</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Logo</b><span class="sub">Found in the page markup</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Assistant persona</b><span class="sub">A first draft you will rewrite in step 4</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>8 questions and answers</b><span class="sub">2 look like marketing copy</span></span>
      <span class="ui-toggle">off</span>
    </div>
  </div>
</Screen>

<Aside type="tip">
You can run this again later. After a site redesign the same screen comes back
as **Read my website again** and proposes a fresh set of changes for you to
accept or ignore.
</Aside>

> **What this gives you.** An agent carrying your logo, your colour and a rough
> draft of your voice, before you have written a word.

### 3. Set the profile, then talk to it

Four fields decide how the agent presents itself: its name, a one line tagline,
the brand colour, and a plain English description of how it should behave. Rina
names it Nordwell Assistant, taglines it *Furniture, delivery and showroom
questions*, and writes three sentences of description.

Then the part people skip. Open **Preview** and talk to it. Preview runs the
agent exactly as it is configured right now, and nothing you say there reaches
your inbox or your reports, so you can ask the rude question you would never
risk in front of a customer.

It will be bad. That is the point of finding out now.

> **What this gives you.** A working agent you can hold a conversation with, and
> an honest first read on how far it has to go.

---

## Stage 2: teach it

This stage decides whether the agent is good. Everything after it is tuning. The
console groups these four screens as the Brain, and they deserve most of your
time.

### 4. Write the Agent Brief

The brief is everything the agent knows about who it is and how to reply. You do
not write one long instruction. You add a separate prompt for each thing you
want it to get right, and each one carries a type that tells the agent what kind
of thing it is reading.

| Type | What it is for |
|---|---|
| **Identity** | Give the agent its voice and character |
| **Role** | Define the job it does and where it stops |
| **Instruction** | Tell it the steps to follow |
| **Context** | Give it facts to always have on hand |
| **Memory** | Record what it has learned about the business |
| **Sample** | Show it what a good answer looks like |
| **Rule** | Set a limit it must never cross |

<Screen
  path="Agent  /  Agent Brief"
  label="The Agent Brief, showing six prompts with their types and the composed token budget"
  caption="Rule carries a mark because publish protects it from AI rewriting. The other six types are categories, not severities, so they share one quiet treatment."
>
  <div class="screen-head">
    <span class="t">Agent Brief</span>
    <span class="ui-btn primary">Publish</span>
    <span class="d">Everything your agent knows about who it is and how to reply.</span>
  </div>
  <div class="ui-tabs"><span class="on">Prompts 6</span><span>Composed and publish</span></div>
  <div class="ui-list">
    <div class="ui-row">
      <span class="ui-chip">Identity</span>
      <span class="grow"><b>How we talk to customers</b></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="ui-chip">Role</span>
      <span class="grow"><b>What I answer, and when I hand over</b></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="ui-chip mark">Rule</span>
      <span class="grow"><b>Never quote a delivery date</b></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="ui-chip mark">Rule</span>
      <span class="grow"><b>Never say an item is in stock</b></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="ui-chip">Sample</span>
      <span class="grow"><b>Oak versus walnut, answered well</b></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="ui-chip">Context</span>
      <span class="grow"><b>Showroom addresses and hours</b></span>
      <span class="ui-toggle on">on</span>
    </div>
  </div>
  <div class="ui-meter" aria-hidden="true"><i class="s2"></i><i class="s2"></i><i class="s4"></i><i class="s3"></i><i class="s1"></i></div>
  <div class="ui-legend"><span>Identity</span><span>Role</span><span>Rule</span><span>Sample</span><span>Context</span></div>
</Screen>

Rina writes six. Three things about this screen save real time later. Every
prompt can be switched off without deleting it, so you can test whether a rule
is what caused a bad answer. Every prompt keeps its own version history. And the
**Composed and publish** tab shows the whole brief exactly as the agent receives
it, with a bar showing how much of the budget each type is eating.

<Aside type="caution">
Publishing is a separate, deliberate press. Until you publish, your edits are
saved but not live, so a half written rule can sit there overnight without a
customer ever meeting it.
</Aside>

> **What this gives you.** An agent that stays on message, knows what it may not
> guess at, and can be rolled back one prompt at a time.

Detail on how the seven types compose is in
[Writing the brief](/how-to/agent/brief/).

### 5. Load the Knowledge

An agent with no material to read is a confident stranger. This screen has three
tabs.

**Sources** is anything that updates on its own. Add a website and set how many
pages and how deep to go. Add an RSS or podcast feed and every item becomes a
document. **Documents** is everything indexed, from any origin: PDFs, text,
markdown, spreadsheets, CSVs, or something you write by hand right there.
**Usage** shows what the indexing cost and what ran when.

<Screen
  path="Agent  /  Knowledge  /  Sources"
  label="A website source showing pages found, pages fetched, documents produced and errors"
  caption="The four counters are the point of this tab. A crawl that found 61 pages and produced 12 documents did not work, and without these numbers you would not know until an answer was wrong."
>
  <div class="screen-head">
    <span class="t">Knowledge</span>
    <span class="ui-btn">Add knowledge source</span>
  </div>
  <div class="ui-tabs"><span>Documents 74</span><span class="on">Sources 2</span><span>Usage</span></div>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>nordwell.example</b><span class="sub">Website  ·  max 120 pages  ·  depth 3</span></span>
      <span class="ui-chip ok">Done</span>
    </div>
    <div class="ui-grid">
      <div class="ui-card"><b>61</b><span>Found</span></div>
      <div class="ui-card"><b>61</b><span>Fetched</span></div>
      <div class="ui-card"><b>58</b><span>Docs</span></div>
      <div class="ui-card"><b>0</b><span>Errors</span></div>
    </div>
  </div>
</Screen>

Rina crawls the site, then uploads the delivery zone sheet as a spreadsheet and
the care instructions PDF the manufacturer sends. Then they write two documents
by hand, because the site has never said either out loud: the real returns
window, and the fact that Sunday delivery exists but costs extra.

<Aside type="tip">
There is a **Test search** button. Use it. Type a customer question and see
which documents come back. If the right document is not in that list, the agent
was never going to find it either, and no amount of prompt writing fixes that.
</Aside>

> **What this gives you.** Answers that come from your own material instead of
> being invented to fill a gap.

More in [Adding knowledge](/how-to/agent/knowledge/).

### 6. Write the Help center

Help articles do two jobs at once. Visitors browse them inside the chat widget
like a small help site, and the agent answers from them. A good article is paid
for twice.

This is the place for the questions you answer by hand every day. Rina writes
eight, starting with the four that were the reason for buying any of this: oak
versus walnut, delivery areas and timings, the returns window, and how to book a
showroom visit.

Keep crawled pages in Knowledge and keep the articles you wrote on purpose here.
The separation matters when an answer goes wrong, because you want to know
instantly whether the source was something you authored or something the crawler
found.

> **What this gives you.** The ten questions that used to interrupt your day get
> answered without you, and visitors can browse them without asking at all.

### 7. Build the Catalog

Knowledge lets the agent describe your products. The catalog lets it show them,
with a picture, a price and a link, inside the chat.

Each item takes a title, images, a category and collection, tags, a description,
a list of features, a link to the product page, and a price. Price is flexible on
purpose: a fixed amount, a per unit amount, a set of duration tiers for anything
hired rather than sold, or nothing at all when the honest answer is on request.

<Screen
  path="Agent  /  Catalog"
  label="The catalog list with readiness marks and the demand gaps panel"
  caption="Readiness is checking four things per item: image, price, category, description. An item with no image renders as a blank card in the chat, which looks worse than not showing it."
>
  <div class="screen-head">
    <span class="t">Catalog</span>
    <span class="ui-btn">Import CSV</span>
    <span class="d">Products and services for your widget, also indexed so the AI can recommend them.</span>
  </div>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Ashmere oak dining table</b><span class="sub">Dining  ·  from 1,240</span></span>
      <span class="ui-chip ok">Ready</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Lindholm two-seat sofa</b><span class="sub">Living  ·  from 890</span></span>
      <span class="ui-chip ok">Ready</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Verity bar stool</b><span class="sub">Kitchen  ·  price not set</span></span>
      <span class="ui-chip">Missing image, price</span>
    </div>
  </div>
  <div class="ui-row">
    <span class="grow"><b>Demand gaps</b><span class="sub">Asked for 14 times this fortnight, nothing matched: bar stools</span></span>
  </div>
</Screen>

Four hundred products is too many to type, so Rina exports from the shop system
and uses the CSV import. **Readiness** then flags every item missing an image, a
price, a category or a description. **Demand gaps** collects what customers
searched for and found nothing for. After a fortnight Rina discovers people keep
asking for bar stools, which Nordwell sells but never listed online.

> **What this gives you.** The agent recommends real products with real pictures
> and real prices, and starts telling you what you are missing.

---

## Stage 3: shape how it talks

The agent now knows things. This stage is about manners: making replies quick to
answer, making certain sentences exact, and learning who is on the other end.

### 8. Add answer suggestions

When the agent asks a question, it can offer the answers people usually give as
tappable pills. You write a rule by giving it the words that appear in the
agent's question and the options to show.

<Screen
  phone
  path="The widget on a phone"
  label="A chat on a phone where the agent's question is followed by three tappable pills"
  caption="Shortcuts, not a menu. The visitor can ignore every pill and type whatever they want, and roughly half of them do."
>
  <div class="ui-chat">
    <div class="ui-msg">The Ashmere comes in oak and walnut. Which were you thinking?</div>
    <div class="ui-pills"><span>Oak</span><span>Walnut</span><span>Not sure yet</span></div>
    <div class="ui-msg them">Oak</div>
    <div class="ui-msg">Good choice. Oak is in both showrooms if you want to see it before you buy.</div>
  </div>
</Screen>

Rina adds three rules. Wood gets Oak, Walnut and Not sure yet. Delivery gets the
three zones. Showroom gets the two branches.

> **What this gives you.** Conversations that finish in three taps instead of
> three paragraphs, which matters a great deal on a phone.

More in [Suggestion pills](/how-to/agent/suggestions/).

### 9. Write the saved responses

Some sentences must be exact. Bank details, a booking confirmation, a refund
policy line, the opening greeting. You do not want a language model choosing its
own words for any of those, however good it is.

A saved response is a message you wrote, delivered exactly as written, with live
values filled in. Each one has a key and can hold a version per language. There
are two ways one gets used. **Bound** responses fire automatically at a moment,
such as the greeting. **Referenced** responses are called by name from a prompt
in your brief, so the agent decides when the moment has arrived but not what to
say.

Rina writes four: the greeting, the delivery charge explanation, the showroom
booking confirmation, and the returns policy. There is a **Draft with AI**
button that gets you a first version, which you then edit until it is your
wording.

<Aside type="note">
Saved responses also hold the fixed phrases for phone calls, so this work is
reused in stage 7 rather than repeated.
</Aside>

> **What this gives you.** The sentences you cannot afford to have paraphrased
> become impossible to paraphrase.

More in [Saved responses](/how-to/agent/saved-responses/).

### 10. Decide how it gets to know people

Two separate settings live here, and confusing them is the common mistake on
this screen.

**Soft identification** is the agent casually asking who it is talking to. You
choose how many messages in it asks, which details it collects from name, email
and mobile, and you write the exact wording of every ask. It never blocks the
chat. If someone ignores the question, the conversation carries on.

**Verification** is a one time code, and it does block.

<Screen
  path="Agent  /  Visitor identity"
  label="The identity and verification settings, with soft identification on and verification set to on demand"
  caption="Browsing sofas needs no code. Asking where your delivery is does. That is the whole reason this step comes before journeys."
>
  <div class="screen-head">
    <span class="t">Identity and verification</span>
    <span class="ui-btn primary">Save identity settings</span>
  </div>
  <span class="ui-eyebrow">Soft identification</span>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Ask who I am talking to</b><span class="sub">Never blocks the chat</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Ask after N messages</b></span>
      <span class="ui-chip">2</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Collect</b></span>
      <span class="ui-chip">name</span><span class="ui-chip">email</span><span class="ui-chip off">phone</span>
    </div>
  </div>
  <span class="ui-eyebrow">Verification (OTP)</span>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Require verification</b></span>
      <span class="ui-chip off">off</span><span class="ui-chip mark">on_demand</span><span class="ui-chip off">required</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Verify via</b></span>
      <span class="ui-chip mark">email</span><span class="ui-chip off">phone</span>
    </div>
  </div>
</Screen>

The three verification settings are **off**, which never asks; **on_demand**,
which asks only when a task needs it, such as looking up an order; and
**required**, which asks for a code before any conversation at all.

> **What this gives you.** Every conversation has a name attached to it, and
> anything private sits behind a check rather than a hopeful assumption.

---

## Stage 4: give it hands

Up to here the agent talks. From here it does things: finishing a task, reaching
into the systems you already run, and putting the result where your team will
see it.

### 11. Turn on the journeys you need

A journey is a job the agent completes rather than only answers. There is a
gallery of ready made ones grouped by what they are for. You do not build them.
You switch one on, tell it where to send the result, and publish it.

| Group | Journeys |
|---|---|
| Support | Submit a ticket, Talk to a human, Request a return, Email transcript |
| Sales | Capture a lead, Request a quote, Callback request |
| Commerce | Find a store, Find a product, Track order, Place an order, Pre-order for tomorrow, Share order feedback |
| Billing | Pay an invoice, Manage subscription, Book an appointment |

<Screen
  path="Journeys"
  label="The journey gallery, with two published, one saved as a draft and one not yet enabled"
  caption="Enable, bind the action, then publish. A journey saved as a draft is configured and inert, which is the right state to leave one in overnight."
>
  <div class="screen-head">
    <span class="t">Journeys</span>
    <span class="d">Goal-completing journeys for your agent. Enable, bind an action, then publish.</span>
  </div>
  <span class="ui-eyebrow">Commerce</span>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Track order</b><span class="sub">live tracker  ·  auth: verify</span></span>
      <span class="ui-chip ok">Published</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Find a product</b><span class="sub">card  ·  auth: none</span></span>
      <span class="ui-chip">Not enabled</span>
    </div>
  </div>
  <span class="ui-eyebrow">Support</span>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Talk to a human</b><span class="sub">card  ·  auth: none</span></span>
      <span class="ui-chip ok">Published</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Request a return</b><span class="sub">card  ·  auth: identify</span></span>
      <span class="ui-chip">Draft</span>
    </div>
  </div>
</Screen>

Each journey arrives with the questions it will ask, the phrases that trigger
it, and how it presents the result. You can rewrite all three. Three settings
decide how it behaves:

<Steps>

1. **The action.** Either a built in one, such as filing a ticket or handing the
   chat to your inbox, or a web address of your own that receives the collected
   answers as a single message.

2. **The result.** A summary card, a set of buttons, or a live tracker.

3. **The access level.** Open to anyone, needs a name and email first, or needs
   a verified code first.

</Steps>

Rina turns on four: Track order pointed at the delivery system, Book an
appointment for showroom visits, Talk to a human, and Capture a lead. Track
order is set to need a verified code, which is why step 10 came first.

<Aside type="caution">
Be specific with trigger phrases. A journey set to fire on the word "order" will
hijack somebody asking whether they can order in walnut, and the customer will
never see the answer they wanted. Narrow phrases beat broad ones every time.
</Aside>

> **What this gives you.** The agent finishes jobs. A delivery question ends
> with a tracked delivery, not with a promise that somebody will get back to
> you.

More in [Journeys](/how-to/engage/journeys/).

### 12. Connect the tools you already run

There are two doors into your other systems, and they suit different situations.

**Integrations** are the ready made connections: Shopify, WhatsApp Business,
WordPress, HubSpot, Stripe, Calendly and Google Drive. You enable one at the
workspace level and assign it to the app that should use it. Grant the least
access that makes it work, because a read only connection cannot cause an
incident.

**Connected tools** is the general purpose door, for systems with no ready made
connection. If yours can publish its actions over MCP, the shared standard tools
now use to describe what they can do, you paste its address and a key and the
agent can call those actions mid-conversation. The connection is scoped to one
app, so a tool connected for Nordwell is not silently available to a second
brand.

Rina connects Shopify for stock and Calendly for showroom slots, and leaves the
general purpose door alone until there is a reason to open it.

> **What this gives you.** The agent reads and writes in the systems that hold
> the truth, instead of holding a stale copy of it.

More in [Channels and integrations](/how-to/connect/channels/) and
[MCP](/how-to/connect/mcp/).

### 13. Decide where the work lands

A conversation that produces work is only useful if the work leaves the
conversation. Five places catch it, and most businesses need two of them.

| Where | What it holds |
|---|---|
| **Tasks** | Follow ups and tickets attached to the app. A filed ticket lands here |
| **Data store** | Custom records the agent reads and writes, for anything that is not a ticket |
| **Events** | The running stream of what happened, which is where you look when something did not fire |
| **Webhooks** | Those events, pushed to a system of yours |
| **Workflows** | Steps chained together, with approvals where a person should sign off first |

Rina uses Tasks and one webhook into the delivery system. The rest can wait until
there is a real need.

> **What this gives you.** Work that starts in a chat ends in your team's queue,
> rather than in a transcript nobody reads.

---

## Stage 5: choose the engine and prove it

The console groups these three screens as Ship. They are the last three before
anybody outside your company can reach the agent.

### 14. Pick the model

The model is the engine that writes the replies. Faster ones cost less and are
fine for short factual answers. Stronger ones handle nuance and awkward
questions better, and cost more per conversation.

You choose a provider and a model, and four dials sit underneath. **Temperature**
controls how varied the wording is. **Top-p** is a second control on the same
thing, and most people leave it alone. **Max tokens** caps how long a reply can
be. There is also a system prompt override, which you should leave empty,
because the Agent Brief already writes that for you.

Two guardrails are worth knowing about. Only models your plan includes appear in
the list. And switching sends a real test message to the new model first, so it
cannot be set to something that does not answer.

<Aside type="tip">
Start on the cheaper model. Move up only when step 15 shows you a specific
question it keeps getting wrong that a stronger model gets right.
</Aside>

> **What this gives you.** The trade between cost and quality becomes a decision
> you make on evidence.

### 15. Score it before a customer does

This screen turns changing the agent from a gamble into a routine. It has five
tabs.

**Suites** are your real questions. Not the ones you wish customers asked. The
awkward one about price belongs here. **Scorers** define what counts as a good
answer. **Runs and A/B** runs a suite, and can run the same suite against two
models side by side so you see the difference rather than argue about it.
**Continuous** watches the pass rate on live conversations. **Gates** marks a
suite as one that must pass, which stops a bad change going out quietly.

<Screen
  path="Agent  /  Testing and evals  /  Runs and A/B"
  label="A suite run showing fourteen of twenty cases passing, with the six failures grouped by cause"
  caption="Six failures is a morning of work, not a mystery, because each one names what was missing."
>
  <div class="screen-head">
    <span class="t">Nordwell, the real twenty</span>
    <span class="ui-btn primary">Run suite</span>
  </div>
  <div class="ui-tabs"><span>Suites 1</span><span>Scorers</span><span class="on">Runs and A/B</span><span>Continuous</span><span>Gates</span></div>
  <div class="ui-grid">
    <div class="ui-card"><b>20</b><span>Cases</span></div>
    <div class="ui-card"><b>14</b><span>Passed</span></div>
    <div class="ui-card"><b>6</b><span>Failed</span></div>
    <div class="ui-card"><b>70%</b><span>Pass rate</span></div>
  </div>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Do you deliver on Sundays?</b><span class="sub">Confidently wrong. No document says so</span></span>
      <span class="ui-chip">Fail</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>How much is the Ashmere?</b><span class="sub">Correct but evasive. A rule is too tight</span></span>
      <span class="ui-chip">Fail</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Is the Lindholm in walnut?</b><span class="sub">Answered from the catalog</span></span>
      <span class="ui-chip ok">Pass</span>
    </div>
  </div>
</Screen>

Rina writes twenty questions from the last month of WhatsApp messages. The first
run fails six. Four are missing knowledge, one is a brief rule that was too
strict, and one is the model being genuinely wrong.

Three failure shapes cover almost everything:

| What you see | What it means |
|---|---|
| Confidently wrong | Knowledge is missing, so it filled the gap |
| Correct but evasive | A brief rule is too tight |
| Correct but endless | You never told it to be brief, and nobody reads paragraph four in a chat window |

> **What this gives you.** You can change the brief, the knowledge or the model
> and know within minutes whether you made it better or worse.

More in [Testing and publishing](/how-to/agent/testing/).

### 16. Publish

One switch decides whether guests can reach this agent at all. The same screen
shows what is currently in effect, what will change when you publish, and how
much bigger or smaller the brief has become since last time.

Taking it offline later stops new conversations without deleting anything, so
going live is a reversible decision rather than a final one.

> **What this gives you.** The agent is reachable. Everything from here is about
> where people can reach it from.

---

## Stage 6: put it on your site

The widget is the front door most customers will use, and it is a small product
in its own right rather than a box that appears in the corner.

### 17. Build the widget

The Widget Studio walks five stages in order: Configure, Preview, Test, Deploy,
Monitor. Configure holds seven panels: Branding, Header and home, Content,
Behavior, Business hours, AI and advanced, and Features.

<Screen
  path="Widget  /  Configure  /  Features"
  label="The five widget capability switches, three on and two off"
  caption="Proactive is off on purpose. A box that jumps at a customer browsing sofas is the fastest way to teach them to close it."
>
  <div class="ui-tabs"><span class="on">Configure</span><span>Preview</span><span>Test</span><span>Deploy</span><span>Monitor</span></div>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>File attachments</b><span class="sub">Let visitors upload images and documents in chat.</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>CSAT rating</b><span class="sub">Ask for a satisfaction score after each resolved conversation.</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Human handoff</b><span class="sub">Route to a live agent in your inbox when the AI is not enough.</span></span>
      <span class="ui-toggle on">on</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Voice input</b><span class="sub">Show a mic affordance so visitors can speak a message.</span></span>
      <span class="ui-toggle">off</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Proactive messages</b><span class="sub">Auto-open with a nudge after a delay or on exit intent.</span></span>
      <span class="ui-toggle">off</span>
    </div>
  </div>
</Screen>

Rina turns on attachments, because customers send photos of the room they are
furnishing, plus the rating and the handoff. Proactive stays off.

**Deploy** then gives ten routes to get it live: a plain snippet for any
website, a prompt you can hand to an AI coding assistant to wire it into your
codebase, Google Tag Manager, WordPress, Webflow, Wix, Squarespace, a Shopify
theme embed that needs no code, a mobile app SDK for iOS and Android, and a QR
code pointing at a hosted chat page.

<Aside type="tip">
The QR code is the one people underestimate. Rina prints it on delivery notes
and puts it on a card in both showrooms, so a customer standing in front of a
sofa can ask about it without finding a member of staff. Scans arrive tagged as
the qr source, so you can measure it.
</Aside>

> **What this gives you.** A front door on every page of your site, in your
> colours, plus a printable one for the physical world.

More in [Widget](/how-to/widget/).

### 18. Set up the handover

The agent needs to know when to stop. Four settings screens decide that, and
they take about twenty minutes together.

**Business hours** set when your team is online and what the agent says when
they are not. **Conversation** covers greetings, automatic closing of stale
chats, and how messages are handled. **Notifications** decide when your team is
emailed or alerted. **Privacy** sets how long chat and call data is kept.

Everything handed over lands in the **Inbox**, where a person picks it up and
continues the same conversation the customer was already in. The customer never
starts again.

> **What this gives you.** The agent knows its limits, and a customer who hits
> one is passed to a person rather than to a dead end.

More in [Inbox](/how-to/engage/inbox/).

---

## Stage 7: give it a phone

Voice is added to an agent that already works in writing. A phone agent that
says the wrong thing simply says it out loud, faster, to somebody who cannot
scroll back.

### 19. Set up the voice agent

Voice settings form a chain. Each link is meaningless until the one before it is
decided, and the last one is the step people skip.

<Figure
  label="Voice settings as a dependency chain, ending at a test call"
  caption="Warming has no visible result until you skip it. The phrases are already correct without it. They are just slow the first time each caller hears them."
>
<svg viewBox="0 0 700 120" xmlns="http://www.w3.org/2000/svg">
  <text x="0" y="14" class="d-eyebrow">DECIDE IN THIS ORDER</text>

  <rect x="0" y="28" width="104" height="46" rx="8" class="d-box" />
  <text x="12" y="48" class="d-label">Agent</text>
  <text x="12" y="64" class="d-sub">brief, knowledge</text>

  <path d="M108 51 L116 51" class="d-arrow" />
  <polygon points="122,51 115,47.5 115,54.5" class="d-arrow-head" />

  <rect x="122" y="28" width="104" height="46" rx="8" class="d-box" />
  <text x="134" y="48" class="d-label">Languages</text>
  <text x="134" y="64" class="d-sub">and their order</text>

  <path d="M230 51 L238 51" class="d-arrow" />
  <polygon points="244,51 237,47.5 237,54.5" class="d-arrow-head" />

  <rect x="244" y="28" width="104" height="46" rx="8" class="d-box" />
  <text x="256" y="48" class="d-label">Voice</text>
  <text x="256" y="64" class="d-sub">one per language</text>

  <path d="M352 51 L360 51" class="d-arrow" />
  <polygon points="366,51 359,47.5 359,54.5" class="d-arrow-head" />

  <rect x="366" y="28" width="104" height="46" rx="8" class="d-box" />
  <text x="378" y="48" class="d-label">Phrases</text>
  <text x="378" y="64" class="d-sub">per language</text>

  <path d="M474 51 L482 51" class="d-arrow" />
  <polygon points="488,51 481,47.5 481,54.5" class="d-arrow-head" />

  <rect x="488" y="28" width="88" height="46" rx="8" class="d-box-accent d-pulse" />
  <text x="500" y="48" class="d-label">Warm</text>
  <text x="500" y="64" class="d-sub">record them</text>

  <path d="M580 51 L588 51" class="d-arrow" />
  <polygon points="594,51 587,47.5 587,54.5" class="d-arrow-head" />

  <rect x="594" y="28" width="104" height="46" rx="8" class="d-box" />
  <text x="606" y="48" class="d-label">Number</text>
  <text x="606" y="64" class="d-sub">assign to agent</text>

  <text x="0" y="100" class="d-accent-text">A readiness checklist ticks each link off as you finish it.</text>
</svg>
</Figure>

Work in that order. Enable voice for the app, choose the languages in spoken
order, pick a voice for each language, write the greeting and fixed phrases per
language, warm them, then connect a number and assign it.

<Screen
  path="Voice AI  /  Overview"
  label="The voice readiness checklist with three of four items complete"
  caption="Every item ticks off as you finish its link in the chain. When they are all green, a Test call button appears, plus a demo dialer link you can send to a colleague."
>
  <div class="screen-head">
    <span class="t">Voice AI</span>
    <span class="ui-btn">Share demo dialer</span>
    <span class="d">Answer and place phone calls with Nordwell Assistant's AI agent.</span>
  </div>
  <div class="ui-tabs"><span class="on">Overview</span><span>Inbox</span><span>Insights</span><span>Numbers</span><span>Campaigns</span><span>Voice and Routing</span></div>
  <span class="ui-eyebrow">Readiness</span>
  <div class="ui-list">
    <div class="ui-row">
      <span class="grow"><b>Voice enabled</b><span class="sub">The agent will answer calls.</span></span>
      <span class="ui-chip ok">Done</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Language and voice set</b><span class="sub">English, Bengali</span></span>
      <span class="ui-chip ok">Done</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Phone number connected</b></span>
      <span class="ui-chip ok">Done</span>
    </div>
    <div class="ui-row">
      <span class="grow"><b>Number assigned to an agent</b><span class="sub">Nothing answers until this is set</span></span>
      <span class="ui-chip">To do</span>
    </div>
  </div>
</Screen>

Five tabs run it afterwards: Overview, an Inbox of calls, Insights, Numbers, and
Campaigns for outbound calling.

<Aside type="caution">
If the platform refuses a language, it is telling you the selected voice
genuinely cannot speak it. Change the voice for that language rather than
removing the language.
</Aside>

> **What this gives you.** The phone gets answered at eight in the evening, in
> the language the caller actually speaks, by the same agent that answers your
> website.

The full setup, with the parts this summary skips, is in
[Set up a voice agent](/how-to/voice/setup/).

---

## Stage 8: run it

The build is finished. What is left is the loop that keeps it good, and it takes
about half an hour a week.

### 20. Watch it, and fix the top thing

Six places tell you how it is going. You only need to open three of them
regularly.

| Where | What it answers |
|---|---|
| **Reports** | Volume, response time, satisfaction scores and automatic quality checks |
| **Conversations** | The transcript archive. Read five a week. This is where you find the questions your suite is missing |
| **LLM** | What you are spending across every brand, with budget alerts before a surprise rather than after one |
| **Customers** | The people who have talked to you, built from what step 10 collected |
| **Audit** | Who changed what, which matters the first time somebody asks why the agent started saying something new |
| **Team** | Roles and permissions, so a showroom manager can work the inbox without being able to rewrite the brief |

The loop is short. Read a few conversations, find the worst answer, decide
whether it was missing knowledge, a brief rule or the model, fix that one thing,
add the question to your test suite, and publish. Then do nothing else until
next week.

> **What this gives you.** You find out the agent is wrong from a report you
> read on a Monday, rather than from a customer who has already left.

---

## Where your agent can be reached

One agent, many doors. The brief, the knowledge, the catalog and the journeys
are shared across every channel, so your answers do not depend on which app
somebody opened.

| Channel | What it covers | What you need | Status |
|---|---|---|---|
| Website widget | Your own site, in your colours, with articles and product cards | Nothing, it is built in | Live |
| WhatsApp | The channel most customers reach for first | A WhatsApp Business account and its access token | Live |
| Facebook Messenger | Messages to your Facebook Page | Page access, granted by signing in | Live |
| Instagram DM | Direct messages to your Instagram account | Instagram account access | Live |
| Telegram | A Telegram bot answering as your business | A bot token from BotFather | Live |
| Slack | Internal desks: staff asking the agent questions | A Slack app token and signing secret | Live |
| SMS | Text messages, for customers with no app | A number and account with an SMS provider | Live |
| Email | Your support inbox, answered as a conversation | Mailbox login details | Live |
| Voice (phone) | Inbound and outbound calls, covered in stage 7 | A telephony account and a number | Live |
| Twitter / X DM | Direct messages on X | Account access tokens | Live |
| OU Chat | The platform's own chat app, and a short link per business | Nothing, it is built in | Live |
| Programmable API | Anywhere else: your app, a kiosk, an in-car screen | Developer time on your side | Live |
| LINE | The main messenger in Japan, Thailand and Taiwan | Channel credentials | Coming |
| TikTok | Messages to a TikTok business account | Business account access | Coming |
| LinkedIn Page | Publishing as your company, and replying to comments | Page admin access | Coming |

Two things vary between channels, and both are worth knowing before you connect
a second one. Some let you message first, and some only let you reply inside a
time window after the customer wrote to you. And rich things like product
carousels and buttons render fully in the widget and become plain text
elsewhere, so write answers that read correctly as plain text and treat the rich
version as a bonus.

<Aside type="tip">
Get one channel right before adding a second. Every channel you add multiplies
the places a bad answer can appear. The exception is when your customers are
demonstrably somewhere else already: if nobody uses your website contact form
and everyone messages you on WhatsApp, the website is not the place to perfect
anything.
</Aside>

---

## If you only have one week

| When | Steps | What you are doing |
|---|---|---|
| Day 1 | 1 to 3 | Read your website, set the profile, talk to it in Preview. About an hour |
| Days 2 and 3 | 4 to 7 | The brief, the knowledge, the help articles, the catalog. This is the work that decides quality |
| Day 4 | 8 to 11 | Suggestions, saved responses, identity, and the two or three journeys you need |
| Day 5 | 14 to 17 | Pick the model, run twenty real questions, publish, put the widget on the site |

That leaves steps 12, 13, 18, 19 and 20 for week two: connecting your other
systems, deciding where the work lands, the handover settings, voice, and the
weekly reporting loop. Each is an addition to something that already works, and
each is easier once the agent underneath is answering well.

## Next

<CardGrid>
	<LinkCard
		title="Writing the brief"
		href="/how-to/agent/brief/"
		description="The seven prompt types in detail, and the order they compose in."
	/>
	<LinkCard
		title="Set up a voice agent"
		href="/how-to/voice/setup/"
		description="Stage 7 in full, including the parts this guide summarises."
	/>
	<LinkCard
		title="Testing and publishing"
		href="/how-to/agent/testing/"
		description="Preview, cases and assertions, and going live deliberately."
	/>
	<LinkCard
		title="All How to topics"
		href="/how-to/"
		description="The screen you are on right now, documented one page at a time."
	/>
</CardGrid>