Agents

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).

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#

{
  "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": "Kore",
    "speaking_rate": 1.15
  }
}

Fields#

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

Fields to collect#

{ "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" }

The AI reads names and phone numbers back to confirm them; phone numbers are read in three groups.

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).

"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.

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.

Voices#

Pick one of Google's Chirp 3 HD Japanese voices by name. You can listen to each voice in the dashboard (Agents).

Speaking rate#

1.0 is normal speed. On the phone that tends to feel slow, so the default is 1.15. Choose one of these values.

Languages#

Conversations are in Japanese today. More languages are coming.

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.

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 cannot be deleted (409 in_use). Change the tenant's agent_id first.

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 and place names in vocabulary for steadier recognition.
• To try an agent quickly, talk to it from the Web in the test environment.