ページの一覧

ドキュメント

会話中のツール

会話の途中で AI に API を呼ばせる方法。ツールの定義、署名付きの呼び出し(自社の API)、署名なしの呼び出しと API キー(ほかの会社の API)、確認してから使うツール、ツールを試す方法、応答の扱い、誤りの種類、二重実行の防止。

Markdown で見る

ツール(tools)をエージェント設定に書くと、AI は会話の途中で API を呼び、その結果を使って答えます。予約の空きを調べる、電話番号で顧客を探す、予約を入れる、といった使い方ができます。

呼び方は 2つあります。

呼び方 sign 向いている相手 送るもの
署名付き true(省いたとき) 自社の API voicast の署名を付けた tool.call の JSON を POST
署名なし false ほかの会社の API 引数をそのまま(GET はクエリ、POST は JSON の本文)

どちらにも API キーを付けられます。呼び出しは voicast のサーバーが行い、URL と API キーは音声の接続や AI には渡しません。AI に渡すのは、そのエージェント設定の tools と、connectors で名前を並べた連携の操作だけです。

管理画面では、エージェント設定の[ツール]で追加し、ツールごとの[試す]で 1回呼んで確かめられます(ツールを試す)。

ツールの定義#

json
"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 ○ 英小文字で始まり、英小文字・数字・_ の 40文字まで。予約済みの名前は使えません。連携のツールの名前と重ならないこと
description ○ いつ使うか(500文字まで)。AI はこれを読んで使うかを決めます
url ○ 呼ぶ先。https で、インターネットから引ける名前だけ(IP アドレスの直書き・localhost・社内向けの名前は不可)。500文字まで
method GET か POST。省くと POST。署名付きのツールは POST だけです
sign 省くと true(署名付き)。false で署名なし
auth API キーを付ける。{ "type": "api_key", "header": "…", "value": "…" }(API キー)
parameters 引数(引数)
confirm true なら、voicast が決まった確認の文で相手の同意を伺ってから使い、結果も決まった文で伝えます(確認してから使うツール)。予約・取り消しなど書き換えるツールに付けます
confirm_message confirm のツールの確認の文(200文字まで)。{引数の名前} に値を差し込みます
done_message confirm のツールが済んだときの文(200文字まで)。{引数の名前} を差し込めます。空文字 "" なら済んだときの文を言いません

ツールは 1つのエージェント設定に 10個までです。AI はツールを使う前に「お調べしますので、少々お待ちください」と一言伝えます。

引数#

parameters は、AI が会話から聞き取って渡す値です。properties は 20個まで、型は string・number・integer・boolean、enum は 50個までです。required に並べた引数は必須です。

  • 送るのは parameters に定義した引数だけです。AI がほかの名前の値を付けても送りません。空の値(空の文字列・null)も送りません。
  • 必須の引数がそろわないときは API を呼ばず、AI に invalid_arguments を返します。
  • 名前の読みの引数(name_kana・ふりがな など)があれば、AI は相手には聞かずに、聞こえた読みを入れます。書き方は description に指定があればそのとおりに、無ければ全角カタカナです(名前の読み)。名前の引数(name など)には、これまでどおり聞き取れたとおり(音声認識の字)が入ります。

署名付きの呼び出し(自社の API)#

sign を省くか true にすると、voicast が url に署名付きで POST します。サービスの側は 1本の 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 呼び出しごとに 1つの ID。見出しの idempotency-key も同じ
arguments AI が決めた引数(定義した引数だけ)
call.channel phone か web。ツールを試すとき(ツールを試す)は test
call.tenant.external_id 自社の顧客の ID。どの会社の予約表を見るかを決めるのに使います。ツールを試すときに tenant_id を省くと call.tenant は null です
call.from かけてきた番号(電話で、TwiML の from を渡したとき)
test ツールを試すとき(ツールを試す)だけ true

auth を付けたツールは、API キーのヘッダーも付きます。

署名なしの呼び出し(ほかの会社の API)#

sign: false にすると、引数をそのまま送ります。署名も tool.call の形も付けないので、ほかの会社の REST API をそのまま呼べます。相手の認証は API キーで行います。

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 を付けると、呼び出しのたびに API キーをヘッダーに付けます。署名付きのツールにも付けられます。

json
"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 の応答の本文を AI に渡します。

json
{ "slots": ["2026-10-07T10:00:00+09:00", "2026-10-07T14:30:00+09:00"] }
本文 AI に渡すもの
JSON そのまま
JSON でない(文字など) { "text": "…" }
空 {}
4,000文字を超える 先頭の 4,000文字を { "text": "…", "truncated": true } で
  • 待つのは 8秒までです。超えると失敗として扱います。
  • 別の URL へ移す応答(3xx)には付いて行きません(upstream_error)。
  • 4,000文字を超えた本文は切られ、JSON としては渡りません。AI に要る項目だけを返します。
  • 「空きが無い」「見つからない」など、想定した結果は 2xx で { "slots": [] } や { "found": false, "message": "その番号の方は見つかりませんでした" } のように返すと、AI が自然に伝えられます。

