> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice agent settings and customization

> Find voice agent prompts, voices, languages, greetings, knowledge, actions, recordings, and post-call fields. Map console settings to the Agents API.

Open [Agents](https://console.pyai.com/agents), select the correct project, and
choose a saved agent. The console and Agents REST API edit the same profile.
Save changes, then start a new test call to check the effective configuration.

## Find a setting in the console

| What you want to change | Where to find it | Details |
| - | - | - |
| Name, role, instructions, speaking perspective | **Identity & voice** | [Instructions and role](#instructions-and-role) |
| Voice and spoken language | **Identity & voice** → **Voice** / **Language** | [Voice and language](#voice-and-language) |
| Opening line and greeting variations | **Identity & voice** → **Opening greeting** | [Greetings](https://docs.pyai.com/guides/agent-greeting.md) |
| Record calls and spoken disclosure | **Identity & voice** → **Advanced & compliance** | [Recording and consent](#recording-and-consent) |
| Reference documents and websites | **Knowledge** | [Knowledge bases](https://docs.pyai.com/guides/knowledge-bases.md) |
| Use workspace knowledge defaults | **Identity & voice** | [Knowledge inheritance](https://docs.pyai.com/guides/knowledge-bases.md#step-3-bind-it-to-your-agents) |
| Enable tools and supply their credentials | **Actions** | [Tool settings](https://docs.pyai.com/guides/omni-tools.md#tool-settings-per-agent-config) |
| Extract custom fields after a call | **Information to collect** | [Post-call data capture](https://docs.pyai.com/guides/post-call-extraction.md) |
| Widget appearance, allowed origins, phone connection | **Website & phone** | [Website customization](https://docs.pyai.com/guides/website-voice-widget.md#appearance-and-actions) |
| Read, update, and connect from code | **API integration** | [Agents API](https://docs.pyai.com/guides/create-agents-api.md) |
| Check setup and test the saved agent | **Review & test** | [Test your changes](#test-your-changes) |

## Instructions and role

Put identity, business policy, conversation flow, and boundaries in **Agent
prompt** (`persona_system_prompt` in the REST API). The response's
`prompt_limit_characters` gives your current character allowance. Knowledge
documents belong in **Knowledge**; keep the prompt focused on how to use them.

`role` selects a starting operating standard. Your instructions remain
authoritative for identity and business policy. Choose `custom` for a workflow
outside the built-in roles. Use `persona_perspective: "caller"` for a simulated
caller or training partner; the default `"agent"` represents the business.

**Write for me**, **Improve**, and **Generate variations** produce drafts.
Review them before applying and saving. They do not configure the tools needed
to perform bookings, transfers, or other business actions.

## Voice and language

Select an Omni-compatible voice in the voice picker. The API field is
`voice_id`; inspect `configured.voice_id` to see the canonical served voice.
Set `language` explicitly for a known language, and check
`configured.language_active` and `language_fallback` before assuming it is active.
The [language reference](https://docs.pyai.com/reference/language-support.md) owns the current roster.

**Voice delivery** is under **Advanced & compliance**. Current Omni routes
support neutral delivery only: leave it blank or set `voice_instruct` to `null`
in the Agents REST API. For a realtime `configure` reset, send an empty string.
A saved custom direction can be rejected when the call configures. Tone and
business instructions in the prompt are separate from this voice control.

For a custom voice, follow [Voice cloning](https://docs.pyai.com/guides/voice-cloning.md), then select
the ready voice in the agent. A voice available for TTS is not automatically
available for every realtime language or product.

## Conversation behavior and vocabulary

Some controls are available through the API even when the editor has no
dedicated field:

| Agent field | Purpose |
| - | - |
| `idle_check_in` | `auto` checks on a silent caller, `patient` waits longer, and `off` waits for the caller to speak. Support agents default to `patient`; most other roles default to `auto`. |
| `persona_perspective` | `agent` represents the business; `caller` represents the person calling it. |
| `vocabulary` | Up to five distinctive names or phrases for speech recognition. Use `[]` or `null` to disable. |
| `continuity` | Opt in to an advisory prior-call caller card when the caller can be resolved. It does not authorize actions. |

Vocabulary is sanitized and fixed at session start, including across transport
reconnects. Omni does not inherit organization Hear vocabulary and has no
inline vocabulary override. Keep terms specific; biasing one name can make
unrelated recognition worse.

`barge_sensitivity`, `ack_mode`, and `keyterms` are stored compatibility fields
that do not change the current Omni runtime. Use `vocabulary` instead of
`keyterms`. In your media client, interruption handling still requires clearing
queued playback on the documented control event; see the
[browser guide](https://docs.pyai.com/guides/browser-voice-agent.md#barge-in-latency-quality).

## Recording and consent

Turn on **Record calls** only when your application should retain audio. Set
**Recording disclosure** (`consent_line`) when enabling `recordings_enabled`.
The spoken order is disclosure, opening greeting, then conversation. Recording
defaults to off. Greeting variants never rotate the consent line.

See [Greetings and recording disclosure](https://docs.pyai.com/guides/agent-greeting.md) for examples
and [Security and data](https://docs.pyai.com/security-and-data.md) for retention. Transcript storage
must [preserve speaker roles](https://docs.pyai.com/guides/omni-transcripts.md).

## Saved settings and per-call overrides

To load a saved profile, connect to Omni with `session_label` equal to its
`agent_id`. A different opaque label does not select that profile. For fields
supported by the realtime protocol, inline `configure` values override saved
settings for that session. REST uses `persona_system_prompt`; realtime uses
`persona`. Do not copy an entire Agent object into `configure`.

Update only the fields you want to change with `POST /v1/agents/{id}`. Omitted
fields stay unchanged; `null` clears fields that permit it. Read the profile
back, then check the new session's `configured` acknowledgement. Updates do
not rewrite an active call.

```bash theme={null}
export AGENT_ID="agent_..." # replace with your saved agent ID
curl --fail-with-body -sS "https://api.pyai.com/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idle_check_in":"patient","vocabulary":["North Clinic"]}'
```

Use the [Agents API guide](https://docs.pyai.com/guides/create-agents-api.md) for creation and updates,
and the [Omni protocol](https://docs.pyai.com/realtime/omni-protocol.md) for supported session fields.
Tools and knowledge bindings have their own dedicated setup guides above.

## Test your changes

Save, then open **Review & test** and start a fresh browser call. Check the
opening line, voice, language, knowledge answers, and any setup warnings.
Browser calls can test conversation behavior; phone transfers and other carrier
actions require the actual phone transport. Check the
[call-control requirements](https://docs.pyai.com/guides/omni-tools.md#engine-mode-call-control) before
enabling those actions.

If a setting appears ineffective, check the selected project and agent, saved
values, `session_label`, inline overrides, and the `configured` response in that
order. A stored field is not proof that the current runtime applies it.


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