---
title: "智能體步驟與交接"
description: "將智能體拆分為多個步驟，各自設有專屬指示、工具及已收集的值，並可在通話期間於智能體之間轉接來電。"
---

單一提示詞會一次過為模型提供整項工作。**步驟**讓它每次處理通話的一個階段：每個步驟都有專屬指示、專屬工具、可選的逐字說出句子，以及必須收集後才能繼續的值。**交接**讓你機構內的另一個智能體可在通話途中接手，並保留完整對話記錄，讓來電者毋須重複已說的內容。

每個智能體一開始都是單一提示詞。在你加入步驟或交接前，當中的設定不會改變。

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

| 適合使用步驟的情況 | 適合保留單一提示詞的情況 |
| --- | --- |
| 通話包含必須依序進行的階段：先核實，再預約。 | 對話屬開放式：常見問題、接待、一般支援。 |
| 智能體繼續前必須擷取某個值。 | 不需要按固定次序收集任何資料。 |
| 規則絕不可變通，例如「未滿 18 歲的來電者須轉介給監護人」。 | 模型的判斷足以處理每個分支。 |
| 必須在通話中的固定位置執行查詢。 | 來電者提出要求時即可呼叫工具。 |
| 通話的部分內容屬於另一個智能體，並使用其專屬提示詞及語音。 | 一個角色可處理所有事項。 |

步驟並非預設腳本電話流程。在步驟內，模型會如同使用單一提示詞般進行對話。步驟決定模型正在處理的事項、可使用的工具，以及離開前必須完成的內容。

## 分步智能體的建立方式

當智能體設有步驟時，其 `prompt` 會儲存**共用指示**：適用於每個步驟的角色設定及規則。每個步驟會在此基礎上加入專屬指示。每次互動時，模型都會看到共用指示、目前步驟的名稱及指示，以及至今收集的值。

在建立工具中，將智能體由**單一提示詞**切換為**步驟**。你會看到每個步驟的卡片，其中包括名稱、指示、說出句子、工具、已收集的值及轉換設定、交接選擇器，以及步驟的唯讀流程圖。切換回單一提示詞時，系統會提供一個合併共用指示及所有步驟內容的整合提示詞。

透過 API，`steps` 及 `handoffs` 是
[智能體](/api-reference/agents)的欄位。與其他智能體欄位相同，`PATCH` 會將它們暫存於草稿中；`POST /v1/agents/{agent_id}/deploy` 會將它們發佈上線。傳送
`"steps": null` 會將智能體切換回單一提示詞。測試通話及
**交談**會使用草稿版本。

<Tip>
  [智能助手](/yue/guides/ask-the-copilot)可根據描述建立步驟
  （「加入一個在預約前核實出生日期的步驟」），並可編輯單一步驟而不影響其他步驟。
</Tip>

### 步驟欄位

| 欄位 | 含義 |
| --- | --- |
| `id` | 必填。由小寫英文字母、數字及底線組成，須以字母開頭，最多 40 個字元。在智能體內必須唯一。 |
| `name` | 必填顯示名稱，長度為 1 至 80 個字元。 |
| `instructions` | 必填，最多 20,000 個字元。與 `prompt` 一樣支援 `{{var}}` [通話變數](/yue/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` 字串比較。從未收集的數值會令所有 op 均為假，惟 `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` 格式的日期 |

已收集數值屬於通話內容。它們會在通話中顯示於逐字記錄旁邊，並遵循相同的保留、刪除及資料遮蔽規則。關閉智能體的通話錄音後，已收集數值不會儲存，亦不會傳送至網絡掛鈎；步驟時間線則仍會保留。請參閱[在通話中查看資料的位置](#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`](/yue/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](/yue/guides/use-with-openai-realtime) 工作階段，包括已儲存智能體的工作階段；
- 由[動態通話設定](/yue/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 [匯入](/yue/guides/import-agents)時，系統會將多提示智能體、流程、路徑及工作流程匯入為步驟，並將 squad 及智能體轉移匯入為已匯入智能體之間的轉交。匯入前，審閱頁面會同時顯示兩者。

## 範例：牙科登記

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

```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="/yue/guides/prompting">
    撰寫適合電話對話的共用指示及步驟指示。
  </Card>
  <Card title="建立工具整合" icon="code" href="/yue/guides/build-tool-integration">
    建立供你的步驟及 Webhook 步驟呼叫的工具。
  </Card>
  <Card title="測試你的智能體" icon="flask" href="/yue/guides/test-agents">
    部署前，在每個分支執行相同情境。
  </Card>
  <Card title="智能體 API" icon="robot" href="/api-reference/agents">
    涵蓋每個智能體欄位、草稿及部署。
  </Card>
</CardGroup>