ツールの応答で会話を終える(end_call)#

応答の JSON に end_call を入れると、AI に任せずに、その場で締めの言葉を 1 回だけ言って会話を終えます。担当者への取り次ぎをツールの中で済ませたときなど、AI に続きを話させたくないときに使います。

json
{ "found": false, "end_call": { "outcome": "handoff", "message": "あいにく、そのお名前の者が見当たりませんでした。受付の担当者がまいりますので、少々お待ちください。", "reason": "名簿にいない名前", "fields": { "visitor_name": "鈴木" } } }
項目 内容
outcome 会話の結果。completed・answered・handoff のどれか(既定 handoff)
message 締めに言う文(200 文字まで)。省くと結果ごとの決まった締め
reason 会話の記録に残す終えた理由
fields 聞き取った項目(エージェント設定の fields にあるものだけ残ります)

声で返す会話と、文字で返す会話(output: "text")で使えます。

誤りの種類#

失敗すると、AI に次の error を渡します。AI はおわびして、担当者からの折り返しなどを伝えます。

起きたこと error
401・403 unauthorized(API キーを確認してください)
404 not_found
ほかの 2xx 以外(3xx・429・5xx など)・接続できない upstream_error
8秒以内に応答が無い timeout
必須の引数が無い invalid_arguments(API は呼ばない)
auth のツールに API キーが預けられていない missing_api_key(API は呼ばない)

署名の検証#

署名付きのツールの要求には Standard Webhooks の署名が付いています。確かめ方とコード(Node.js・Python・PHP・Go)は 結果の受け取り と同じで、鍵だけが違います。

署名シークレット(whsec_…)は環境ごとに 1つです。管理画面の環境の設定(管理者以上)、API の GET /v1/tools/secret、MCP の get_tools_secret で確かめ、「再発行」・POST /v1/tools/secret/rotate・rotate_tools_secret で再発行できます。再発行してから 24時間は、古いシークレットの署名も並べて送るので、そのあいだに自社の側のシークレットを差し替えます(ライブラリには新旧の両方のシークレットを渡せます)。

js
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 を渡します。

二重実行の防止#

会話の中では、voicast も同じ tool_call_id を 1回だけ実行し、2度目には前の結果を返します。そのうえで、予約を入れるツールなどは自社の側でも、同じ要求が 2度届いたら 1回だけ実行します。tool_call_id(見出しの idempotency-key)を保存し、同じ ID には前の結果を返します。

js
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 のツールは、確認の文で相手の同意をいただいてから使い、結果も設定した文で伝えます。予約・変更・取り消し・登録など、相手の情報を書き換えるツールには必ず付けます。読み取るだけのツール(空きを調べる・顧客を探す)には要りません。

相手が同意したら、voicast はツールを使う前に「かしこまりました。少々お待ちください。」と言い(英語は "Certainly. One moment, please."、中国語は「好的,请稍等。」、韓国語は「알겠습니다. 잠시만 기다려 주세요.」)、ツールの結果が届いたら完了の文を 1回だけ言います。

完了の文(done_message)を省くと「お手続きが済みました。」、失敗したときは「申し訳ございません、お手続きはまだ確定しておりません。担当者から折り返しご連絡いたします。」です。

完了の文を空文字("done_message": "")にすると、済んだときの文を言いません。応答の end_call の message だけを言わせたいとき(担当者に知らせて「担当の者がまいりますので、少々お待ちください。」で締めるなど)に使います。end_call が無ければ、AI がツールの結果を伝えます。失敗したときの文は変わりません。

確認の文(confirm_message)と完了の文(done_message)は、{引数の名前} に値を差し込めます。

json
{
  "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 のツールも確認なしで呼びます。

ツールを試す#

ツールを 1回だけ呼んで、相手の応答を確かめます。会話の中で AI が呼ぶときと同じ処理(同じ署名・API キー・8秒の打ち切り)です。

  • 管理画面: エージェント設定の[ツール]で、ツールの[試す]を押すと「ツールを試す」のダイアログが開くので、引数を入力して呼びます。保存の前のフォームの内容で呼べます。[試した結果]に成功・失敗、状態コード、処理時間、本文が出ます。開発者以上のロールの人が使えます。
  • API: POST /v1/tools/try(API リファレンス)
  • MCP: try_tool(MCP)
  • SDK: tools.try()(SDK)
bash
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_…" }'
json
{
  "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 キーは、ツールに要る権限だけのものを使います(読み取るだけのツールには、読み取りだけのキー)。