Skip to main content
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, 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 and Roles and permissions.

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 and 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 and Merge requests.

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: You publish into dev and promote a version to staging, then prod. Each environment runs one version and has its own environment variables, 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 and A/B tests.

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. See Flow agents, Step types and Transitions.

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. Every value is text, and a missing value renders as empty. For conditions and loops, prompts and messages use Jinja. See Variables and Jinja syntax.

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, 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 and Knowledge base.

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 and Protect personal data.

Calls and the Conversation log

A call reaches an agent through a channel: a phone number (inbound, outbound or a batch call), 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 receives its results. See Conversation log, Call details and Live calls.

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.

Quickstart

Build and publish your first agent.

Limits

Every number you can run into.

Troubleshooting

Common problems and how to fix them.

Introduction

What Hamsa Agents is and what happens on a call.