---
name: voice-agent
description: >
  Пошагово собирает в Савви голосового ИИ-агента, который отвечает на звонки клиентов: задаёт вопросы о компании,
  берёт факты с сайта и из документов, создаёт базу знаний, пишет короткую инструкцию-сценарий под звонок,
  ставит голос и модель, защищает персональные данные, проверяет агента тестовыми разговорами и объясняет,
  как позвонить ему из браузера и подключить номер. Всё через MCP Савви.
  Триггеры: «голосовой агент», «агент на звонки», «бот отвечает на звонки», «ИИ-администратор по телефону»,
  «собери голосового агента», «/voice-agent».
---

# Голосовой агент для звонков (Савви)

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

Главные правила голоса (из руководства Савви и практики):
- **Инструкция короткая**: только ход разговора. Чем она длиннее, тем дольше пауза в трубке.
- **Факты в базе знаний**: цены, адрес, часы, услуги. В инструкции их нет.
- **Одна мысль и один вопрос за реплику**, реплика до 20 слов. Точка — это пауза.
- **Явная цель и прощание**: без них агент отвечает на вопросы и не доводит клиента до результата.

## 0. Проверка перед стартом
- Вызови `get_info_about_self_user`. Не отвечает → попроси пользователя: `/mcp` → `suvvy` → Authenticate.
- Посмотри баланс (`user_balance.total_tokens`, 1 токен = 0,001 ₽) и тариф (`active_subscription.name`).
  Тестовые разговоры тратят баланс. Голос, стиль и скорость речи меняются на тарифе Pro и выше:
  на стартовом агент говорит голосом по умолчанию — это нормально, скажи пользователю.

## 1. Вопросы пользователю (одним сообщением, коротко, с примерами)
1. Компания: название, город, чем занимается.
2. Ссылка на сайт.
3. Документы, если есть: прайс, FAQ, регламент, скрипт администратора (путь к файлу или текст в чат).
4. Кто звонит и зачем: 2–3 самых частых повода звонка.
5. Цель звонка: что считаем успехом (записан на время, едет сейчас, оставил заявку, узнал цену и адрес).
6. Что срочное и требует особой реакции (если есть).
7. Чего агенту нельзя: советы, скидки, обещания сроков, темы.
8. Имя агента и голос: женский или мужской. Приветствие — или предложи своё: «<Компания>, здравствуйте. Чем могу помочь?»
9. Говорить ли в начале, что отвечает ИИ-ассистент.

Не хватает ответа — предложи разумный вариант по умолчанию и иди дальше, не устраивай допрос.

## 2. Факты
- Сайт: открой главную и страницы «Услуги», «Цены», «Контакты», «О компании», «FAQ», «Доставка/Запись» (WebFetch).
- Документы: PDF и картинки читай напрямую; DOCX и XLSX — попроси сохранить в PDF/CSV или вставить текстом.
- Собери таблицу «факт — источник». Только то, что написано у компании. Чего нет — **не выдумывай**:
  спроси пользователя или не включай. Цены без даты актуальности уточни у пользователя.

## 3. План → «да» пользователя
Покажи коротко и дождись подтверждения:
- роль и цель звонка;
- сценарий шагами (Шаг 0 — главный/срочный вопрос);
- список записей базы знаний (названия);
- голос, приветствие, ограничения.

## 4. Создать агента
1. `create_instance(template_code="voice", name="<Компания> — голосовой администратор")`.
   Шаблон «voice» сразу ставит голос: синтез ElevenLabs v4 Turbo, голос «Мария 2», распознавание Yandex SpeechKit,
   фоновый офисный шум. Инструкция после создания — общая заглушка, её заменяет раздел 5.
2. Голос нужно добавить существующему агенту для переписки (а не создавать нового)? Тогда вместо шага 1 —
   `enable_instance_voice_mode(instance_id, update_instruction=false)`: база знаний останется та же.
   Агенту из голосового шаблона этот вызов не нужен.
3. Модель — `update_instance_llm`:
   `llm_code="gpt-4.1"` (модель для голоса по умолчанию в Савви, открыта клиентам — проверено 05.11.2026),
   `llm_settings={"reasoning_effort":"minimal","verbosity":"low"}`, `max_answer_tokens=180` (страховка от длинных реплик),
   `randomness=0`. Список `get_llm_list` огромный (больше 100 моделей) — без нужды не вызывай; другую модель бери
   только с `is_admin_only: false` и `works_with_voice: true`.

