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.