---
title: "智慧體步驟與轉接"
description: "將智慧體拆分為各自具備指示、工具與蒐集值的步驟，並在通話途中於智慧體之間轉接通話。"
---

單一提示詞會一次將整項工作交給模型。**步驟**會一次處理通話的一個階段：每個步驟都有自己的指示、工具、可選的逐字唸出台詞，以及在繼續前必須收集的值。**交接**可讓你組織中的另一個智慧體在通話途中接手，並保留完整逐字稿，讓來電者不必重複說明。

每個智慧體一開始都是單一提示詞。在你新增步驟或交接前，沒有任何內容會改變。

## 使用步驟還是單一提示詞？

| 適合使用步驟的情況 | 適合保留單一提示詞的情況 |
| --- | --- |
| 通話有必須依序進行的階段：先驗證，再預約。 | 對話是開放式的：常見問題、總機、一般支援。 |
| 智慧體繼續前必須擷取某個值。 | 不需要依固定順序收集任何資訊。 |
| 規則絕不能彈性處理，例如「未滿 18 歲的來電者轉給監護人」。 | 模型的判斷足以處理每個分支。 |
| 必須在通話的固定時點執行查詢。 | 來電者提出要求時即可呼叫工具。 |
| 通話的一部分屬於另一個智慧體，且有自己的提示詞與語音。 | 由單一角色處理所有事項。 |

步驟不是照稿進行的電話選單。模型在步驟內仍會像使用單一提示詞時一樣進行對話。步驟會決定目前處理的工作、可使用的工具，以及離開前需要取得的內容。

## 具有步驟的智慧體如何建立

當智慧體具有步驟時，其 `prompt` 會包含**共用指示**：適用於每個步驟的角色設定與規則。每個步驟會在此基礎上加入自己的指示。每一輪中，模型都會看到共用指示、目前步驟的名稱與指示，以及目前已收集的值。

在智慧體的編輯器中，開啟 **指示**，並在提示詞的標題下選取 **拆分為步驟**。Zeus 會提出步驟建議，將提示詞的每個區段顯示在它將成為的步驟旁；**使用這些步驟**會保留它們，**保留單一提示詞**則會返回。之後，大綱會列出 **共用指示** 和每個步驟。步驟頁面包含其名稱、逐字呈現的第一行、指示、蒐集的值和可使用的工具，旁邊則顯示它接下來前往何處，以及從何處進入。**流程**會以圖表顯示步驟。交接至其他智慧體的設定位於 **工具與交接**。

步驟的 **儲存**會將步驟暫存至草稿；當你在智慧體頁首選取 **部署** 後，來電者便會取得這些步驟。共用指示中的 **單一提示詞** / **步驟** 切換功能，可將智慧體轉回單一提示詞，並合併共用指示與每個步驟。在舊版檢視中，建置工具的 **單一提示詞** / **步驟** 切換功能也有相同作用。

透過 API，`steps` 和 `handoffs` 是
[智慧體](/api-reference/agents)的欄位。如同所有智慧體欄位，`PATCH` 會將它們暫存至草稿；`POST /v1/agents/{agent_id}/deploy` 會使它們上線。傳送
`"steps": null` 會將智慧體切回單一提示詞。測試通話會使用草稿。

<Tip>
  [Zeus](/zh-Hant/guides/ask-the-copilot) 可根據描述建立步驟
  （「新增一個在預約前驗證出生日期的步驟」），並在不影響其他步驟的情況下編輯單一步驟。
</Tip>

### 步驟欄位