## 5. Инструкция (`update_instance_mcp`, поле `instruction`)
Пиши по шаблону, подставь своё, лишнее выкинь. Итог — не длиннее 2 500 знаков. Фактов (цен, адресов, часов) в ней нет.

```
#РОЛЬ
Ты — <Имя>, <должность> <компании> в <город>. <Кем ты НЕ являешься: «Ты не врач».> Твоя задача — разобраться, что нужно звонящему, и довести его до <цель>.

#ЦЕЛЬ ЗВОНКА
Звонок успешен, когда <клиент записан на день и время / едет сейчас / оставил заявку> и подтвердил это вслух.
Каждая твоя реплика заканчивается вопросом или шагом вперёд. Когда цель достигнута — коротко попрощайся.

#ДЛИНА РЕПЛИКИ — ГЛАВНОЕ ПРАВИЛО
Это телефонный разговор. Реплика — максимум две короткие фразы, не больше 20 слов. Даже если вопрос широкий — одна главная мысль.
Один вопрос за реплику. Клиент задал два вопроса — ответь на первый и спроси, рассказать ли про второй.
Цену, адрес и время называй отдельным коротким предложением. Контакт называй один, остальные — если попросят.
Точка — это пауза. Цифры и время произноси словами.
Говори от <женского/мужского> лица, на «Вы». Можно начинать фразу с «Так», «Смотрите», «Ага», но не в каждой реплике.

#ХОД РАЗГОВОРА
Шаг 0. Сначала <проверь срочность / главный вопрос>. Если <срочно: перечисли признаки> — сразу <что делать>; нужный адрес или контакт сначала возьми из базы знаний через get_file_text. Остальное потом.
Шаг 1. Узнай, что случилось или что нужно клиенту.
Шаг 2. <Уточни одно главное: кто/что/когда — по одному вопросу.>
Шаг 3. Предложи решение: <услуга / специалист / приезд>. Цену называй из базы знаний, только если спросили или это нужно для решения.
Шаг 4. <Запись/заявка: собери по одному: имя, удобное время.> Проговори итог: <что, когда, где>. Дождись «да».
Шаг 5. Назови адрес отдельной репликой, если клиент едет. Попрощайся.

#БАЗА ЗНАНИЙ
Любой факт — цены, адрес, контакты, часы работы, услуги, условия — бери только из базы знаний: сначала get_file_text, потом отвечай.
Без вызова факты не называй, даже если кажется, что знаешь. Из файла бери только то, о чём спросили.
В файле нет ответа — не говори ни «да», ни «нет»: скажи, что уточнишь, и предложи <перезвон администратора / приехать>.

#ОГРАНИЧЕНИЯ
Никогда не выдумывай цены, имена сотрудников, свободное время, услуги и контакты.
Не обещай скидки и промокоды. Не говори «записала» и «оформила», если сама ничего не записываешь, — говори «передам администратору».
Слова «база знаний» клиенту не произноси.
<Запреты бизнеса: «Не давай медицинских советов, не называй лекарства и дозировки», «Не называй сроки доработок».>
Не произноси вслух телефон, адрес и полное имя клиента.
```

Как адаптировать под нишу:
- **Шаг 0 — самый важный вопрос ставь первым.** Иначе агент собирает анкету, когда клиенту срочно.
  Клиника — срочность; сервис — «машина на ходу?»; доставка — «заказ уже оформлен?».
- Запреты пиши прямо и коротко. Если клиент давит («ну а таблетку-то можно?»), агент повторяет отказ и зовёт к специалисту.
- Слово, которое синтез речи произносит с неправильным ударением, — впиши в инструкцию блок
  «#ЗАПРЕЩЁННЫЕ СЛОВА: не говори «<слово>», вместо него — «<замена>»». ⚠️ «Замены» в кабинете в голосе не работают.

## 6. База знаний (`create_faq_document`)
- Каждая запись — отдельный вызов `create_faq_document(instance_id, title, text)`. Пакетного создания в MCP больше нет;
  записей много (50+) — собери таблицу «Вопрос — Ответ» и загрузи через `create_faq_documents_from_xlsx`.
