会話中のツール
会話の
ツール
呼び方は
| 呼び方 | sign |
向いている |
送る |
|---|---|---|---|
| 署名付き | true |
自社の |
voicast のtool.call の |
| 署名なし | false |
ほかの |
引数を |
どちらにもtools と、connectors で
管理画面では、
ツールの定義#
"tools": [
{
"name": "find_free_slots",
"description": "予約の空きを調べる。相手が希望の日を言ったときに使う",
"url": "https://saas.example.com/voicast/tools",
"parameters": {
"properties": {
"date": { "type": "string", "description": "希望の日(YYYY-MM-DD)" },
"menu": { "type": "string", "enum": ["検診", "治療", "クリーニング"] }
},
"required": ["date"]
}
},
{
"name": "create_booking",
"description": "予約を入れる。空きを伝えて、相手が日時を選んだら使う",
"url": "https://saas.example.com/voicast/tools",
"confirm": true,
"parameters": {
"properties": {
"start": { "type": "string", "description": "開始の日時(ISO 8601)" },
"name": { "type": "string" },
"phone": { "type": "string" }
},
"required": ["start", "name"]
}
},
{
"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 |
○ | 呼ぶ先。localhost・社内向けの |
method |
GET かPOST。POST。POST だけです |
|
sign |
省くとtruefalse で |
|
auth |
API キーを{ "type": "api_key", "header": "…", "value": "…" } |
|
parameters |
引数 |
|
confirm |
true なら、 |
|
confirm_message |
confirm の{引数の名前} に |
|
done_message |
confirm の{引数の名前} を"" なら |
ツールは
引数#
parameters は、properties はstring・number・integer・boolean、enum はrequired に
- 送るのは
parametersに定義した 引数だけです。 AI が ほかの 名前の 値を 付けても 送りません。 空の 値 (空の 文字列・ null)も 送りません。 - 必須の
引数が そろわない ときは API を 呼ばず、 AI に invalid_argumentsを返します。 - 名前の
読みの 引数 ( name_kana・ふりが な など) が あれば、 AI は 相手には 聞かずに、 聞こえた 読みを 入れます。 書き方は descriptionに指定が あれば その とおりに、 無ければ 全角 カタカナです (名前の 読み )。 名前の 引数 ( nameなど)には、 これまで どおり 聞き取れた とおり (音声認識の 字) が 入ります。
署名付きの呼び出し(自社の API)#
sign をtrue にurl に
POST https://saas.example.com/voicast/tools
content-type: application/json
user-agent: voicast-tools/1
webhook-id: msg_6f1c…
webhook-timestamp: 1790000042
webhook-signature: v1,Rk9x…
idempotency-key: tc_7f3a9c2e…
{
"type": "tool.call",
"tool": "find_free_slots",
"tool_call_id": "tc_7f3a9c2e…",
"arguments": { "date": "2026-10-07" },
"call": {
"id": "call_…",
"channel": "phone",
"provider_call_id": "CA…",
"from": "+819012345678",
"tenant": { "id": "ten_…", "external_id": "clinic-123" }
}
}| 項目 | 内容 |
|---|---|
tool |
ツールの |
tool_call_id |
呼び出しごとにidempotency-key も |
arguments |
AI が |
call.channel |
phone かweb。test |
call.tenant.external_id |
自社のtenant_id をcall.tenant はnull です |
call.from |
かけてきたfrom を |
test |
ツールをtrue |
auth を
署名なしの呼び出し(ほかの会社の API)#
sign: false にtool.call の
GET https://api.example-crm.com/v1/customers/search?phone=09012345678
accept: application/json
user-agent: voicast-tools/1
idempotency-key: tc_7f3a9c2e…
authorization: Bearer sk_live_…GETは引数を クエリで 送ります。 urlに書いた クエリは 残り、 同じ 名前の 引数が あれば 引数の 値で 置き換えます。 POSTは引数を JSON の 本文 (例: { "phone": "09012345678" })で 送ります。 idempotency-keyは署名付きと 同じく、 呼び出しごとに 1つの 値です。
API キー#
auth を
"auth": { "type": "api_key", "header": "X-API-Key", "value": "…" }headerがAuthorizationならBearer <キー>を、ほかの ヘッダー ( X-API-Keyなど)なら キーを そのまま 付けます。 headerは英数字と -の64文字までです。 Content-Type・Host・Cookie・Idempotency-Key・webhook-signatureなど、決まった 意味の ある ヘッダーは 使えません。 valueは1〜2,000文字です。 保存すると 設定から 外し、 エージェントと ツールの 名前ごとに 暗号化して 預かります。 エージェント設定の バージョンの 履歴には 残らず、 API でも 管理画面でも 値は 返しません。 - エージェントの
応答の tool_keysに、預かっている キーの name(ツールの 名前) ・ hint(末尾 4文字。 12文字未満の キーは 空) ・ updated_atが並びます。 - 2回目からの
保存では valueを省けます。 預けた キーを そのまま 使います。 キーを 変更する ときだけ valueを渡します。 - 預けた
キーは ツールの 名前と URL の オリジン ( https://とホスト名) に 結び 付きます。 ツールの 名前を 変えた とき、 URL の オリジンを 変えた とき、 別の エージェントに ツールを 写した ときは valueを入れ直します。 キーの 無いまま authのツールを 保存すると 422 invalid_configです。 - URL の
オリジンを 変えた ツールと、 外した ツールの 預けた キーは、 保存の ときに 削除します (同じ オリジンのまま パスを 変える ときは、 キーを そのまま 使います) 。 - バージョンを
戻しても (前の バージョンの 設定で 保存し直しても) 、 同じ 名前で URL の オリジンが 同じ ツールは、 いま預けている キーを 使います。 - エージェントを
削除すると、 預けた キーも 削除します。 - 認証の
要らない API は authを省きます。
応答の扱い#
2xx の
{ "slots": ["2026-10-07T10:00:00+09:00", "2026-10-07T14:30:00+09:00"] }| 本文 | AI に |
|---|---|
| JSON | そのまま |
| JSON でない |
{ "text": "…" } |
| 空 | {} |
| 4,000文字を |
先頭の{ "text": "…", "truncated": true } で |
- 待つのは
8秒までです。 超えると 失敗と して 扱います。 - 別の
URL へ 移す応答 (3xx) には 付いて 行きません ( upstream_error)。 - 4,000文字を
超えた 本文は 切られ、 JSON と しては 渡りません。 AI に 要る 項目だけを 返します。 「空きが 無い」 「見つからない」 など、 想定した 結果は 2xx で { "slots": [] }や{ "found": false, "message": "その番号の方は見つかりませんでした" }のように返すと、 AI が 自然に 伝えられます。
ツールの応答で会話を終える(end_call)#
応答のend_call を
{ "found": false, "end_call": { "outcome": "handoff", "message": "あいにく、そのお名前の者が見当たりませんでした。受付の担当者がまいりますので、少々お待ちください。", "reason": "名簿にいない名前", "fields": { "visitor_name": "鈴木" } } }| 項目 | 内容 |
|---|---|
outcome |
会話のcompleted・answered・handoff のhandoff) |
message |
締めに |
reason |
会話の |
fields |
聞き取ったfields に |
声でoutput: "text")
誤りの種類#
失敗すると、error を
| 起きた |
error |
|---|---|
| 401・403 | unauthorized |
| 404 | not_found |
| ほかの |
upstream_error |
| 8秒以内に |
timeout |
| 必須の |
invalid_arguments |
auth の |
missing_api_key |
署名の検証#
署名付きの
署名シークレットwhsec_…)GET /v1/tools/secret、get_tools_secret でPOST /v1/tools/secret/rotate・rotate_tools_secret で
import express from 'express';
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.VOICAST_TOOLS_SECRET); // whsec_…
const app = express();
app.post('/voicast/tools', express.raw({ type: 'application/json' }), async (req, res) => {
let body;
try {
body = wh.verify(req.body, req.headers);
} catch {
return res.sendStatus(401);
}
const clinic = body.call.tenant.external_id;
switch (body.tool) {
case 'find_free_slots':
return res.json({ slots: await findSlots(clinic, body.arguments.date) });
case 'create_booking':
// 同じ tool_call_id は 1 回だけ実行する
return res.json(await createBookingOnce(body.tool_call_id, clinic, body.arguments));
default:
return res.status(404).json({ error: 'unknown tool' });
}
});SDK のverifyToolCall でも
ツールを"test": true がtenant_id をcall.tenant はnull なので、body.call.tenant.external_id はbody.test をtenant_id を
二重実行の防止#
会話のtool_call_id をtool_call_ididempotency-key)
async function createBookingOnce(toolCallId, clinic, args) {
const done = await db.toolRuns.get(toolCallId);
if (done) return done.result;
const result = await createBooking(clinic, args);
await db.toolRuns.put(toolCallId, { result });
return result;
}確認してから使うツール#
confirm: true の
相手が
完了のdone_message)
完了の"done_message": "")end_call のmessage だけをend_call が
確認のconfirm_message)done_message){引数の名前} に
{
"name": "create_booking",
"description": "予約を入れる。空きを伝えて、相手が日時を選んだら使う",
"url": "https://saas.example.com/voicast/tools",
"confirm": true,
"confirm_message": "{start}に、{menu}で、{name}様のご予約をお取りしてよろしいでしょうか。",
"done_message": "ご予約をお取りしました。{start}にお待ちしております。",
"parameters": {
"properties": {
"start": { "type": "string", "description": "開始の日時(YYYY-MM-DDTHH:MM)" },
"menu": { "type": "string", "enum": ["検診", "治療", "クリーニング"] },
"name": { "type": "string" },
"name_kana": { "type": "string", "description": "お名前の読み(全角カタカナ)" }
},
"required": ["start", "name"]
}
}- 日時の
値 ( 2026-10-19T14:00のようなYYYY-MM-DDTHH:MM、日付だけの YYYY-MM-DD、時差付きも 可) は、 話し言葉の 日時 ( 「10月19日月曜日の 午後2時」 ) に して 差し込みます。 - 名前の
引数 ( name・〜_name)は、 読みの 引数 ( name_kanaなど)が あれば、 その 読み (ひらが な) で 差し込みます。 電話では 字は 聞こえないので、 読みの 引数を 付けて おくと、 名前を 聞こえた とおりに 確かめられます。 - 引数に
無い 名前を 書くと、 保存の ときに 422 invalid_configです。値の 無い 引数は 空に なります。 - 省くと、
確認の 文は 引数の 値を つないだ既定の 文 (ID の 引数 〜_idと電話番号・読みは 入れません) ( 「10月19日月曜日の 午後2時、 クリーニング、 やまだ様の 内容で、 お手続きして よろしいでしょうか。 」 ) です。 - 会話の
言語 (日本語・英語・中国語・韓国語) ごとに、 voicast が その 言語の 文で 言います。 confirm_message・done_messageは書いた 言語の 会話でだけ 使い、 違う 言語の 会話では 既定の 文に します。 - 書き換えられなかった
とき ( 空きが 埋まっていたなど) は、 2xx で { "ok": false, "message": "その時間は埋まっています" }か{ "error": "slot_taken", "message": "…" }のように返すか、 4xx を 返します。 2xx で okがfalseでなくerrorも無ければ、 済んだと 伝えます。 ok: false・errorのときは 「申し訳ございません、 お手続きは まだ 確定しておりません。 」 とだけ 伝え、 AI が 理由を 伝えて ほかの 日時などを 伺います。
ツールをconfirm の
ツールを試す#
ツールを
- 管理画面: エージェント設定の
[ツール]で、 ツールの [試す]を 押すと 「ツールを 試す」 の ダイアログが 開くので、 引数を 入力して 呼びます。 保存の 前の フォームの 内容で 呼べます。 [試した 結果]に 成功・失敗、 状態コード、 処理時間、 本文が 出ます。 開発者以上の ロールの 人が 使えます。 - API:
POST /v1/tools/try(API リファレンス) - MCP:
try_tool(MCP) - SDK:
tools.try()(SDK)
curl https://api.voicast.jp/v1/tools/try \
-H "Authorization: Bearer $VOICAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "agt_…", "tool": "find_free_slots", "arguments": { "date": "2026-10-07" }, "tenant_id": "ten_…" }'{
"tool": "find_free_slots",
"ok": true,
"result": { "slots": ["2026-10-07T10:00:00+09:00"] },
"status": 200,
"body": "{\"slots\":[\"2026-10-07T10:00:00+09:00\"]}",
"truncated": false,
"duration_ms": 182
}toolは、保存した ツールの 名前 ( agent_idが必要) か、 保存の 前の ツールの 定義 ( toolsの1つと 同じ 形) です。 預けた キーを 使うのは、 保存した ツールを 名前で 渡した ときだけです。 定義で 渡すときは API キーを auth.valueに入れます ( authがあって valueが無ければ 422 missing_api_key)。 - 会話の
料金は かからず、 会話の 記録にも 残りません。 confirmのツールも 確認なしで 呼びます。 予約を 入れる ツールなど、 書き換える ツールは 実際に 書き換わります。 - 署名付きの
ツールの 本文には "test": trueが付き、 call.channelはtest、call.idはtry_…です。tenant_idを省くと call.tenantはnullです。 - 試すときも、
署名付きの ツールには 本物の 呼び出しと 同じ 署名を 付けて 送ります。 署名だけでは 本物の 会話と 見分けられません。 書き込みを する API は、 本文の test: true( call.channelがtest)を 見て、 書き込みを せずに 返すか、 断るように してください。 - 回数は
環境ごとに 1分 30回までです。 超えると 429 rate_limitedとRetry-Afterを返します。
気をつけること#
- ツールの
結果に 無い ことを AI は 答えません。 答えてほしい 情報 (料金・ 場所など) は 応答に 入れるか、 エージェント設定の faqに書きます。 - 個人情報は、
AI に 要る 分だけを 返します (生年月日などを そのまま 返さない) 。 - 署名付きの
ツールで 呼ばれる URL は、 署名を 確かめるまで 何もしないようにします。 署名の 無い 要求・古い webhook-timestampの要求は 断ります。 - ほかの
会社の API の API キーは、 ツールに 要る 権限だけの ものを 使います (読み取るだけの ツールには、 読み取りだけの キー) 。