ThunderPhone v3 уже доступен.Самостоятельный запуск — от 2 ¢/мин.Читать анонс

Using the dashboard

Шаги и передачи между агентами

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

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

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

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

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

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

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

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

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

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

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

Поля этапа

ПолеЗначение
idОбязательно. Строчные буквы, цифры и символы подчёркивания; начинается с буквы, до 40 символов. Уникально в пределах агента.
nameОбязательное отображаемое имя от 1 до 80 символов.
instructionsОбязательно, до 20 000 символов. Поддерживает переменные звонка {{var}}, как и prompt.
sayНеобязательная реплика, произносимая дословно при входе на этап, до 1 000 символов. Поддерживает {{var}}.
toolsnull предоставляет этапу все инструменты, подключённые к агенту. Список ограничивает этап указанными инструментами по имени. Встроенные действия, такие как end_call и transfer_call, на каждом этапе следуют настройкам агента.
collectДо 20 значений, которые собирает этап. У каждого есть name, type, description и required (по умолчанию true).
on_enter_toolНеобязательное имя инструмента, автоматически вызываемого при входе на этап. См. Этапы вебхука.
transitionsУпорядоченный список этапов, на которые можно перейти дальше. См. Переходы.
global_whenНеобязательно. Делает этап доступным с любого этапа. См. Глобальные этапы.
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. Если ничего не совпало и модель не указала этап, агент остаётся на текущем этапе.

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

Переходы condition и always также проверяются при каждом входе на этап, поэтому последовательность этапов, для которых решение принимает код, выполняется сразу. Цепочка останавливается:

  • на этапе, который уже был посещён в этом запуске;
  • после 8 переходов;
  • на этапе, для которого ещё нужно собрать обязательные значения, если у этапа нет on_enter_tool (этап webhook всегда выполняет маршрутизацию по своему результату).

Произносится только строка say этапа, на котором останавливается цепочка.

Этап без переходов является конечным. Агент завершает работу на нём и завершает или переводит звонок с помощью обычных встроенных действий.

Сбор значений

Перечислите в collect, что требуется этапу. Модель передаёт значения при вызове go_to_step, и они остаются доступными до конца звонка.

typeСодержит
stringЛюбой текст
numberЧисло
booleantrue или false
dateДату в формате YYYY-MM-DD

Собранные значения относятся к содержимому звонка. Они отображаются рядом с расшифровкой звонка и подчиняются тем же правилам хранения, удаления и редактирования. Когда запись звонка агента отключена, собранные значения не сохраняются и не отправляются в webhook; хронология этапов всё равно сохраняется. См. Где посмотреть это в звонке.

Произносимые реплики

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 перечисляет других агентов в вашей организации, которые могут принять звонок:

[{"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 зарезервированы для агентов с этапами или передачами, поэтому ваши собственные инструменты не могут использовать эти имена.

Где посмотреть это в звонке

Откройте звонок в Истории звонков. Временная шкала этапов рядом с расшифровкой показывает каждый этап, на который перешёл звонок, и причину перехода; там же перечислены собранные значения.

Объект звонка и вебхук завершения звонка (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 — это a, за которым следует идентификатор агента. via указывает, что перевело звонок:

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

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

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

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

  • сеансам Realtime, включая сеансы для сохранённого агента;
  • встроенным конфигурациям, возвращаемым вебхуком динамической конфигурации звонка. Вебхук, возвращающий agent_id, использует этапы этого агента.

Ограничения

ОграничениеЗначение
Этапов на агента100
Собираемых значений на этап20
Целей передачи на агента8
Агентов, доступных за один звонок8
Размер JSON steps200 КБ
instructions этапа20 000 символов
Строка say1 000 символов
Сохранённый результат on_enter_tool4 КБ

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

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

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

Импорт из Retell, Bland, Vapi или ElevenLabs переносит агентов с несколькими промптами, потоки, маршруты и рабочие процессы как этапы, а группы и передачи агентов — как передачи между импортированными агентами. На странице проверки отображаются оба типа до импорта.

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

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

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

Звонящий, который говорит «пятнадцать», переходит к 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"}.

Пример: от стойки регистрации к биллингу

Два агента. Стойка регистрации (агент 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"
}

Следующие шаги