- **Одна запись — одно намерение.** Название — вопрос клиента его словами: «Сколько стоит ночной приём?»,
  «Где вы находитесь и как добраться?», «Как записаться?». На старт хватит 5–10 записей.
- Текст записи — законченный: с названием компании, конкретными цифрами и условиями. Без «см. выше».
- **Все цены — в одной записи**, с явными метками («днём — …, ночью — …»). Иначе агент назовёт дневную цену на ночной вопрос.
- Перечни закрывай, только когда точно знаешь: «Других услуг нет», «Работаем только с кошками и собаками».
  Чего нет в данных компании, не пиши «нет» от себя («Рассрочки нет») — агент выдаст это клиенту как факт.
  Спроси пользователя или не пиши ничего: на пустое место агент по инструкции ответит «уточню».
- Ошибка «Заголовок документа FAQ для поиска уже занят» → такое название уже есть в другом агенте аккаунта; переформулируй.
- Проверь: `get_instance_faq_documents` — у каждой записи `title_for_search` по смыслу совпадает с названием
  (это английский перевод для поиска). Если там «New File» — запись не найдётся, обнови название.

## 7. Защита персональных данных (152-ФЗ)
Барьер, который проверяет каждый ответ до того, как клиент его услышит:
1. `create_call_condition(instance_id, title="Агент называет данные клиента", groups=[{"condition_list":[{"type":"llm_call_instruction",
   "call_instruction":"Агент произносит личные данные самого звонящего: его имя, телефон или домашний адрес. Адреса, телефоны, почта, сайт и мессенджеры компании нарушением НЕ являются."}]}])`.
   Без второй фразы барьер ложно срабатывает на контакты самой компании и вырезает их из ответа.
2. `create_instance_prediction_guardrail(instance_id, title="Не называть данные клиента", call_condition_id=<id>,
   action={"type":"regenerate","hint":"Перепиши ответ без имени, телефона и адреса клиента","max_regenerate_count":1})`.
Адрес **компании** агент называет как обычно — барьер только про данные клиента.

## 8. Голос (`update_instance_voice_settings` и `update_instance_voice_extra_settings`)
Сначала `get_instance` → посмотри `voice_settings`: шаблон уже ставит рабочие значения.

`update_instance_voice_settings`:
- `start_message` — приветствие («<Компания>, здравствуйте. Чем могу помочь?»);
- `ai_disclaimer` — фраза про ИИ, если пользователь хочет («Вам отвечает ИИ-ассистент.»), иначе не трогай;
- `silence_response` = `{"timeout_seconds": 10, "phrase_list": ["Алло?", "Вы здесь?"], "instruction": null}`;
- `background_audio` = `{"ambient_sound": "office_ambience", "volume": 0.2}` — пауза не звучит пустой тишиной.

`update_instance_voice_extra_settings` → `tts_model` (передай объект целиком: возьми текущий из `voice_settings.tts_model`
и замени только нужные поля). Голосовой шаблон уже ставит ElevenLabs v4 Turbo и «Мария 2» — обычно меняешь только стиль:
- `name`: `"elevenlabs/eleven_v4_turbo"` (ElevenLabs v4 Turbo);
- `voice_id`: женский — «Мария 2» `J4tzTjMXY75Yma7NXDAR`; мужской — выбери из
  `get_voice_agent_tts_voice_list(provider_type="elevenlabs", tts_model_id="elevenlabs/eleven_v4_turbo")` с `language: "ru"`
  и `is_admin_only: false`;
- `speech_style`: `"warmly"` (тёплый — клиники, салоны, сервис), `"professional"` (деловой — B2B, юристы, финансы),
  `"lively"` (живой — магазины, доставка). Писать «говори тепло» в инструкцию не нужно — стиль задаётся здесь.
- скорость и стабильность оставь как есть.
`stt_model` (распознавание): оставь модель шаблона, в `keywords` впиши название компании, улицы, фамилии сотрудников —
так их лучше распознаёт.

Вызов вернул ошибку тарифа → оставь голос по умолчанию и скажи пользователю, что голос и стиль меняются на тарифе Pro и выше.
Любые модели и голоса бери только с `is_admin_only: false`.

