SDK Antigravity : définition, installation et premier agent

Qu'est-ce que le SDK Antigravity ?

Un SDK permet à une application d'appeler une capacité produit de façon maintenue. Le SDK Antigravity sert à définir un agent, connecter des outils approuvés et récupérer un résultat depuis Python. Il convient aux assistants internes, tests et workflows répétables.

La distinction essentielle est le propriétaire du workflow : l'IDE sert au travail interactif, la CLI aux commandes de terminal et le SDK à l'application qui orchestre le processus. Ils se complètent sans partager une version ou configuration universelle.

Installer le SDK Antigravity pour Python

Commencez par la page officielle de démarrage du SDK et les métadonnées PyPI actuelles. Vérifiez Python, les extras, l'authentification et les imports au lieu de copier un ancien exemple. Utilisez un environnement et un projet jetables, gardez les secrets hors de Git et commencez par une requête réversible.

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate   # macOS or Linux
python -m pip install --upgrade pip
python -m pip install google-antigravity

1. Créer un environnement isoléUtilisez un environnement virtuel local pour faciliter la résolution et le retour arrière.
2. Installer depuis la source maintenueSuivez les instructions officielles, y compris les extras et l'authentification actuels.
3. Figer après un test réussiLancez l'exemple minimal et notez la version et le runtime validés.
4. Ne pas committer la configurationUtilisez des variables d'environnement ou un gestionnaire de secrets.
5. Lire les notes avant une mise à jourL'API du SDK peut évoluer indépendamment du bureau, de la CLI ou de l'IDE.

Confirmez les prérequis Python et les instructions actuelles avant la production.

Créer un premier agent simple

Un bon premier agent possède une seule mission, une instruction claire et un résultat vérifiable manuellement. Demandez-lui de résumer une courte note de version ou de classer un fixture local. N'ajoutez pas en même temps navigateur, shell, base de données et écriture : un échec deviendrait difficile à isoler.

Les noms de classes et propriétés de réponse dépendent de la version actuelle du SDK. L'exemple montre la forme du quickstart : configurer, envoyer une requête, inspecter le résultat et respecter le cycle de vie documenté. Considérez-le comme un support d'apprentissage, pas comme une garantie d'API permanente.

from google.antigravity import Agent, AgentConfig

config = AgentConfig(
    instructions="Summarize the supplied release note in three bullets."
)
agent = Agent(config=config)
result = agent.run("Release note: the test suite now reports flaky browser checks.")
print(result)

• Entrée — Utilisez un fixture court avec une réponse attendue.
• Résultat — Inspectez le résultat avant d'ajouter l'automatisation.
• Cycle de vie — Suivez le cycle de vie et les reprises documentés.
• Reproductibilité — Conservez le prompt, la version, les réglages et le résultat.

Ajouter les outils un par un

Les outils relient le raisonnement de l'agent à une action externe. Un outil peut lire un fichier, interroger un service limité, calculer une valeur ou appeler une opération de dépôt. Choisissez l'action minimale qui apporte une vraie utilité, définissez un contrat d'entrée court, validez les arguments et retournez un résultat borné. Journalisez les identifiants non sensibles et le résultat ; n'exposez pas le dossier personnel et n'accordez pas l'écriture quand la lecture suffit.

Utiliser des sous-agents pour des rôles séparés

Un sous-agent est utile quand une tâche possède un rôle distinct : planification, recherche, validation ou mise en forme. Donnez à chaque rôle une frontière d'entrée et de sortie claire ; le planificateur ne doit pas hériter des identifiants du validateur.

Commencez en séquence pour inspecter chaque transfert. Ajoutez parallélisme, délais et reprises lorsque les frontières sont stables, en laissant les échecs partiels visibles.

Retourner une sortie structurée vérifiable

Le texte libre est pratique pour une personne, mais fragile pour la logique. Si le résultat alimente une base, une interface, un test ou un agent, utilisez la sortie structurée actuelle du SDK avec un petit schéma et validez-le localement.

Un schéma ne rend pas la réponse vraie : vérifiez types, valeurs autorisées et champs obligatoires. Séparez les diagnostics de la sortie utilisateur.

result = agent.run("Classify the fixture.")
validated = {
    "label": result.label,
    "confidence": float(result.confidence),
    "needs_review": bool(result.needs_review),
}
assert validated["label"] in {"pass", "review", "fail"}

• Validez l'objet retourné dans votre application.
• Utilisez des enums et des chaînes bornées pour les choix finis.
• Traitez les champs manquants ou mal formés comme un échec visible.
• Séparez les diagnostics de la sortie utilisateur.

SDK, IDE ou CLI : choisir la bonne surface

Le SDK intègre un workflow d'agent dans le code, l'IDE sert aux projets interactifs et la CLI aux commandes et scripts. Choisissez la surface propriétaire du travail, pas trois boutons pour le même workflow.

Leurs versions peuvent évoluer à des dates différentes. Notez la source et la date du composant utilisé.

Contrôles de sécurité et de fiabilité

Un SDK peut intégrer un agent à une application réelle. Examinez l'origine du paquet, les identifiants, les destinations réseau, les chemins, les arguments et les journaux. Commencez avec un projet jetable et un compte de test si des données externes sont touchées.

Gardez l'approbation visible pour modifier des fichiers, envoyer des messages, dépenser, changer un compte ou publier. Ajoutez des délais et reprises bornées, et distinguez entrée invalide, service indisponible, permission refusée et relecture humaine.

• Identifiants — Utilisez un gestionnaire de secrets ; ne commitez jamais de token.
• Chemins — Autorisez les seuls dossiers du projet nécessaires, jamais la racine du disque.
• Actions — Séparez lecture, écriture, shell, navigateur et réseau.
• Observabilité — Notez identifiants, durée, résultat et catégories d'erreur sûres.
• Récupération — Documentez désactivation, révocation, fixture et retour arrière.

Dépannage courant du SDK Antigravity

En cas d'échec initial, réduisez le système à une variable à la fois.

Le paquet s'installe mais l'import échoue

Vérifiez environnement et interpréteur, puis comparez l'import au quickstart actuel. Consultez les métadonnées avant de modifier le code.

L'agent renvoie une erreur d'autorisation

Comparez identifiants, portée et permissions avec la documentation. Retirez les secrets des journaux et retentez la requête minimale.

Un outil se bloque ou se répète

Ajoutez un délai, journalisez la frontière et testez avec une entrée fixe. Limitez les reprises et ne répétez pas une écriture inconnue.

La sortie structurée est incomplète

Réduisez le schéma et validez localement les champs obligatoires. Traitez refus, troncature et données mal formées comme une relecture.

Référence de version et règle de source

Le 12 septembre 2026, PyPI indiquait google-antigravity v0.1.16. Les listes officielles indiquaient bureau v2.13.0, CLI v1.2.0 et IDE v2.5.5 ; ces surfaces évoluent séparément.

Utilisez les pages officielles et notez la version installée. La page officielle de téléchargement reste le fallback pour bureau et CLI.