# Voice agent

> Configure a Voice agent: its model and prompts, output variables, tools, handoffs between agents, and the call transcript, with fixes for common issues.

## What it does

Attaches an agent to a live phone call and speaks with the caller. Audio streams directly to a real-time speech model, which allows the caller to interrupt the agent mid-speech. Configure the model, persona, prompt, tools, and context grounding indexes directly on the node.

Both call directions use the same three-step shape:

| Direction | Node sequence |
|---|---|
| Inbound | **[Incoming Call](./node-incoming-call.md)** → **Voice agent** → **[End Call](./node-end-call.md)** |
| Outbound | **[Create Outgoing Call](./node-create-outgoing-call.md)** → **Voice agent** → **[End Call](./node-end-call.md)** |

The node is labeled **Voice agent** in the **Agent** category of the **Add node** panel.

## Configuration reference

| Field | Description |
|---|---|
| **Model** | The real-time speech model. The default is `gpt-realtime-2.1`. |
| **Persona** | The voice for the selected model. The default is **Marin**. |
| **System prompt** | The agent's role, its standing instructions, and how it should close the conversation. |
| **Temperature** | Response creativity from `0` to `1`. |
| **Maximum tokens** | Maximum token for a conversation. |
| **Call context** | In the **Call settings** section. The call this agent attaches to. Bind it to an upstream `callContext`, for example, `$vars.createOutgoingCall1.output.callContext`. |

## Output variables

You may optionally configure structured output variables in the **Outputs** section of the properties panel. They are useful for setting goal-oriented or routing variables to use in downstream nodes within the workflow.

Each output variable you declare becomes a field on the agent's output object, referenced as `$vars.<agentName>.output.<name>`. Give each one a name and a type, then instruct the agent in the variable's description field how to populate it. Output generation is driven by a combination of the agent's system prompt and the output variable descriptions.

The agent populates them when it ends its voice session.

