Voice Agent
Voice Agent turns a NappAI flow into an agent that takes calls by phone or from the browser. The caller speaks, the agent listens, thinks with the connected model and answers out loud. When it needs to do something, such as looking up an order, transferring the call or hanging up, it uses the tools you connect to it.
It is a trigger: the flow does not run top to bottom, but once per call. A flow can have only one Voice Agent node. This page is the reference for every field of the node; the step-by-step guide is in Create a voice agent and the overview in Introduction to the voice agent.
If you prefer a single model that hears, thinks and speaks, with no separate STT, model and TTS, use Voice Agent Realtime.
When to use it
- You want to answer your customers’ frequent questions by phone at any time: opening hours, order status, prices.
- You want a virtual receptionist that routes each call to the right department.
- You want a voice assistant on your website that visitors can use from the browser.
- You want a flow to place outbound calls, for example appointment reminders, with Outbound Call.
Configuration
Connectors
There are four connectors under the node. Model, STT and TTS are required.
| Connector | What you connect |
|---|---|
| Tools | What the agent can do during the call: any NappAI component in tool mode (your CRM, a database, email, a web search, a sub-flow…), a sub-agent, and the call tools Transfer Call, Hang Up Call and Say to Caller. The agent decides when to use each one from its description. |
| Model (required) | The model that drives the conversation. Its settings, such as the credential or reasoning, are configured in that component. The models you can use are listed in Create a voice agent. |
| STT (required) | How the agent hears: a Voice Agent family component ending in STT, such as Parakeet (local, multilingual). |
| TTS (required) | How the agent speaks: a component ending in TTS, such as Supertonic (local). |
With Fallback Engines on, three more connectors appear: Fallback model, Fallback STT and Fallback TTS. With Waiting Phrases set to Another model, the Waiting Phrases connector appears. With Guardrails on, Guardrail Model appears. With Enable Skills on, Skills appears. They are explained below.
Common tab
| Field | What it does |
|---|---|
| Agent Name (required) | The agent’s name in the Voice Agent menu, in the widget and in the history. It identifies its calls. |
| Greeting | The first sentence the agent says when the call connects. Default: “Hola, ¿en qué puedo ayudarte?”. |
| System Prompt | Who the agent is, what it knows and how it must behave. The platform adds the rules of a call on top (language, tool use, how to speak), so only what is specific to your business goes here. |
| Enabled | Turns the agent off without unpublishing it. On by default. |
| Fallback Engines | Keeps the call going when a provider fails. When on, the Fallback model, Fallback STT and Fallback TTS connectors appear; they are used only if the main one stops answering. Connect only the ones you want a backup for. Off by default. |
The fallback model receives the same conversation and the same tools, so it is best from another provider and able to use tools. The fallback voice must speak the same language.
Call Ambience
Complete silence sounds like a dropped call. That is why the office ambience and the typing while a tool works are on by default.
| Field | What it does |
|---|---|
| Background Ambience | A soft sound bed under the whole call: office (default), city, forest or crowded_room. Empty for none. |
| Ambience Volume | Loudness of the ambience, from 0 (silent) to 1 (as loud as the voice). Default: 0.12, barely noticeable, which is the point. |
| Typing While Working | Plays keyboard typing only while a tool is working. On by default. |
| Typing Volume | Loudness of that typing, from 0 to 1. Default: 0.25. |
| Typing While Thinking | Plays soft typing while the agent prepares its answer, so the pause is not silence. It stops as soon as the agent speaks. Off by default. |
| Thinking Volume | Loudness of that typing, from 0 to 1. Default: 0.15. |
Timeouts
| Field | What it does |
|---|---|
| Maximum Call Duration (S) | The longest a call may last, in seconds. When reached, the agent says goodbye and hangs up. Default: 600. |
| Inactivity Before Hanging Up (S) | Seconds of silence before acting on inactivity. It never fires while a tool is working or a result is still to be given. Default: 45. |
| Tool Calls | How tools share the conversation. In the background (default): the conversation goes on while a tool works, several can run at once and, if one is slow, the agent says a short waiting phrase. One at a time: the agent waits for each result before speaking and tools run one after another. |
| Tool Timeout (S) | How long the agent waits for a tool before apologising. Default: 240. |
| Ask Before Hanging Up | On (default), after the silence the agent asks whether the caller is still there and hangs up only after a second silence of the same length. Off, it says goodbye and hangs up at the first silence. |
| Still There? Phrase | What the agent says to check whether the caller is still on the line, word for word. Empty, the agent asks in its own words in the call’s language. |
| Farewell After Inactivity | What the caller hears before the line closes for inactivity, word for word. Empty, the agent says a brief goodbye in the caller’s language. |
| Farewell At Maximum Duration | What the caller hears when the maximum duration is reached, word for word. Empty, the agent explains and says goodbye in the caller’s language. |
Call recording
| Field | What it does |
|---|---|
| Record Calls | Keeps the audio of every call, caller and agent, next to its transcript in the history, where it can be played back. Recordings are kept for a fixed period set by the platform. Telling the caller they are being recorded is your responsibility, usually in the Greeting. Off by default. |
Advanced tab
The defaults are designed for noisy phone calls. You do not need to touch them to get started. How they affect quality and speed is explained in Quality, noise and latency.
Guardrails
| Field | What it does |
|---|---|
| Guardrails | Checks every action the agent is about to take with its tools against your rules. An action that breaks one is not taken and the agent explains it to the caller. Off by default. |
| Guardrail Rules | The rules, in plain words, one per line, ideally with the reason. |
| If The Check Fails | What happens when the check cannot run: Let the request through (default) or Refuse the request. |
With Guardrails on, the Guardrail Model connector appears for the checking model: a small, fast one. More in Guardrails.
Skills
| Field | What it does |
|---|---|
| Enable Skills | Lets the agent use NappAI skills during the call. Off by default. |
With Enable Skills on, the Skills connector appears under the node. You connect the same skills a Deep Agent uses: a Managed Skill from the NappAI library or a Stored Skill from your skill manager. You can connect several.
How they work on a call:
- The agent only sees each skill’s name and description. When what the caller asks matches one, it reads it before answering. Reading is instant; sometimes the agent first says a short phrase, such as “let me check”.
- What it reads stays in its instructions for the rest of the call. It does not read it again, and conversation memory never trims it.
- It only reads the skill’s text files. Its scripts never run on a call.
- If the call moves to another voice agent, that agent uses its own skills.
With Enable Skills on and no skill connected, the flow cannot be published: the warning tells you to connect one or switch it off. With the field off the agent works exactly as it does without skills, even if some are still connected.
Model Reasoning
| Field | What it does |
|---|---|
| Reasoning Format | What happens to the thinking of a model that reasons before answering. hidden (default): only the answer comes back, which is what a call needs. parsed: the reasoning comes back separately, for review. How much the model reasons is set on the model component itself. |
Waiting Phrases
| Field | What it does |
|---|---|
| Waiting Phrases | While a tool is slow, the agent says short phrases so the caller is not left in silence. Agent's model (default): the agent’s own model writes them. Another model: the Waiting Phrases connector appears so you can connect a second, small and fast model. Off: nothing is said while waiting. |
| Phrase Length | How long the waiting phrases are, including the one the agent says when a tool starts. Short: 5 to 10 words. Medium (default): 12 to 18. Long: 20 to 30. It guides the model; it is not an exact limit. |
| Instructions | How the waiting phrases should sound. |
| Silence Before Speaking (S) | Seconds of silence after the agent’s last words before a waiting phrase. Default: 5. |
| Minimum Gap (S) | Minimum spacing between two waiting phrases. Default: 9. |
| Initial Wait (S) | The tool’s own announcement covers the first seconds; the agent waits this long before the first phrase. Default: 8. |
Conversation memory
Decides how much of the call the model sees on each turn. The full transcript is always kept in the history; this only changes what the model reads.
| Field | What it does |
|---|---|
| Conversation Memory | Keep recent messages (default): only the latest messages. Summarize older messages: older turns are condensed into a short summary the model keeps reading. Full conversation: everything, until the model can take no more. |
| Messages To Keep | How many recent messages the model sees word for word. A turn is two messages and each tool use adds two more. Default: 40. |
| Approximate Token Budget | Rough size of the history the model sees, in tokens (about four characters each). When the recent messages exceed it, older ones are dropped or summarised. Default: 8000. |
| Summary Instructions | What the summary of older turns must keep. It only appears with Summarize older messages. |
VAD and Audio
These fields decide how the caller’s voice is detected, when they have finished speaking and when they can interrupt the agent.
| Field | What it does |
|---|---|
| Speech Sensitivity | How sure the system must be that it hears a voice before it counts as the caller speaking, from 0 to 1. Higher ignores more noise; lower picks up very soft speakers. Default: 0.7. |
| Minimum Speech Duration (S) | Shorter sounds are ignored, so a cough or a click does not count as speech. Default: 0.25. |
| Silence For End Of Turn (S) | How long the caller must be quiet before the agent considers the sentence finished and answers. Shorter answers sooner but may cut people off. Default: 0.4. |
| Speech End Sensitivity | How sure the system must be that the voice has stopped, from 0 to 1. At 0 (default) it adjusts itself. Raise it in very noisy rooms if the noise keeps the caller’s turn open. |
| Longest Wait For End Of Turn (S) | When the caller hesitates or ends with something like “okay, thanks”, the agent waits in silence up to this long before answering. 1 (default) suits quick service; 1.5 to 2 suits dictated numbers or long explanations. |
| End-of-turn Confidence | How sure the agent must be that the caller has finished to answer straight away instead of waiting the maximum above. Lower answers sooner; higher allows longer pauses. At 0 (default) it adjusts itself to the channel. |
| Second end-of-turn check | When the agent is unsure whether the caller has finished, a second model listens to how their last words sounded (intonation and rhythm). If it is sure they have finished, the agent answers at once instead of waiting the Longest Wait For End Of Turn (S) maximum. On rare occasions it may start answering during a long pause. On by default. |
| Leading Padding (S) | Audio kept from just before the voice was detected, so the first syllable is not lost. Default: 0.5. |
| Minimum Duration To Interrupt (S) | How long the caller must speak to interrupt the agent while it is talking. Default: 0.8, which lets a real objection through and ignores a horn or a word from a TV. |
| Resume After False Interruption (S) | If the agent stopped because it thought the caller spoke, but no words follow within this time, it resumes its sentence where it left off. Default: 1.5. |
| Minimum Words To Interrupt | Words the caller must say before the agent stops talking. Default: 2. At 0, a single word, even from a TV, cuts the agent off. It is used with STTs that transcribe while the caller speaks. |
| Ignore Other Voices | Learns the caller’s voice and tells it apart from others. A voice that is not theirs, such as someone behind them or a TV, does not cut the agent off and, once the caller is recognised, gets no answer either. It adds no delay and works with any STT. On by default. |
| Other Voices: How Strict | gentle ignores only voices clearly unlike the caller’s; balanced (default) is the recommended middle; strict ignores more background voices and, now and then, the caller has to repeat a very short word. |
| Noise Reduction | Cleans background noise and separates the caller’s voice from chatter before deciding whether they are speaking. On by default. See how the agent listens. |
| Noise Reduction Strength | From 0 (gentle) to 3 (strong). Stronger removes more noise but can thin out the caller’s voice. Default: 1. |
| Echo Cancellation | Removes the agent’s own voice if it comes back through the caller’s microphone, as with a speakerphone. Turn it on only if you hear the agent reacting to itself. Off by default. |
| Automatic Gain Control | Evens out callers who speak very loud or very soft. Off by default, because while the caller is silent it also turns up the background, so a second voice in the room gets louder. |
Call context
| Field | What it does |
|---|---|
| Tell The Model About The Call | Before the caller speaks, the model is told the date and time, the calling number, the dialled number and whether the call comes from the phone or the web. On a call from the widget, who is calling is whatever the page passes in its caller parameter (see Web widget). Facts only: what the agent does with them is up to your System Prompt. On by default. |
| Time Zone | The time zone the date and time are given in, by its international name, for example Europe/Madrid (default) or America/Mexico_City. |
Phone numbers, SIP trunks and the widget avatar are not node fields: you choose them when you publish the agent in the Voice Agent menu.
Output
The node has two outputs, Tool Result and Tools Connected. The voice platform itself uses them to run the agent’s tools during the call: you do not need to connect them to anything.
What happens on each call (the transcript, the tools used, the recording if it is on and why it ended) is kept in the call history.
Example
An online shop wants to answer order questions by phone.
- Add a Voice Agent to the canvas.
- Connect a model component to Model, Parakeet (local, multilingual) to STT and Supertonic (local) to TTS.
- Type “Customer service” in Agent Name and “Hi, I’m the shop’s assistant. How can I help?” in Greeting.
- In System Prompt, explain what it can look up and when to transfer or hang up.
- Connect to Tools the component that looks up orders in tool mode, a Transfer Call to the support team and a Hang Up Call.
- Test in the playground, deploy the flow and publish it in the Voice Agent menu.
Good practices
- Write the prompt for the ear: short sentences, one idea at a time, no lists or tables. More tips in Create a voice agent.
- Say in the prompt when to use each tool, for example “if they ask about invoices, transfer to finance”.
- Mark as required the arguments a tool needs to do its job: the agent respects what each tool declares in the flow.
- Without Hang Up Call the agent cannot hang up: the call ends when the caller hangs up, on inactivity or at the maximum duration.
- Test in the playground before publishing. The playground uses the draft you are editing; real calls use the published version.
- If you turn on Record Calls, tell the caller they are being recorded.
- Keep Noise Reduction on if your customers call from the street, the car or busy places.
- Use skills for long procedures (returns, bookings, internal rules) instead of putting everything in the System Prompt: the agent only reads them when the call needs them.
Related components
- Voice Agent Realtime: the alternative with a single realtime model that hears, thinks and speaks.
- Transfer Call: passes the call to another agent, a phone number or a SIP address.
- Hang Up Call: says goodbye and hangs up.
- Say to Caller: reads a text word for word.
- Outbound Call: makes a flow place a phone call with this agent.
- Parakeet (local, multilingual) and Supertonic (local): the recommended hearing and voice to start with.
- Managed Skill and Stored Skill: the skills the agent can read with Enable Skills on.