На конференції AI Engineer інженери Google DeepMind Тор Шефф і Філіп Шмід показують, як будувати розмовні агентні системи на базі Gemini. Окремий блок їхнього воркшопу присвячений тому, з чого взагалі почати: як отримати доступ до Gemini, що таке новий Interactions API, чому він замінює generateContent і як зробити перші кроки, не витрачаючи грошей. Саме на цих аспектах зосередимося в цьому матеріалі.
Від generateContent до Interactions: навіщо Gemini новий API
Gemini як платформа для розробників розвивається швидко, і класичний підхід через generateContent поступово вичерпує себе. У грудні Google DeepMind запустила в бета-версії новий Interactions API, який має стати наступником generateContent і фактично змінити спосіб, у який розробники працюють з моделями Gemini.
Ключова ідея Interactions API — уніфікація. Замість того, щоб мати окремі механізми для “голих” моделей і для складніших агентів, тепер пропонується єдина поверхня, яка працює і з моделями, і з агентами. Це наближає Gemini до того, до чого вже звикли розробники, що працювали з OpenAI чи Anthropic: за духом Interactions API нагадує chat completions та сучасні API конкурентів.
У практичному сенсі це означає, що розробнику більше не потрібно думати в категоріях “це окремий endpoint для моделі, а це — для агента”. Є одна концепція “interaction” — взаємодії, в межах якої можна:
- викликати модель на кшталт Gemini 1.5 Flash Free для швидких відповідей;
- звернутися до вбудованого агента, наприклад Deep Research, який працює довго й асинхронно;
- комбінувати моделі, агентів і інструменти в єдиному сценарії.
Таке вирівнювання під “галузевий стандарт” — не лише косметична зміна. Воно зменшує поріг входу для тих, хто вже працював з OpenAI або Anthropic, і робить перехід на Gemini менш болісним: патерни мислення, структура запитів і спосіб роботи з контекстом стають знайомими.
Інтерфейс, зрозумілий веб-розробникам: менше gRPC, більше “людського” JSON
Попередні версії Gemini API були помітно “гуглівськими”: сильний акцент на protobuf, gRPC, специфічні формати, які добре лягають у внутрішні інфраструктури, але не завжди комфортні для типового веб-розробника. Interactions API свідомо відходить від цієї парадигми.
Новий API:
- менше орієнтований на proto та gRPC;
- більше нагадує звичні HTTP+JSON інтерфейси, з якими працює більшість фронтенд- і бекенд-розробників;
- використовує єдину модель контенту з чітко типізованими блоками.
Центральний елемент — “content blocks”: кожен вхід і вихід моделі або агента описується однаковим типом об’єкта з полем type. Це поле може позначати текст, аудіо, відео, зображення, function_call, а також спеціальний тип thought_signature. Таким чином, замість різнорідних структур для різних модальностей і дій, розробник працює з єдиною схемою, де все — просто різні типи контенту.
Для веб-розробника це означає менше “перемикання контексту” між форматами і протоколами. Взаємодія з Gemini стає схожою на роботу з будь-яким сучасним REST/streaming API: знайомі JSON-структури, знайомі патерни стрімінгу через Server-Sent Events (SSE), знайомий підхід до авторизації через API-ключ.
Саме підтримка SSE — ще один важливий штрих. Interactions API дозволяє отримувати відповіді в стрімінговому режимі, що критично для розмовних інтерфейсів, де користувач очікує перших токенів відповіді вже за частки секунди. Для фронтенду це означає можливість будувати чат-інтерфейси з “друком у реальному часі” без складних обхідних маневрів.
Єдиний API для моделей і агентів: від швидких відповідей до глибоких досліджень
Одне з ключових стратегічних рішень Interactions API — об’єднати в одному інтерфейсі як класичні моделі, так і агентів, які можуть виконувати складні багатокрокові завдання.
З боку моделей у воркшопі як “робоча конячка” використовується Gemini 1.5 Flash Free (часто його називають Gemini Free Flash). Це безкоштовний, швидкий і відносно дешевий варіант, який добре підходить для кодування, планування і типових агентних сценаріїв за умови, що модель отримує чіткі інструкції та “навички” через інструменти.
З боку агентів у Interactions API вже вбудований Deep Research. Це агент, який може виконувати довгі дослідницькі завдання у фоновому режимі — на рівні 10–15 хвилин, відвідуючи сотні сайтів. У споживчому продукті Gemini подібний режим знайомий як “глибоке дослідження”: користувач формулює запит, отримує план, а далі система самостійно збирає й узагальнює інформацію.
У контексті API це виглядає як ще один “агент”, до якого можна звернутися так само, як до моделі. Розробник у запиті або вказує модель (наприклад, Gemini 1.5 Flash Free), або агента (наприклад, Deep Research). Поверхня API при цьому залишається однаковою, що спрощує перемикання між швидкими відповідями й довгими асинхронними сценаріями.
Важливо, що Interactions API з самого початку спроєктований з урахуванням довготривалих задач. Для таких агентів, як Deep Research, передбачено асинхронне виконання у фоні: запит можна запустити, а потім або опитувати API, або (коли це стане доступно) отримувати нотифікації через вебхуки. Це знімає необхідність тримати HTTP-з’єднання відкритим хвилинами, що суперечить добрим практикам веб-розробки.
Серверний стан, кешування і контроль над контекстом
Ще одна фундаментальна відмінність Interactions API від generateContent — поява серверного стану. У класичній схемі клієнт повинен був щоразу надсилати повну історію діалогу, щоб модель “пам’ятала” контекст. Це ускладнювало клієнтську логіку, збільшувало обсяг даних і витрати на токени.
У новому API з’являється поняття previousInteractionId. Кожна взаємодія зберігається на сервері, і замість того, щоб повторно надсилати всю історію, клієнт може передати ідентифікатор попередньої взаємодії. Сервер “прикріпить” новий запит до вже наявного контексту.
Це дає кілька практичних переваг.
По-перше, спрощується клієнтська логіка. Розробнику не потрібно вручну збирати й обрізати історію діалогу для кожного запиту. Достатньо зберігати previousInteractionId і передавати його в наступних викликах.
По-друге, суттєво покращується кешування. Оскільки сервер бачить стабільний контекст, він може ефективніше кешувати кодування вхідних токенів. Для розробників це перетворюється на економію: закешовані вхідні токени можуть бути до 90% дешевшими, а стартапи, які вже використовують цей механізм, бачать у 2–3 рази кращі показники cache hit rate. Для проєктів із великими й повторюваними контекстами це може стати помітним фактором у структурі витрат.
Водночас Interactions API не нав’язує серверний стан. Якщо команда хоче повністю контролювати контекст на клієнтському боці — з міркувань безпеки, комплаєнсу чи складної “інженерії контексту” — це залишається можливим. Розробник може продовжувати самостійно формувати історію діалогу й надсилати її в кожному запиті, не покладаючись на збережений на сервері стан.
Такий “подвійний режим” важливий для підприємств, де політики обробки даних можуть вимагати жорсткого контролю над тим, що саме зберігається на стороні постачальника моделі. Interactions API надає гнучкість: можна обрати або зручність і економію через серверний стан, або повний клієнтський контроль.
Інструменти, комбінування та єдина модель контенту
Хоча глибокий розбір інструментів і агентів виходить за межі цього матеріалу, для розуміння Interactions API важливо відзначити ще кілька моментів.
По-перше, новий API працює з інструментами як з першокласними об’єктами. Підтримуються як вбудовані інструменти на кшталт Google Search, так і кастомні, включно з віддаленими MCP-інструментами. Це дозволяє будувати агентів, які в одному сценарії можуть іти в пошук, викликати власні функції, звертатися до зовнішніх сервісів.
По-друге, нещодавно з’явилася можливість комбінувати Google Search із власними функціями в одному виклику. Це була одна з найзапитуваніших можливостей: розробники хотіли, щоб агент міг одночасно користуватися глобальним веб-пошуком і внутрішніми інструментами застосунку, не розбиваючи логіку на кілька окремих кроків.
По-третє, Interactions API представляє виклики функцій і результати цих викликів як структуровані типи в результаті взаємодії. Це означає, що модель не просто “вигадує” текст із описом того, що вона нібито викликала, а повертає чітко структуровані об’єкти function_call і function_result. Для розробника це спрощує побудову циклів, де код:
- аналізує вихід моделі;
- бачить, що потрібно викликати певну функцію;
- виконує її локально;
- додає результат назад у контекст;
- продовжує взаємодію, поки модель не припинить викликати інструменти.
Єдина модель контенту з типами text, audio, video, image, function_call, thought_signature робить цей процес уніфікованим. Незалежно від того, чи модель відповідає текстом, генерує зображення, ініціює виклик функції або “позначає” внутрішні міркування через thought_signature, усе це виглядає для клієнта як послідовність контент-блоків із різними типами.
Як отримати доступ до Gemini: AI Studio, ai.dev і безкоштовний рівень
Щоб почати працювати з Interactions API, потрібен API-ключ Gemini. Google DeepMind рекомендує отримувати його через Google AI Studio — веб-інструмент, який одночасно слугує “пісочницею” для експериментів із моделями та панеллю керування ключами.
Дістатися до AI Studio можна кількома шляхами. Найкоротший — перейти на ai.dev: цей домен просто редіректить на AI Studio, але саме його організатори воркшопу просять використовувати. Також працюють адреси ai.studio та aistudio.com, але ai.dev — найпростіший для запам’ятовування.
Процес отримання ключа виглядає так:
- Користувач заходить на ai.dev або AI Studio.
- Авторизується під своїм Google-акаунтом.
- У розділі API keys (зазвичай у правому верхньому куті) натискає “Create API key”.
- Якщо потрібно, створює або імпортує проєкт, дає йому будь-яку назву.
- Через кілька секунд отримує згенерований ключ.
Важливий момент: для безкоштовного рівня не потрібна банківська картка. Достатньо мати Google-акаунт. Усі приклади, які демонструються у воркшопі, спеціально підібрані так, щоб укладатися в ліміти безкоштовного тарифу. Це дозволяє учасникам і, ширше, будь-яким розробникам повторювати приклади, експериментувати з Interactions API і Gemini 1.5 Flash Free, не ризикуючи отримати несподіваний рахунок.
Такий підхід знижує бар’єр входу: студенти, інді-розробники, невеликі команди можуть почати працювати з Gemini без фінансових зобов’язань, а вже потім, за потреби, переходити на платні тарифи.
Безпека доступу: чому API-ключ Gemini — це секрет
На фоні загального ентузіазму щодо нових можливостей API організатори воркшопу окремо наголошують на безпеці. API-ключ Gemini — це секретний обліковий реквізит, який дає доступ до облікового запису розробника й до його квоти використання. Витік такого ключа може призвести до небажаних витрат або зловживань.
Типова помилка — випадкове публікування ключа в репозиторіях на GitHub. Часто це стається через те, що ключ “зашивають” безпосередньо в код, який потім комітять у публічний репозиторій. Інша поширена проблема — демонстрації на екрані, коли ключ видно під час презентації або запису відео.
Рекомендації тут класичні, але їх варто повторити:
- не вставляти ключ безпосередньо в код, який потрапляє в репозиторій;
- зберігати ключ у змінних середовища, конфігураційних файлах, які не комітяться (наприклад, через
.gitignore); - не ділитися ключем із колегами “на словах” або в чатах без потреби;
- у разі витоку — негайно відкликати ключ і згенерувати новий.
Під час воркшопу демонстраційний ключ, який випадково опинився на екрані, одразу ж видаляють. Це показовий приклад того, як слід поводитися з такими секретами: навіть якщо витік стався в “безпечному” середовищі, краще перестрахуватися й перевипустити ключ.
Перші кроки: що дає Interactions API розробнику вже сьогодні
Навіть якщо не заглиблюватися в побудову складних агентів, Interactions API вже зараз пропонує набір можливостей, які роблять його привабливим стартовим майданчиком для нових проєктів.
По-перше, це уніфікований інтерфейс для моделей і агентів. Розробник може почати з простого сценарію — наприклад, чат-бота на базі Gemini 1.5 Flash Free — і поступово додавати агентні можливості, не змінюючи фундаментально спосіб взаємодії з API.
По-друге, це зручна модель контенту й підтримка мультимодальності. Навіть якщо сьогодні застосунок працює лише з текстом, архітектура, побудована на content blocks, буде готова до майбутнього розширення на аудіо, відео чи зображення без радикальної перебудови.
По-третє, це серверний стан і покращене кешування, які дають змогу зменшити витрати й спростити клієнтський код. Для стартапів і невеликих команд, які уважно стежать за бюджетом, це може стати вирішальним аргументом на користь Interactions API.
По-четверте, це знайомий для веб-розробників стек: HTTP, JSON, SSE, мінімум специфічних протоколів. Це означає, що інтеграція з фронтендом, бекендом на Node.js, Python чи будь-якій іншій популярній платформі не вимагатиме глибокого занурення в gRPC або protobuf.
Нарешті, безкоштовний рівень доступу через AI Studio дозволяє експериментувати без ризику. Усі приклади з воркшопу свідомо спроєктовані так, щоб укладатися в ліміти free tier, тож розробник може повторити їх, адаптувати під свої задачі й поступово нарощувати складність.
Висновок: Interactions API як нова точка входу в екосистему Gemini
Запуск Interactions API в бета-версії — це не просто черговий endpoint у лінійці Gemini. Це спроба переосмислити, як розробники взаємодіють із моделями й агентами, зробити цей досвід ближчим до галузевих стандартів і водночас зберегти сильні сторони екосистеми Google.
Уніфікований інтерфейс для моделей і агентів, серверний стан із покращеним кешуванням, єдина модель контенту для тексту, аудіо, відео, зображень і викликів функцій, підтримка SSE, вбудовані агенти на кшталт Deep Research, можливість комбінувати Google Search із власними інструментами — усе це формує платформу, на якій можна будувати як прості чат-боти, так і складні розмовні системи.
Для тих, хто лише починає знайомство з Gemini, шлях виглядає досить прямолінійно: зайти на ai.dev, отримати безкоштовний API-ключ через AI Studio, уважно поставитися до безпеки цього ключа й почати експериментувати з Interactions API на базі Gemini 1.5 Flash Free. Далі — питання уяви й конкретних бізнес-завдань.
Джерело
Building Conversational Agents — Thor Schaeff and Philipp Schmid, Google DeepMind