Open in
エージェントのステップと引き継ぎ
エージェントをそれぞれ独自の指示、ツール、収集した値を持つステップに分割し、通話の途中でエージェント間で通話を引き継ぎます。
単一のプロンプトでは、モデルに仕事全体を一度に任せます。ステップでは、一度に通話の1つのフェーズを任せます。各ステップには、それぞれの指示、専用のツール、任意の一語一句読み上げる文、次に進む前に収集する必要がある値があります。引き継ぎでは、組織内の別のエージェントが通話の途中から引き継げます。文字起こしはそのまま保持されるため、発信者が同じことを繰り返す必要はありません。
すべてのエージェントは単一のプロンプトとして開始します。ステップまたは引き継ぎを追加するまで、その内容は変わりません。
ステップまたは単一のプロンプト?
| ステップを使用する場合 | 単一のプロンプトを維持する場合 |
|---|---|
| 通話に、確認してから予約するなど、順番に進める必要があるフェーズがある。 | 会話がFAQ、受付、一般サポートのように自由形式である。 |
| エージェントが次に進む前に値を取得する必要がある。 | 決まった順序で収集する必要がない。 |
| 「18歳未満の発信者は保護者につなぐ」のように、例外を認めないルールがある。 | すべての分岐でモデルの判断に任せられる。 |
| 通話内の決まったタイミングで検索を実行する必要がある。 | 発信者が求めたときにいつでもツールを呼び出せる。 |
| 通話の一部を、独自のプロンプトと音声を持つ別のエージェントが担当する。 | 1つのペルソナですべてを処理する。 |
ステップは、スクリプト化された電話ツリーではありません。各ステップ内では、モデルは単一のプロンプトの場合と同じように会話を進めます。ステップによって、取り組む内容、使用できるツール、離れる前に必要な情報が決まります。
ステップ型エージェントの構築方法
エージェントにステップがある場合、prompt には共有指示が含まれます。これは、すべてのステップに適用されるペルソナとルールです。各ステップは、その上に独自の指示を追加します。各ターンでモデルには、共有指示、現在のステップの名前と指示、これまでに収集された値が表示されます。
エージェントのエディターで 指示 を開き、プロンプトの見出しの下にある ステップに分割 を選択します。Zeus はステップを提案し、プロンプトの各セクションを対応するステップと並べて表示します。これらのステップを使用 で保持し、1つのプロンプトを維持 で元に戻せます。その後、アウトラインには 共有指示 と各ステップが表示されます。ステップのページには、名前、入力時に一語一句そのまま発話する最初の行、指示、収集する値、使用できるツールに加え、次に移動する先と遷移元が表示されます。フロー ではステップがグラフとして表示されます。他のエージェントへのハンドオフは ツールとハンドオフ にあります。
ステップの 保存 ではステップが下書きに保存され、エージェントのヘッダーで デプロイ を選択すると発信者に反映されます。共有指示の 1つのプロンプト / ステップ 切り替えでは、共有指示とすべてのステップを結合した単一のプロンプトにエージェントを戻せます。旧ビューでは、ビルダーの 単一プロンプト / ステップ 切り替えで同じ操作を行えます。
API では、steps と handoffs はエージェントのフィールドです。すべてのエージェントフィールドと同様に、PATCH は下書きに保存し、POST /v1/agents/{agent_id}/deploy で本番環境に反映します。"steps": null を送信すると、エージェントは単一のプロンプトに戻ります。テスト通話では下書きが使用されます。
ステップフィールド
| フィールド | 意味 |
|---|---|
id | 必須。小文字、数字、アンダースコアを使用でき、文字で開始し、最大40文字です。エージェント内で一意である必要があります。 |
name | 必須の表示名。1〜80文字です。 |
instructions | 必須。最大20,000文字です。prompt と同様に、{{var}} 通話変数をサポートします。 |
say | 任意。ステップに入ったときに一語一句そのまま発話する行です。最大1,000文字です。{{var}} をサポートします。 |
tools | null の場合、ステップではエージェントに接続されたすべてのツールを使用できます。リストを指定した場合、ステップで使用できるツールは名前で指定したものに制限されます。end_call や transfer_call などの組み込みアクションは、すべてのステップでエージェントの設定に従います。 |
collect | ステップで収集する値を最大20個指定できます。各値には name、type、description、required(デフォルトは true)があります。 |
on_enter_tool | 任意。ステップに入ったときに自動的に呼び出すツール名です。Webhook ステップを参照してください。 |
transitions | ステップが次に移動できる先の順序付きリストです。遷移を参照してください。 |
global_when | 任意。このステップを任意のステップから到達可能にします。グローバルステップを参照してください。 |
voice | 任意。このステップの音声 ID です。エージェントがカスタム音声設定を使用している場合は無視されます。 |
グラフ自体は {"start_step": "<step id>", "steps": [...]} です。通話は start_step から始まります。
遷移
各遷移には、ステップIDを指定する to と、次のいずれか1つを含めます。
when: 自然言語で記述し、モデルが判断します。エージェントには、移動可能なステップを一覧表示する組み込みのgo_to_stepツールがあり、各whenはそのステップを選択する理由として使用されます。condition: 収集した値に基づくルールで、コードが判断します。モデルはこれをスキップしたり、会話で回避したりできません。"always": true: 確認せずに次へ進みます。まずコードが判断します。ステップに入った直後、または必須値が収集された時点で、最初に一致したconditionまたはalwaysの遷移が、モデルがwhenを選ぶ前に適用されます。そのため、alwaysは条件のフォールバックとして条件の後に置くか、単独で使用してステップを次のステップへ直接つなげます。alwaysを持つステップは、whenの選択を待ちません。
condition は {"value": <collected name or dotted path>, "op": <op>, "target": <literal>} です。
op | 値が真になる条件 |
|---|---|
eq, ne | target と等しい、または等しくない |
lt, lte, gt, gte | target より小さい、以下、大きい、または以上 |
in, not_in | target リスト内のいずれかの値である、または値ではない |
exists, missing | 収集済みである、または未収集である(target なし) |
eq、ne、in、not_in は、空白を削除した後に大文字と小文字を区別せずテキストを比較します。数値は数値として、日付は YYYY-MM-DD 文字列として比較されます。一度も収集されていない値では、missing を除くすべての演算子が偽になります。
when と global_when は、発話内容ではなく、「発信者が予約を取りたい」のような条件として記述します。エージェントはこれらを内部ルーティングメモとして認識し、読み上げたり、ステップを変更していることに言及したりしないよう指示されます。
モデルが go_to_step を呼び出すと、次の処理が行われます。
- ステップ内のすべての
required値が存在している必要があります。不足している値がある場合、モデルには不足している値が示され、発信者に尋ねます。 - 値が保存されます。
conditionとalwaysの遷移が順番に確認されます。最初に一致した遷移が適用されます。- それ以外の場合、エージェントはモデルが選択したステップへ移動します。
- 何も一致せず、モデルもステップを指定しなかった場合、エージェントは現在のステップに留まります。
グローバルステップへのジャンプは例外です。発信者が話題を変えた場合は、現在のステップに必須値の不足があっても、そのステップの条件が確認される前に進みます。
condition と always の遷移は、ステップに入るたびにも確認されるため、コードによって判断される一連のステップはまとめて実行されます。連鎖は次の場合に停止します。
- この実行中にすでに訪問したステップに到達した場合。
- 8ホップ後。
- 収集すべき必須値が残っているステップに到達した場合。ただし、ステップに
on_enter_toolがある場合を除きます(Webhookステップは常にその結果に基づいてルーティングされます)。
連鎖が停止したステップの say 行だけが発話されます。
遷移がないステップは終端です。エージェントはそこで処理を完了し、通常の組み込みアクションで通話を終了または転送します。
値の収集
ステップで必要な項目を collect に一覧表示します。モデルは go_to_step を呼び出す際に値を渡し、それらは通話の残りの間も利用できます。
type | 保持する値 |
|---|---|
string | 任意のテキスト |
number | 数値 |
boolean | true または false |
date | YYYY-MM-DD 形式の日付 |
収集した値は通話コンテンツです。通話では文字起こしの横に表示され、同じ保持、削除、マスキングのルールが適用されます。エージェントの通話録音をオフにすると、収集した値は保存もWebhookへの送信もされませんが、ステップタイムラインは保持されます。通話での確認場所を参照してください。
Say 行
エージェントがステップに入ると、say は記述どおりに発話されます。その後、モデルはその行が発話されたことを認識したうえで、同じ応答内で新しいステップを続行するため、繰り返しません。say はあいさつ、必須の告知、固定文言に使用し、応答の残りはモデルに任せてください。
開始ステップの say は、同意に関するアナウンスメントがある場合はその後に、エージェントが先に発話するときの開始文になります。発信者が先に発話した場合は、IVR や留守番電話のあいさつではなく、人に対するエージェントの最初の応答の冒頭になります。
通話が __previous__ または引き戻しによってステップに戻った場合、そのステップの say は再度発話されません。音声が誤読する可能性がある内容は、正しく発音されるように記述してください。Say 行では {{var}} の通話変数を使用できますが、収集済みの値は使用できません。
Webhook ステップ
on_enter_tool をエージェントのツールのいずれかに設定すると、モデルを待たずにステップに入った直後に実行されます。その引数には、ツールのパラメータ名と一致する名前の収集済みの値が使用されます。結果は <tool>_result という名前の収集済みの値として保存され、4 KB に切り詰められます。ステップの condition および always 遷移は直ちに確認されるため、検索結果だけで通話をルーティングできます。
保存される値には、次の 2 つのフィールドがあります。
| フィールド | 内容 |
|---|---|
status | エンドポイントが返した HTTP ステータスコード。 |
response | レスポンス本文。 |
本文フィールドに基づいてルーティングするには lookup_account_result.response.<field> を、ステータスコードに基づいてルーティングするには lookup_account_result.status を使用します。
検索は最大 8 秒間実行されます。ただし、ツール固有のタイムアウトがそれより短い場合は、そのタイムアウトが適用されます。3 秒を超える場合、発信者が無音のままにならないよう、エージェントが短い文を発話します。エンドポイントが 400 以上のステータスを返した場合、または時間内に応答しなかった場合、エージェントは現時点では確認できないことを発信者に伝え、実行可能な対応を続けます。
グローバルステップ
global_when を持つステップには、その説明が当てはまる場合、どのステップからでも到達できます。when と同様に、モデルが判断します。請求に関する質問、担当者への接続依頼、苦情など、発信者がいつでも持ち出せる話題に使用してください。
グローバルステップで "to": "__previous__" を指定した遷移は、通話をその前にアクティブだったステップへ戻すため、発信者は中断したところから再開できます。ステップは再開されます。on_enter_tool は再度実行されず、say も繰り返されず、エージェントは最初からやり直すことなく続行します。
引き継ぎ
handoffs には、通話を引き継げる同じ組織内の他のエージェントを一覧で指定します。
[{"agent_id": 413, "when": "The caller asks about billing or a refund"}]エージェントには、これらのエージェントと理由を含む組み込みの hand_off ツールが提供されます。遷移と同様に、各 when は内部ルーティング用のメモであり、読み上げられることはありません。
引き継ぐ際、エージェントは「Sure, I'll send you over to our billing team」のように、発信者がどこへつながるかを伝える短い一文を自身の音声で話します。その後、対象エージェントのプロンプト、ステップ、ツール、音声に切り替わり、同じ文字起こしで通話が継続します。新しいエージェントは簡潔に自己紹介し、発信者の直前のリクエストに回答します。転送を告知することはありません。以降は対象エージェントのナレッジベースを利用できます。
通話が初めてエージェントに到達したときは、そのエージェントの start_step から開始します。ステップの on_enter_tool が実行され、その say が読み上げられます。すでに訪問したエージェントへ通話が戻った場合、そのエージェントは on_enter_tool を実行せず、say を繰り返したり再度自己紹介したりすることなく、直前のステップから再開します。収集済みの値は、通話中のすべてのエージェントで共有されます。
- 対象は同じ組織内のエージェントである必要があり、エージェントは自分自身に引き継ぐことはできません。
- 通話レベルの設定はすべて、応答したエージェントに保持されます。これには、プロダクト、言語、最初に話す人、ボイスメール、同意告知、その他すべての通話設定が含まれます。
- 対象エージェントはさらに別のエージェントへ、または元のエージェントへ引き継げます。1回の通話で最大8つのエージェントに到達できます。
- テスト通話では、テスト対象エージェントのドラフトが実行されます。引き継ぎ先のエージェントでは、デプロイ済みバージョンが実行されます。
- 2つのエージェントに同じ名前で異なる定義のツールがある場合、通話で保持されるのは1つだけであり、応答したエージェントのツールが常に優先されます。保存時にアプリが警告を表示します。
- エージェントはステップなしで引き継ぎを設定できます。その場合、プロンプト全体がそのまま使用されます。
go_to_step と hand_off は、ステップまたは引き継ぎがあるエージェントでは予約されています。そのため、独自のツールでこれらの名前は使用できません。
通話での確認場所
通話履歴で通話を開きます。文字起こしの横にあるステップタイムラインには、通話が入った各ステップとその理由が表示され、収集された値も一覧表示されます。
通話オブジェクト と通話完了Webhook(telephony.complete / web.complete)には、steps_trace と collected_values として同じデータが含まれます。どちらもステップのない通話には含まれません。
"steps_trace": [
{"t_ms": 0, "agent": "a412", "step": "greet", "via": "start"},
{"t_ms": 51230, "agent": "a412", "step": "verify", "via": "model"},
{"t_ms": 98410, "agent": "a412", "step": "minor", "via": "condition"}
],
"collected_values": {"full_name": "Dana Reyes", "dob": "2010-04-02", "age": 15}agent は、エージェントIDの前に a を付けた値です。via は通話を移動させた要因を示します。
via | 意味 |
|---|---|
start | 通話はこのステップで開始しました。 |
model | モデルが go_to_step、when、または global_when を通じてステップを選択しました。 |
condition | condition または always の遷移が一致しました。 |
on_enter | Webhookステップの結果に対して遷移が一致しました。 |
handoff | 別のエージェントが引き継ぎました。 |
ステップが実行される場所
ステップは、すべてのエージェント(および旧来のプロダクト値)でネイティブに実行されます。受信、発信、キャンペーン通話、テスト通話、Web通話、ウィジェット通話に対応します。
それ以外の場所でもエージェントは機能しますが、構造は使用されません。共有指示とすべてのステップを順番に統合した、フラット化されたプロンプトが実行されます。対象は次のとおりです。
- 保存済みエージェントのセッションを含むRealtimeセッション。
- 動的通話設定Webhookが返すインライン設定。
agent_idを返すWebhookでは、そのエージェントのステップが使用されます。
制限
| 制限 | 値 |
|---|---|
| エージェントあたりのステップ数 | 100 |
| ステップあたりの収集値数 | 20 |
| エージェントあたりのハンドオフ先数 | 8 |
| 1回の通話で到達可能なエージェント数 | 8 |
steps JSON のサイズ | 200 KB |
ステップの instructions | 20,000文字 |
say 行 | 1,000文字 |
保存される on_enter_tool の結果 | 4 KB |
ルールに違反する保存では、steps.steps[2].transitions[0].to のように、不正なフィールドのパスとともに 400 が返されます。tools と on_enter_tool のツール名は、エージェントに接続されたツールである必要があります。
ステップごとの言語設定、モデルをスキップするスクリプト化されたステップ、say 行内の収集値はサポートされていません。
インポートしたエージェント
Retell、Bland、Vapi、ElevenLabs からのインポートでは、マルチプロンプトエージェント、フロー、パスウェイ、ワークフローがステップとして取り込まれ、スクワッドとエージェント転送がインポートしたエージェント間のハンドオフとして取り込まれます。インポート前に、レビュー画面で両方を確認できます。
例: 歯科の初診受付
順番に3つのステップを設定します。あいさつ、患者情報の収集、予約です。
{
"prompt": "You are Ava, the front desk assistant at Acme Dental. Be warm and brief. Ask one question at a time.",
"steps": {
"start_step": "greet",
"steps": [
{
"id": "greet",
"name": "Greeting",
"instructions": "Greet the caller and ask how you can help.",
"say": "Thanks for calling Acme Dental, this is Ava. How can I help you today?",
"tools": null,
"collect": [],
"transitions": [
{"to": "details", "when": "The caller wants to book an appointment"}
]
},
{
"id": "details",
"name": "Patient details",
"instructions": "Ask for the caller's full name, date of birth and the reason for the visit. Read the date of birth back and ask the caller to confirm it.",
"tools": null,
"collect": [
{"name": "full_name", "type": "string", "description": "Caller's full name", "required": true},
{"name": "dob", "type": "date", "description": "Date of birth", "required": true},
{"name": "reason", "type": "string", "description": "Reason for the visit", "required": true},
{"name": "new_patient", "type": "boolean", "description": "First visit to the practice", "required": false}
],
"transitions": [
{"to": "book", "when": "The caller has confirmed their details"}
]
},
{
"id": "book",
"name": "Book",
"instructions": "Offer the two earliest open slots from book_slot and book the one the caller picks. Confirm the date and time, then say goodbye and end the call.",
"tools": ["book_slot"],
"collect": [],
"transitions": []
}
]
}
}PATCH /v1/agents/{agent_id} でステージングし、テスト通話で試してからデプロイします。名前、生年月日、来院理由を収集するまで、details ステップから予約へ引き継ぐことはできません。new_patient は任意です。
例: 年齢制限付きの分岐
モデルは誰とでも会話できますが、予約対象者はコードで決定します。年齢を収集してから、モデル独自の選択が考慮される前に年齢に基づいてルーティングします。
{
"id": "verify",
"name": "Verify age",
"instructions": "Ask for the caller's age.",
"tools": null,
"collect": [
{"name": "age", "type": "number", "description": "Caller's age in years", "required": true}
],
"transitions": [
{"to": "guardian", "condition": {"value": "age", "op": "lt", "target": 18}},
{"to": "book", "when": "The caller has given their age"}
]
}15歳と言う発信者は、モデルの判断にかかわらず guardian に進みます。その他の発信者は全員 book に進みます。どちらもグラフ内の別の場所にある通常のステップです。
例: アカウント検索のWebhookステップ
発信者がアカウント番号を伝えると、次のステップに入る際に検索が実行され、
結果に応じてルートが選択されます。簡潔にするため、not_found、collections、support
ステップは省略しています。
[
{
"id": "identify",
"name": "Identify",
"instructions": "Ask for the caller's account number and read it back digit by digit.",
"tools": null,
"collect": [
{"name": "account_number", "type": "string", "description": "Account number", "required": true}
],
"transitions": [
{"to": "lookup", "when": "The caller has confirmed their account number"}
]
},
{
"id": "lookup",
"name": "Look up account",
"instructions": "Tell the caller what you found on their account and ask how you can help.",
"tools": ["lookup_account"],
"collect": [],
"on_enter_tool": "lookup_account",
"transitions": [
{"to": "not_found", "condition": {"value": "lookup_account_result.response.found", "op": "eq", "target": false}},
{"to": "collections", "condition": {"value": "lookup_account_result.response.account_status", "op": "in", "target": ["past_due", "suspended"]}},
{"to": "support", "when": "The caller needs help with an active account"}
]
}
]lookup_account は、そのパラメータがこの名前を持つため account_number を受け取ります。
レスポンス本文に "found": false が含まれる場合、通話は
not_found に進みます。account_status が past_due または suspended の場合は
collections に進みます。有効なアカウントでは lookup にとどまり、モデルが対応した後、
support に進みます。検索失敗を専用のステップに送るには、先にステータスの
条件を追加します。エラーレスポンスではステータスコードが保存されるため、
{"value": "lookup_account_result.status", "op": "gte", "target": 400}
で検出できます。タイムアウトまたは応答なしの場合は "error" が保存されるため、
{"value": "lookup_account_result.status", "op": "eq", "target": "error"}
で検出できます。
例: 受付から請求担当へ
2つのエージェントを使用します。受付(エージェント 412)がすべての通話に応答し、請求に関する
質問を、専用のプロンプト、ツール、音声を持つ請求担当エージェント(エージェント 413)へ引き継ぎます。
受付側:
{
"handoffs": [
{"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"}
]
}発信者を引き戻せるように、請求担当エージェント側:
{
"handoffs": [
{"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"}
]
}受付は「請求担当チームにおつなぎします」などの短い案内を行い、請求担当エージェントが名乗って、 受付が終えた地点から会話を引き継ぎます。請求担当から戻された場合、受付は発信者に再度あいさつせず、 中断した地点から再開します。通話の商品、言語、同意に関する案内、その他の通話設定は、 応答した受付に引き継がれます。
請求対応に専用のエージェントではなく専用の指示だけが必要な場合は、代わりに受付で グローバルステップを使用します。質問に回答すると、通話は発信者がいたステップに戻ります。
{
"id": "billing",
"name": "Billing questions",
"instructions": "Answer questions about bills and payments. Offer to send a payment link by email.",
"tools": null,
"collect": [],
"transitions": [
{"to": "__previous__", "when": "The billing question is answered"}
],
"global_when": "The caller asks about a bill or payment at any point"
}