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