| 欄位 | 說明 |
| --- | --- |
| `id` | 必填。僅限小寫字母、數字和底線，必須以字母開頭，最多 40 個字元。在智慧體內必須唯一。 |
| `name` | 必填顯示名稱，長度為 1 至 80 個字元。 |
| `instructions` | 必填，最多 20,000 個字元。與 `prompt` 相同，支援 `{{var}}` [通話變數](/zh-Hant/guides/call-variables)。 |
| `say` | 進入步驟時逐字唸出的可選台詞，最多 1,000 個字元。支援 `{{var}}`。 |
| `tools` | `null` 會讓步驟使用附加至智慧體的所有工具。清單會依名稱將步驟限制為指定工具。`end_call` 和 `transfer_call` 等內建動作在每個步驟中皆遵循智慧體的設定。 |
| `collect` | 步驟最多可收集 20 個值。每個值包含 `name`、`type`、`description` 和 `required`（預設為 `true`）。 |
| `on_enter_tool` | 可選工具名稱，進入步驟時會自動呼叫。請參閱 [Webhook 步驟](#webhook-steps)。 |
| `transitions` | 步驟可前往的下一個位置之排序清單。請參閱[轉換條件](#transitions)。 |
| `global_when` | 可選。讓任何步驟都能抵達此步驟。請參閱[全域步驟](#global-steps)。 |
| `voice` | 此步驟的可選語音 ID。當智慧體使用自訂語音設定時會忽略此欄位。 |

流程圖本身是 `{"start_step": "<step id>", "steps": [...]}`。通話會從
`start_step` 開始。

## 轉換

每個轉換都包含 `to`（步驟 ID），以及以下其中一項：

- **`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` 時：

1. 步驟中的每個 `required` 值都必須存在。若有缺少，模型會得知缺少哪一項，並向來電者詢問。
2. 值會被儲存。
3. 系統會依序檢查 `condition` 和 `always` 轉換。第一個符合者生效。
4. 否則，智慧體會移至模型選擇的步驟。
5. 若沒有任何項目符合，且模型未指定步驟，智慧體會留在目前步驟。

跳轉至[全域步驟](#global-steps)是例外：來電者已變更主題，因此即使目前步驟仍缺少必要值，也會直接前往，且會在檢查該步驟的條件之前執行。

每次進入步驟時，也會檢查 `condition` 和 `always` 轉換，因此一連串由程式碼決定的步驟會一次完成。鏈結會在以下情況停止：

- 到達本次執行中已造訪過的步驟；
- 經過 8 次跳轉後；
- 到達仍需收集必要值的步驟，除非該步驟具有 `on_enter_tool`（Webhook 步驟一律會依其結果路由）。

只會說出鏈結停止所在步驟的 `say` 行。

沒有轉換的步驟為**終端步驟**。智慧體會在該處完成流程，並使用其一般內建動作結束或轉接通話。

## 收集值

在 `collect` 中列出步驟所需的內容。模型呼叫 `go_to_step` 時會傳遞這些值，且它們會在剩餘通話期間持續可用。

| `type` | 可儲存的內容 |
| --- | --- |
| `string` | 任何文字 |
| `number` | 數字 |
| `boolean` | `true` 或 `false` |
| `date` | `YYYY-MM-DD` 格式的日期 |

已收集的值屬於通話內容。它們會顯示在通話中的逐字稿旁，並遵循相同的保留、刪除和遮蔽規則。當智慧體的通話錄音已關閉時，已收集的值不會被儲存，也不會傳送至 Webhook；步驟時間軸仍會保留。請參閱
[如何在通話中查看](#where-to-see-it-on-a-call)。

## 朗讀內容

當智慧體進入步驟時，會完全依照 `say` 中的內容朗讀。模型接著會在同一則回覆中繼續處理新步驟，並知道該內容剛剛已說過，因此不會重複。將 `say` 用於問候語、必要告知與固定措辭，其餘回覆內容交由模型處理。

起始步驟的 `say` 是智慧體在任何同意告知後率先說話時的開場白。若來電者先說話，則它會成為智慧體對真人的首則回覆，絕不會對 IVR 或語音信箱問候語說出。

當通話透過 `__previous__` 或交還返回某個步驟時，該步驟的 `say` 不會再次朗讀。請依照應有的聽感撰寫：將語音可能誤讀的內容完整拼寫。朗讀內容支援 `{{var}}` 通話變數，但不支援已收集的值。

## Webhook 步驟

將 `on_enter_tool` 設為智慧體的其中一項工具，該工具會在進入步驟後立即執行，無須等待模型。其引數為名稱與工具參數名稱相符的已收集值。結果會儲存為名為 `<tool>_result` 的已收集值，並截斷為 4 KB；系統會立即檢查步驟的 `condition` 與 `always` 轉場，因此查詢可依據自身結果為通話路由。

儲存的值包含兩個欄位：

| 欄位 | 內容 |
| --- | --- |
| `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` 會列出你組織中可接手通話的其他智慧體：

```json
[{"agent_id": 413, "when": "The caller asks about billing or a refund"}]
```

智慧體會取得內建的 `hand_off` 工具，其中包含這些智慧體與理由。如同轉場，每個 `when` 都是內部路由註記，絕不會被唸出來。

轉接時，智慧體會用自己的語音說一句簡短的話，告知來電者將被轉往何處，例如「好的，我會將你轉接給我們的帳務團隊」。接著，目標智慧體的提示詞、步驟、工具與語音會接手，並以相同的逐字稿繼續通話。新的智慧體會簡短自我介紹並回應來電者最後的要求，不會宣布轉接。此後即可使用目標智慧體的知識庫。

通話首次進入某個智慧體時，會從該智慧體的 `start_step` 開始：步驟的 `on_enter_tool` 會執行，且其 `say` 會被說出。當通話轉回先前已造訪的智慧體時，該智慧體會從原本所在的步驟繼續，不會執行 `on_enter_tool`、重複其 `say` 或再次自我介紹。所有智慧體都會共用通話中收集的值。

- 目標必須是同一組織中的智慧體，且智慧體不能將通話交接給自己。
- 所有通話層級的設定都保留在接聽的智慧體上：產品、語言、由誰先說話、語音信箱、同意告知，以及其他所有通話設定。
- 目標智慧體可以繼續交接，也可以交接回來。一通電話最多可經過 8 個智慧體。
- 測試通話會執行你所測試智慧體的草稿版本。它交接的智慧體則會執行其已部署版本。
- 如果兩個智慧體有名稱相同但定義不同的工具，通話中只會保留其中一個，且一律以接聽智慧體的工具為準。儲存時應用程式會發出警告。
- 智慧體可以在沒有步驟的情況下設定交接。會直接使用其完整提示詞。

`go_to_step` 和 `hand_off` 在具有步驟或轉接的智慧體上是保留名稱，因此你自己的工具不能使用這些名稱。

## 在通話中查看

在 **通話紀錄** 中開啟通話。逐字稿旁的步驟時間軸會顯示通話進入過的每個步驟及其原因，並同時列出收集的值。

[通話物件](/api-reference/calls#retrieve-a-call)和通話完成 Webhook（[`telephony.complete` / `web.complete`](/zh-Hant/webhooks/call-complete)）會以 `steps_trace` 和 `collected_values` 提供相同資料。未使用步驟的通話不會包含這兩者。

```json
"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` 是 `a` 後接智慧體 ID。`via` 說明通話是如何移動的：

| `via` | 意義 |
| --- | --- |
| `start` | 通話從此步驟開始。 |
| `model` | 模型透過 `go_to_step`、`when` 或 `global_when` 選擇了此步驟。 |
| `condition` | `condition` 或 `always` 轉場符合條件。 |
| `on_enter` | 轉場符合 Webhook 步驟的結果。 |
| `handoff` | 其他智慧體接手。 |

## 步驟執行的位置

步驟會在每個智慧體（以及舊版產品值）上原生執行，適用於
來電、撥出和行銷活動通話、測試通話，以及網頁與小工具通話。

在其他所有地方，智慧體仍可運作，只是沒有這種結構：它會執行扁平化提示詞，依序合併共用指示與每個步驟。這包括：

- [Realtime](/zh-Hant/guides/use-with-openai-realtime) 工作階段，包括已儲存智慧體的工作階段；
- 由[動態通話設定](/zh-Hant/guides/dynamic-call-config) Webhook 傳回的內嵌設定。傳回 `agent_id` 的 Webhook 會使用該智慧體的步驟。

## 限制

| 限制 | 值 |
| --- | --- |
| 每個智慧體的步驟數 | 100 |
| 每個步驟收集的值數量 | 20 |
| 每個智慧體的交接目標數 | 8 |
| 單次通話可觸及的智慧體數 | 8 |
| `steps` JSON 的大小 | 200 KB |
| 步驟的 `instructions` | 20,000 個字元 |
| `say` 行 | 1,000 個字元 |
| 儲存的 `on_enter_tool` 結果 | 4 KB |

若儲存時違反規則，會傳回 `400` 及錯誤欄位的路徑，例如
`steps.steps[2].transitions[0].to`。`tools` 和 `on_enter_tool` 中的工具名稱
必須是已附加至該智慧體的工具。

不支援每個步驟使用不同語言、略過模型的腳本化步驟，以及 say 行中的收集值。

## 匯入的智慧體

從 Retell、Bland、Vapi 或 ElevenLabs [匯入](/zh-Hant/guides/import-agents)
時，會將多提示詞智慧體、流程、路徑和工作流程帶入為步驟，並將小隊與智慧體轉接帶入為匯入智慧體之間的交接。匯入前，審查頁面會同時顯示兩者。

## 範例：牙科初診

依序包含三個步驟：問候、收集病患資料、預約。

```json
{
  "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` 為選填。

## 範例：年齡限制分支

模型可以與任何人交談，但由程式碼決定誰能預約。收集年齡後，在考量模型自身的選擇之前，先依年齡進行路由。

```json
{
  "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"}
  ]
}
```

無論模型如何決定，說自己十五歲的來電者都會前往 `guardian`。
其他所有人都會前往 `book`。兩者皆為圖表中其他位置的一般步驟。

## 範例：帳戶查詢 webhook 步驟

來電者提供帳戶號碼，進入下一個步驟時會執行查詢，並根據結果選擇路徑。為求簡潔，省略了 `not_found`、`collections` 和 `support` 步驟。

```json
[
  {
    "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"}` 可捕捉該情況。

## 範例：總機轉接至帳務

兩個智慧體。總機（智慧體 `412`）接聽每一通電話，並將帳務問題轉交給具有獨立提示、工具和語音的帳務智慧體（智慧體 `413`）。

在總機上：

```json
{
  "handoffs": [
    {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"}
  ]
}
```

在帳務智慧體上，讓它能將來電者轉回：

```json
{
  "handoffs": [
    {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"}
  ]
}
```

總機會說一句簡短的話，例如「我來為你轉接帳務團隊」，接著帳務智慧體會自我介紹，並從總機結束之處繼續對話。帳務轉回時，總機會從原本的位置繼續，不會再次向來電者問候。由於電話是由總機接聽，通話的產品、語言、同意公告及其他通話設定都會保留在總機上。

如果帳務只需要自己的指示，而不需要獨立的智慧體，請改在總機上使用全域步驟。問題回答完畢後，通話會回到來電者原先所在的步驟：

```json
{
  "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"
}
```

## 後續步驟

<CardGroup cols={2}>
  <Card title="提示詞指南" icon="pen" href="/zh-Hant/guides/prompting">
    撰寫適用於電話通話的共用指示與步驟指示。
  </Card>
  <Card title="建立工具整合" icon="code" href="/zh-Hant/guides/build-tool-integration">
    建立供你的步驟與 Webhook 步驟呼叫的工具。
  </Card>
  <Card title="測試你的智慧體" icon="flask" href="/zh-Hant/guides/test-agents">
    在部署前，針對每個分支執行相同的情境測試。
  </Card>
  <Card title="智慧體 API" icon="robot" href="/api-reference/agents">
    所有智慧體欄位、草稿與部署功能。
  </Card>
</CardGroup>
