# Agents

> How to write an agent: the AI's role, greeting, fields to collect, FAQ, handoff rules, voice and speaking rate.

Source: https://voicast.jp/en/docs/agents

An agent decides what the AI says, what it collects and when it hands off to a person. One agent can serve many tenants. Create agents in the dashboard (Agents), with the API (`POST /v1/agents`) or over MCP (`create_agent`).

Conversations are in Japanese today, so the text you write (greeting, persona, labels, rules, FAQ) is in Japanese. Field keys and other identifiers are ASCII.

## Shape

```json
{
  "name": "Dental reception",
  "config": {
    "greeting": "お電話ありがとうございます。さくら歯科です。ご用件をお話しください。",
    "persona": "落ち着いた丁寧な受付。1 回の発話は 2 文まで",
    "fields": [
      { "key": "name", "label": "お名前", "required": true },
      { "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" },
      { "key": "purpose", "label": "ご用件", "required": true }
    ],
    "handoff_when": ["人と話したいと言われた", "急な痛みや腫れがある"],
    "closing": "承知しました。担当者から折り返しご連絡します。",
    "closing_answered": "ほかにご不明な点があれば、またお電話ください。",
    "faq": [
      { "q": "診療時間は", "a": "平日は 9 時から 18 時、土曜は 13 時までです。日曜・祝日は休みです。" }
    ],
    "domain": "歯科医院",
    "vocabulary": ["インプラント", "ホワイトニング", "定期検診"],
    "voice": "Kore",
    "speaking_rate": 1.15
  }
}
```

## Fields

