---
title: "エージェントのステップと引き継ぎ"
description: "エージェントをそれぞれ独自の指示、ツール、収集した値を持つステップに分割し、通話の途中でエージェント間で通話を引き継ぎます。"
---

単一のプロンプトでは、モデルに仕事全体を一度に任せます。**ステップ**では、一度に通話の1つのフェーズを任せます。各ステップには、それぞれの指示、専用のツール、任意の一語一句読み上げる文、次に進む前に収集する必要がある値があります。**引き継ぎ**では、組織内の別のエージェントが通話の途中から引き継げます。文字起こしはそのまま保持されるため、発信者が同じことを繰り返す必要はありません。

すべてのエージェントは単一のプロンプトとして開始します。ステップまたは引き継ぎを追加するまで、その内容は変わりません。

## ステップまたは単一のプロンプト？

| ステップを使用する場合 | 単一のプロンプトを維持する場合 |
| --- | --- |
| 通話に、確認してから予約するなど、順番に進める必要があるフェーズがある。 | 会話がFAQ、受付、一般サポートのように自由形式である。 |
| エージェントが次に進む前に値を取得する必要がある。 | 決まった順序で収集する必要がない。 |
| 「18歳未満の発信者は保護者につなぐ」のように、例外を認めないルールがある。 | すべての分岐でモデルの判断に任せられる。 |
| 通話内の決まったタイミングで検索を実行する必要がある。 | 発信者が求めたときにいつでもツールを呼び出せる。 |
| 通話の一部を、独自のプロンプトと音声を持つ別のエージェントが担当する。 | 1つのペルソナですべてを処理する。 |

ステップは、スクリプト化された電話ツリーではありません。各ステップ内では、モデルは単一のプロンプトの場合と同じように会話を進めます。ステップによって、取り組む内容、使用できるツール、離れる前に必要な情報が決まります。

## ステップ型エージェントの構築方法

エージェントにステップがある場合、`prompt` には**共有指示**が含まれます。これは、すべてのステップに適用されるペルソナとルールです。各ステップは、その上に独自の指示を追加します。各ターンでモデルには、共有指示、現在のステップの名前と指示、これまでに収集された値が表示されます。

エージェントのエディターで **指示** を開き、プロンプトの見出しの下にある **ステップに分割** を選択します。Zeus はステップを提案し、プロンプトの各セクションを対応するステップと並べて表示します。**これらのステップを使用** で保持し、**1つのプロンプトを維持** で元に戻せます。その後、アウトラインには **共有指示** と各ステップが表示されます。ステップのページには、名前、入力時に一語一句そのまま発話する最初の行、指示、収集する値、使用できるツールに加え、次に移動する先と遷移元が表示されます。**フロー** ではステップがグラフとして表示されます。他のエージェントへのハンドオフは **ツールとハンドオフ** にあります。

ステップの **保存** ではステップが下書きに保存され、エージェントのヘッダーで **デプロイ** を選択すると発信者に反映されます。共有指示の **1つのプロンプト** / **ステップ** 切り替えでは、共有指示とすべてのステップを結合した単一のプロンプトにエージェントを戻せます。旧ビューでは、ビルダーの **単一プロンプト** / **ステップ** 切り替えで同じ操作を行えます。

API では、`steps` と `handoffs` は[エージェント](/api-reference/agents)のフィールドです。すべてのエージェントフィールドと同様に、`PATCH` は下書きに保存し、`POST /v1/agents/{agent_id}/deploy` で本番環境に反映します。`"steps": null` を送信すると、エージェントは単一のプロンプトに戻ります。テスト通話では下書きが使用されます。

<Tip>
  [Zeus](/ja/guides/ask-the-copilot) は説明からステップを作成できます
  （「予約前に生年月日を確認するステップを追加」など）。また、他のステップに触れずに1つのステップを編集できます。
</Tip>

### ステップフィールド

| フィールド | 意味 |
| --- | --- |
| `id` | 必須。小文字、数字、アンダースコアを使用でき、文字で開始し、最大40文字です。エージェント内で一意である必要があります。 |
| `name` | 必須の表示名。1〜80文字です。 |
| `instructions` | 必須。最大20,000文字です。`prompt` と同様に、`{{var}}` [通話変数](/ja/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` から始まります。

## 遷移

各遷移には、ステップ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` を呼び出すと、次の処理が行われます。

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` はあいさつ、必須の告知、固定文言に使用し、応答の残りはモデルに任せてください。

開始ステップの `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` には、通話を引き継げる同じ組織内の他のエージェントを一覧で指定します。

```json
[{"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` は、ステップまたは引き継ぎがあるエージェントでは予約されています。そのため、独自のツールでこれらの名前は使用できません。

## 通話での確認場所

**通話履歴**で通話を開きます。文字起こしの横にあるステップタイムラインには、通話が入った各ステップとその理由が表示され、収集された値も一覧表示されます。

[通話オブジェクト](/api-reference/calls#retrieve-a-call) と通話完了Webhook（[`telephony.complete` / `web.complete`](/ja/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` は、エージェントIDの前に `a` を付けた値です。`via` は通話を移動させた要因を示します。

| `via` | 意味 |
| --- | --- |
| `start` | 通話はこのステップで開始しました。 |
| `model` | モデルが `go_to_step`、`when`、または `global_when` を通じてステップを選択しました。 |
| `condition` | `condition` または `always` の遷移が一致しました。 |
| `on_enter` | Webhookステップの結果に対して遷移が一致しました。 |
| `handoff` | 別のエージェントが引き継ぎました。 |

## ステップが実行される場所

ステップは、すべてのエージェント（および旧来のプロダクト値）でネイティブに実行されます。受信、発信、キャンペーン通話、テスト通話、Web通話、ウィジェット通話に対応します。

それ以外の場所でもエージェントは機能しますが、構造は使用されません。共有指示とすべてのステップを順番に統合した、フラット化されたプロンプトが実行されます。対象は次のとおりです。

- 保存済みエージェントのセッションを含む[Realtime](/ja/guides/use-with-openai-realtime)セッション。
- [動的通話設定](/ja/guides/dynamic-call-config)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 からの[インポート](/ja/guides/import-agents)では、マルチプロンプトエージェント、フロー、パスウェイ、ワークフローがステップとして取り込まれ、スクワッドとエージェント転送がインポートしたエージェント間のハンドオフとして取り込まれます。インポート前に、レビュー画面で両方を確認できます。

## 例: 歯科の初診受付

順番に3つのステップを設定します。あいさつ、患者情報の収集、予約です。

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

15歳と言う発信者は、モデルの判断にかかわらず `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"}`
で検出できます。

## 例: 受付から請求担当へ

2つのエージェントを使用します。受付（エージェント `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="/ja/guides/prompting">
    電話でも確実に機能する共通指示とステップ指示を作成します。
  </Card>
  <Card title="ツール連携を構築" icon="code" href="/ja/guides/build-tool-integration">
    ステップおよびWebhookステップから呼び出すツールを作成します。
  </Card>
  <Card title="エージェントをテスト" icon="flask" href="/ja/guides/test-agents">
    デプロイ前に、すべての分岐に対して同じシナリオを実行します。
  </Card>
  <Card title="Agents API" icon="robot" href="/api-reference/agents">
    すべてのエージェントフィールド、下書き、デプロイについて確認します。
  </Card>
</CardGroup>
