ページの一覧

ドキュメント

エージェント設定

AI の役割・あいさつ・聞き取る項目・よくある質問・担当者に転送するときの条件・声・話す速さ・言語を決める、エージェント(agent)の書き方。

Markdown で見る

エージェント(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": "female-firm",
    "speaking_rate": 1.0
  }
}

項目#

項目 必須 内容 上限
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 声の ID(下)。省くと female-breezy
speaking_rate 話す速さ(下)。省くと 1.0
language 会話の言語(下)。省くと ja
tools 会話中に API(自社の API・ほかの会社の API)を呼ぶツール(下)。会話中のツール 10 個
connectors 連携(ほかの会社の API)を使う。連携 10 個
recording true で会話を録音する(下)。省くと録音しない
max_call_minutes 1 回の会話の長さの上限(分。下)。省くと 30

知らない項目は保存しません。誤りがあると 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 つに区切って読み上げます。名前は漢字を使わず、聞こえた読みで復唱します。

名前の読み#

電話では字が聞こえないので、name などに入る漢字は、音声認識が当てた字です(「こばやし まこと」が「小林真琴」になるなど、同じ読みの別の字のことがあります)。 読みも残すときは、読みの項目を足してください。key が kana で終わる(name_kana など)か、furigana・yomi・reading を含む項目と、label に「読み」「ふりがな」「フリガナ」「カナ」がある項目は、AI が相手には聞かずに、聞こえた読みを全角カタカナで入れます(label に「ひらがな」とあればひらがな)。

json
{ "key": "name_kana", "label": "お名前の読み" }
  • 半角カナ・ひらがな・カタカナの違いはそろえ、空白は 1 つにします(ヤマダ タロウ)
  • name などほかの項目の値と形は変わりません。読みの項目を足さなければ、結果もこれまでと同じです
  • テンプレートには、どれも name_kana(お名前の読み)が入っています

担当者に転送するとき(handoff_when)#

当てはまったら、AI は名前などを聞かずにすぐ会話を終え、結果を handoff にします。電話なら、そのあと人に転送します(電話でつなぐ)。

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

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

AI は締めに「担当者におつなぎします。少々お待ちください。」と言います。人に渡す前にすること(道具で調べる・お名前などを伺う)や、人に渡すときの言い方を persona に書くと、AI はそれを済ませてから、その言い方で締めます(200 文字まで。結果は handoff のまま)。その場で転送しないとき(「お手数ですが、店舗のお電話にお掛け直しください」など)に使います。

よくある質問(faq)#

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

会話の結果#

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

outcome 管理画面の表示 いつ
completed 完了 必須の項目がそろい、担当者から折り返す
answered 質問に回答 よくある質問に答えて用が済んだ
handoff 担当者に転送 担当者に転送するときの条件に当たった(転送はお使いのシステムで行う)
hangup 途中で終了 相手が途中で切った・黙ったまま(聞き直しても返事が無い)
time_limit 時間の上限で終了 会話の長さの上限(max_call_minutes)に達した(下)
error 失敗 音声サーバーの障害など

声(voice)#

次の声から ID で選びます。どの声も、選べるすべての言語で話せます。管理画面の「エージェント設定」で試聴できます。

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 が会話中に呼ぶ API です。予約の空きの確認や顧客の検索などに使います。AI に渡すのは、このエージェント設定の tools と、connectors で名前を並べた連携の操作だけです。

json
"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 ○ ツールの名前。英小文字で始まり、英小文字・数字・_ の 40文字まで
description ○ 何をするツールか、いつ使うか(500文字まで)
url ○ 呼ぶ先(https)
method GET か POST。省くと POST
sign 省くと true。voicast の署名を付けて tool.call の形で POST します(自社の API 向け)。false は引数をそのまま送ります(ほかの会社の API 向け)
auth { "type": "api_key", "header", "value" }。API キーをヘッダーに付けます
parameters 引数。AI が会話から聞き取って渡します
confirm true なら、voicast が決まった確認の文で相手の同意を伺ってから使い、結果も決まった文で伝えます
confirm_message confirm のツールの確認の文(200文字まで)。{引数の名前} に値を差し込みます
done_message confirm のツールが済んだときの文(200文字まで)。{引数の名前} を差し込めます。空文字 "" なら済んだときの文を言いません(会話中のツール)
  • API キー(auth.value)は保存すると設定から外し、暗号化して預かります。バージョンの履歴には残らず、応答の tool_keys に名前と末尾 4文字だけが並びます。2回目からは value を省けます。
  • 詳しくは会話中のツールを見てください。

