All pages

Docs

Agents

How to write an agent: the AI's role, greeting, fields to collect, FAQ, handoff rules, voice, speaking rate and language.

View as Markdown

An agent decides what the AI says, what it collects and when it hands off to a person. One agent can serve many tenants. Create agents in the dashboard (Agents), with the API (POST /v1/agents) or over MCP (create_agent). You can also start from a template.

Conversations are in Japanese today, so the text you write (greeting, persona, labels, rules, FAQ) is in Japanese. Field keys and other identifiers are ASCII.

Shape#

json
{
  "name": "Dental reception",
  "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
  }
}

Fields#

Field Required Description Limit
greeting yes The first thing the AI says, read out as written 300 chars
persona yes Role and manner of speaking (e.g. calm, polite receptionist; at most two sentences per turn) 1,000 chars
fields yes What to collect (below) 1–20
handoff_when yes When to hand off to a person (below). May be an empty array 20 items, 200 chars each
closing yes What the AI says when it has collected everything (not used when a tool that changes bookings succeeded; the AI ends with a short thank-you instead. See Connectors) 300 chars
closing_answered What it says when an FAQ answer settled the call 300 chars
faq Frequent questions [{ q, a }] 50; q 200 chars, a 1,000 chars
domain Line of business (a hint for speech recognition) 200 chars
vocabulary Industry terms and proper nouns (hints for speech recognition). A {{name}} entry adds the per-conversation value, split on commas (、 or ,), for that conversation only (e.g. location names) 200 items, 50 chars each
voice Voice ID (below). Defaults to female-breezy
speaking_rate Speaking rate (below). Defaults to 1.0
language Conversation language (below). Defaults to ja
tools APIs (yours or third-party) the AI can call during a call (below). See Tools 10
connectors Connections to third-party APIs. See Connections 10
recording true records the conversation (below). Omit to not record
max_call_minutes Maximum length of one conversation in minutes (below). Defaults to 30

Unknown keys are dropped. Invalid input returns 422 invalid_config with one entry per problem in details.

Fields to collect#

json
{ "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" }
Key Description
key Name in the call's fields. Starts with a lowercase letter; lowercase letters, digits and _, up to 40 chars. Must be unique
label How the AI asks for it (up to 100 chars)
required When true, the call does not finish until it is collected
type text (default) or phone. Phone numbers are stored as digits only, and the AI asks again unless the number is 10 or 11 digits starting with 0 (Japanese numbers)

The AI reads names and phone numbers back to confirm them; phone numbers are read in three groups. Names are read back by how they sound, not by kanji.

Name readings#

On the phone the caller's kanji cannot be heard, so the kanji in name and similar fields are the speech recognizer's guess (a different character with the same reading is common, e.g. 小林真琴 for こばやし まこと). To keep the reading too, add a reading field. For fields whose key ends with kana (such as name_kana) or contains furigana, yomi or reading, and fields whose label contains 読み, ふりがな, フリガナ or カナ, the AI fills in the reading it heard in full-width katakana, without asking the caller (hiragana when the label says ひらがな).

json
{ "key": "name_kana", "label": "お名前の読み" }
  • Half-width kana, hiragana and katakana are unified and spaces collapsed (ヤマダ タロウ)
  • The values and format of name and other fields do not change. Without a reading field, results are the same as before
  • Every template includes name_kana (お名前の読み)

Handoff rules#

When a rule matches, the AI ends the conversation right away (without asking for a name and so on) and the outcome is handoff. On the phone you then transfer the call to a person (Phone).

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

Write rules as plain sentences. Avoid broad rules (such as "the caller asked a question"), or most calls will be handed off.

The AI closes with "I'll connect you to a staff member. Please hold on a moment." If persona describes what to do before handing off (looking something up with a tool, asking for the name and so on) or what to say when handing off, the AI does that first and closes with those words (up to 200 characters; the outcome is still handoff). Use this when you do not transfer the call right away, for example to ask the caller to call the shop's own number.

FAQ#

When asked, the AI answers using only these answers. Anything not written here is not guessed; the AI offers a callback instead. When an answer settles the call, the outcome is answered and the AI closes with closing_answered.

Outcomes#

When the AI ends the conversation, the call's outcome is set.

outcome When
completed All required fields were collected; staff will call back
answered An FAQ answer settled the call
handoff A handoff rule matched (connect a person now)
hangup The caller hung up before the end, or stayed silent even after being asked again
time_limit The conversation reached its maximum length (max_call_minutes, below)
error The voice server failed

Voices#

Pick one of the following voices by ID. Every voice speaks every supported language. You can listen to each voice in the dashboard (Agents).

