Prompt agents

A prompt agent is a single agent driven by one prompt. It is the fastest way to something useful, and it is the right shape whenever the conversation does not have to follow a fixed path.

The prompt

The prompt is the agent's instructions and it is where most behaviour lives. If the agent does not ask for something, uses the wrong tone, skips a step or fails to confirm, the fix is almost always here rather than in a setting.

Write it like a brief for a new employee:

You are the receptionist for Acme Dental.

Your job: find out whether the caller wants to book, move or cancel an
appointment, then collect their full name and phone number.

Always: confirm the details back before ending.
Never: give medical advice, or quote a price.
If asked anything else: say a colleague will call back.

Who speaks first

first_speaker decides whether the agent greets or waits.

• assistant - the agent opens with its greeting.
• user - the agent stays silent until the caller speaks.

This is the most common cause of an agent that appears to do nothing, or that talks over a caller who has already started.

Turn-taking

endpointing.stop_secs is how long a pause has to last before the agent decides the caller has finished. Raise it if the agent interrupts; lower it if replies feel slow.

Silence

By default the agent waits indefinitely. Set silence_timeout_seconds above zero to have it nudge a silent caller, with idle_message as what it says and idle_max_prompts as how many times before it gives up and ends the call.

max_duration_seconds is a hard cap on call length regardless of what is happening.

Speech that cannot be transcribed

Sometimes a caller audibly speaks but the transcriber cannot commit their words - most often speech in a language the agent was not configured for. Instead of going silent, the agent's model receives an automatic system note containing whatever fragment was captured, marked as an unverified transcript with a detected-language hint, and reacts from its own prompt: by default it politely asks the caller to repeat themselves in the language the agent speaks.

Because the note reaches your prompt, you can decide what happens. For example:

If you receive a notice that the caller could not be understood and the
fragment looks like Spanish, say - in English - that support is available
in English only, and offer the callback line.

• unclear_message - pin a fixed sentence to speak instead of involving the model.
• unclear_max_prompts - how many consecutive unintelligible turns before the agent gives up and ends the call with its farewell (default 2; 0 turns recovery off).

This only ever triggers when the caller genuinely spoke: background noise or silence never produces an apology to nobody.

Ending the call

• end_call_phrases - things a caller says that end the call, matched literally.
• end_call_enabled - lets the agent judge from intent that the caller wants to wrap up, rather than waiting for an exact phrase.
• end_call_message - the farewell.

Speaking style

speaking_style controls how the agent sounds rather than what it says: whether it uses natural fillers while it thinks, whether it backchannels ("mm-hm") while the caller talks, and its overall style.

Voicemail

voicemail.enabled lets an outbound call detect an answering machine and leave voicemail.message instead of talking to a beep.

Compliance

compliance.redact_pii replaces structured identifiers in stored transcripts. It is currently inactive and cannot be turned on. See Privacy and compliance.

What else an agent can have

• Models and voices - which model, transcriber and voice.
• Knowledge base - answer from your own documents.
• Tools - take actions mid-conversation.
• Variables and extraction - pass data in, capture data out.