Agents

An agent is what your caller actually speaks to. It carries four things that matter and several that are optional:

curl "$TONE_API/v1/agents" -X POST \
  -H "Authorization: Bearer $TONE_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Order confirmation",
    "purpose": "transactional",
    "systemPrompt": "You call customers to confirm a cash-on-delivery order. Confirm the order, ask which day suits them for delivery, then thank them and end the call. Be brief and polite.",
    "voice": {
      "ttsModel": "bulbul:v3",
      "ttsVoice": "simran",
      "sttModel": "saaras:v3",
      "languages": ["hi-IN", "en-IN"]
    }
  }'

Write the task, not the manners

The platform already handles the conversational layer: interruptions, matching the caller's language, waiting when they go quiet, ending the call when it is over. A prompt that spends its words on "be polite and let the user finish" is spending them twice.

Write what the call is for, what counts as done, and what the agent must not promise. That is the part only you know.

Purpose is not a label

🔴 purpose decides which calling window applies to every call this agent makes, and whether consent is required before it dials at all.

It defaults to promotional — the strictest — precisely so that getting it wrong fails safe. There is deliberately no per-call override: a request field that relaxed the gate would make the whole audit trail worthless, because a caller could simply opt out of being checked. See Compliance.

Draft and live

A new agent is always a draft, whatever you send.

• A draft can be dialled outbound. It will not answer inbound calls.
• Publishing freezes the working copy into an immutable numbered version and points the agent at it.

Editing an agent changes nothing about calls in progress and nothing about what answers your phone number. Publishing is the step that changes behaviour — see Agent versioning.

Variables

inputVariables are {{placeholders}} the prompt can reference and each call can fill:

{ "inputVariables": [{ "name": "customer_name", "default": "there" }] }

curl "$TONE_API/v1/calls" -X POST \
  -H "Authorization: Bearer $TONE_KEY" \
  -H 'content-type: application/json' \
  -d '{"agentId":"...","numberId":"...","toE164":"+919876543210",
       "variables":{"customer_name":"Priya"}}'

Give every variable a default, even an empty-sounding one. A placeholder with nothing behind it is how an agent ends up saying "your order ORDER_ID".

outputVariables run the other way: fields extracted from the transcript after the call and returned as outputs on the call record. The description is the extraction instruction — write it as you would tell a person what to look for, not as a field label.

evaluationCriteria are questions a post-call judge answers about the call, returned as evaluations with a verdict and a rationale each. Use them for "did this call do its job", not for data you want back — that is what output variables are for.

Call settings

callSettings is how the call runs rather than what it says: the opening line, background ambience, what to do when the caller goes quiet, voicemail handling, a maximum duration and a farewell. Custom lines are translated into the agent's languages automatically when you save.

Two of those are stripped on inbound calls, deliberately: an opening line is written as "calling from X about Y" and would greet someone who rang you, and voicemail detection is a callee-side judgement that would hang up on a real person.

Deleting

Deleting an agent unassigns its numbers rather than releasing them, and keeps its call log. Deleting the agent must not erase the record of what it said.