# Agents

Source: https://docs.usetone.ai/agents

> The thing that talks — a prompt, a voice, a language set, and the regulatory purpose that decides when it may call.

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

| | |
|---|---|
| `systemPrompt` | What it is trying to do, in your words |
| `voice` | Which model transcribes, which speaks, in which voice, in which languages |
| `purpose` | The regulatory sender classification — this decides *when* it may call |
| `status` | `draft` or `live` |

```bash
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.

| Purpose | When it may call (IST) | Consent required |
|---|---|---|
| `promotional` | 09:00 – 21:00 | Yes |
| `collections` | 08:00 – 19:00 | No |
| `service` | any time | No |
| `transactional` | any time | No |

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](/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](/agent-versioning).

## Variables

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

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

```bash
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.