エージェント設定
AI の
エージェントPOST /v1/agents)create_agent)
全体の形#
{
"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": "female-firm",
"speaking_rate": 1.0
}
}項目#
| 項目 | 必須 | 内容 | 上限 |
|---|---|---|---|
greeting |
○ | 最初の |
300 文字 |
persona |
○ | 役割と |
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 |
声のfemale-breezy |
||
speaking_rate |
話す速さ1.0 |
||
language |
会話のja |
||
tools |
会話中に |
10 個 | |
connectors |
連携 |
10 個 | |
recording |
true で |
||
max_call_minutes |
1 回の30 |
知らないinvalid_config で、details に
聞き取る項目(fields)#
{ "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" }| 項目 | 内容 |
|---|---|
key |
結果のfields の_ の |
label |
AI が |
required |
true なら、 |
type |
textphone。phone は |
名前と
名前の読み#
電話ではname などにkey がkana でname_kana など)furigana・yomi・reading をlabel にlabel に
{ "key": "name_kana", "label": "お名前の読み" }- 半角カナ・
ひらが な・カタカナの 違いは そろえ、 空白は 1 つにします ( ヤマダ タロウ) nameなどほかの 項目の 値と 形は 変わりません。 読みの 項目を 足さなければ、 結果も これまでと 同じです - テンプレートには、
どれも name_kana(お名前の 読み) が 入っています
担当者に転送するとき(handoff_when)#
当てはhandoff にします。
"handoff_when": ["人と話したいと言われた", "怒っている", "急な痛みや腫れがある", "聞き取れない状態が 2 回続いた"]条件は
AI はpersona にhandoff の
よくある質問(faq)#
聞かれたら、answered にclosing_answered で
会話の結果#
AI がoutcome が
outcome |
管理画面の |
いつ |
|---|---|---|
completed |
完了 | 必須の |
answered |
質問に |
よく |
handoff |
担当者に |
担当者に |
hangup |
途中で |
相手が |
time_limit |
時間の |
会話のmax_call_minutes) |
error |
失敗 | 音声サーバーの |
声(voice)#
次の
| ID | 性別 | 管理画面の |
|---|---|---|
female-breezy |
女性 | 軽やかな |
female-firm |
女性 | きっぱりした |
female-youthful |
女性 | 若々しい |
female-bright |
女性 | 明る |
female-cheerful |
女性 | 朗らかな |
female-upbeat |
女性 | 弾むような |
female-warm |
女性 | 温かい |
female-gentle |
女性 | やさしい |
female-soft |
女性 | 柔らかい |
female-smooth |
女性 | なめらかな |
female-clear |
女性 | はっきりした |
female-brisk |
女性 | は |
female-mature |
女性 | 大人っぽい |
female-easygoing |
女性 | おおらかな |
male-calm |
男性 | 落ち着いた |
male-upbeat |
男性 | 明る |
male-firm |
男性 | きっぱりした |
male-deep |
男性 | 重厚な |
male-energetic |
男性 | 元気な |
male-friendly |
男性 | 親しみやすい |
male-clear |
男性 | はっきりした |
male-easygoing |
男性 | 気さくな |
male-smooth |
男性 | なめらかな |
male-gravelly |
男性 | 低くかすれた |
male-informative |
男性 | 説明上手な |
male-steady |
男性 | 穏やかな |
male-casual |
男性 | くだけた |
male-lively |
男性 | 生き |
male-savvy |
男性 | 物知りな |
male-breathy |
男性 | 息まじりの |
話す速さ(speaking_rate)#
1.0 が
| 数 | 速さ |
|---|---|
0.85 |
とても |
0.9 |
ゆっくり |
0.95 |
少し |
1.0 |
ふつう |
1.05 |
ほんの |
1.1 |
や |
1.15 |
少し |
1.2 |
速め |
1.25 |
かなり |
1.3 |
速い |
1.4 |
とても |
1.5 |
いちばん速い |
言語(language)#
AI が
| 値 | 言語 |
|---|---|
ja |
日本語 |
en |
英語 |
zh |
中国語 |
ko |
韓国語 |
auto |
相手に |
- 音声認識・AI の
返事・声が その 言語に なります。 声 ( voice)は、 どの 言語でも 同じ声で 話します。 greeting・closing・closing_answeredは書いた とおりに 読み上げます。 ja以外を選んだら、 その 言語で 書いてください。 人に つなぐ ときや 聞き直しなど、 決まった 言い回しは voicast が その 言語で 話します。 autoは、相手が 話した 言語で 返事を します。 最初の あいさつは 書いた 言語の まま 流れ、 相手の 言語が 分かるまでは 日本語で 話します。 締めの 言葉は、 書いた 言語が 相手の 言語と 同じ ときだけ 使い、 違えば voicast が その 言語の 決まった 締めを 話します。
ツール(tools)#
AI がtools と、connectors で
"tools": [
{
"name": "find_customer",
"description": "電話番号で顧客を探す。会話の最初に、かけてきた番号で使う",
"url": "https://api.example-crm.com/v1/customers/search",
"method": "GET",
"sign": false,
"auth": { "type": "api_key", "header": "Authorization", "value": "sk_live_…" },
"parameters": {
"properties": { "phone": { "type": "string", "description": "電話番号(数字だけ)" } },
"required": ["phone"]
}
}
]| 項目 | 必須 | 内容 |
|---|---|---|
name |
○ | ツールの_ の |
description |
○ | 何を |
url |
○ | 呼ぶ先 |
method |
GET かPOST。POST |
|
sign |
省くとtrue。tool.call のfalse は |
|
auth |
{ "type": "api_key", "header", "value" }。 |
|
parameters |
引数。 |
|
confirm |
true なら、 |
|
confirm_message |
confirm の{引数の名前} に |
|
done_message |
confirm の{引数の名前} を"" なら |
- API キー
( auth.value)は 保存すると 設定から 外し、 暗号化して 預かります。 バージョンの 履歴には 残らず、 応答の tool_keysに名前と 末尾 4文字だけが 並びます。 2回目からは valueを省けます。 - 詳しくは会話中の
ツール を見てください。
管理画面のフォーム#
管理画面の
| 欄 | API の |
|---|---|
| ツール名 | name |
| 説明 | description |
| URL | url |
| メソッド | method |
| 署名を |
sign |
| 確認してから |
confirm |
| 確認の |
confirm_message・done_message |
| 認証 |
auth |
| API キーを |
auth.header |
| API キー | auth.value。 |
| 引数 |
parameters |
ツールごとの
録音(recording)#
"recording": true に
- 電話と
Web・アプリの 両方の 会話で、 相手と AI の 両方の 声を 1 本の 音声 (MP3・モノラル) に 録ります。 文章だけを 返す会話 ( output: "text")は、 相手の 声だけです。 - 録音は
会話が 終わってから 保存し、 保存してから 環境の 保存期間 (1・7・14・30 日。 初期値は 30 日) が 過ぎると 自動で 削除します。 期限は 会話の recording.expires_atで分かります (保存期間) 。 - 録音は
会話記録の 画面で 再生でき、 API ( GET /v1/calls/{id}/recording)でも 取れます (結果の 受け取り )。 できたら Webhook の call.recording_readyが届きます。 - 録音の
保存に 追加の 料金は かかりません (会話 1 分 10 円の まま。料金と 請求 )。 - バージョンを
変えても、 進行中の 会話は 始まった ときの バージョンの 設定で 録音するかを 決めます。
録音するgreeting に
会話の長さの上限(max_call_minutes)#
1 回の5・10・15・30・6030 分です。
- 上限の
少し 前に、 AI は 決まった 言葉 (日本語は 「お時間と なりましたので、 これで 失礼いたします。 」 ) で 会話を 終えます。 会話の outcomeはtime_limitです。 - 予約などの
手続きが 済んでいないまま 終える ときは、 締めの 前に その ことを 伝えます。 - 長さは
電話と Web・アプリの 両方で、 会話が つながった ときから 数えます。
バージョン#
エージェント設定をPUT /v1/agents/{id})agent.version)GET /v1/agents/{id}?version= で
PUT ではconfig を
ツールの
テナントへの割り当て#
テナントのagent_id が、<Parameter name="agent">、POST /v1/sessions のagent_id で、
テナントかin_use)agent_id をagent_id をPATCH /v1/tenants/{id}/sip-credentials/{credential})
テンプレート#
最初からGET /v1/agent-templates、list_agent_templates で
id |
名前 | 聞き取る |
変更する |
|---|---|---|---|
dental_clinic |
歯科医院の |
ご用件・初めての |
|
restaurant |
飲食店の |
ご希望の |
|
inquiry |
問い合わせの |
ご用件・会社名・ |
|
take_message |
不在時の |
ご伝言を |
|
car_service |
整備工場・タイヤショップの |
ご用件・ご希望の |
- どれも、
AI の 役割 ( persona)・ あいさつ・ 聞き取る 項目・よく ある 質問の 例・ 担当者に 引き継ぐ ときの 例・ 締めの あい さつが 入っています。 歯科医院と 整備工場・タイヤショップは、 人に 渡すときに、 医院・店舗の 電話番号を 伝えて 直接掛け直していただく 言い方で 締めます (結果は handoff)。 番号は、 医院・店舗の 情報を 返す連携の 道具で 確かめます。 番号が 分からない ときは、 先に お名前・ お電話番号・ご用件を 伺い、 スタッフから 折り返すと 伝えます。 連携 ( connectors・tools)は 入っていません。 空き状況の 確認と 予約の 確定は、 スタッフが 折り返して行う 形です。 カレンダーなどを つないで AI が 予約を 入れた ときは、 締めの あいさつ ( closing)の 代わりに 短い お礼で 締めます。 - 医院や
店の 名前・営業時間などは 「〇〇歯科」 「株式会社〇〇」 「〇〇 (営業時間) 」 の 形で 置いてあります。 お使いの 名前や 内容に 変更してから 作成します。 「〇〇」 が 残っていると 422 invalid_configになり、 detailsに変更する 箇所が 並びます。 - 文言は、
歯科医院・飲食店・整備工場の 予約・会社の 電話応対の 例文に 合わせて 書いています。 あいさつでは、 AI が 受けている こと・話の 内容を 記録する こと・担当者と 話す方法を 伝えます。
管理画面で試す#
管理画面の
- 会話に
使う テナントを 選びます。 ツールと 連携には、 この テナントの お客様 ID ( external_id)と テナント専用の 連携が 使われます。 実際の お客様と 分けるには、 試す用の テナントを 作って おきます (管理画面は テナントを 自動では 作りません) 。 - [開始]を
押し、 マイクの 使用を 許可すると、 AI が あいさつします。 - 話している
あいだ、 文字起こし・AI が 呼んだ ツール (名前・引数・結果) ・ 聞き取った 項目・会話の 結果・経過時間が 画面に 出ます。 - [終了]で
切ります。 会話は 会話記録に 残り ( channel: 'web')、 Webhook や 会話後の 通知も 実際の 会話と 同じように 送られます。
- 会話は、
保存した 最新の バージョンで 進みます。 保存していない 変更は 反映されません。 - 試す会話も
料金が かかります。 実際の 会話と 同じく、 1 分 10 円 (税抜) を 残高から 差し 引きます (テスト環境でも 同じです) 。 残高が 無ければ 始められません (402 balance_depleted)。 - 使えるのは、
開発者以上の ロールの 人です。
書き方のこつ#
personaに「1 回の 発話は 2 文まで」 と 書くと、 電話で 聞きやすくなります。 - 聞き取る
項目は 少なくします。 必須の 項目が 多いと 会話が 長くなります。 - 業界の
用語・商品名・店名・スタッフの 名前・地名は vocabularyに入れると、 聞き取りが 安定します (人の 名前や 地名は、 入れると 字の 取り違えが 大きく 減ります。聞き取りの 正しさ )。 - 試すときは、
管理画面の [ブラウザーで 試す] (管理画面で 試す )が 手早い 方法です。 自社の 画面から 試すときは、 テストの 環境で Web・アプリから つなぎます。
聞き取りの正しさ#
日本語にvocabulary に
| 標準語 | 方言 | |
|---|---|---|
| 聞き取り精度 | 94% | 93% |
※当社の