> ## 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.

# Create, import and manage agents

> Create a single prompt or flow agent, see what a new agent starts with, and duplicate, export, import or delete agents from the Agents list.

Every agent lives in a project and starts in the **Agents list**. This page shows how to create a single prompt agent or a flow agent, what a new agent is set up with, and how to duplicate, move between projects and delete agents.

## Before you start

What you can do depends on your role in the project. These are the default permissions; an owner can change them per member (see [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md)).

| Action | Owner | Admin | User |
| - | - | - | - |
| Create and duplicate agents | Yes | Yes | Yes |
| Edit and test agents | Yes | Yes | Yes |
| Export and import agents | Yes | Yes | No |
| Delete agents | Yes | Yes | No |

## Pick an agent type

| Type | Menu entry | Use it when |
| - | - | - |
| Single prompt agent | **Create prompt agent** ("For simple, one-off tasks.") | One set of instructions can handle the whole call, such as answering questions about your business. See [Single prompt agents](https://docs.tryhamsa.com/agents/build/single-prompt.md). |
| Flow agent | **Create flow agent** ("For complex, multi-turn interactions.") | The call has stages, fixed rules or API calls at set points. See [Flow agents](https://docs.tryhamsa.com/agents/flow/overview.md). |

You can't change an agent's type after you create it. To move from one type to the other, create a new agent.

## Create an agent

**1. Open the create menu**

In the sidebar, open **Agents list** and click **Create agent**.

**2. Choose the type**

Choose **Create prompt agent** or **Create flow agent**.

**3. Name the agent**

Enter the **Agent name** (up to 150 characters) and click **Create**.

![The Create single prompt agent dialog with an agent name typed in, its 15/150 character count 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 opens right away: the single prompt editor for a single prompt agent, the [flow builder](https://docs.tryhamsa.com/agents/flow/flow-builder.md) for a flow agent. Names don't have to be unique, so give each agent a name your team can tell apart.

You can also start from the command menu: press Cmd+K on Mac or Ctrl+K on Windows and search for the create or import entries.

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

## What a new agent starts with

Creation only asks for a name. Everything else starts from these values, which you then change in the editor.

| Setting | Starts as | Where to change it |
| - | - | - |
| Greeting (single prompt) | "Hello, how can I help you today?" | [Greeting message](https://docs.tryhamsa.com/agents/build/single-prompt.md#write-the-greeting) |
| Instructions | "You are a helpful assistant that will answer users questions." | **Agent instructions** (single prompt) or **System prompt** (flow) |
| Voice | Carla, an Arabic voice | [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md) |
| Model | Gemini 3.5 Flash Lite | [Choose the model](https://docs.tryhamsa.com/agents/settings/model.md) |
| Speech recognition | Hamsa-STT-S4 | [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md#speech-recognition-model) |
| Noise cancellation | Telephony optimized, per conversation | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#noise-cancellation) |
| Prompt enhancer | Basic | [Write a prompt that works on calls](https://docs.tryhamsa.com/agents/build/write-a-prompt.md#what-the-prompt-enhancer-adds) |
| Max call duration | 5 minutes | [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#end-the-call) |
| Phone number | None | [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md) |

Your edits save to your own draft. Callers only hear what is published. See [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md).

## Find and open agents

The **Agents list** shows every agent in the project with its **Agent type**, **Dialect**, **Voice**, **Model** and **Created** date. Depending on your permissions it also shows **Phone number** and **Calls**.

![The Agents list with four agents, their type, model, calls and created date, and Import agent and Create agent at the top right](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/agents-list-light.webp)

* Search by name or agent ID. Click **Filter** to filter by **Agent type**, **Language** or **Dialect**; you can pick several values in each, for example **Saudi** and **Emirati**.
* In projects with the [Outcome dashboard](https://docs.tryhamsa.com/agents/monitor/outcome-dashboard.md) (in beta), an **Outcome** column opens each agent's dashboard ("View the outcome dashboard").
* Click a row to open the agent. Hover the name to copy its agent ID (**Copy agent ID**).
* Open a row's menu for **Edit**, **View calls**, **Duplicate agent** and **Delete**.

![The Agents list Filter set to Dialect is any of Saudi, Emirati, with the dialect list open and Saudi and Emirati ticked](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/agents-list-dialect-filter-light.webp)

![An agent row's menu open, with Edit, View calls, Outcome dashboard, Duplicate agent and Delete](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/agent-row-menu-light.webp)

## Duplicate an agent

Duplicate an agent to try a different approach without touching the original, or to start a new agent from one that works.

**1. Open the row menu**

In **Agents list**, open the agent's row menu and choose **Duplicate agent**.

**2. Name the copy**

The name starts as the original's name followed by "(Copy)". Change it if you like.

**3. Choose what to copy**

Under **What to copy**, pick one option, then click **Duplicate agent**.

![The Duplicate agent dialog with the name Support Concierge (Copy) and the What to copy options Just the agent and The agent and its history](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/duplicate-agent-dialog-light.webp)

| Option | What the copy gets |
| - | - |
| **Just the agent** | Your draft of the agent, or the live version if you have no draft. No versions. |
| **The agent and its history** | Also every published version and everyone's drafts. |

Calls, phone numbers and share links are never copied.

## Move an agent to another project

Export an agent to a `.hamsa` file, then import that file into another project, in the same account or a different one.

**1. Export the agent**

Open the agent, open **More actions** in the editor header and choose **Export**. Save your changes first: **Export** is off while there are unsaved changes ("Save your changes before exporting"). The browser downloads a `.hamsa` file.

The file holds the agent's **published** version, the one that answers calls, not your draft. To export recent edits, publish them first. An agent that was never published exports with the settings it was created with.

![The More actions menu in the editor header, with Live call logs, Calls, Publish page, Export and Copy agent ID](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/more-actions-menu-light.webp)

**2. Switch to the other project**

Open the project you want to import into.

**3. Import the file**

In **Agents list**, click **Import agent** and choose the `.hamsa` file. Hamsa creates the agent and opens it.

What the file carries:

| Included | Not included |
| - | - |
| Greeting, instructions, dynamic variable defaults, the flow and its steps | Knowledge base items (connect the new project's own) |
| Voice settings, model settings, call settings, outcome schema | Phone numbers (assign one after import) |
| Tools the agent uses, with their settings | Webhook authentication (the webhook URL is kept) |
| A project voice the agent uses, recreated in the new project | Your draft, other versions, and call history |

On import, a tool with the same name and version as one already in the project is reused; any other tool is created in the project. On-hold music and ambient sound tracks that the new project can't use fall back to the default track.

> [!WARNING]
>
> The file contains working credentials: your tools' authentication tokens and headers, and the custom model's API key. It's encrypted, but anyone who imports it gets an agent that calls your APIs with your credentials. Share it only within your own team, and use it to move agents between your own projects.

## Delete an agent

**1. Open the row menu**

In **Agents list**, open the agent's row menu and choose **Delete**.

**2. Confirm**

In **Delete agent**, click **Delete**.

![The Delete agent confirmation, which says the action cannot be undone, with Cancel and Delete](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/delete-agent-dialog-light.webp)

**3. Undo if you need to**

The agent leaves the list at once, and a toast says "Deleted" with the agent's name. Click **Undo** within about six seconds to bring it back. After that the agent is deleted for good.

![The Agents list without Billing Assistant, and the toast Deleted Billing Assistant with Undo](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/delete-agent-undo-light.webp)

The delete is sent when the six seconds pass, when you dismiss the toast, or as soon as you go to another part of the app, switch project or close the tab. If it fails, the agent comes back to the list and the toast says why.

Deleting an agent releases its phone numbers, so calls to those numbers no longer reach it. The knowledge base items, tools and policies it used stay in the project for other agents.

## Good to know

* Agent names are required and can be up to 150 characters. You can rename an agent from the editor header.
* There is no limit on the number of agents in a project.
* Export and import are for moving an agent between projects. To copy an agent inside the same project, use **Duplicate agent**.
* A `.hamsa` file can only be imported through **Import agent**. It is not meant to be read or edited by hand.

## Related

> [card] [Single prompt agents](https://docs.tryhamsa.com/agents/build/single-prompt.md)
>
> Write the greeting and instructions, and set up the agent.

> [card] [Flow agents](https://docs.tryhamsa.com/agents/flow/overview.md)
>
> Build a call out of steps and transitions.

> [card] [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md)
>
> How edits become what callers hear.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Call the agent from the browser or your phone.


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