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

# How Hamsa Agents fits together

> The ideas behind Hamsa Agents in one place: projects and roles, agents, drafts and versions, environments, steps, variables, tools, safety, calls and credits.

This page explains the main ideas in Hamsa Agents and how they connect, one short section each. Read it once before you build something larger than the [quickstart](https://docs.tryhamsa.com/agents/quickstart.md), then follow the links when you need the detail.

## Projects and members

A project is the shared space where your team builds. Agents, the knowledge base, tools, phone numbers, secrets, voices you add, the Conversation log and API keys all live in a project. Switch projects and you see a different set.

Each member has a role: **Owner**, **Admin** or **User**. Users build, edit and test. Owners and Admins also review and publish changes, manage phone numbers and batch calls, and invite people. Only the Owner handles billing. The Owner can turn single permissions on or off for one member.

See [Projects](https://docs.tryhamsa.com/overview/projects/overview.md) and [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## Agents

An agent is one voice assistant: its instructions, voice, model, tools and call settings. There are two types, and you pick one when you create the agent:

* A **single prompt agent** runs the whole call from one set of instructions.
* A **flow agent** runs the call as steps on a canvas, connected by transitions.

Both types share the same settings for the model, voice, call behavior, knowledge base, webhook and safety rules. See [Create an agent](https://docs.tryhamsa.com/agents/build/create-an-agent.md) and [Pick an agent type](https://docs.tryhamsa.com/agents/introduction.md#pick-an-agent-type).

## Drafts, versions and merge requests

You never edit what callers hear directly.

* **Draft.** Every member edits their own private draft of an agent. It saves on its own and only you see it.
* **Version.** Publishing turns a draft into a numbered version (v1, v2, v3). A version never changes after that, and you can roll back to an earlier one.
* **Merge request.** A User can't publish. They request a merge, and an Owner or Admin reviews it, tests it and merges it into the next version. Owners and Admins can use merge requests too, to get a second pair of eyes.

Some things are not part of a version: phone numbers, and the policies, guardrails and functions added to an agent. Changing those reaches calls right away.

See [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md) and [Merge requests](https://docs.tryhamsa.com/agents/release/merge-requests.md).

## Environments: dev, staging and prod

Every agent starts in **Versioning** mode: **Publish live** makes a version and callers hear it from the next call.

When you want to check changes before callers hear them, turn on deployments for the agent. It then has three environments:

| Environment | What it's for |
| - | - |
| dev | Your latest work. New versions land here. |
| staging | The final check before release. |
| prod | What callers hear. |

You publish into dev and promote a version to staging, then prod. Each environment runs one version and has its own [environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md), so the same version can call a test API in staging and the real one in prod. Each phone number points at one environment; the website widget and calls without a chosen environment land in prod. Turning on deployments can't be undone.

See [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md) and [A/B tests](https://docs.tryhamsa.com/agents/release/ab-tests.md).

## Steps and transitions

A flow agent is built from **steps**: boxes on the canvas that each do one job, such as talk with the caller, call an API, check a value, transfer the call or end it. Every flow has one Start step. The app says "node" on some buttons, such as **Add node**.

**Transitions** are the ways out of a step. Some the model picks from what the caller said, some follow fixed rules on values, keys the caller presses, or whether an API call worked. **Global steps** can be reached from any point in the flow, for example "speak to a person".

**Live variables** keep a value up to date for the whole call, such as the caller's name or a request to speak to a person, whichever step the call is in. A transition can move the call as soon as one matches. See [Live variables](https://docs.tryhamsa.com/agents/variables/live-variables.md).

See [Flow agents](https://docs.tryhamsa.com/agents/flow/overview.md), [Step types](https://docs.tryhamsa.com/agents/flow/steps/overview.md) and [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md).

## Variables

Variables let one agent adapt to each call. You write `{{customer_name}}` in a prompt, message or tool setting, and the agent fills in the value on the call.

| Kind | Where the value comes from |
| - | - |
| System | Hamsa, on every call: date and time, the caller's number, the call direction |
| Dynamic | You, when the call starts: from the API, the web SDK, a batch call file or a test |
| Environment | The agent's environment, one value per dev, staging and prod |
| Extracted | The conversation (flow agents): what the caller says, an API's response, keys pressed |
| Local | A step that sets it (flow agents) |
| Live | What the caller says, read again after every caller turn in any step (flow agents) |

Every value is text, and a missing value renders as empty. For conditions and loops, prompts and messages use Jinja. See [Variables](https://docs.tryhamsa.com/agents/variables/overview.md) and [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md).

## Tools and the knowledge base

**Tools** let the agent act during a call. You create them once in **APIs & MCPs** and add them to any agent in the project:

* API request tools call your HTTP endpoints.
* MCP servers offer their functions to the agent.
* Web tools ask the web page the caller is on to do something.

Passwords and tokens go in [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md), not in the tool.

The **Knowledge base** holds documents and text your agents search for answers. Each item is split into chunks, which you can review before it becomes searchable. On a call, the agent searches the items attached to it by meaning, in Arabic and English.

See [APIs & MCPs](https://docs.tryhamsa.com/agents/tools/overview.md) and [Knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md).

## Safety

* **Policies** are instructions the agent follows, on every turn or when the caller's words fit a description.
* **Guardrails** check what the caller says, what the agent is about to say, or both, and act when they match: say a set line, end the call or run a function. Start a guardrail in **Monitor** to watch what it would catch, then switch it to **Enforce**.
* **Functions & macros** are small JavaScript and Jinja helpers that guardrails check with or run.

Rules live in the project library and are added per agent.

See [Policies & guardrails](https://docs.tryhamsa.com/agents/safety/policies-and-guardrails.md) and [Protect personal data](https://docs.tryhamsa.com/agents/safety/personal-data.md).

## Calls and the Conversation log

A call reaches an agent through a channel: a phone number (inbound, outbound or a [batch call](https://docs.tryhamsa.com/agents/connect/batch-calls.md)), the website widget or public page, or your own app with the web SDK. Test calls from the editor use your draft; every other call runs a published version.

Every call, tests included, is saved in the **Conversation log** with its status, transcript, recording, analysis and outcome. **Live calls** shows the calls going on now, where Owners and Admins can listen in, guide the agent or take over. When a call ends, the agent's [webhook](https://docs.tryhamsa.com/agents/connect/webhooks.md) receives its results.

See [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md), [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md) and [Live calls](https://docs.tryhamsa.com/agents/monitor/live-calls.md).

## Credits

Calls are paid for in credits. Credits, the plan and the limit on calls at the same time belong to the project Owner's account, not to a project: every project that Owner has shares one balance and one limit.

* Your plan adds credits every month, and you can buy more. Each batch lasts twelve months, and the batch that expires soonest is spent first.
* A call can only start while the balance is above zero. A call in progress is never cut short.

See [Billing](https://docs.tryhamsa.com/overview/billing.md).

## Related

> [card] [Quickstart](https://docs.tryhamsa.com/agents/quickstart.md)
>
> Build and publish your first agent.

> [card] [Limits](https://docs.tryhamsa.com/agents/reference/limits.md)
>
> Every number you can run into.

> [card] [Troubleshooting](https://docs.tryhamsa.com/agents/reference/troubleshooting.md)
>
> Common problems and how to fix them.

> [card] [Introduction](https://docs.tryhamsa.com/agents/introduction.md)
>
> What Hamsa Agents is and what happens on a call.


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