Один агент, три версії: Interactions API проти ADK проти Antigravity SDK
Той самий агент Gemini створив три варіанти за допомогою Interactions API, Google ADK та Antigravity SDK, які були порівняні за механізмами циклів, інструментами, процедурами автентифікації та способами розгортання в Cloud Run.
Джерела: I built the same agent three ways: Interactions API, ADK, and the Antigravity SDK
Система Google тепер пропонує три зовсім різні шляхи створення функціонального агента: Interactions API, який є інтерфейсом Gemini API для роботи з агентами, ADK — повноцінна фреймворк-система, та Antigravity SDK — інструментарій, що лежить в основі Antigravity CLI. Чесним способом їх порівняння є створення одного агента тричі та спостереження за змінами: хто керує циклом роботи агента, як підключаються інструменти та які моделі працюють. Кожна версія також завантажується до Cloud Run.
Тестовий агент
Кожна версія відповідає на один тип запитання, а саме на думку громадськості щодо певної теми, як вона відображається на Hacker News. Вона читає дані з bigquery-public-data.hacker_news.full — публічного набору даних, який охоплює 49 мільйонів статей та коментарів та відстає від реального часу приблизно на день. Усі три версії потребують однакового набору функцій: можливості писати SQL-запити зі звичайних запитань, виконувати їх та узагальнювати отримані результати.
BigQuery підключається по-різному кожного разу. API Interactions використовує вручну написану функцію, ADK — власний набір інструментів, а Antigravity SDK — MCP.
Облікові дані
Є два типи облікових даних:
export GOOGLE_API_KEY="..." # get this at aistudio.google.com
gcloud auth application-default login
Існують два типи облікових даних, оскільки API Interactions у цій конфігурації базується на API Gemini, яке вимагає ключа, тоді як ADK та Antigravity SDK звертаються безпосередньо до проєкту в хмарі та зовсім не використовують ключі.
Якщо придивитися уважніше до API Interactions: воно приймає або параметр model= — звичайну модель, або параметр agent= — агента, якого хостує Google, а чий цикл та доступні інструменти працюють на цій платформі. Інструмент у цій версії — це локальна функція на Python, що виключає можливість використання агента, який знаходиться на сервері, тому використовується параметр model=, а цикл інструменту залишається у локальному коді. Корпоративна платформа Google (раніше Vertex AI) має власну експериментальну версію цього API, але тестування її з кількома моделями призводило до відхилення кожного запиту з параметром model=.
Безкоштовний тариф BigQuery з обсягом 1 ТБ запитів на місяць легко вміщує демонстраційні запити, обсяг яких становить приблизно від 1 до 17 ГБ. Версії, які використовувалися під час тестування, були google-genai 2.17.0, google-adk 2.6.2 та google-antigravity 0.1.10, з моделлю gemini-3.6-flash.
Перший шлях: Interactions API
Встановіть пакети за допомогою pip install google-genai google-cloud-bigquery. Інструмент є звичайною функцією довжиною близько десяти рядків:
def execute_sql(query: str) -> list[dict]:
client = bigquery.Client()
config = bigquery.QueryJobConfig(maximum_bytes_billed=20 * 10**9)
rows = client.query_and_wait(query, job_config=config, max_results=50)
return [{k: str(v) for k, v in dict(row).items()} for row in rows]
Він виконує будь-який SQL-запит, створений моделлю, та повертає до 50 рядків у вигляді звичайних словників. Параметр maximum_bytes_billed обмежує обсяг сканування одного запиту до 20 ГБ, тому ніщо не стає занадто дорогим. Жодної явної обробки облікових даних не потрібно, оскільки bigquery.Client() автоматично використовує локальний вхід gcloud, а у Cloud Run ця сама функція тихо використовує обліковий запис сервісу.
Модель ніколи не бачить тіла функції, лише те, що там оголошено, тому саме оголошення містить схему даних:
execute_sql_tool = {
"type": "function",
"name": "execute_sql",
"description": (
"Run a BigQuery Standard SQL SELECT query against "
"`bigquery-public-data.hacker_news.full`, the public Hacker News "
"dataset (stories and comments since 2006). Columns: id INT, "
"type STRING (story/comment/job/poll), title STRING (stories only), "
"text STRING (body, HTML-escaped), `by` STRING (username), score INT, "
"parent INT, descendants INT, timestamp TIMESTAMP, url STRING, "
"dead BOOL, deleted BOOL. Returns at most 50 rows."
),
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
}
Блок parameters залишається невеликим: один обов’язковий рядок із SQL-запитом. Опис має більше значення, адже це єдиний шлях, через який модель дізнається назву таблиці та її стовпці. Більш точні формулювання тут призводять до кращих запитів.
Решта — це цикл інструменту, приблизно з десяток рядків:
while True:
calls = [s for s in interaction.steps if s.type == "function_call"]
if not calls:
break
results = [{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": [{"type": "text", "text": json.dumps(execute_sql(**step.arguments))}],
} for step in calls]
interaction = client.interactions.create(
model=MODEL,
input=results,
system_instruction=INSTRUCTION,
tools=[execute_sql_tool],
previous_interaction_id=interaction.id,
)
Один цикл виконує кожен крок function_call, який генерує модель, передає отримані результати як наступний вхід та продовжує цей процес, поки у відповіді не залишиться жодних викликів. Одна деталь є особливо важливою: історія операцій ніколи не надсилається знову. Сервер зберігає її, а previous_interaction_id просто посилається на попередній крок, що дозволяє зберігати розмір кожного запиту мінімальним. Об’єкт client є вхідним портом SDK до API Gemini, і його створення без аргументів дозволяє отримати значення GOOGLE_API_KEY з середовища. Після розгортання на Cloud Run це саме значення підключається як змінна середовища з Secret Manager. Усе інше, включаючи вибір SQL-запитів та момент зупинки, визначається самою моделлю.
Наразі MCP тут не є доступним варіантом. У документації до API Interactions це вказано як обмеження: Gemini 3 не підтримує віддалений MCP, але ця функція має з’явитися незабаром.
Висновок: найбільше коду, найменше залежностей та повний контроль.
Другий варіант: ADK
Встановіть за допомогою pip install google-adk google-cloud-dataplex google-cloud-bigquery.
import google.auth
from google.adk import Agent
from google.adk.integrations.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.integrations.bigquery.config import BigQueryToolConfig, WriteMode
credentials, _ = google.auth.default()
toolset = BigQueryToolset(
credentials_config=BigQueryCredentialsConfig(credentials=credentials),
bigquery_tool_config=BigQueryToolConfig(write_mode=WriteMode.BLOCKED),
)
root_agent = Agent(name="hn_opinion_agent", model=..., instruction=..., tools=[toolset])
ADK постачає готову інтеграцію з BigQuery під назвою BigQueryToolset. Окрім функції execute_sql вона надає допоміжні засоби для роботи з метаданими, такі як get_table_info, які дозволяють агенту читати саму схему, а не отримувати її у вигляді запиту. Одне налаштування, WriteMode.BLOCKED, робить усе лише для читання.
Жоден API-ключ не з’являється ніде. Набір інструментів BigQuery вимагає явного об’єкта облікових даних, який google.auth.default() повертає після логіну через gcloud, разом із ідентифікатором проєкту, який ця версія проігноровує. З боку моделі роботу виконує одна змінна: GOOGLE_GENAI_USE_ENTERPRISE=TRUE направляє трафік до моделі через обліковий рахунок Cloud. Після цього, у середовищі Cloud Run, як запити, так і запити до моделі виконуються під ім’ям облікового запису сервісу.
Ця платформа виконує цикл та зберігає сесії, включаючи історію розмови між кроками, у пам’яті та в базі даних у разі необхідності постійного зберігання.
Висновок: мінімальний код та максимальні можливості, оскільки готові інструменти дозволяють агенту самостійно працювати з даними.
Третій варіант: Antigravity SDK
Встановіть його за допомогою pip install google-antigravity.
from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.types import McpStreamableHttpServer
bigquery_mcp = McpStreamableHttpServer(
name="bigquery",
type="http",
url="https://bigquery.googleapis.com/mcp",
headers={"Authorization": f"Bearer {token}",
"x-goog-user-project": project},
enabled_tools=["execute_sql_readonly", "get_table_info", ...],
)
config = LocalAgentConfig(system_instructions=..., mcp_servers=[bigquery_mcp])
async with Agent(config) as agent:
response = await agent.chat(question)
Кріпленню надається системна інструкція та один сервер MCP, і один виклик agent.chat() охоплює планування, використання інструментів та підсумковий звіт. Під цим знаходиться цикл, який керує Antigravity CLI разом із його інструментами для роботи з файлами та оболонкою.
До BigQuery можна отримати доступ через MCP за адресою bigquery.googleapis.com/mcp — це керований кінцевий пункт від Google, який приймає лише токени автентифікації типу OAuth (отримані за допомогою команди gcloud auth print-access-token). Список enabled_tools виступає у ролі списку дозволених інструментів MCP, які агент може використовувати. На цьому кінцевому пункті існують функції execute_sql та execute_sql_readonly, і саме активація лише другої запобігає можливості агента записувати дані. Автентифікація моделі відповідає стандарту ADK, використовуючи обліковий запис у лептопі та сервісний обліковий запис у Cloud Run.
Перед вибором цього рішення існують два моменти, які потрібно врахувати:
- Моделі обмежені Gemini. Antigravity IDE також пропонує Claude та GPT-OSS, яких бракує у SDK, хоча їх може замінити локальний сервер, сумісний з OpenAI, наприклад Ollama.
- ID проекту має бути вказаний у інструкціях системи. Кожен інструмент на хостованому кінцевому пункті вимагає аргумента
projectId, який вказує на проект у хмарі, що виконує запит, а модель заповнює його під час виклику інструменту.
Висновок: зручний спосіб отримати агента, який також може редагувати файли та виконувати команди шелу.
Розгортання у Cloud Run
Усі три варіанти можна розгорнути у Cloud Run. Різниця полягає у кількості коду, який потрібно написати для сервісу.
- API взаємодії: достатньо невеликого обгортка FastAPI навколо цього циклу. Оскільки сервер зберігає хід розмови, сам сервіс не зберігає жодного стану, а викликаючі програми повертають лише
previous_interaction_id. Проблема полягає у тому, що цей API все ще не може автентифікуватися як обліковий запис сервісу, тож це єдиний сервіс, який потребує API-ключа, який отримується з Secret Manager.
adk api_server запускає його локально, а adk deploy cloud_run створює сервер, контейнер та конфігурацію розгортання. Слідкуйте за двома важливими моментами. По-перше, додаткові пакети набору інструментів (bigquery та dataplex) потрібно вказати у файлі requirements.txt у самій папці агента. По-друге, змінні середовища не передаються під час розгортання, тому GOOGLE_GENAI_USE_ENTERPRISE необхідно додати до сервісу пізніше. Існує повністю керований варіант — Agent Runtime — для тих, хто не хоче піклуватися про обслуговування сервісу.agent.chat() та запакуйте його у вигляді зображення контейнера. Одна зміна стосується лише часу обслуговування: заголовок автентифікації MCP більше не може походити від входу gcloud у ноутбуці, тому токен потрібно створювати та оновлювати з облікового запису сервісу.Обмеження доступу не вимагає багато зусиль. Використання параметра --no-allow-unauthenticated дозволяє обмежити доступ лише тим користувачам, які мають відповідні права IAM. Для тестового виклику можна використати токен ідентичності за допомогою команди curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" або запустити команду gcloud run services proxy; у браузерах також слід додати механізм IAP.
Налаштування ідентичностей майже не коштує грошей. Сервіс Cloud Run завжди працює під певною ідентичністю, і якщо не вказано інше, це буде стандартний обчислювальний обліковий запис проєкту. Одна ідентичність керувала роботою BigQuery для усіх трьох сервісів, а також для викликів моделей у ADK та Antigravity. Єдиним ручним кроком було надання прав на читання секретного ключа API для сервісу Interactions — ролі roles/secretmanager.secretAccessor, яка була прив’язана до самого секрету.
Проте не копіюйте це сліпо. Стандартний обліковий запис має широкі права та часто має роль редактора на рівні проекту. Для будь-чого, що виходить за межі демо-версії, потрібен окремий обліковий запис для кожного сервісу, обмежений необхідними ролями, які вказуються під час розгортання за допомогою --service-account.
Який вибрати
ADK на Cloud Run є розумною відправною точкою для більшості завдань. Він пропонує повний набір інструментів та підтримку MCP, просте керування сеансами та історією, а також свободу вибору будь-якої моделі, а не лише Gemini та Gemma. API Interactions пояснює, як насправді працюють агенти, оскільки логіка їхньої роботи є відкритою. SDK Antigravity найкраще підходить, коли агенту потрібно редагувати файли та виконувати команди оболонки.
Пов’язана література
- Gemini Spark: пояснення, завдання, навички, графіки, безпека та ціни — що робить цей постійно активний агент Gemini Spark від Google у Gmail, Календарі та Docs, як працюють його механізми безпеки, скільки він коштує, де його блокують та хто повинен його використовувати.
- Агентське інжиніринг та концепція Outer Loop: місце розташування Antigravity та Agents CLI — специфікації, методи оцінки та правила безпеки визначають принципи агентського інжинірингу. Розгляд інструменту Agents CLI від Google, його рівня використання в GCP та відмінностей Antigravity від інших інструментів для програмування.