ID Gender Dashboard name
female-breezy (default) Female Breezy female
female-firm Female Firm female
female-youthful Female Youthful female
female-bright Female Bright female
female-cheerful Female Cheerful female
female-upbeat Female Upbeat female
female-warm Female Warm female
female-gentle Female Gentle female
female-soft Female Soft female
female-smooth Female Smooth female
female-clear Female Clear female
female-brisk Female Brisk female
female-mature Female Mature female
female-easygoing Female Easygoing female
male-calm Male Calm male
male-upbeat Male Upbeat male
male-firm Male Firm male
male-deep Male Deep male
male-energetic Male Energetic male
male-friendly Male Friendly male
male-clear Male Clear male
male-easygoing Male Easygoing male
male-smooth Male Smooth male
male-gravelly Male Gravelly male
male-informative Male Informative male
male-steady Male Steady male
male-casual Male Casual male
male-lively Male Lively male
male-savvy Male Savvy male
male-breathy Male Breathy male

Speaking rate#

1.0 is normal speed and the default. Choose one of these values.

Value Speed
0.85 Very slow
0.9 Slow
0.95 A little slow
1.0 Normal (default)
1.05 Barely faster
1.1 Slightly faster
1.15 A little faster
1.2 Faster
1.25 Quite fast
1.3 Fast
1.4 Very fast
1.5 Fastest

Language#

Choose the language the AI speaks with callers.

Value Language
ja (default) Japanese
en English
zh Chinese (Mandarin, Simplified)
ko Korean
auto Match the caller (Japanese, English, Chinese or Korean)
  • Speech recognition, the AI's replies and the voice all use that language. The voice (voice) is the same in every language.
  • greeting, closing and closing_answered are read exactly as written. If you choose a language other than ja, write them in that language. Built-in lines, such as handing off to a person or checking whether the caller is still there, are spoken by voicast in that language.
  • auto replies in the language the caller speaks. The greeting plays as written, and the AI speaks Japanese until it knows the caller's language. A closing is used only when it is written in the caller's language; otherwise voicast speaks its built-in closing in that language.

Tools#

APIs the AI calls during a call, such as checking open slots or looking up a customer. The AI only gets this agent's tools and the connection actions listed by name in 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"]
    }
  }
]
Field Required Description
name yes Tool name. Starts with a lowercase letter; lowercase letters, digits and _, up to 40 chars
description yes What the tool does and when to use it (up to 500 chars)
url yes Where to call (https)
method GET or POST. Default POST
sign Default true: a signed tool.call POST (for your own API). false sends the arguments as they are (for third-party APIs)
auth { "type": "api_key", "header", "value" }: sends an API key in a header
parameters Arguments the AI collects in the conversation
confirm When true, voicast asks the caller with a fixed confirmation message before the tool runs, and tells the result in a fixed message
confirm_message Confirmation message for a confirm tool (up to 200 characters). {argument name} inserts the value
done_message Message said when a confirm tool succeeds (up to 200 characters). {argument name} can be inserted. An empty string "" says no completion message (Tools)
  • The API key (auth.value) is taken out of the settings on save and stored encrypted. It is not kept in the version history; tool_keys in the response lists only the tool name and the last 4 characters. You can leave value out on later saves.
  • See Tools for details.

In the dashboard#

Under Tools in the agent settings form, press Add tool (up to 10).

Field API field
Tool name name
Description description
URL url
Method method
Sign requests sign
Confirm before use confirm
Confirmation message, Completion message (shown only for confirm-before-use tools) confirm_message, done_message
Authentication (None / API key) auth
Header for the API key (Authorization (Bearer) / Other) auth.header
API key auth.value. Not shown again after saving; enter a key only to change it
Arguments (name, description, required) parameters

Press Try on a tool to enter arguments and call the API once; Results shows success or failure, the status code, the elapsed time and the body. It uses what is in the form, even before you save. There is no conversation charge and nothing is added to the conversation history. Tools that change data really change it (see Trying tools).

Recording (recording)#

Set "recording": true to record conversations. In the dashboard, use [Record conversations] in the agent settings. Recording is off by default.

  • Both phone and Web/app conversations are recorded, with the caller and the AI mixed into one audio file (MP3, mono). Conversations that return text only (output: "text") contain only the caller's voice.
  • The recording is saved when the conversation ends and is deleted automatically once the environment's retention period (1, 7, 14 or 30 days; 30 days by default) has passed since it was saved. The call's recording.expires_at tells you when (Retention).
  • You can play recordings from the conversation records in the dashboard or fetch them with GET /v1/calls/{id}/recording (Results). A call.recording_ready webhook is sent when a recording is ready.
  • Storing recordings costs nothing extra (still ¥10 per minute of conversation; see Pricing and billing).
  • A conversation in progress follows the setting of the version it started with.

Tell the caller the conversation is recorded. Voices are personal information. When recording, tell the caller at the start of the conversation, for example by adding "This call is recorded for quality purposes." to the greeting. Whether you must notify the caller and how long you may keep recordings depends on your industry and on the rules of each country or region. Also state in your service's terms and privacy policy that you record and store conversations.

Maximum length (max_call_minutes)#

Choose the maximum length of one conversation: 5, 10, 15, 30 or 60 minutes. Defaults to 30. In the dashboard, choose it in the agent settings under [Maximum conversation length].

  • Shortly before the limit, the AI ends the conversation with a fixed closing (in English: "We've reached the time limit, so I'll have to end the call here. Thank you."). The call's outcome is time_limit.
  • If a booking or other change is not finished, the AI says so before the closing.
  • The length is counted from when the conversation connects, for phone and web/app conversations alike.

