---
title: "Шаги и передачи между агентами"
description: "Разделяйте агента на шаги с собственными инструкциями, инструментами и собранными значениями, а также передавайте звонки между агентами в ходе разговора."
---

Один промпт сразу задаёт модели всю задачу. **Этапы** дают ей по одной
фазе звонка: у каждого этапа есть собственные инструкции, собственные инструменты,
необязательная реплика, произносимая дословно, и значения, которые необходимо собрать
перед переходом дальше. **Передачи** позволяют другому агенту в вашей организации
принять звонок в середине разговора с сохранённой расшифровкой, чтобы звонящему не
приходилось повторяться.

Каждый агент начинается с одного промпта. Ничего не меняется, пока вы не добавите
этапы или передачи.

## Этапы или один промпт?

| Используйте этапы, когда | Оставьте один промпт, когда |
| --- | --- |
| Звонок состоит из фаз, которые должны происходить по порядку: сначала проверка, затем запись. | Разговор не ограничен строгим сценарием: FAQ, ресепшен, общая поддержка. |
| Значение нужно получить до перехода агента дальше. | Ничего не нужно собирать в фиксированном порядке. |
| Правило нельзя нарушать, например: «звонящие младше 18 лет направляются к опекуну». | Решения модели достаточно для любого сценария. |
| Поиск нужно выполнить в определённый момент звонка. | Инструменты можно вызывать всегда, когда этого просит звонящий. |
| Часть звонка относится к другому агенту с собственным промптом и голосом. | Один образ агента обрабатывает всё. |

Этапы — это не сценарное телефонное дерево. Внутри этапа модель ведёт
разговор так же, как с одним промптом. Этап определяет, над чем она
работает, какие инструменты может использовать и что ей нужно, прежде чем
она сможет его покинуть.

## Как устроен агент с этапами

Когда у агента есть этапы, его `prompt` содержит **общие инструкции**:
образ агента и правила, применимые на каждом этапе. Каждый этап добавляет
собственные инструкции поверх них. В каждом ходе модель видит общие инструкции,
название и инструкции текущего этапа, а также собранные к этому моменту значения.

В редакторе агента откройте **Инструкции** и выберите **Разделить на этапы**
под заголовками промпта. Zeus предложит этапы, показав каждый раздел
промпта рядом с этапом, в который он преобразуется; **Использовать эти этапы**
сохранит их, а **Оставить один промпт** вернёт вас назад. После этого в структуре будут перечислены **Общие
инструкции** и каждый этап. На странице этапа указаны его название, первая строка слово
в слово, инструкции, собираемые им значения и инструменты, которые он может использовать,
а рядом — куда он переходит дальше и откуда поступает. **Поток** показывает
этапы в виде графа. Передачи другим агентам находятся в разделе **Инструменты и передачи**.

Кнопка **Сохранить** на этапе сохраняет этапы в черновик; звонящие получат их после того, как вы
выберете **Развернуть** в заголовке агента. Переключатель **Один промпт** / **Этапы**
в разделе «Общие инструкции» возвращает агента к одному промпту, объединяющему
общие инструкции и все этапы. В старом представлении переключатель конструктора
**Один промпт** / **Этапы** делает то же самое.

В API `steps` и `handoffs` являются полями
[агента](/api-reference/agents). Как и для любого поля агента, `PATCH` сохраняет их
в черновик; `POST /v1/agents/{agent_id}/deploy` вводит их в действие. Отправка
`"steps": null` возвращает агента к одному промпту. Тестовые вызовы
используют черновик.

<Tip>
  [Zeus](/ru/guides/ask-the-copilot) может создавать этапы по описанию
  («добавить этап, который проверяет дату рождения перед бронированием») и редактировать один этап,
  не изменяя остальные.
</Tip>

### Поля этапа

