Assistant-agent — голосовий асистент Humanoid Company
Голосовий асистент, з яким можна говорити як з людиною. Він бачить ваш Google Календар, пошту й нотатки, вміє шукати в інтернеті й виконує прохання голосом: «що в мене завтра?», «запиши зустріч з Олегом на п'ятницю о 15:00», «чи є нові листи від бухгалтерії?», «додай у нотатки ідею для демо».
Працює у двох варіантах: десктопна програма з wake word і веб-версія для команди, яку достатньо відкрити в браузері.
🎙️ Спробуйте просто зараз: voice-agents-web-three.vercel.app. Нічого встановлювати не треба, достатньо браузера й мікрофона.
Що вміє
- Природна розмова голосом. В основі — OpenAI GPT-Live. Веб-версія працює лише на ньому; у десктопній лишився запасний варіант — OpenAI Realtime (
VOICE_ENGINE=realtime).
- Розумне перебивання. Агент зупиняється, лише коли ви справді хочете взяти слово (стоп-слово або початок вашої репліки), і не реагує на «угу», «ага», фоновий шум чи власне ехо.
- Google Календар. Переглядає, створює й змінює події.
- Gmail. Читає й шукає листи, допомагає з відповідями.
- Нотатки (Google Drive + Docs): додати, прочитати, знайти.
- Вебпошук через Tavily (необов'язково).
- Єва. Покликати: «Єва, скажи», «Привіт, Єва», «Гей, Єва», «Єво, слухай»… Пауза — лише «Дякую, Єва» (навіть посеред відповіді). Пауза не завершує розмову: Єва все пам'ятає. На паузі з нею просто не говорять: Єва слухає фоном, про що говорять поруч, і може потім про це нагадати. Вимикається кнопкою «Слухати фоном на паузі» на сайті або
BACKGROUND_LISTENING=false на десктопі.
- Голоси. 10 голосів на вибір; змінити можна посеред розмови — голосом чи на сайті, пам'ять зберігається. Темп, манера й гучність — одразу.
- Налаштування мови та імені асистента.
Кожен користувач входить своїм Google-акаунтом. Сторонні сервіси на кшталт n8n не потрібні: агент звертається до Google API напряму.
Як влаштовано
Веб-версія (для команди)
Браузер (web/, Vercel) ──WebRTC: мікрофон і звук──► OpenAI GPT-Live
│ ▲
│ SDP-оффер, вхід у Google │ sideband (інструменти)
▼ │
Бекенд (server/, Render) ────────────────────────────────┘
└─ Google Calendar / Gmail / нотатки, вебпошук
- Звук іде напряму між браузером і OpenAI, тому затримка мінімальна, а ехо придушує сам браузер.
- Ключ OpenAI зберігається лише на бекенді.
- Інструменти (Google, вебпошук) виконує бекенд через sideband-з'єднання з тією ж сесією.
- Дані входу в Google зберігаються лише в пам'яті сервера і зникають після його перезапуску.
Десктопна версія
Wake word «Єва, скажи» → голосова сесія → локальний Agent Router → Google API. Мікрофон, VAD і захист від ехо локальні, токени Google зберігаються в Windows Credential Manager.
| Десктоп (main.py) | Веб |
|---|
| Запуск розмови | «Єва, скажи» | кнопка «Почати розмову», далі «Єва, скажи» |
| Пауза | «Дякую, Єва» | «Дякую, Єва» або кнопка «Пауза» |
| Звук | локальний мікрофон, VAD, власний захист від ехо | WebRTC у браузері |
| Вхід у Google | OAuth Desktop-клієнт, вікно на тому ж ПК | OAuth Web-клієнт, редірект на бекенд |
| Токени | Windows Credential Manager | пам'ять сервера |
Єва: пауза, голос і пам'ять
- Ім'я + звертання будить Єву: «Єва, скажи», «Привіт, Єва», «Гей / Хей, Єва», «Єво, слухай / послухай»,
«Єва, допоможи / підкажи», «Агов, Єва». Саме ім'я не будить (розмова про Єву не має її вмикати).
Що сказано після фрази («Привіт, Єво, що в мене завтра?»), одразу йде їй.
«Дякую, Єва» — єдина фраза для паузи: обриває її мовлення. Розпізнавання терпиме до варіантів
(«Єво», «Ева», без коми, дрібні помилки) — правила в
voice/wake_phrases.py, їхня копія для сайту
в web/app.js (тест tests/test_eva_phrases_js.py стежить, щоб вони не розійшлися).
- На сайті фрази слухає вбудоване розпізнавання браузера (Chrome, Edge, Safari; у Firefox — кнопки
«Пауза» / «Продовжити»), а «Дякую, Єва» ще й транскрипт GPT-Live. Пауза довше 30 с (і 90 с тиші — автопауза) закриває сесію, бо GPT-Live рахує кожну відкриту секунду;
«Єва, скажи» відкриває нову з усією історією.
- Пам'ять не залежить від голосу. Голос GPT-Live фіксований на сесію, тож новий голос — це нова
сесія, яка стартує з усією попередньою розмовою (
voice/conversation.py → Live input). Історію
веде бекенд (сайт) або Assistant (десктоп); «Нова розмова» чи вихід з Google її стирають.
- Темп і манера — інструкції моделі, діють одразу (
set_voice_style, панель на сайті). Тембру й
точної швидкості GPT-Live не має. Гучність — повзунок на сторінці. «Прослухати» грає
зразки з web/samples/.
- Перевірка пам'яті на справжній моделі (кілька центів):
RUN_LIVE_TESTS=1 pytest -q -k live_memory.
Структура проєкту
| Шлях | Призначення |
|---|
main.py, assistant.py | десктопний застосунок: життєвий цикл (сон ↔ сесія), пам'ять, спільні хелпери інструментів |
voice/ | драйвери голосових рушіїв (live_driver.py, realtime_driver.py), логіка перебивання, налаштування голосу й мови |
router/agent_router.py | локальний роутер: вільний текст → інтенти |
tools/ | схеми інструментів для Live і Realtime, міст до роутера, вебпошук |
server/ | бекенд веб-версії (FastAPI) |
web/ | фронтенд веб-версії (статичні файли) |
render.yaml, requirements-server.txt | деплой бекенду на Render |
DEPLOY.md | покрокова інструкція з розгортання веб-версії |
Швидкий старт
Спробувати веб-версію
Відкрийте voice-agents-web-three.vercel.app → «Почати розмову» → дозвольте мікрофон → говоріть. Щоб агент бачив календар і пошту, натисніть «Підключити Google». Якщо Google попередить, що застосунок не перевірено: «Додатково» → «Перейти до …».
Розгорнути веб-версію
Коротко: OAuth-клієнт Web application у Google Cloud → бекенд на Render (Blueprint з render.yaml) → фронтенд на Vercel (Root Directory = web). Деталі — у DEPLOY.md.
Змінні середовища бекенду:
| Змінна | Опис |
|---|
OPENAI_API_KEY | ключ OpenAI |
PUBLIC_BACKEND_URL | публічна адреса бекенду, без / у кінці |
FRONTEND_ORIGINS | адреса(и) фронтенду через кому |
GOOGLE_OAUTH_WEB_CLIENT_ID / GOOGLE_OAUTH_WEB_CLIENT_SECRET | дані Web OAuth-клієнта |
ACCESS_CODE | пароль на сторінку; порожнє значення = доступ для всіх, у кого є посилання |
WEB_SEARCH_API_KEY | ключ Tavily (необов'язково) |
GOOGLE_CALENDAR_TIMEZONE | часовий пояс, за замовчуванням Europe/Kyiv |
Локальний запуск веб-версії
uv sync --group server
# .env: OPENAI_API_KEY, PUBLIC_BACKEND_URL=http://localhost:8000,
# GOOGLE_OAUTH_WEB_CLIENT_ID/SECRET (redirect http://localhost:8000/auth/google/callback)
.venv/Scripts/python.exe -m uvicorn server.app:app --port 8000
# фронтенд
python -m http.server 5173 -d web
# відкрити http://localhost:5173/?backend=http://localhost:8000
Обмеження
- Поки застосунок не пройшов верифікацію Google, під час входу з'являється попередження, а кількість користувачів обмежена сотнею.
- На безкоштовному плані Render сервер засинає після ~15 хвилин без запитів. Перше відкриття триває до хвилини, і після цього Google треба підключити знову.
- Голосові сесії оплачуються з балансу OpenAI, тому задайте ліміт витрат у налаштуваннях OpenAI.
