Як побудувати кодового агента на Gemini: практичний погляд на Interactions API

У Google DeepMind активно переосмислюють, як розробники працюють з великими мовними моделями. На воркшопі AI Engineer інженери Thor Schaeff та Philipp Schmid показують, як із новим Interactions API будувати агентів, які не просто відповідають у чаті, а реально працюють з кодом: читають і змінюють файли, запускають bash-команди, підтримують багатокрокові діалоги й ефективно керують контекстом.

Цей матеріал зосереджений саме на такому кодовому агенті та на тому, як Interactions API змінює підхід до стану сесії, кешування й виклику інструментів.

Від generateContent до Interactions: чому архітектура агента змінюється

Interactions API, запущений у бета-версії в грудні, має замінити знайомий багатьом розробникам generateContent. Формально це нова поверхня для Gemini, але практично — інший спосіб мислити про взаємодію з моделлю.

Замість жорстко «модель-центричного» підходу Interactions API пропонує єдиний інтерфейс і для моделей, і для агентів. Це наближає його до того, що вже стало стандартом у галузі: формат, подібний до chat completions в OpenAI чи API Anthropic, з чіткою структурою повідомлень і контент-блоків.

У цьому ж інтерфейсі розробники можуть:

• викликати моделі на кшталт Gemini 1.5 Flash Free (у воркшопі її називають Gemini Free Flash) для швидких, дешевих кодових і планувальних задач;
• працювати з агентами, які мають власну логіку, інструменти та довготривалі сесії.

Кодовий агент, який демонструють у воркшопі, будується саме поверх цього нового API. Він не просто генерує текст, а:

• читає файли з файлової системи;
• записує нові файли або змінює існуючі;
• виконує bash-команди локально.

Це вже не «чат з моделлю», а повноцінний інструмент розробника, який може автоматизувати частину рутини — від створення файлів до запуску скриптів.

Серверний стан і previousInteractionId: як агент «пам’ятає» розмову

Ключова зміна, яка робить таких агентів практичними, — поява серверного стану в Interactions API. Раніше типовий підхід вимагав від клієнта щоразу надсилати всю історію діалогу, щоб модель «пам’ятала» контекст. Це ускладнювало клієнтський код і збільшувало витрати на токени.

Тепер Interactions API дозволяє передавати previousInteractionId. Це ідентифікатор попередньої взаємодії, до якої сервер «прикріплює» новий запит, використовуючи вже збережену історію. Для кодового агента це означає:

• не потрібно вручну збирати й пересилати весь діалог;
• можна мислити категоріями «черговий крок у сесії», а не «повна розмова щоразу».

У демонстраційному прикладі використовується клієнт GenAI з класом Agent, який зберігає глобальний previousInteractionId. Цей ідентифікатор оновлюється після кожного виклику Interactions API й використовується в наступному запиті. Таким чином, агент підтримує багатокрокову розмову, не дублюючи історію на клієнті.

Цей підхід особливо важливий для кодового агента, який:

• отримує від користувача інструкції;
• викликає інструменти (читання файлів, bash-команди);
• повертає результат і продовжує діалог, спираючись на попередні кроки.

Серверний стан дозволяє зосередитися на логіці інструментів і контролі агента, а не на механічному менеджменті контексту.

Дешевше й швидше: як серверний стан покращує кешування

Запровадження серверного стану в Interactions API має ще один важливий наслідок — значно кращу роботу імпліцитного кешування вхідних даних.

Коли клієнт перестає щоразу пересилати повну історію, сервер отримує можливість ефективніше повторно використовувати вже закодовані токени. У практичних термінах це означає:

• кешовані вхідні токени можуть бути до приблизно 90% дешевшими;
• стартапи, які вже використовують Interactions API, бачать у 2–3 рази кращі показники потрапляння в кеш.

Для кодового агента, який веде довгі сесії з багатьма кроками, це критично. Кожен новий запит не дублює попередній контекст, а лише посилається на нього через previousInteractionId. Сервер розуміє, які частини вже були закодовані, і може:

• не повторювати обробку однакових фрагментів;
• зменшувати вартість і затримку відповідей.

Це робить багатокрокових агентів економічно привабливішими, особливо коли йдеться про сценарії, де користувачі активно експериментують, уточнюють завдання, змінюють вимоги до коду або просять агента послідовно рефакторити проєкт.

Свобода вибору: коли варто керувати контекстом на клієнті

Попри всі переваги серверного стану, Interactions API не змушує розробників покладатися на нього. Якщо є потреба повністю контролювати контекст на клієнті, це залишається можливим.

Є кілька причин, чому хтось може обрати саме такий шлях:

• необхідність тонкого «інжинірингу контексту», коли потрібно явно видаляти або переформатовувати частини історії;
• вимоги безпеки або комплаєнсу, які диктують, що саме й у якому вигляді може зберігатися на стороні сервера;
• інтеграція з власними системами пам’яті, де історія діалогу зберігається у внутрішніх базах даних, векторних сховищах тощо.

Interactions API дозволяє працювати в обох режимах. Кодовий агент може:

• або покладатися на previousInteractionId і делегувати стан серверу;
• або формувати повний контекст на клієнті й надсилати його як звичайний вхід.

Ця гнучкість важлива для команд, які будують складні системи навколо агентів: наприклад, коли один агент повинен «забувати» частину історії, а інший — мати до неї повний доступ через окреме сховище.

Як працює кодовий агент: цикл інструментів і структуровані виклики функцій

Серцем демонстраційного кодового агента є цикл, який поєднує модель, інструменти та стан сесії. Його завдання — дозволити моделі планувати й делегувати дії, а локальному коду — безпечно виконувати ці дії.

Логіка виглядає так:

