Un agent, trois versions : API Interactions contre ADK contre SDK Antigravity
Le même agent Gemini a développé trois méthodes, utilisant l’API Interactions, Google ADK et le SDK Antigravity, qui ont été comparées en ce qui concerne les boucles de traitement, les outils, l’authentification et les déploiements via Cloud Run.
Sources: I built the same agent three ways: Interactions API, ADK, and the Antigravity SDK
La plateforme de Google propose aujourd’hui trois approches très différentes pour créer un agent fonctionnel : l’Interactions API, qui constitue l’interface correspondant à l’époque des agents dans la Gemini API, ADK, un framework complet, et le Antigravity SDK, le moteur sous-jacent à l’Antigravity CLI. Une façon équitable de les comparer consiste à créer un agent trois fois afin de voir quels changements surviennent : qui gère la boucle d’exécution de l’agent, comment les outils sont intégrés et quels modèles fonctionnent. Chaque version ainsi créée est également déployée sur Cloud Run.
L’agent de test
Chaque génération répond à un type de question, à savoir l’opinion publique sur un sujet telle qu’elle apparaît sur Hacker News. Elle se base sur bigquery-public-data.hacker_news.full, un ensemble de données publics couvrant 49 millions d’articles et de commentaires, avec un retard d’environ un jour par rapport au temps réel. Les trois versions nécessitent les mêmes compétences : écrire du SQL à partir d’une question simple, l’exécuter et synthétiser les opinions qui en résultent.
BigQuery est intégré différemment à chaque fois. L’API Interactions utilise une fonction écrite manuellement, ADK dispose de son propre ensemble d’outils, tandis que le SDK Antigravity emploie MCP.
Credenciaux
Deux types de credenciaux sont requis :
export GOOGLE_API_KEY="..." # get this at aistudio.google.com
gcloud auth application-default login
Deux identifiants existent car l’API Interactions dans cette configuration repose sur l’API Gemini, qui exige une clé, tandis qu’ADK et le SDK Antigravity s’adressent directement au projet Cloud et évitent complètement les clés.
Un examen plus approfondi de l’API Interactions montre qu’elle accepte soit model=, un modèle simple, soit agent=, un agent hébergé par Google dont les boucles et les outils accessibles s’exécutent sur la plateforme. L’outil utilisé dans cette version est une fonction Python locale, ce qui exclut l’utilisation d’un agent hébergé ; il s’agit donc de model= et la boucle d’outil reste dans le code local. La plateforme d’entreprise de Google (anciennement Vertex AI) dispose de sa propre version expérimentale de cette API, mais les tests effectués avec plusieurs modèles ont entraîné le rejet de toutes les requêtes model=.
Le plan gratuit de BigQuery, offrant 1 TB de requêtes par mois, suffit amplement aux requêtes de démonstration, qui consomment entre 1 et 17 GB. Les versions utilisées lors des tests étaient google-genai 2.17.0, google-adk 2.6.2 et google-antigravity 0.1.10, avec le modèle gemini-3.6-flash.
Voie numéro un : l’API Interactions
Installez les paquets avec pip install google-genai google-cloud-bigquery. L’outil se résume à une fonction ordinaire d’environ dix lignes :
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]
Il exécute n’importe quelle requête SQL générée par le modèle et renvoie jusqu’à 50 lignes sous forme de dictionnaires simples. maximum_bytes_billed limite chaque requête à 20 GB de traitement, ce qui évite les coûts excessifs. Aucune gestion explicite des identifiants n’est nécessaire, car bigquery.Client() utilise automatiquement la connexion gcloud locale, et sur Cloud Run, la même fonction utilise discrètement le compte de service.
Le modèle ne voit jamais le corps de la fonction, seulement ce qui y est déclaré, de sorte que la déclaration contient déjà le schéma :
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"],
},
}
Le bloc parameters reste compact : une chaîne obligatoire contenant la requête SQL. La description est plus importante, car c’est le seul canal par lequel le modèle apprend le nom de la table et ses colonnes. Des formulations plus précises y permettent d’obtenir de meilleures requêtes.
Il ne reste plus que la boucle de l’outil, composée d’une douzaine de lignes :
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,
)
Une boucle exécute chaque étape function_call émise par le modèle, soumet les résultats en tant que nouvelle entrée et continue en boucle jusqu’à ce qu’aucune appel ne reste. Un détail se distingue : l’historique n’est jamais renvoyé. Le serveur le stocke, et previous_interaction_id fait simplement référence à l’étape précédente, ce qui permet de garder chaque requête de taille réduite. L’objet client constitue l’interface du SDK vers l’API Gemini ; en le créant sans arguments, la clé GOOGLE_API_KEY est récupérée depuis l’environnement. Une fois déployé sur Cloud Run, cette même valeur est montée en tant que variable d’environnement depuis Secret Manager. Tout le reste, y compris les requêtes SQL à exécuter et le moment d’arrêter, relève des appels effectués par le modèle.
MCP n’est pas encore une option ici. Les documents de l’API Interactions le présentent comme une limitation, indiquant que Gemini 3 ne prend pas en charge MCP à distance et que cette fonctionnalité arrivera bientôt.
Verdict : le plus de code, le moins de dépendances et un contrôle total.
Deuxième solution : ADK
Installez-le avec 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 inclut une intégration prête à l’emploi avec BigQuery appelée BigQueryToolset. En plus de execute_sql, elle met à disposition des outils de métadonnées tels que get_table_info, qui permet à l’agent de lire le schéma directement plutôt que de le recevoir dans une demande. Une configuration, WriteMode.BLOCKED, rend tout en lecture seule.
Aucune clé API n’apparaît nulle part. Le kit d’outils BigQuery exige un objet de crédences explicite, que google.auth.default() renvoie à partir de la connexion locale gcloud, accompagné d’un ID de projet que cette version ignore. Du côté du modèle, une seule variable suffit : GOOGLE_GENAI_USE_ENTERPRISE=TRUE dirige le trafic vers le modèle via le compte Cloud. Une fois sur Cloud Run, les requêtes ainsi que les demandes de modèle sont effectuées au nom du compte de service.
Le framework exécute la boucle et conserve les sessions, y compris l’historique des conversations au fil des échanges, en mémoire ici ainsi que dans une base de données lorsque la persistance est nécessaire.
Verdict : code minimal et capacités maximales, car les outils prédéfinis permettent à l’agent d’explorer les données sans aide extérieure.
Troisième option : le Antigravity SDK
Installez-le avec 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)
Le harnais reçoit une instruction système ainsi qu’un serveur MCP, et une seule appelation de agent.chat() couvre la planification, l’utilisation des outils et le résumé de fin. En dessous se trouve la boucle qui pilote l’Antigravity CLI, incluant ses outils de fichiers et de shell.
BigQuery est accessible via MCP, par l’intermédiaire de bigquery.googleapis.com/mcp, une extrémité gérée par Google qui ne prend que des tokens OAuth (obtenus via gcloud auth print-access-token). La liste enabled_tools sert de liste d’autorisation des outils MCP que l’agent peut appeler. Les fonctions execute_sql et execute_sql_readonly existent toutes deux sur cette extrémité, et ce n’est en activant uniquement la seconde que l’agent ne peut pas écrire. L’authentification des modèles correspond à ADK, en utilisant le compte Cloud sur un ordinateur portable ainsi que le compte de service sur Cloud Run.
Deux précautions s’imposent avant de le choisir :
- Les modèles sont limités à Gemini. L’IDE Antigravity propose également Claude et GPT-OSS, qui manquent dans le SDK, bien qu’un serveur local compatible OpenAI comme Ollama puisse faire l’affaire.
- Le ID du projet doit figurer dans les instructions du système. Chaque outil sur l’endpoint hébergé nécessite un argument
projectIdindiquant le projet Cloud qui exécute la requête, et le modèle le remplit lorsqu’il appelle l’outil.
Verdict : une solution pratique pour disposer d’un agent capable d’éditer des fichiers et d’exécuter des commandes shell.
Déploiement sur Cloud Run
Tous les trois peuvent être déployés sur Cloud Run. Ce qui diffère, c’est la quantité de code à écrire pour le service.
- Interactions API : un petit wrapper FastAPI autour du boucle suffit. Comme le serveur gère la conversation, le service lui-même ne conserve aucun état, et les appels ne renvoient que
previous_interaction_id. Le problème : cette API ne peut toujours pas s’authentifier en tant que compte de service, ce qui en fait le seul service nécessitant une clé API provenant du Secret Manager. - ADK : rien à configurer du côté serveur.
adk api_serverle lance localement, tandis queadk deploy cloud_rungénère le serveur, le conteneur ainsi que la configuration de déploiement. Faites attention à deux points importants. Premièrement, les paquets supplémentaires du kit d’outils (bigquery et dataplex) doivent être listés dans le fichier requirements.txt situé dans le dossier de l’agent. Deuxièmement, les variables d’environnement ne sont pas transmises lors du déploiement, il faut donc ajouterGOOGLE_GENAI_USE_ENTERPRISEau service par la suite. Une option entièrement gérée, Agent Runtime, est disponible pour ceux qui ne souhaitent pas entretenir de service. - Antigravity SDK : il faut envelopper manuellement
agent.chat()et le packager sous forme d’image de conteneur. Une modification s’applique uniquement lors du déploiement : l’en-tête MCP Authorization ne peut plus provenir de la connexion gcloud d’un ordinateur portable, donc le jeton doit être généré et renouvelé depuis le compte de service.
Restreindre l’accès ne demande que peu d’efforts. En utilisant --no-allow-unauthenticated lors du déploiement, on limite les appels aux seuls utilisateurs disposant des permissions IAM. Pour un appel de test, associez un jeton d’identité avec curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" ou lancez gcloud run services proxy ; pour les navigateurs, ajoutez IAP en amont.
La configuration des identités était presque gratuite. Un service Cloud Run s’exécute toujours sous une identité donnée, qui est par défaut le compte de service de calcul du projet, sauf indication contraire. Une seule identité gérait BigQuery pour les trois services ainsi que les appels aux modèles dans ADK et Antigravity. La seule autorisation manuelle accordée était celle de lire le secret de la clé API du service Interactions, roles/secretmanager.secretAccessor, attaché au secret lui-même.
Cependant, ne copiez pas cela aveuglément. Le compte par défaut dispose de permissions généreuses et occupe souvent le rôle d’Éditeur au niveau du projet. Tout usage au-delà d’une démonstration nécessite un compte de service dédié pour chaque service, limité aux rôles requis et fournis au moment du déploiement via --service-account.
Lequel choisir
ADK sur Cloud Run constitue un point de départ judicieux pour la plupart des tâches. Il offre un ensemble d’outils complet ainsi que du support MCP, une gestion simple des sessions et de l’historique, et la liberté de choisir n’importe quel modèle, pas seulement Gemini et Gemma. L’API Interactions montre comment les agents fonctionnent réellement, puisque le cycle est entièrement visible. Le SDK Antigravity convient le mieux lorsque l’agent doit modifier des fichiers et exécuter des commandes en ligne de commande.
Lectures complémentaires
- Gemini Spark expliqué : tâches, compétences, plannings, sécurité et tarifs — Ce que fait l’agent Gemini Spark toujours actif de Google dans Gmail, Calendar et Docs, comment fonctionnent ses couches de sécurité, son coût, les endroits où il est bloqué et qui devrait l’adopter.
- L’ingénierie agente et le Outer Loop : où s’inscrivent Antigravity et Agents CLI — Les spécifications, les évaluations et les règles de contrôle définissent l’ingénierie agente. Une présentation de la CLI Agents de Google, de sa couche de production GCP, et de la manière dont Antigravity diffère des autres outils de codage.