Адны агент, тры способы стварэння: 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.
Першы спосаб: API Interactions
З’явіце пакеты за дапамою 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, а таксама ID праекта, які гэты варыянт працы не выкарыстоўвае. З боку модэлю ўсю працу выканае адна зменная: 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 так і не можа аўтэнтыфікацыявацца як аднацоўгі кантакт, таму ён едыні служба, якой патрэбна кантактная канфігурацыя, якая выдаецца з Secret Manager.
adk api_server запускае яго локальна, а adk deploy cloud_run стварае сервер, кантэйнер і настройкі пры запуску. Зважайце на два важлівыя моменты. Першы — дадатковыя пакеты набора інструментаў (bigquery і dataplex) павінны быць пераказаныя ў файле requirements.txt, які знаходзіцца ў папцы агента. Другі — зменныя сераўіса не пераходзяць пад час запуску, таму GOOGLE_GENAI_USE_ENTERPRISE павінен быць даданы пасля таго ў самы сераўіс. Існуе варыянт абсалютнага керавання — Agent Runtime, які падходзіць тым, хто не хоча кераваць жадным сераўісам.agent.chat() і запакаваце яго як адпаведны образ кантэйнера. Адна змена стосуецца толькі часу аддачы: заголовак MCP Authorization больш не можа выйшаць з працэса глыбокага запуску 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 адрозніцца ад іншых інструментаў для програмавання.