Synthesia и LiveKit: как собрать ИИ-гида с аватаром, который сам нажимает кнопки. Пошагово
Содержание
- Что получится в итоге
- Что понадобится
- Если вы работаете из России
- Что важно знать до старта
- Шаг 1. Получаем два ключа
- Шаг 2. Берём готовое приложение
- Шаг 3. Ставим навыки для кодинг-агента
- Шаг 4. Ставим задачу кодинг-агенту
- Шаг 5. Вставляем ключи
- Шаг 6. Запускаем и проверяем первый разговор
- Шаг 7. Даём гиду инструменты
- Шаг 8. Подключаем документацию продукта
- Что делать, если гид отвечает плохо
- Что дальше
Новый сотрудник открывает корпоративный сервис и не понимает, что писать в какое поле. Документацию он не читает, в поддержку писать неловко. Обычно всё заканчивается вопросом коллеге или заброшенным аккаунтом.
Есть другой путь: встроить в приложение гида, с которым можно поговорить голосом. Он отвечает на вопросы по вашей документации, подсказывает следующий шаг и даже сам нажимает кнопки. Такого гида собирают из трёх частей: платформа Synthesia даёт говорящего аватара, LiveKit отвечает за связь в реальном времени, а языковая модель думает над ответом. Раньше это был большой проект для команды разработчиков. Теперь установщик навыков учит кодинг-агента, как подключать аватара, а человек описывает задачу словами.
Разбираем по шагам, как это собрать на готовом приложении. И что из этого повторить в России.
Что получится в итоге
В правом нижнем углу приложения появляется виджет с живым аватаром. Нажали Start conversation, и гид здоровается. Он знает, на каком экране вы находитесь, отвечает только по документации продукта и называет, откуда взял ответ. Если попросить, заполнит поля формы, но ничего не сохранит: решение остаётся за человеком. Может открыть нужный раздел, создать задачу и перенести её на другой этап доски.
Для примера возьмём учебное приложение Launchpad: это система управления проектами с доской из четырёх этапов, людьми и справочным центром. Устройство то же для любого сервиса: CRM, внутреннего портала, личного кабинета клиента.
Что понадобится
- Приложение на Next.js. В примере это учебный проект с готовой авторизацией. Гида можно добавить и в уже работающий продукт.
- Аккаунт Synthesia с доступом к Interactive Avatar API и ключ API.
- Аккаунт LiveKit Cloud и свой проект там. Через него идёт голос и картинка аватара.
- Ключ OpenAI. Он нужен для модели, которая ведёт разговор в реальном времени.
- Кодинг-агент. В примере это Cursor с моделью Claude Opus 5.5, но подойдёт любой агент из списка поддерживаемых.
- Python и Node.js. Агент гида на Python, приложение на Next.js.
Если вы работаете из России
Здесь придётся быть осторожным. Synthesia, LiveKit Cloud и OpenAI это зарубежные облачные сервисы. Доступ к ним и оплата из России могут быть затруднены, это нужно проверять до начала работы.
Что можно сделать:
- Заменить модель. Ключ OpenAI нужен только для разговора. Вместо него можно подключить открытую модель на своём сервере или российскую модель, если она подходит по качеству русской речи и умеет вызывать инструменты.
- Заменить агента. Навыки из примера ставятся не только в Cursor. В списке поддерживаемых есть Codex, Gemini CLI, Kimi Code CLI, OpenCode, Pi, Zed. Те, что умеют работать с любыми моделями, например OpenCode и Pi, можно направить на открытую модель. Это проверьте по их документации.
- Развернуть связь у себя. У LiveKit есть открытая серверная часть, её можно поставить на свой сервер вместо облака. Это уточняйте по документации проекта.
- Обойтись без аватара. Аватар Synthesia это облачный сервис, готовой открытой замены ему в примере нет. Но весь остальной гид, то есть голос, инструменты и база знаний, работает и без картинки. Для первого запуска в закрытом контуре этого хватит.
Что важно знать до старта
- Технология новая. Interactive Avatar API работает в бета-режиме, поэтому названия кнопок и поля могут отличаться от скриншотов.
- Навыки получают полные права агента. После установки терминал предупреждает: проверьте навыки до использования, они запускаются с полными разрешениями. Откройте файлы и прочитайте.
- Ключ API только на сервере. Страница Synthesia прямо пишет: хранить его в окружении сервера и никогда не класть в код браузера.
- Гид умеет столько, сколько ему сказали. На вопрос «что ты умеешь» первая версия дала пустой ответ: никто не описал ей возможности. Чаще всего причина в контексте и инструментах, а не в технологии.
- Гид тратит деньги. Разговор расходует минуты аватара Synthesia и запросы к модели OpenAI. По комментарию в файле настроек LiveKit Cloud отдельно считает распознавание и озвучку речи. Оцените расходы до запуска для всех сотрудников.
- Простая проверка не покажет всего. Тестируйте с перебиванием, уточнениями и вопросами, на которые вы заранее знаете ответ.
Шаг 1. Получаем два ключа
Первый ключ в Synthesia. В личном кабинете откройте вкладку Developers. Первый пункт там называется Create an API key. Ключ сохраните в серверное окружение, как SYNTHESIA_API_KEY. Во втором пункте сразу лежат два пути: через кодинг-агента и через быстрый старт. Нам нужен первый.

