Написать в Telegram

Synthesia и LiveKit: как собрать ИИ-гида с аватаром, который сам нажимает кнопки. Пошагово

Содержание
  1. Что получится в итоге
  2. Что понадобится
  3. Если вы работаете из России
  4. Что важно знать до старта
  5. Шаг 1. Получаем два ключа
  6. Шаг 2. Берём готовое приложение
  7. Шаг 3. Ставим навыки для кодинг-агента
  8. Шаг 4. Ставим задачу кодинг-агенту
  9. Шаг 5. Вставляем ключи
  10. Шаг 6. Запускаем и проверяем первый разговор
  11. Шаг 7. Даём гиду инструменты
  12. Шаг 8. Подключаем документацию продукта
  13. Что делать, если гид отвечает плохо
  14. Что дальше

Новый сотрудник открывает корпоративный сервис и не понимает, что писать в какое поле. Документацию он не читает, в поддержку писать неловко. Обычно всё заканчивается вопросом коллеге или заброшенным аккаунтом.

Есть другой путь: встроить в приложение гида, с которым можно поговорить голосом. Он отвечает на вопросы по вашей документации, подсказывает следующий шаг и даже сам нажимает кнопки. Такого гида собирают из трёх частей: платформа 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. Во втором пункте сразу лежат два пути: через кодинг-агента и через быстрый старт. Нам нужен первый.

Раздел Developers в Synthesia: ключ API и команда установки навыков
Раздел Developers в Synthesia: ключ API и команда установки навыков

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

Проект в LiveKit Cloud: отсюда открываются ключи API через Manage API keys
Проект в LiveKit Cloud: отсюда открываются ключи API через Manage API keys

Шаг 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 и вставить его идентификатор.

Файл с ключами агента: поля для LiveKit, Synthesia и OpenAI пока пустые
Файл с ключами агента: поля для LiveKit, Synthesia и OpenAI пока пустые

В примере вышла ошибка: файл в папке агента назвали .env.local, а нужен просто .env. Исправили одной репликой кодинг-агенту: в папке агента теперь файл .env. Имена файлов лучше проверять сразу.

Шаг 6. Запускаем и проверяем первый разговор

Агента гида запускают рядом с приложением. По строке в начале agent.py: команда python agent/agent.py dev. Режим console использует тестовую комнату без аватара. Но проще попросить самого кодинг-агента:

Запусти агента и приложение.

Он поднимет оба процесса. В примере приложение открылось на порту 3212, а старые процессы пришлось остановить.

В правом нижнем углу приложения появится кнопка помощи, а при нажатии виджет с кнопкой Start conversation.

Виджет гида в углу приложения с кнопкой Start conversation
Виджет гида в углу приложения с кнопкой Start conversation

Нажимаем. Гид подключается, здоровается и называет проект, в котором вы находитесь. Он работает как человек на видеозвонке: его можно перебить, он остановится и ответит на новый вопрос.

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

Шаг 7. Даём гиду инструменты

Гид только говорит, пока ему не дали руки. Инструмент это действие, которое он может выполнить в приложении. Просим агента:

Когда я прошу показать часть приложения, пусть гид нажимает настоящие кнопки.

Потом добавляем второе действие:

Пусть гид добавляет задачи и переносит их между этапами, когда я прошу, через кнопки New task и Move task. Он должен сказать, что готово, только после успешного сохранения.

Последняя фраза важна: так гид не пообещает того, чего не сделал.

Запрос кодинг-агенту: гид должен добавлять и двигать задачи кнопками
Запрос кодинг-агенту: гид должен добавлять и двигать задачи кнопками

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

Гид перенёс задачу на другой этап, об этом пишет сама доска
Гид перенёс задачу на другой этап, об этом пишет сама доска

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

Гид говорит и сам выбрал процесс Campaign, ничего не сохраняя до кнопки Create
Гид говорит и сам выбрал процесс 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. Это может дать другую задержку, её лучше замерить.

Хороший приём: открыть чат с кодинг-агентом, описать, что гид отвечает не так, и попросить улучшить контекст. Установленные навыки подскажут, где что поправить.

Что дальше

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

Мы в Агентехе учим сотрудников ставить задачи ИИ-агентам, подключать им инструменты и знания компании и проверять результат на реальных рабочих сценариях. Как устроено обучение.

Написать в Telegram