Ein Agent, drei Implementierungen: Interactions API gegen ADK gegen Antigravity SDK
Derselbe Gemini-Agent wurde auf drei Arten erstellt – mit der Interactions-API, Google ADK und dem Antigravity SDK – und im Hinblick auf Schleifen, Tools, Authentifizierung sowie Cloud-Run-Deployment verglichen.
Quellen: I built the same agent three ways: Interactions API, ADK, and the Antigravity SDK
Googles Technologiestack bietet mittlerweile drei völlig unterschiedliche Wege zu einem funktionsfähigen Agenten: die Interactions API, die die Oberfläche der Gemini API für Agenten darstellt, ADK, ein vollständiges Framework, sowie das Antigravity SDK, das die Grundlage für die Antigravity CLI bildet. Eine angemessene Methode, sie miteinander zu vergleichen, besteht darin, jeweils einen Agenten dreimal zu erstellen und zu beobachten, was sich ändert: Wer kontrolliert den Agenten-Loop, wie werden Tools angebunden und welche Modelle funktionieren. Jede Erstellung wird außerdem auf Cloud Run bereitgestellt.
Der Testagent
Jede Konfiguration beantwortet eine bestimmte Art von Frage, nämlich die öffentliche Meinung zu einem Thema, wie sie auf Hacker News zu finden ist. Sie liest aus bigquery-public-data.hacker_news.full – einem öffentlichen Datensatz mit 49 Millionen Beiträgen und Kommentaren – dessen Aktualisierungen etwa einen Tag hinter dem Echtzeitzustand zurückbleiben. Alle drei Versionen benötigen dasselbe Set an Fähigkeiten: SQL aus einer einfachen Frage schreiben, diese ausführen und die zurückkehrenden Meinungen zusammenfassen.
BigQuery wird jedes Mal auf unterschiedliche Weise integriert. Die Interactions API erhält eine manuell geschriebene Funktion, ADK nutzt sein eigenes Toolset, während das Antigravity SDK MCP verwendet.
Authentifizierungsdaten
Es sind zwei Arten von Authentifizierungsdaten erforderlich:
export GOOGLE_API_KEY="..." # get this at aistudio.google.com
gcloud auth application-default login
Es existieren zwei Anmeldeinformationen, weil die Interactions API in dieser Konfiguration auf der Gemini API basiert, die einen Schlüssel erfordert, während ADK und das Antigravity SDK direkt auf das Cloud-Projekt zugreifen und Schlüssel völlig überspringen.
Ein genauerer Blick auf die Interactions API: Sie akzeptiert entweder model=, ein einfaches Modell, oder agent=, einen von Google gehosteten Agenten, dessen Schleifen und verfügbare Tools auf der Plattform laufen. Das Tool in dieser Version ist eine lokale Python-Funktion, was einen gehosteten Agenten ausschließt; daher wird model= verwendet und die Tool-Schleife bleibt im lokalen Code. Googles Unternehmensplattform (früher Vertex AI) verfügt über ihre eigene experimentelle Variante der API, doch Tests mit mehreren Modellen führten bei jeder model=-Aufruf zu Ablehnungen.
Die kostenlose Stufe von BigQuery mit 1 TB an Abfragen pro Monat reicht problemlos aus, um die Demo-Abfragen zu bewältigen, die etwa 1 bis 17 GB an Daten verarbeiten. Zu Testzeit standen die Versionen google-genai 2.17.0, google-adk 2.6.2 und google-antigravity 0.1.10 zur Verfügung, wobei das Modell gemini-3.6-flash verwendet wurde.
Route eins: Die Interactions API
Installieren Sie die Pakete mit pip install google-genai google-cloud-bigquery. Das Tool besteht aus einer gewöhnlichen Funktion mit etwa zehn Zeilen:
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]
Es führt jeden SQL-Befehl aus, den das Modell erzeugt, und gibt bis zu 50 Zeilen als einfache Wörterbücher zurück. maximum_bytes_billed begrenzt eine Abfrage auf 20 GB Scannvolumen, sodass nichts teuer wird. Es kommt zu keiner expliziten Handhabung von Anmeldeinformationen, da bigquery.Client() den lokalen gcloud-Anmeldedaten verwendet, und auf Cloud Run nutzt dieselbe Funktion stillschweigend das Servicekonto.
Das Modell sieht niemals den Funktionskörper, nur das, was deklariert ist, wodurch die Deklaration das Schema enthält:
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"],
},
}
Der parameters-Block bleibt klein: ein erforderlicher String, der die SQL-Anfrage enthält. Die Beschreibung ist wichtiger, denn sie ist der einzige Weg, über den das Modell den Tabellennamen sowie seine Spalten lernt. Präzisere Formulierungen führen zu besseren Abfragen.
Übrig bleibt der Tool-Loop, bestehend aus etwa einem Dutzend Zeilen:
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,
)
Eine Runde führt jeden function_call-Schritt aus, den das Modell ausgibt, übermittelt die Ergebnisse als nächste Eingabe und wiederholt diesen Vorgang, bis in der Antwort keine Aufrufe mehr vorhanden sind. Ein wichtiger Punkt ist: Die Historie wird niemals erneut gesendet. Der Server speichert sie, und previous_interaction_id verweist einfach auf den vorherigen Schritt, wodurch jede Anfrage klein bleibt. Das client-Objekt ist der Eingangspunkt des SDK zur Gemini-API; seine Erstellung ohne Argumente lädt GOOGLE_API_KEY aus der Umgebungslaufzeitvariable. Wenn es auf Cloud Run bereitgestellt wird, wird derselbe Wert als Umgebungsvariable über Secret Manager bereitgestellt. Alles Weitere, einschließlich der Auswahl des zu ausführenden SQL-Abfragen und des Zeitpunkts zum Beenden, wird vom Modell gesteuert.
MCP ist hier derzeit noch keine Option. In den Dokumentationen zur Interactions-API wird es als Einschränkung aufgeführt, wobei angegeben wird, dass Gemini 3 kein entferntes MCP unterstützt und dass diese Funktion bald verfügbar sein wird.
Urteil: Am meisten Code, am wenigsten Abhängigkeiten und vollständige Kontrolle.
Route zwei: ADK
Installieren Sie es mit 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 enthält eine fertig erstellte Integration mit BigQuery namens BigQueryToolset. Neben execute_sql stellt es Metadaten-Hilfsfunktionen wie get_table_info bereit, die es dem Agenten ermöglichen, das Schema selbst zu lesen, anstatt es in einer Anfrage zu erhalten. Eine Einstellung namens WriteMode.BLOCKED stellt alles auf Leseschutz um.
Es erscheint nirgends eine API-Schlüssel. Das BigQuery-Toolset verlangt ein explizites Credentials-Objekt, das google.auth.default() über den lokalen gcloud-Anmeldungsprozess zusammen mit einer Projekt-ID zurückgibt, die in dieser Version ignoriert wird. Auf der Modellseite übernimmt eine einzige Variable die Funktion: GOOGLE_GENAI_USE_ENTERPRISE=TRUE leitet den Modellverkehr über das Cloud-Konto. Sobald alles auf Cloud Run läuft, werden sowohl die Abfragen als auch die Modellanfragen unter dem Service-Konto durchgeführt.
Das Framework führt die Schleife aus und speichert Sessions, einschließlich der Konversationsgeschichte über mehrere Nachrichtenaustausche, hier im Speicher sowie in einer Datenbank, wenn eine dauerhafte Speicherung erforderlich ist.
Fazit: Minimale Codemenge bei maximaler Funktionalität, da die vorgefertigten Tools es dem Agenten ermöglichen, ohne Hilfsmittel in den Daten herumzusuchen.
Route drei: das Antigravity SDK
Installieren Sie es mit 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)
Dem Harness wird eine Systemanweisung sowie ein MCP-Server zugewiesen, und ein einziger Aufruf von agent.chat() umfasst die Planung, die Nutzung von Werkzeugen sowie die abschließende Zusammenfassung. Darunter befindet sich der Loop, der die Antigravity CLI antreibt, inklusive ihrer Datei- und Shell-Werkzeuge.
Zu BigQuery wird über MCP über bigquery.googleapis.com/mcp Zugang hergestellt – ein von Google betriebener, verwalteter Endpunkt, der nur OAuth akzeptiert (über gcloud auth print-access-token). Die Liste enabled_tools dient als Allowlist der MCP-Werkzeuge, die der Agent aufrufen darf. Sowohl execute_sql als auch execute_sql_readonly sind am Endpunkt verfügbar, und durch die Aktivierung nur des zweiten wird verhindert, dass dieser Agent schreibt. Die Modellauthentifizierung entspricht ADK und verwendet das Cloud-Konto auf einem Laptop sowie das Service-Konto auf Cloud Run.
Vor der Auswahl gelten zwei Einschränkungen:
- Die verfügbaren Modelle sind auf Gemini beschränkt. Die Antigravity IDE bietet außerdem Claude und GPT-OSS an, die im SDK fehlen, obwohl ein lokaler, mit OpenAI kompatibler Server wie Ollama als Ersatz dienen kann.
- Die Projekt-ID gehört zu den Systemanweisungen. Jedes Tool am gehosteten Endpunkt benötigt ein
projectId-Argument, mit dem das Cloud-Projekt benannt wird, das die Abfrage ausführt, und das Modell füllt diesen Wert bei der Aufrufung des Tools aus.
Fazit: ein praktischer Weg zu einem Agenten, der auch Dateien bearbeiten und Shell-Befehle ausführen kann.
Deployment auf Cloud Run
Alle drei Lösungen lassen sich auf Cloud Run deployen. Der Unterschied liegt darin, wie viel des Services selbst geschrieben werden muss.
- Interaktions-API: Ein kleiner FastAPI-Wrapper um den Loop reicht aus. Da der Server das Gespräch speichert, behält der Service selbst keinen Zustand, und die Aufrufer geben lediglich
previous_interaction_idzurück. Das Problem: Diese API kann sich weiterhin nicht als Service-Konto authentifizieren, wodurch sie der einzige Service ist, der eine API-Schlüssel benötigt, der aus dem Secret Manager stammt. - ADK: Auf der Serverseite gibt es nichts zu konfigurieren.
adk api_serverführt die Funktion lokal aus, währendadk deploy cloud_runden Server, den Container sowie die Bereitstellungskonfiguration erstellt. Achten Sie auf zwei wichtige Punkte: Erstens müssen die zusätzlichen Pakete des Toolsets (bigquery und dataplex) in den eigenen requirements.txt-Datei im Agentenordner aufgeführt werden. Zweitens werden Umgebungsvariablen bei der Bereitstellung nicht übertragen, weshalbGOOGLE_GENAI_USE_ENTERPRISEanschließend dem Service hinzugefügt werden muss. Für alle, die keinen eigenen Service warten möchten, gibt es die voll verwaltete Option Agent Runtime. - Antigravity SDK: Umfassen Sie
agent.chat()manuell und packen Sie es als Containerbild zusammen. Eine Änderung gilt nur beim Bereitstellen: Der MCP Authorization-Header kann nicht mehr aus dem gcloud-Login eines Laptops stammen, sodass der Token aus dem Servicekonto erstellt und erneuert werden muss.
Der Zugriff einzuschränken erfordert nur wenig Aufwand. Durch die Verwendung von --no-allow-unauthenticated werden nur Anrufende mit IAM-Rechten zugelassen. Für einen Testanruf kann ein Identitäts-Token mit curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" verwendet werden oder gcloud run services proxy gestartet werden; bei Browsern sollte zusätzlich IAP hinzugefügt werden.
Die Einrichtung der Identitäten war nahezu kostenlos. Ein Cloud Run-Dienst läuft stets unter einer bestimmten Identität – sofern nicht anders angegeben, handelt es sich dabei um das Standard-Computing-Service-Konto des Projekts. Eine einzige Identität kümmerte sich um BigQuery für alle drei Dienste sowie um die Modellaufrufe in ADK und Antigravity. Die einzige manuelle Berechtigung war das Lesen des API-Schlüssels für den Interactions-Dienst, nämlich roles/secretmanager.secretAccessor, das direkt dem Schlüssel selbst zugeordnet wurde.
Kopieren Sie das jedoch nicht blindlings. Das Standardkonto verfügt über umfangreiche Berechtigungen und hat oft die Rolle des Editors auf Projektebene. Für Anwendungen über das Demo-Niveau ist ein spezielles Servicekonto pro Service erforderlich, das auf die beim Bereitstellen über --service-account angegebenen und benötigten Rollen beschränkt ist.
Welches wählen?
ADK auf Cloud Run ist ein sinnvoller Ausgangspunkt für die meisten Aufgaben. Es bietet ein vollständiges Werkzeugset sowie MCP-Unterstützung, einfache Handhabung von Sitzungen und Historie sowie die Freiheit, beliebige Modelle auszuwählen – nicht nur Gemini und Gemma. Die Interactions API zeigt, wie Agenten tatsächlich arbeiten, da der Ablauf vollständig sichtbar ist. Das Antigravity SDK eignet sich am besten, wenn ein Agent Dateien bearbeiten und Shell-Befehle ausführen muss.
Weitere Literatur
- Gemini Spark erklärt: Aufgaben, Fähigkeiten, Zeitpläne, Sicherheit und Preis — Was das ständig verfügbare Gemini Spark-Agent von Google in Gmail, Kalender und Docs leistet, wie seine Sicherheitsschichten funktionieren, wie viel es kostet, wo es blockiert ist und wer es nutzen sollte.
- Agentic Engineering und der Outer Loop: Wo Antigravity und Agents CLI passen — Spezifikationen, Bewertungen und Sicherheitsmaßnahmen definieren das Agentic Engineering. Ein Überblick über Google’s Agents CLI, seine GCP-Produktionsumgebung sowie die Unterschiede von Antigravity zu anderen Programmierwerkzeugen.