![The Voice agent selected, with Model set to gpt-realtime-2.1, Persona set to Marin, a System prompt, an empty Outputs section, and, under Call settings, Call context set to $vars.createOutgoingCall1.output.callContext.](https://dev-assets.cms.uipath.com/assets/images/maestro-automate/voice-agent-outputs-automate-324f5e1e.webp)

The two most common uses are call summaries and [handoffs](#handoffs). For a summary, declare an output such as `call_summary` and use its description to tell the agent to summarize the call. The agent writes it when it ends its session, and downstream nodes read it as `$vars.voiceAgent1.output.call_summary`.

![Edit output dialog for a Voice agent output named call_summary, type String, with the description Summarize the call and Required turned on.](https://dev-assets.cms.uipath.com/assets/images/maestro/voice-agent-call-summary-92561ffb.png)

## Tools

Connect tools to the **Tools** handle to give the agent capabilities it can call while reasoning. The agent decides during its loop whether and when to call each connected tool. Each tool carries a description that tells the agent what the tool is for, so write clear descriptions when a tool exposes one.

While designing tools for voice agents:
* The caller waits through every tool call, so keep each tool's job small and fast.
* Tools the agent calls in the same round return together, the slowest one sets how long the caller hears silence.
* After a timeout the agent may report failure and try again, so make tools idempotent. A tool call that has not returned in 180 seconds will time out.

### Tool availability

| Tool category | Availability |
|---|---|
| RPA processes | Available |
| API workflows | Available |
| Activities | Available |
| Other workflows (Maestro) | Available |
| Process orchestration | Available |
| Coded functions | Available |
| Agent (call a deployed standalone agent) | Available |
| Connectors | Available |
| Context Grounding indexes | Available |
| Built-in tools (Analyze Files, Deep RAG, Batch Transform) | Not available |
| Escalations | Not available |
| Model Context Protocol (MCP) tools | Not available |
| A2A (Agent-to-Agent) | Not available |
| Intelligent Xtraction and Processing (IXP) (document extraction) | Not available |

### Built-in voice tools

Every voice agent has access to two built-in tools. These are included but not shown in the canvas:
1. **Dual-Tone Multi-Frequency (DTMF) tool**: used to press digits on phone key pad, which can be used to navigate external phone trees
2. **End session**: used to exit the conversation without ending the call. Useful for voice agent [handoffs](#handoffs).

### Tool guardrails

Tool-level guardrails are available on the tools connected to the Voice agent node. You can filter or block on a tool's input parameters. Configure the guardrail on the tool attached to the Voice agent's Tools handle. [tool guardrails](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/tool-guardrails) has more details.

## Handoffs

Ending a voice session is not the same as ending the call. When an agent ends its session it exits the call but leaves the line open: the agent populates its output variables, and the workflow moves to the next node. Only the **[End call](./node-end-call.md)** node and the caller can hang up the call.

That is what makes handoffs possible. Chain Voice agent nodes and bind them all to the same **Call context**. Each agent ends its own session when it is done, and only the last path reaches **End call**, so the caller stays on the line throughout.

![A workflow that places an outgoing call, attaches a Voice agent, then uses a Switch node with Billing and Invoice branches routing to a Billing voice agent and an Invoice voice agent, both of which lead to an End call node.](https://dev-assets.cms.uipath.com/assets/images/maestro/voice-agent-handoff-flow-0a46c7a2.png)

A handoff has two parts:

* **Route to the right agent.** Give the first agent an output variable, for example `handoff`, and use its description to tell the agent which value to set. Branch on that value with a **Switch** node so each case leads to the agent that handles it.
* **Carry the context over.** A receiving agent knows nothing about what was already said. Either reference a call summary output from the first agent in its system prompt (`$vars.voiceAgent1.output.call_summary`), or add a **[Get Conversation Context](./node-get-conversation-context.md)** node on the branch and reference the transcript instead. The [Call transcript](#call-transcript) section has details.

:::note
Handing a call off to a human isn't supported. There is no live call transfer.
:::

The Voice agent has no **Escalations** connection, because a call can't wait while a person completes a task. To have a person act on the outcome of a call, add a node from the **Human** category, such as [Quick Form](./node-quick-form.md), after the Voice agent.

## Call transcript

To read a transcript after a call, open the execution trace of a test run, or the trace of a deployed run, as [Monitor runs](monitor-runs.md) describes. [Observability](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/conversational-agents-voice-observability) has more details.

To use the transcript inside the workflow:

1. Add a **[Get Conversation Context](./node-get-conversation-context.md)** node.
2. Pass in `$vars.<incomingOrOutgoingCallNodeId>.output.callContext.conversationId`. For example, `<incomingOrOutgoingCallNodeId>` can be `createOutgoingCall1`.
3. Reference the transcript as `$vars.<getConversationContextNodeId>.output.conversationContext.messages`. For example, `getConversationContextNodeId` can be `getConversationContext1`.

For example, you can pass the transcript to an autonomous agent for processing:

![A workflow that places an outgoing call, attaches a Voice agent with a Web Search tool, ends the call, then uses Get Conversation Context and an Autonomous Agent to process the transcript.](https://dev-assets.cms.uipath.com/assets/images/maestro/voice-get-transcript-flow-e2a93edb.png)

## Common issues

**The agent talks normally but never runs a tool.**
No unattended or default robot with a serverless machine is assigned where the workflow runs, so every tool call comes back as an error and the agent stays conversational. Ask your administrator to assign a robot, then call again. [Folder requirements](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/conversational-agents-deployment#orchestrator-folder-requirements) has more details.

**The call ends before the conversation is finished, but there are no errors.**
The agent ended its own session mid-conversation, and the workflow moved on to **End call**. That is likely a prompting issue where the voice agent thought it finished helping the caller and decided to end the session.

**The agent stalls or produces static reading digit strings.**
With Gemini Live at **Temperature** `0`, long digit strings can stall or sound distorted. Raise **Temperature** slightly. If the issue persists, try the other model.

**The agent fails to attach with a tool schema error.**
The Gemini model accepts a narrow schema subset. Flatten the tool's input schema, or wrap the tool in an API workflow with a flat input schema and use the workflow as the tool instead.

**The call connects, nobody speaks, and it drops after about 25 seconds.**
A call that never attaches an agent is ended after about 25 seconds of dead air. Bind **Call context** to the `callContext` from the [Incoming Call](./node-incoming-call.md) trigger or the [Create Outgoing Call](./node-create-outgoing-call.md) node.

## Next steps
- [Incoming Call](./node-incoming-call.md): starts an inbound call workflow.
- [Create Outgoing Call](./node-create-outgoing-call.md): starts an outbound call.
- [End Call](./node-end-call.md): ends the call.
- [Deployment](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/conversational-agents-voice-deployment): connecting a number and binding it to a workflow.
- [Community](community.md): ask questions and share workflows with other builders on the UiPath Forum.