| Поле | Значение |
| --- | --- |
| `id` | Обязательно. Строчные буквы, цифры и символы подчёркивания; начинается с буквы, до 40 символов. Уникально в пределах агента. |
| `name` | Обязательное отображаемое имя от 1 до 80 символов. |
| `instructions` | Обязательно, до 20 000 символов. Поддерживает [переменные звонка](/ru/guides/call-variables) `{{var}}`, как и `prompt`. |
| `say` | Необязательная реплика, произносимая дословно при входе на этап, до 1 000 символов. Поддерживает `{{var}}`. |
| `tools` | `null` предоставляет этапу все инструменты, подключённые к агенту. Список ограничивает этап указанными инструментами по имени. Встроенные действия, такие как `end_call` и `transfer_call`, на каждом этапе следуют настройкам агента. |
| `collect` | До 20 значений, которые собирает этап. У каждого есть `name`, `type`, `description` и `required` (по умолчанию `true`). |
| `on_enter_tool` | Необязательное имя инструмента, автоматически вызываемого при входе на этап. См. [Этапы вебхука](#webhook-steps). |
| `transitions` | Упорядоченный список этапов, на которые можно перейти дальше. См. [Переходы](#transitions). |
| `global_when` | Необязательно. Делает этап доступным с любого этапа. См. [Глобальные этапы](#global-steps). |
| `voice` | Необязательный идентификатор голоса для этого этапа. Игнорируется, когда агент использует пользовательскую конфигурацию голоса. |

Сам граф имеет вид `{"start_step": "<step id>", "steps": [...]}`. Звонок
начинается с `start_step`.

## Переходы

У каждого перехода есть `to`, идентификатор этапа и ровно одно из следующего:

- **`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 или приветствию голосовой почты.

`say` этапа не произносится повторно, когда звонок возвращается к нему через `__previous__` или обратную передачу. Пишите его так, как он должен звучать: проговаривайте всё, что голос может неверно прочитать. Произносимые реплики поддерживают переменные звонка `{{var}}`, но не собранные значения.

## Этапы webhook

Установите `on_enter_tool` в один из инструментов агента, и он запустится сразу при входе в этап, не дожидаясь модели. Его аргументы — собранные значения, имена которых совпадают с именами параметров инструмента. Результат сохраняется как собранное значение с именем `<tool>_result`, обрезается до 4 КБ, а переходы `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) и вебхук завершения звонка ([`telephony.complete` / `web.complete`](/ru/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`, за которым следует идентификатор агента. `via` указывает, что перевело звонок:

| `via` | Значение |
| --- | --- |
| `start` | Звонок начался на этом этапе. |
| `model` | Модель выбрала этап через `go_to_step`, `when` или `global_when`. |
| `condition` | Сработал переход `condition` или `always`. |
| `on_enter` | Переход сработал по результату этапа вебхука. |
| `handoff` | Другой агент принял звонок. |

## Где выполняются этапы

Этапы нативно работают на каждом агенте (и в значениях старого продукта), во
входящих, исходящих и кампанийных звонках, тестовых звонках, а также веб-звонках и звонках из виджета.

Во всех остальных случаях агент по-прежнему работает, но без структуры: он использует развёрнутый промпт, который по порядку объединяет общие инструкции и все этапы. Это относится к:

- сеансам [Realtime](/ru/guides/use-with-openai-realtime), включая сеансы для сохранённого агента;
- встроенным конфигурациям, возвращаемым вебхуком [динамической конфигурации звонка](/ru/guides/dynamic-call-config). Вебхук, возвращающий `agent_id`, использует этапы этого агента.

## Ограничения

| Ограничение | Значение |
| --- | --- |
| Этапов на агента | 100 |
| Собираемых значений на этап | 20 |
| Целей передачи на агента | 8 |
| Агентов, доступных за один звонок | 8 |
| Размер JSON `steps` | 200 КБ |
| `instructions` этапа | 20 000 символов |
| Строка `say` | 1 000 символов |
| Сохранённый результат `on_enter_tool` | 4 КБ |

При сохранении с нарушением правила возвращается `400` с путём к некорректному
полю, например `steps.steps[2].transitions[0].to`. Имена инструментов в `tools` и
`on_enter_tool` должны соответствовать инструментам, подключённым к агенту.

Языки для отдельных этапов, сценарные этапы, которые пропускают модель, и
собираемые значения внутри строк say не поддерживаются.

## Импортированные агенты

[Импорт](/ru/guides/import-agents) из Retell, Bland, Vapi или ElevenLabs
переносит агентов с несколькими промптами, потоки, маршруты и рабочие процессы
как этапы, а группы и передачи агентов — как передачи между импортированными
агентами. На странице проверки отображаются оба типа до импорта.

## Пример: оформление пациента в стоматологии

Три этапа по порядку: приветствие, сбор данных пациента, запись.

```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="/ru/guides/prompting">
    Напишите общие инструкции и инструкции для этапов, которые надёжно работают по телефону.
  </Card>
  <Card title="Создание интеграции с инструментом" icon="code" href="/ru/guides/build-tool-integration">
    Создайте инструменты, которые вызывают ваши этапы и этапы вебхуков.
  </Card>
  <Card title="Тестирование агентов" icon="flask" href="/ru/guides/test-agents">
    Запустите одинаковые сценарии для каждой ветки перед развертыванием.
  </Card>
  <Card title="API агентов" icon="robot" href="/api-reference/agents">
    Все поля агента, черновики и развертывание.
  </Card>
</CardGroup>