## 9. Проверка тестовыми разговорами
Тестовый чат в режиме звонка: `get_new_test_dialogue_for_instance_by_instance_id` →
`send_message_to_test_dialogue_by_id(dialogue_id, fake_channel="test_voice_call", messages=[{"message_sender":"customer","message_data":{"data_type":"text","content":"…"}}])` →
`get_dialogue_messages_by_dialogue_id(dialogue_id, elements=4)`.
Отправка возвращает только `Successful`, ответ агента читай отдельно: последние записи — ответ, проверка барьера,
`get_file_text` и его вызов (новые сверху). Цена разговора — `get_dialogue_by_id` → `total_tokens_amount` (÷1000 = ₽).
**Перед каждым сценарием — новый чат.** Пиши по одной реплике, как живой клиент.
Приветствие и фразу про ИИ тестовый чат не проигрывает — их слышно только на тестовом звонке в кабинете.
Почта в ответе вида «собака», «точка» — это нормальная подготовка текста к озвучке, не ошибка.

Минимум 5 сценариев:
1. Главный повод звонка — до цели и прощания (4–6 реплик).
2. Срочный случай (Шаг 0) — агент сразу ведёт к действию, без анкеты, контакт или адрес — из базы.
3. Вопрос о цене и адресе (у онлайн-сервиса — о цене и как связаться) — цифры точно как в базе знаний.
4. Вопрос, ответа на который в базе нет (например, «А рассрочка есть?») — агент не выдумывает.
5. Давление на запрет («ну посоветуйте хоть что-нибудь») — агент держит отказ и зовёт к специалисту.

Проверяй каждую реплику агента: слов ≤ 20 (до 25 терпимо), вопрос один, цифры из базы, вызов `get_file_text` перед фактами,
нет данных клиента, есть шаг вперёд. Нашёл ошибку — правь инструкцию или запись базы и прогоняй сценарий заново.
Покажи пользователю итог таблицей: сценарий — прошёл/нет — что поправил.

## 10. Что пользователь делает в кабинете (через MCP нельзя)
1. **Послушать голос**: агент → «Доп. настройки» → настройки голосового агента → «Прослушать».
2. **Тестовый звонок**: вкладка «Инструкция» → «Тестовый звонок», говорить в микрофон компьютера. Минуты списываются с баланса.
3. **Демо-ссылка**, чтобы дать позвонить другим: карточка агента → ☰ → «Демо-ссылка» → «Публичный доступ» → срок и лимит минут.
4. **Свой номер**: «Подключить телефонию» → «Входящие звонки» → добавить номер. Подойдёт номер любого оператора с SIP:
   номер, сервер, порт, логин, пароль — из кабинета оператора. Перед этим Савви просит заполнить реквизиты организации,
   оплатить счёт с расчётного счёта (от 5 000 ₽, вся сумма приходит на баланс и уходит на звонки) и подписать заверение.
   Можно подключить самому или написать в поддержку Савви — подключат и проверят. Потом у оператора направить входящие на агента.
5. **Цена**: минута разговора — от 15 ₽, точная зависит от тарифа, голос на цену не влияет.
   Звонок короче 15 секунд считается посекундно, длиннее — целыми минутами.

## Грабли
1. Длинная инструкция → паузы в трубке. Режь до хода разговора, факты — в базу.
2. Нет Шага 0 → на срочный вопрос агент собирает анкету.
3. Нет цели и прощания → агент отвечает и молчит, клиент вешает трубку без результата.
4. Цены в разных записях → путает цены. Все цены — в одной записи с метками.
5. «Нет» от себя в базе («Рассрочки нет», хотя компания этого не говорила) → агент уверенно отказывает клиенту.
   Пиши в базу только факты компании; на пустое место агент ответит «уточню».
9. Срочный шаг без вызова базы → агент выдумывает почту или телефон. В Шаге 0 прямо требуй get_file_text.
6. «Замены» слов в кабинете в голосовом канале не применяются — неудобные слова запрещай в инструкции.
7. Модели и голоса с `is_admin_only: true` клиенту недоступны — не ставь их.
8. Реплики всё равно длинные → проверь, что `max_answer_tokens=180` и правило длины стоит в инструкции блоком, а не строкой в конце.