модель отримує запит користувача разом із описами доступних інструментів. У випадку кодового агента це, зокрема, функції для читання файлів, запису файлів і виконання bash-команд.

Interactions API повертає не просто текстову відповідь, а структурований результат, де окремі блоки можуть бути позначені як function_call або як результат функції. Це принципово важливо: замість парсити текст, розробник працює зі строго типізованими структурами.

Кодовий агент далі:

1. Переглядає вихідні дані взаємодії й шукає в них виклики функцій.
2. Для кожного виклику визначає, яку локальну функцію потрібно виконати: наприклад, прочитати файл main.py або запустити npm test.
3. Виконує відповідну функцію в локальному середовищі.
4. Додає результат виконання як ще один структурований блок у взаємодію.
5. Повторно викликає Interactions API з оновленим контекстом, доки модель не припинить викликати інструменти.

Цей рекурсивний цикл триває доти, доки модель не вирішить, що всі необхідні дії виконано й можна повернути фінальну відповідь користувачу.

Ключовий момент: Interactions API експонує як самі виклики функцій, так і результати цих функцій як структуровані типи у вихідних даних. Це дає змогу будувати надійний, передбачуваний код агента без крихкого парсингу тексту.

Структуровані function_call: чому це критично для надійних інструментів

У попередніх поколіннях API розробникам часто доводилося довіряти «текстовим протоколам»: модель повертала інструкцію на кшталт «виклич функцію read_file з аргументом path=’main.py’», а клієнтський код мав це розпізнати, розпарсити й виконати.

Такий підхід крихкий:

• модель може змінити формат відповіді;
• помилки форматування важко відловити;
• безпека страждає, бо важко гарантувати, що аргументи відповідають очікуваному типу.

Interactions API вирішує це, представляючи виклики функцій як окремий тип контенту. Кожен function_call — це структурований об’єкт із чітко визначеними полями, так само як і результат функції.

Для кодового агента це означає:

• можна однозначно визначити, яку саме функцію потрібно викликати;
• аргументи приходять у передбачуваному форматі;
• результати можна так само структуровано додати назад у взаємодію.

Це відкриває шлях до складніших сценаріїв:

• комбінування кількох інструментів у межах одного кроку;
• побудова складних планів, де модель послідовно викликає різні функції;
• безпечніше виконання команд, оскільки можна явно валідувати аргументи до їхнього запуску.

У демонстраційному агенті цей механізм використовується для роботи з файловою системою й bash. Але той самий підхід можна застосувати до будь-яких інструментів: від внутрішніх API до зовнішніх сервісів.

Чому для кодового агента обрали Gemini 1.5 Flash Free

У воркшопі як базову модель для кодового агента використовують Gemini 1.5 Flash Free, яку позиціонують як швидку й економічну. Вона оптимізована для сценаріїв, де важливі:

• низька вартість;
• висока швидкість відповіді;
• здатність планувати й працювати з інструментами за умови, що їй надано якісні інструкції та «навички» (skills).

Для кодового агента це логічний вибір. Більшість операцій — це не глибокий аналіз великих корпусів тексту, а:

• розуміння коротких інструкцій користувача;
• планування послідовності викликів інструментів;
• генерація або модифікація коду в межах конкретних файлів.

У такому режимі швидкість і вартість мають більшу вагу, ніж максимальна «потужність» моделі. Використання безкоштовного рівня Gemini 1.5 Flash Free також робить приклад доступним для розробників: усі демонстрації воркшопу спроєктовано так, щоб їх можна було виконати в межах free tier.

Практичні аспекти: ключі, безпека й розгортання агента

Хоча основна увага воркшопу зосереджена на логіці агента, не обходиться без базових, але важливих практичних моментів.

Доступ до Gemini відбувається через ключі API, які рекомендують отримувати через Google AI Studio. Потрапити туди можна за адресами ai.dev або ai.studio; потрібен лише Google-акаунт, без кредитної картки. Усе, що демонструється в сесії, вкладається в безкоштовний тариф.

Окремо наголошується: ключ API — це секрет. Його не можна:

• ділити з іншими;
• вбудовувати в клієнтський код, який потрапляє в публічні репозиторії;
• ненавмисно «засвічувати» у скріншотах чи демо.

Для кодового агента це особливо важливо, оскільки він часто працює в середовищі розробника, де є спокуса «швидко зашити ключ у скрипт». Правильний підхід — зберігати ключ у змінних середовища або в конфігураційних файлах, які не потрапляють у контроль версій.

Висновок: кодові агенти як наступний крок у роботі з LLM

Кодовий агент, побудований на Interactions API, демонструє, як змінюється роль великих мовних моделей у розробці. Вони перестають бути просто «розумними автодоповнювачами» й перетворюються на активних учасників робочого процесу, здатних:

• читати й змінювати файли;
• виконувати команди в середовищі розробника;
• підтримувати довгі, багатокрокові сесії з ефективним керуванням станом.

Серверний стан через previousInteractionId спрощує побудову таких агентів і водночас робить їх дешевшими завдяки кращому кешуванню. Структуровані виклики функцій і результати в Interactions API дозволяють будувати надійні, безпечні цикли інструментів без крихкого парсингу тексту.

А можливість за бажанням повністю керувати контекстом на клієнті залишає простір для складних, кастомізованих архітектур, де агент — лише один із компонентів більшої системи.

У підсумку Interactions API не просто оновлює синтаксис виклику Gemini. Він задає нову модель мислення: від «запиту до моделі» до «оркестрації агента, інструментів і стану». І кодові агенти, подібні до продемонстрованого на воркшопі, показують, що цей підхід уже готовий до практичного використання в повсякденній розробці.

Джерело

Building Conversational Agents — Thor Schaeff and Philipp Schmid, Google DeepMind