Один агент, три реализации: 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 подключается по-разному в каждом случае: Interactions API использует вручную написанную функцию, 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 является входом в API Gemini через SDK; его создание без аргументов позволяет получить значение 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 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.
- Идентификатор проекта указывается в системных инструкциях. Каждый инструмент на хостинговом конце требует аргумента
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 Explained: Tasks, Skills, Schedules, Security and Pricing — Чем занимается круглосуточный агент Gemini Spark от Google в Gmail, Calendar и Docs, как работают механизмы безопасности, сколько он стоит, где он заблокирован и кому стоит им воспользоваться.
- Agentic Engineering and the Outer Loop: Where Antigravity and Agents CLI Fit — Технические характеристики, методы оценки и правила использования определяют принципы агентного инжиниринга. Рассмотрение инструмента Agents CLI от Google, его производственного слоя в GCP и того, чем Antigravity отличается от других инструментов для программирования.