| Field | Required | Description | Limit |
| --- | --- | --- | --- |
| `greeting` | yes | The first thing the AI says, read out as written | 300 chars |
| `persona` | yes | Role and manner of speaking (e.g. calm, polite receptionist; at most two sentences per turn) | 1,000 chars |
| `fields` | yes | What to collect (below) | 1–20 |
| `handoff_when` | yes | When to hand off to a person (below). May be an empty array | 20 items, 200 chars each |
| `closing` | yes | What the AI says when it has collected everything | 300 chars |
| `closing_answered` | | What it says when an FAQ answer settled the call | 300 chars |
| `faq` | | Frequent questions `[{ q, a }]` | 50; q 200 chars, a 1,000 chars |
| `domain` | | Line of business (a hint for speech recognition) | 200 chars |
| `vocabulary` | | Industry terms and proper nouns (hints for speech recognition) | 200 items, 50 chars each |
| `voice` | | Voice name (below). Defaults to `Aoede` | |
| `speaking_rate` | | Speaking rate (below). Defaults to `1.15` | |
| `tools` | | Your API endpoints the AI can call during a call. See [Tools](https://voicast.jp/en/docs/tools.md) | 10 |
| `connectors` | | Connections such as Google Calendar or Slack. See [Connections](https://voicast.jp/en/docs/connectors.md) | 10 |

Unknown keys are dropped. Invalid input returns 422 `invalid_config` with one entry per problem in `details`.

## Fields to collect

```json
{ "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" }
```

| Key | Description |
| --- | --- |
| `key` | Name in the call's `fields`. Starts with a lowercase letter; lowercase letters, digits and `_`, up to 40 chars. Must be unique |
| `label` | How the AI asks for it (up to 100 chars) |
| `required` | When `true`, the call does not finish until it is collected |
| `type` | `text` (default) or `phone`. Phone numbers are stored as digits only, and the AI asks again unless the number is 10 or 11 digits starting with 0 (Japanese numbers) |

The AI reads names and phone numbers back to confirm them; phone numbers are read in three groups.

## Handoff rules

When a rule matches, the AI ends the conversation right away (without asking for a name and so on) and the outcome is `handoff`. On the phone you then transfer the call to a person ([Phone](https://voicast.jp/en/docs/phone.md#handoff)).

```json
"handoff_when": ["人と話したいと言われた", "怒っている", "急な痛みや腫れがある", "聞き取れない状態が 2 回続いた"]
```

Write rules as plain sentences. Avoid broad rules (such as "the caller asked a question"), or most calls will be handed off.

## FAQ

When asked, the AI answers using only these answers. Anything not written here is not guessed; the AI offers a callback instead. When an answer settles the call, the outcome is `answered` and the AI closes with `closing_answered`.

## Outcomes

When the AI ends the conversation, the call's `outcome` is set.

| `outcome` | When |
| --- | --- |
| `completed` | All required fields were collected; staff will call back |
| `answered` | An FAQ answer settled the call |
| `handoff` | A handoff rule matched (connect a person now) |
| `hangup` | The caller stayed silent, even after being asked again |
| `error` | The conversation was cut off, or the voice server failed |

## Voices

Pick one of Google's Chirp 3 HD Japanese voices by name. You can listen to each voice in the dashboard (Agents).

| Name | Gender | Character |
| --- | --- | --- |
| `Aoede` (default) | Female | Breezy |
| `Kore` | Female | Firm |
| `Leda` | Female | Youthful |
| `Zephyr` | Female | Bright |
| `Autonoe` | Female | Bright |
| `Laomedeia` | Female | Upbeat |
| `Sulafat` | Female | Warm |
| `Vindemiatrix` | Female | Gentle |
| `Achernar` | Female | Soft |
| `Despina` | Female | Smooth |
| `Erinome` | Female | Clear |
| `Pulcherrima` | Female | Forward |
| `Gacrux` | Female | Mature |
| `Callirrhoe` | Female | Easy-going |
| `Charon` | Male | Calm and informative |
| `Puck` | Male | Upbeat |
| `Orus` | Male | Firm |
| `Alnilam` | Male | Firm |
| `Fenrir` | Male | Excitable |
| `Achird` | Male | Friendly |
| `Iapetus` | Male | Clear |
| `Umbriel` | Male | Easy-going |
| `Algieba` | Male | Smooth |
| `Algenib` | Male | Gravelly |
| `Rasalgethi` | Male | Informative |
| `Schedar` | Male | Even |
| `Zubenelgenubi` | Male | Casual |
| `Sadachbia` | Male | Lively |
| `Sadaltager` | Male | Knowledgeable |
| `Enceladus` | Male | Breathy |

## Speaking rate

`1.0` is normal speed. On the phone that tends to feel slow, so the default is `1.15`. Choose one of these values.

| Value | Speed |
| --- | --- |
| `0.85` | Very slow |
| `0.9` | Slow |
| `0.95` | A little slow |
| `1.0` | Normal |
| `1.05` | Barely faster |
| `1.1` | Slightly faster |
| `1.15` | A little faster (default) |
| `1.2` | Faster |
| `1.25` | Quite fast |
| `1.3` | Fast |
| `1.4` | Very fast |
| `1.5` | Fastest |

## Languages

Conversations are in Japanese today. More languages are coming.

## Versions

Updating an agent (`PUT /v1/agents/{id}`) creates a new version. Calls already in progress keep the version they started with; the next call uses the new one. Each call records the version it used (`agent.version`), and `GET /v1/agents/{id}?version=` returns that version's config.

`PUT` takes the whole `config`; partial updates are not supported.

## Assigning to tenants

A tenant's `agent_id` is the default agent for its calls. You can override it per call: `<Parameter name="agent">` on the phone, or `agent_id` in `POST /v1/sessions` for Web and apps.

An agent used by a tenant cannot be deleted (409 `in_use`). Change the tenant's `agent_id` first.

## Tips

- Putting "at most two sentences per turn" (「1 回の発話は 2 文まで」) in `persona` makes the AI easier to follow on the phone.
- Collect as few fields as you can. Many required fields make calls long.
- Put industry terms, product names and place names in `vocabulary` for steadier recognition.
- To try an agent quickly, talk to it from the [Web](https://voicast.jp/en/docs/web.md) in the test environment.