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

# Build, test and publish your first agent

> Go from an empty project to a published voice agent: create a single prompt agent, write its prompt, pick a voice, test it in the browser, then go live.

This guide takes you from an empty project to an agent that people can call. You create a single prompt agent, write a short prompt, pick a voice, talk to it in your browser, publish it, and then put it on your website or a phone number.

## Before you start

* A Hamsa account. Every account comes with a **Default** project and free credits to try Hamsa. Calls use [credits](https://docs.tryhamsa.com/overview/billing.md), and a call can only start while your balance is above zero.
* The Owner or Admin role in the project, to publish. A User can do every step up to publishing, then asks an Owner or Admin to merge their draft (see [Merge requests](https://docs.tryhamsa.com/agents/release/merge-requests.md)).
* A computer with a microphone, and a browser that is allowed to use it.
* For the phone part: a phone number from Twilio or a SIP provider.

## 1. Create the agent

**1. Open the Agents list**

In the sidebar, click **Agents list**.

**2. Create a single prompt agent**

Click **Create agent** and choose **Create prompt agent**.

![The Create agent menu open on the Agents list, with Create prompt agent and Create flow agent](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/create-agent-menu-light.webp)

**3. Name it**

Enter an **Agent name**, for example "Acme front desk", and click **Create**. The single prompt editor opens.

![The Create single prompt agent dialog with Acme front desk typed in Agent name and the Create button](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/create-prompt-agent-dialog-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=dc18311f63140dc251c952dd16b25118)

The editor has two cards on the left, **Greeting message** and **Agent instructions**, and the **Configuration** panel on the right. Your edits save on their own to your draft, which only you see. See [Single prompt agents](https://docs.tryhamsa.com/agents/build/single-prompt.md) for everything on this screen.

![The single prompt editor: Greeting message and Agent instructions on the left, the Configuration panel with its sections on the right, and Test and Publish live in the header](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/single-prompt-editor-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=2396365b97e15a3264b3682c3db913d9)

## 2. Write the greeting and the prompt

**1. Write the greeting**

On the **Greeting message** card, keep the **Static message** tab and replace the text with your first line, for example "Hello, this is Sara from Acme Dental. How can I help you today?" The greeting can be up to 191 characters.

**2. Write the instructions**

In **Agent instructions**, replace the starting text with a short prompt. Say who the agent is, what it does, the rules it follows and the facts it needs:

```markdown theme={null}
# Role
You are Sara, the front desk assistant for Acme Dental in Amman.

# Goal
Answer questions about opening hours, prices and location.
If the caller wants an appointment, take their name and preferred day,
and tell them a colleague will call back to confirm.

# Rules
- Ask one question at a time.
- Never give medical advice.
- Repeat names and days back to the caller to confirm them.

# Facts
- Open Sunday to Thursday, 9:00 to 17:00.
- A cleaning costs 25 JOD.
```

**3. Leave the prompt enhancer on Basic**

Under the instructions, **Prompt enhancer** is set to **Basic**. It adds Hamsa's speaking rules and tells the model to speak the voice's dialect, so you don't need to write those yourself.

![The Prompt enhancer list open under the instructions, showing Disabled, Basic (selected) and Advanced](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/prompt-enhancer-menu-light.webp)

For what makes a prompt work on a live call, see [Write a prompt that works on calls](https://docs.tryhamsa.com/agents/build/write-a-prompt.md).

## 3. Pick a voice

The voice decides how the agent sounds and which language and dialect it speaks. New agents start with Carla, an Arabic voice.

**1. Open the voice picker**

In **Configuration**, open **Voice settings** and click **Change** on the voice row. **Select agent voice** opens.

**2. Find a voice in your callers' dialect**

Filter by **Dialect** and **Gender**, and press play on a row to hear it.

![Select agent voice in the Configuration panel, with the Dialect filter open listing Gulf and Levantine dialects and how many voices each has](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/settings/voice-picker-dialect-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=4f497a8a4ea979c3ee4233be46871b7c)

**3. Pick it**

Click the voice. The picker closes and the agent now speaks that voice's language and dialect.

If your prompt or greeting is in another language than the voice, change them to match. See [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md).

## 4. Check two call settings

Open **Call settings** in **Configuration**:

![Call settings in the Configuration panel: Wait for user to speak first, On-hold music, Timezone, User gender detection and Smart call end](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/settings/call-settings-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=33b150238b31243328055905be61fdae)

* **Smart call end**: turn it on so the agent can say goodbye and hang up when the conversation is done. With it off, a single prompt agent never hangs up on its own.
* **Timezone**: pick your business's time zone, so the agent gets dates and times right.

Every call is also capped by **Max call duration**, 5 minutes for a new agent. Raise it if your calls run longer. See [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md).

## 5. Test it in the browser

**1. Start a browser call**

In the editor header, click **Test** and choose **Browser call**. If the browser asks for the microphone, allow it. The **Test** button is disabled while changes are still saving.

![The Test menu open in the editor header, with Browser call, Phone call, Chat and Test values](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/test-menu-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=9ecca138f493734824a87d0bfb9f6f4d)

**2. Talk to the agent**

Ask what a caller would ask. Then try the cases your rules cover: an off-topic question, a request for medical advice, a name the agent should repeat back. While the call runs, the **Configuration** panel shows **Live call logs**.

**3. End the call**

Click **End call**. You can also start and end a browser call with Cmd+Shift+Enter on Mac or Ctrl+Shift+Enter on Windows.

**4. Read the call back**

In the editor header, open **More actions** and click **Calls**, then open your test call. Read the transcript, then fix the prompt where the agent hesitated or broke a rule, and test again.

Tests run your own draft. Nobody else hears your changes until you publish. See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md).

![The single prompt editor during a browser test call: End call and the microphone button in the header, and Live call logs on the right listing the call start, the greeting, model replies and a tool call](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/browser-test-call-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=9d09fd5fb49c238b20f31cfcd72cfeac)

## 6. Publish

Callers only ever hear a published version. Publishing turns your draft into version v1.

**1. Click Publish live**

In the editor header, click **Publish live**.

**2. Say what changed**

Fill in **Change summary**, for example "First version of the front desk agent". It is required. **New version label** is optional.

![The Publish live dialog with a change summary filled in, an empty New version label and the Publish live button](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/publish-live-dialog-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=cad4e3949c9c3d4a0fea95b3a92e84ed)

**3. Confirm**

Confirm to publish. Callers hear the new version from the next call.

If you are a User, click **Request merge** instead, and an Owner or Admin publishes it. To test in dev and staging before prod, turn on deployments later; see [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md).

## 7. Put the agent in front of callers

Choose one, or do both.

> [tab] On your website
>
> **1. Open the publish page**
>
> In the agent editor, open **More actions** (the three dots) and click **Publish page**. **Publish agent** opens with a live preview.
>
> **2. Set the look**
>
> Pick a **Theme** and an **Audio visualizer**, and under **Embed** set the **Position** and **Button label** of the floating button. Everything is optional.
>
> **3. Publish the page**
>
> Click **Publish agent**. You get a **Public link** that anyone can open to talk to the agent, with no sign-in.
>
> **4. Add the widget to your site**
>
> Turn on the **Embed** switch, click **Copy**, and paste the snippet before `</body>` on each page where the button should appear. Your site must be served over HTTPS for the microphone to work.
>
> ![The Embed section of the Publish agent page, with Position, Size, Button label and Auto-start call, a preview of the floating button and the Publish agent button](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/publish-page-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=86b6237d4da40838cc591064f82d22ec)
>
> Visitors talk to the published version. See [Embed on your website](https://docs.tryhamsa.com/agents/publishing/embed.md) for widget options and the web SDK.

> [tab] On a phone number
>
> **1. Add your number**
>
> In the sidebar, open **Telephony** > **Bring your own number**, click **Add number** and choose **Twilio** or **SIP trunk**. Fill in the form and click **Add**. For a SIP trunk, also give your provider the values shown on the number's page. See [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md) for each field.
>
> **2. Assign it to the agent**
>
> In the agent, open **Configuration** > **Phone number**. In **Select phone numbers**, pick the number and click **Done**. Assigning a number doesn't need a publish.
>
> ![Select phone numbers in the Configuration panel, with a Twilio number selected, a SIP trunk number and a number already assigned to another agent](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/start/select-phone-numbers-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=f12eac2022c1c1dac318491edbeba627)
>
> **3. Call it**
>
> Call the number from your phone. The published version of the agent answers.
>
> To have the agent call people instead, see [Outbound calls](https://docs.tryhamsa.com/agents/connect/outbound-calls.md) and [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md).

## 8. Watch the calls

Every call, including your tests, is in the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md) in the sidebar, with its transcript, recording and an analysis of how it went. To get each call's results in your own system as it ends, set a [webhook](https://docs.tryhamsa.com/agents/connect/webhooks.md).

## Next steps

> [card] [Add a knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md)
>
> Give the agent documents and text to answer from.

> [card] [Connect an API](https://docs.tryhamsa.com/agents/tools/api-tools.md)
>
> Let the agent look up and change things in your systems.

> [card] [Build a flow agent](https://docs.tryhamsa.com/agents/flow/overview.md)
>
> For calls with fixed stages and rules.

> [card] [How it fits together](https://docs.tryhamsa.com/agents/concepts.md)
>
> The ideas behind projects, versions and environments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.