# 会話の設定

> AI の役割・あいさつ・聞き取る項目・よくある質問・人に引き継ぐ条件・声・話す速さを決める、会話の設定（agent）の書き方。

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

会話の設定（agent）は、AI が何を話し、何を聞き取り、いつ人に渡すかを決めるものです。1 つの設定を複数のテナントで使えます。管理画面の「会話の設定」か、API（`POST /v1/agents`）・MCP（`create_agent`）で作ります。

## 全体の形

```json
{
  "name": "歯科医院の受付",
  "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
  }
}
```

## 項目

| 項目 | 必須 | 内容 | 上限 |
| --- | --- | --- | --- |
| `greeting` | ○ | 最初のあいさつ。そのまま読み上げます | 300 文字 |
| `persona` | ○ | 役割と話し方（例: 落ち着いた丁寧な受付。1 回の発話は 2 文まで） | 1,000 文字 |
| `fields` | ○ | 聞き取る項目（下） | 1〜20 個 |
| `handoff_when` | ○ | 人に引き継ぐ条件（下）。空の配列も可 | 20 個・各 200 文字 |
| `closing` | ○ | 聞き取りが終わったときの締めの言葉 | 300 文字 |
| `closing_answered` | | よくある質問に答えて用が済んだときの締めの言葉 | 300 文字 |
| `faq` | | よくある質問 `[{ q, a }]` | 50 個・q 200 文字・a 1,000 文字 |
| `domain` | | 業種（音声認識の手がかり） | 200 文字 |
| `vocabulary` | | 業界の用語・固有名詞（音声認識の手がかり） | 200 個・各 50 文字 |
| `voice` | | 声の名前（下）。省くと `Aoede` | |
| `speaking_rate` | | 話す速さ（下）。省くと `1.15` | |
| `tools` | | 通話中に自社の API を呼ぶ道具。[通話中の道具](https://voicast.jp/docs/tools.md) | 10 個 |
| `connectors` | | 連携（Google カレンダー・Slack など）を使う。[連携](https://voicast.jp/docs/connectors.md) | 10 個 |

知らない項目は保存しません。誤りがあると 422 `invalid_config` で、`details` に項目ごとの誤りが並びます。

## 聞き取る項目（fields）

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

| 項目 | 内容 |
| --- | --- |
| `key` | 結果の `fields` の名前。英小文字で始まり、英小文字・数字・`_` の 40 文字まで。重ならないこと |
| `label` | AI が聞くときの言葉（100 文字まで） |
| `required` | `true` なら、そろうまで通話を終えません |
| `type` | `text`（既定）か `phone`。`phone` は数字だけにそろえて残し、0 で始まる 10 桁か 11 桁でなければ聞き直します |

名前と電話番号は、AI が聞き取った内容を復唱して確かめます。電話番号は 3 つに区切って読み上げます。

## 人に引き継ぐ条件（handoff_when）

当てはまったら、AI は名前などを聞かずにすぐ会話を終え、結果を `handoff` にします。電話なら、そのあと人に転送します（[電話でつなぐ](https://voicast.jp/docs/phone.md#引き継ぎ)）。

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

条件は普通の文で書きます。広すぎる条件（「質問された」など）は、ほとんどの通話が引き継ぎになるので避けます。

## よくある質問（faq）

聞かれたら、AI はこの答えだけを使って答えます。書いていないことは推測せず、担当者からの折り返しにします。質問に答えて用が済んだら、結果は `answered` になり、`closing_answered` で締めます。

## 通話の結果

AI が会話を終えると、通話の `outcome` が決まります。

| `outcome` | いつ |
| --- | --- |
| `completed` | 必須の項目がそろい、担当者から折り返す |
| `answered` | よくある質問に答えて用が済んだ |
| `handoff` | 引き継ぐ条件に当たった（今すぐ人につなぐ） |
| `hangup` | 相手が黙ったまま（聞き直しても返事が無い） |
| `error` | 会話が途中で切れた・音声サーバーの障害など |

## 声（voice）

Google の Chirp 3 HD の日本語の声から、名前で選びます。管理画面の「会話の設定」で試聴できます。

| 名前 | 性別 | 特徴 |
| --- | --- | --- |
| `Aoede`（既定） | 女性 | 軽やか |
| `Kore` | 女性 | きっぱり |
| `Leda` | 女性 | 若々しい |
| `Zephyr` | 女性 | 明るい |
| `Autonoe` | 女性 | 明るい |
| `Laomedeia` | 女性 | 明るい |
| `Sulafat` | 女性 | 温かい |
| `Vindemiatrix` | 女性 | やさしい |
| `Achernar` | 女性 | 柔らかい |
| `Despina` | 女性 | なめらか |
| `Erinome` | 女性 | はっきり |
| `Pulcherrima` | 女性 | はきはき |
| `Gacrux` | 女性 | 大人っぽい |
| `Callirrhoe` | 女性 | おおらか |
| `Charon` | 男性 | 落ち着いて説明的 |
| `Puck` | 男性 | 明るい |
| `Orus` | 男性 | きっぱり |
| `Alnilam` | 男性 | きっぱり |
| `Fenrir` | 男性 | 元気 |
| `Achird` | 男性 | 親しみやすい |
| `Iapetus` | 男性 | はっきり |
| `Umbriel` | 男性 | 気さく |
| `Algieba` | 男性 | なめらか |
| `Algenib` | 男性 | 低くかすれた |
| `Rasalgethi` | 男性 | 説明的 |
| `Schedar` | 男性 | 落ち着いた |
| `Zubenelgenubi` | 男性 | くだけた |
| `Sadachbia` | 男性 | 生き生き |
| `Sadaltager` | 男性 | 物知り |
| `Enceladus` | 男性 | 息まじり |

## 話す速さ（speaking_rate）

`1.0` がふつうの速さです。電話では少し遅く感じるので、既定は `1.15` です。次の数から選びます。

| 数 | 速さ |
| --- | --- |
| `0.85` | とてもゆっくり |
| `0.9` | ゆっくり |
| `0.95` | 少しゆっくり |
| `1.0` | ふつう |
| `1.05` | ほんの少し速め |
| `1.1` | やや速め |
| `1.15` | 少し速め（既定） |
| `1.2` | 速め |
| `1.25` | かなり速め |
| `1.3` | 速い |
| `1.4` | とても速い |
| `1.5` | いちばん速い |

## 言語

今は日本語の会話に対応しています。ほかの言語は今後対応します。

## 版

会話の設定を変える（`PUT /v1/agents/{id}`）と、新しい版になります。進行中の通話は始まったときの版のまま続き、次の通話から新しい版を使います。通話の記録には使った版（`agent.version`）が残り、`GET /v1/agents/{id}?version=` で当時の中身を見られます。

`PUT` では `config` を全体で渡します（一部だけの変更はできません）。

## テナントへの割り当て

テナントの `agent_id` が、そのテナントの通話の既定の設定です。電話では `<Parameter name="agent">`、Web・アプリでは `POST /v1/sessions` の `agent_id` で、通話ごとに別の設定を使えます。

使っているテナントがある設定は消せません（409 `in_use`）。先にテナントの `agent_id` を替えます。

## 書き方のこつ

- `persona` に「1 回の発話は 2 文まで」と書くと、電話で聞きやすくなります。
- 聞き取る項目は少なくします。必須の項目が多いと通話が長くなります。
- 業界の用語・商品名・地名は `vocabulary` に入れると、聞き取りが安定します。
- 試すときはテストの環境で、[Web・アプリ](https://voicast.jp/docs/web.md)から話すのが手早い方法です。