Versions#

Updating an agent (PUT /v1/agents/{id}) creates a new version. Calls already in progress keep the version they started with; the next call uses the new one. Each call records the version it used (agent.version), and GET /v1/agents/{id}?version= returns that version's config.

PUT takes the whole config; partial updates are not supported.

Tool API keys are stored outside the versions. After rolling back to an earlier version, a tool with the same name uses the key stored now.

Assigning to tenants#

A tenant's agent_id is the default agent for its calls. You can override it per call: <Parameter name="agent"> on the phone, or agent_id in POST /v1/sessions for Web and apps.

An agent used by a tenant or a SIP credential cannot be deleted (409 in_use). First change the tenant's agent_id, and change the SIP credential's agent_id (PATCH /v1/tenants/{id}/sip-credentials/{credential}) or delete it.

Templates#

Ready-made agents you can start from. In the dashboard, they are offered first when you create an agent (or choose “Start from scratch”). The API returns the same list from GET /v1/agent-templates, and MCP from list_agent_templates.

id Name Parts to replace
dental_clinic Dental clinic appointments Clinic name (〇〇歯科), Office hours (〇〇(診療時間)), Parking location (〇〇(駐車場の場所)), Number of parking spaces (〇〇(台数))
restaurant Restaurant reservations Restaurant name (〇〇(店名)), Opening hours (〇〇(営業時間)), Regular closing days (〇〇(定休日)), Cancellation policy (〇〇(キャンセル料の決まり))
inquiry Inquiry intake Company name (株式会社〇〇), Phone hours (〇〇(受付時間)), Address (〇〇(所在地))
take_message Message taking Company name (株式会社〇〇), Business hours (〇〇(営業時間))
car_service Auto service and tire shop bookings Shop name (〇〇(店名)), Business hours (〇〇(営業時間)), Regular closing days (〇〇(定休日)), Address (〇〇(所在地)), Typical service times (〇〇(作業の所要時間の目安)), Payment methods (〇〇(お支払い方法))
  • Each template includes a role (persona), greeting, fields to collect, sample FAQ answers, sample handoff rules and closings. When the dental clinic and auto service templates hand off (outcome handoff), the AI gives the clinic's or shop's own phone number, looked up with a connected tool that returns its details, and asks the caller to call it directly. If the number is not available, it first takes the name, phone number and request, and says staff will call back. They contain no integrations (connectors, tools): staff call back to check availability and confirm bookings. When you connect a calendar and the AI books the appointment itself, the conversation ends with a short thank-you instead of closing.
  • Names, hours and similar details are written as placeholders such as 〇〇歯科, 株式会社〇〇 and 〇〇(営業時間). Replace them before creating the agent. If any 〇〇 remains, the request fails with 422 invalid_config and details lists what to replace.
  • The templates are written in Japanese, following real phone scripts for dental clinics, restaurant reservations, auto service shops and company front desks. The greeting tells callers that an AI is answering, that the call is recorded, and how to reach a person.

Testing in the dashboard#

On an agent's page in the dashboard, press Test in browser to talk to that agent with your browser's microphone. You can check what you built without connecting a phone number or your own Web app.

  1. Choose the tenant for the conversation. Tools and connections receive this tenant's customer ID (external_id) and use its own connections. To keep tests apart from real customers, create a tenant for testing (the dashboard never creates one for you).
  2. Press Start and allow the microphone. The AI greets you.
  3. While you talk, the page shows the transcript, the tools the AI called (name, arguments and result), the collected fields, the outcome and the elapsed time.
  4. Press End to hang up. The conversation is saved to call records (channel: 'web'), and webhooks and post-call notifications are sent as for real conversations.
  • The conversation uses the latest saved version. Unsaved changes are not used.
  • Test conversations are charged like real ones: ¥10 per minute (excl. tax) is deducted from your balance, in the test environment too. Without balance, you can't start (402 balance_depleted).
  • Developers, admins and owners can use it.

Tips#

  • Putting "at most two sentences per turn" (「1 回の発話は 2 文まで」) in persona makes the AI easier to follow on the phone.
  • Collect as few fields as you can. Many required fields make calls long.
  • Put industry terms, product names, store names, staff names and place names in vocabulary for steadier recognition (names of people and places are misrecognized far less often once they are listed; see Recognition accuracy).
  • To try an agent quickly, use Test in browser in the dashboard (Testing in the dashboard). To try it from your own app, connect from the Web in the test environment.

Recognition accuracy#

We combine several AI models that are strong in Japanese and tune them for phone-line audio. We keep testing with phone audio that includes dialects and background noise. Register your business name, staff names and industry terms in vocabulary, and even hard-to-catch names are more likely to be recognized correctly.

Standard Japanese Dialects
Recognition accuracy 94% 93%

*Values from our internal tests measuring how accurately numbers and names are recognized. We measured under several conditions and show the highest value (254 patterns, 1,016 test runs; the values shown were measured at phone audio quality; dialects were measured on public Japanese speech data that includes dialects).