Второй ключ в LiveKit Cloud. Зарегистрируйтесь, создайте проект, затем откройте Settings, раздел API keys, и создайте ключ. Сохраните его целиком: пара ключ и секрет понадобится позже. Заодно запомните адрес проекта, он начинается с wss:// и заканчивается на livekit.cloud.

Шаг 2. Берём готовое приложение
Для примера используют два репозитория. Первый, стартовый, это приложение без аватара. Второй, готовый, это то же приложение после всех шагов: если что-то не получится, можно сверить свой код с ним.
Клонируем стартовый репозиторий в терминале, переходим в его папку и открываем проект в Cursor. Если у вас свой продукт, этот шаг пропустите и работайте в нём.
Шаг 3. Ставим навыки для кодинг-агента
Навык это пакет инструкций, который учит агента работать с конкретным сервисом. Благодаря им агент знает, как подключать аватара, и не придумывает код наугад. Начинаем с навыков Synthesia. В терминале внутри проекта запускаем команду установки навыков Synthesia с флагом -g. Её точный текст виден в разделе Developers, на скриншоте шага 1: копируйте её оттуда.
Установщик покажет список агентов, для которых можно подключить навыки. В примере включены все, а способ установки выбран symlink.

Затем ставим навыки LiveKit. По документации LiveKit это делается одной командой:
npx skills add livekit/agent-skills
Выберите все навыки и установку внутрь проекта. После этого в папке .agents/skills появятся файлы: как строить голосовых агентов, как читать документацию, как тестировать и запускать.
Шаг 4. Ставим задачу кодинг-агенту
Теперь достаточно описать, что нужно. В примере задача такая:
Используй навык Synthesia interactive avatar, навыки агентов LiveKit и минимальный быстрый старт Synthesia, чтобы добавить в это приложение гида по онбордингу. Python-агента положи в отдельную папку. Покажи гида в виджете справа внизу и дай ему мужской голос.
Про отдельную папку можно было и не писать. В примере её указали, чтобы было видно структуру. Модель агента выбирают любую, в примере взят Claude Opus 5.5 в быстром режиме.
Через некоторое время агент создаст папку agent и добавит виджет в приложение. Он же скажет, каких ключей ему не хватает.
Шаг 5. Вставляем ключи
Ключи кладём в два места.
- Файл
.env.localв корне приложения. Копия.env.example. Сюда идут ключи авторизации приложения. В примере это Clerk, настройку которого можно повторить по репозиторию. - Файл
.envв папкеagent. Копия.env.exampleиз этой папки. Здесь адрес проекта LiveKit, ключ и секрет LiveKit, ключ Synthesia и ключ OpenAI. По комментарию в файле, значения LiveKit агент может читать и из.env.localприложения, тогда здесь они не нужны. Ключ OpenAI питает модель, на которой идёт разговор.
Есть и необязательное поле SYNTHESIA_AVATAR_ID. По умолчанию подставлен аватар Kenji с мужским голосом. Если оставить поле пустым, будет он. Свой аватар можно выбрать в студии Synthesia и вставить его идентификатор.

В примере вышла ошибка: файл в папке агента назвали .env.local, а нужен просто .env. Исправили одной репликой кодинг-агенту: в папке агента теперь файл .env. Имена файлов лучше проверять сразу.
Шаг 6. Запускаем и проверяем первый разговор
Агента гида запускают рядом с приложением. По строке в начале agent.py: команда python agent/agent.py dev. Режим console использует тестовую комнату без аватара. Но проще попросить самого кодинг-агента:
Запусти агента и приложение.
Он поднимет оба процесса. В примере приложение открылось на порту 3212, а старые процессы пришлось остановить.
В правом нижнем углу приложения появится кнопка помощи, а при нажатии виджет с кнопкой Start conversation.