管理画面のフォーム#

管理画面のエージェント設定のフォームの[ツール]で、[ツールを追加]を押して追加します(10個まで)。

欄 API の項目
ツール名 name
説明 description
URL url
メソッド method
署名を付ける sign
確認してから使う confirm
確認の文・完了の文(確認してから使うときだけ出ます) confirm_message・done_message
認証(認証なし/API キー) auth
API キーを付けるヘッダー(Authorization(Bearer)/その他) auth.header
API キー auth.value。保存したあとは表示しません。変更するときだけ入力します
引数(名前・説明・必須) parameters

ツールごとの[試す]を押すと、引数を入力して API を 1回呼び、[試した結果]に成功・失敗、状態コード、処理時間、本文が出ます。保存の前のフォームの内容で呼べます。会話の料金はかからず、会話の記録にも残りません。データを変更するツールは、実際に変更されます(ツールを試す)。

録音(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・60(分)から選びます。省くと 30 分です。管理画面ではエージェント設定の[会話の長さの上限]で選びます。

  • 上限の少し前に、AI は決まった言葉(日本語は「お時間となりましたので、これで失礼いたします。」)で会話を終えます。会話の outcome は time_limit です。
  • 予約などの手続きが済んでいないまま終えるときは、締めの前にそのことを伝えます。
  • 長さは電話と Web・アプリの両方で、会話がつながったときから数えます。

バージョン#

エージェント設定を変える(PUT /v1/agents/{id})と、新しいバージョンになります。進行中の会話は始まったときのバージョンのまま続き、次の会話から新しいバージョンを使います。会話記録には使ったバージョン(agent.version)が残り、GET /v1/agents/{id}?version= で当時の中身を見られます。

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

ツールの API キーはバージョンの外に預けます。バージョンを戻しても、同じ名前のツールはいま預けているキーを使います。

テナントへの割り当て#

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

テナントか SIP の接続情報が使っている設定は消せません(409 in_use)。先にテナントの agent_id を替え、SIP の接続情報は agent_id を替える(PATCH /v1/tenants/{id}/sip-credentials/{credential})か削除します。

テンプレート#

最初から中身が入ったエージェント設定です。管理画面の「エージェントの作成」で最初に選べます(「はじめから作成」も選べます)。API は GET /v1/agent-templates、MCP は list_agent_templates で同じものを返します。

id 名前 聞き取る項目 変更する箇所
dental_clinic 歯科医院の電話予約 ご用件・初めてのご来院かどうか・ご希望の日時・お名前・お名前の読み・折り返しのお電話番号 「〇〇歯科」・「〇〇(診療時間)」・「〇〇(駐車場の場所)」・「〇〇(台数)」
restaurant 飲食店の予約 ご希望の日時・人数・ご予約のお名前・お名前の読み・当日ご連絡のつくお電話番号・お席やお料理のご希望 「〇〇(店名)」・「〇〇(営業時間)」・「〇〇(定休日)」・「〇〇(キャンセル料の決まり)」
inquiry 問い合わせの受付 ご用件・会社名・お名前・お名前の読み・折り返しのお電話番号・折り返しのご希望の時間帯 「株式会社〇〇」・「〇〇(受付時間)」・「〇〇(所在地)」
take_message 不在時の伝言 ご伝言をお伝えする相手・ご伝言の内容・会社名・お名前・お名前の読み・折り返しのお電話番号 「株式会社〇〇」・「〇〇(営業時間)」
car_service 整備工場・タイヤショップの予約 ご用件・ご希望の作業・車種・ご希望の日時・お名前・お名前の読み・ご連絡のつくお電話番号・備考 「〇〇(店名)」・「〇〇(営業時間)」・「〇〇(定休日)」・「〇〇(所在地)」・「〇〇(作業の所要時間の目安)」・「〇〇(お支払い方法)」
  • どれも、AI の役割(persona)・あいさつ・聞き取る項目・よくある質問の例・担当者に引き継ぐときの例・締めのあいさつが入っています。歯科医院と整備工場・タイヤショップは、人に渡すときに、医院・店舗の電話番号を伝えて直接掛け直していただく言い方で締めます(結果は handoff)。番号は、医院・店舗の情報を返す連携の道具で確かめます。番号が分からないときは、先にお名前・お電話番号・ご用件を伺い、スタッフから折り返すと伝えます。連携(connectors・tools)は入っていません。空き状況の確認と予約の確定は、スタッフが折り返して行う形です。カレンダーなどをつないで AI が予約を入れたときは、締めのあいさつ(closing)の代わりに短いお礼で締めます。
  • 医院や店の名前・営業時間などは「〇〇歯科」「株式会社〇〇」「〇〇(営業時間)」の形で置いてあります。お使いの名前や内容に変更してから作成します。「〇〇」が残っていると 422 invalid_config になり、details に変更する箇所が並びます。
  • 文言は、歯科医院・飲食店・整備工場の予約・会社の電話応対の例文に合わせて書いています。あいさつでは、AI が受けていること・話の内容を記録すること・担当者と話す方法を伝えます。

管理画面で試す#

管理画面のエージェント設定の画面で[ブラウザーで試す]を押すと、ブラウザーのマイクでそのエージェントと話せます。電話や Web・アプリにつながなくても、作った設定をすぐに確かめられます。

  1. 会話に使うテナントを選びます。ツールと連携には、このテナントのお客様 ID(external_id)とテナント専用の連携が使われます。実際のお客様と分けるには、試す用のテナントを作っておきます(管理画面はテナントを自動では作りません)。
  2. [開始]を押し、マイクの使用を許可すると、AI があいさつします。
  3. 話しているあいだ、文字起こし・AI が呼んだツール(名前・引数・結果)・聞き取った項目・会話の結果・経過時間が画面に出ます。
  4. [終了]で切ります。会話は会話記録に残り(channel: 'web')、Webhook や会話後の通知も実際の会話と同じように送られます。
  • 会話は、保存した最新のバージョンで進みます。保存していない変更は反映されません。
  • 試す会話も料金がかかります。実際の会話と同じく、1 分 10 円(税抜)を残高から差し引きます(テスト環境でも同じです)。残高が無ければ始められません(402 balance_depleted)。
  • 使えるのは、開発者以上のロールの人です。

書き方のこつ#

  • persona に「1 回の発話は 2 文まで」と書くと、電話で聞きやすくなります。
  • 聞き取る項目は少なくします。必須の項目が多いと会話が長くなります。
  • 業界の用語・商品名・店名・スタッフの名前・地名は vocabulary に入れると、聞き取りが安定します(人の名前や地名は、入れると字の取り違えが大きく減ります。聞き取りの正しさ)。
  • 試すときは、管理画面の[ブラウザーで試す](管理画面で試す)が手早い方法です。自社の画面から試すときは、テストの環境で Web・アプリからつなぎます。

聞き取りの正しさ#

日本語に強い複数の AI を組み合わせ、電話の音質に合わせて調整しています。方言や雑音のある電話の音声でも、試験を重ねています。店名・スタッフの名前・業界の言葉を vocabulary に登録すると、聞き取りにくい名前も正しく聞き取りやすくなります。

標準語 方言
聞き取り精度 94% 93%

※当社の社内試験で、数字とお名前の聞き取りを測った値です。条件ごとに測ったうち、一番高い値を載せています(254 パターン・のべ 1,016 回。載せた値は電話の音質で測定。方言は、方言を含む公開の日本語の音声で測定)。