Нажимаем. Гид подключается, здоровается и называет проект, в котором вы находитесь. Он работает как человек на видеозвонке: его можно перебить, он остановится и ответит на новый вопрос.
Первый ответ на вопрос «что ты умеешь» получился бледным: гид сказал, что не может кликать и только подскажет, куда идти. Это ожидаемо: инструментов у него ещё нет.
Шаг 7. Даём гиду инструменты
Гид только говорит, пока ему не дали руки. Инструмент это действие, которое он может выполнить в приложении. Просим агента:
Когда я прошу показать часть приложения, пусть гид нажимает настоящие кнопки.
Потом добавляем второе действие:
Пусть гид добавляет задачи и переносит их между этапами, когда я прошу, через кнопки New task и Move task. Он должен сказать, что готово, только после успешного сохранения.
Последняя фраза важна: так гид не пообещает того, чего не сделал.

После перезапуска гид выполняет цепочки действий. Просьба «перенеси задачу в этап Build» превращается в несколько шагов: открыть панель переноса, выбрать задачу, выбрать этап, нажать кнопку, подтвердить результат голосом. Доска пишет об этом строкой над колонками.

Такой же приём работает с формами. Когда в примере просят помочь с настройкой рабочего пространства, гид сам заполняет название, проект и выбирает процесс Campaign. Но не сохраняет: под кнопкой Create стоит пометка, что до неё ничего не записывается. Решение за человеком.

Шаг 8. Подключаем документацию продукта
Чтобы гид отвечал по делу, ему нужна база знаний. В примере это папка docs/product с короткими файлами в формате Markdown: рабочее пространство, первый проект, процессы, роли, этапы доски, лимиты. Каждый файл начинается с заголовка и ключевых слов.
Источник знаний может быть и другим: база данных или внешний сервис. Тогда достаточно сказать агенту, откуда брать данные, а навыки подскажут, как это настроить.
Как проверить, что гид читает именно документы? Просим агента добавить тестовые файлы с выдуманными фактами:
Обнови файлы в docs/product. Добавь пару тестовых файлов и научи аватара читать из них. Положи туда простую выдуманную информацию, чтобы я мог проверить ответы.
Агент создал заметки о релизах и файл с фактами о команде. Например, талисман команды это трёхногий корги по имени Комета, а день демо проходит каждый четверг в 16:00.
Внутри устроено просто. Файл docs_index.py использует модель эмбеддингов text-embedding-3-small. Вопрос превращается в вектор и сравнивается с абзацами документов. Совпадения ниже порога 0.25 считаются посторонними, а в ответ идут четыре самых близких абзаца.

Проверяем вопросами, ответ на которые известен заранее. Кто талисман команды? Когда демо-день? Как назывался первый релиз и что добавили следующие? Гид отвечает верно и называет документ. Под аватаром в виджете появляется строка вида «From the docs: About the Launchpad team».

Заодно стоит проверить вопрос вне темы: гид по правилам отвечает только по документам и должен честно сказать, что ответа у него нет.
Что делать, если гид отвечает плохо
В примере первая версия отвечала слабо, и причина была не в Synthesia. Аватар не умнее контекста, который ему дали. Что стоит проверять:
- Системный промт. Описан ли гид, его роль, границы и список возможностей.
- Документы. Есть ли в них ответы на вопросы, которые зададут новички.
- Инструменты. Умеет ли гид то, что вы от него ждёте, и сказано ли ему, что он это умеет.
- Модель. В примере после изменений за разговор отвечала модель GPT-4o вместо реалтайм-модели OpenAI. Это может дать другую задержку, её лучше замерить.
Хороший приём: открыть чат с кодинг-агентом, описать, что гид отвечает не так, и попросить улучшить контекст. Установленные навыки подскажут, где что поправить.
Что дальше
Такой гид нужен не только для онбординга. По тому же шаблону собирают голосовую поддержку клиентов и помощника в играх. Меняются документы, инструменты и характер, а схема остаётся: ключи, навыки, задача для агента, инструменты, база знаний, проверка.
Мы в Агентехе учим сотрудников ставить задачи ИИ-агентам, подключать им инструменты и знания компании и проверять результат на реальных рабочих сценариях. Как устроено обучение.