> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Google Antigravity

> Suivez les tours de conversation des agents Google Antigravity dans Agent Lens à des fins d’observabilité et de débogage.

Le [plugin CoreWeave Forge pour Google Antigravity](https://github.com/coreweave/forge-agent-lens-for-google-antigravity) trace les tours de conversation des agents, les appels de modèle, les appels d’outils et les sous-agents. Lorsqu’un tour de conversation se termine, le [Stop hook](https://antigravity.google/docs/hooks) du plugin lit la transcription de la conversation et envoie le tour à Agent Lens sous la forme d’une trace unique. Les tours d’une même conversation Antigravity partagent un ID de conversation, ce qui permet à Agent Lens de les regrouper en une seule conversation.

Ce guide explique comment installer et configurer le plugin, consulter les traces générées et résoudre les problèmes courants.

<Warning>
  Ce plugin envoie les données de session Antigravity à Agent Lens. Ces données peuvent inclure vos prompts, les réponses et le raisonnement du modèle, ainsi que les arguments et les résultats des outils, y compris tout ce qu’un outil affiche.

  Le nettoyage des informations personnelles identifiables (PII) et le masquage des données sensibles ne sont pas implémentés. Le plugin ne supprime ni les secrets ni les données personnelles du contenu capturé. Pour exclure les prompts, les réponses, le raisonnement ainsi que les arguments et les résultats des outils, définissez `FORGE_ANTIGRAVITY_INCLUDE_CONTENT=false`. Les spans contiennent tout de même les noms, les durées et les chemins du Workspace. Voir [Capture du contenu](#content-capture). Si vos exigences de sécurité ou de conformité ne vous permettent pas d’envoyer ces données à Agent Lens, n’installez pas ce plugin.
</Warning>

<h2 id="prerequisites">
  Prérequis
</h2>

Avant d’installer le plugin, vous devez disposer des éléments suivants :

* [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) (`agy`) `1.1.10` ou version ultérieure
* [uv](https://docs.astral.sh/uv/getting-started/installation/), dont la commande `uvx` exécute le hook
* Python 3.10 ou version ultérieure
* Un compte CoreWeave Forge et une [clé API](https://forge.coreweave.com/settings#apikeys)
* Un projet Agent Lens (`[YOUR-TEAM]/[YOUR-PROJECT]`) destiné à recevoir les traces

<h2 id="install-the-plugin">
  Installer le plugin
</h2>

Suivez les étapes ci-dessous pour installer le plugin et envoyer votre première trace à Agent Lens.

<Steps>
  <Step title="Définir votre projet et votre clé API">
    Remplacez `[YOUR-TEAM]/[YOUR-PROJECT]` par votre projet Agent Lens et `[YOUR-API-KEY]` par votre clé API, puis exportez-les :

    ```bash lines theme={"system"}
    export FORGE_TRACE_PROJECT="[YOUR-TEAM]/[YOUR-PROJECT]"
    export WANDB_API_KEY="[YOUR-API-KEY]"
    ```

    Le hook s’exécute dans l’environnement à partir duquel `agy` a été lancé. Définissez `FORGE_TRACE_PROJECT` et la clé API dans le profil de votre shell, ou à l’endroit d’où vous lancez `agy`, et vérifiez que `uvx` figure bien dans ce `PATH`. À la place de `WANDB_API_KEY`, le hook peut aussi lire la clé dans l’entrée de l’hôte Weights & Biases du fichier `~/.netrc`.
  </Step>

  <Step title="Exécuter le programme d’installation">
    ```bash lines theme={"system"}
    uvx forge-agent-lens-for-google-antigravity@latest install
    ```

    Le programme d’installation enregistre le plugin à l’aide de `agy plugin install`, vérifie les paramètres dont le hook a besoin et indique où les traces apparaîtront :

    ```text theme={"system"}
    Installed the Antigravity plugin (forge-agent-lens-for-google-antigravity X.Y.Z).
    ✓ Hook command         uvx forge-agent-lens-for-google-antigravity@X.Y.Z
    ✓ FORGE_TRACE_PROJECT  my-team/antigravity-traces
    ✓ W&B API key          WANDB_API_KEY
    View traces: https://forge.coreweave.com/agent-lens/my-team/antigravity-traces
    ```

    Si le programme d’installation affiche `✗ Hook command`, consultez la section [Dépannage](#troubleshooting).
  </Step>

  <Step title="Démarrer une nouvelle session">
    Lancez une nouvelle session `agy`. Chaque tour de conversation terminé apparaît dans Agent Lens.
  </Step>
</Steps>

<h2 id="view-antigravity-traces-in-agent-lens">
  Afficher les traces Antigravity dans Agent Lens
</h2>

Le programme d’installation affiche un lien vers les traces de votre projet. Vous pouvez également ouvrir votre projet dans l’interface d’Agent Lens :

1. Accédez à [CoreWeave Forge](https://forge.coreweave.com), sélectionnez Agent Lens dans le menu des produits, puis sélectionnez votre projet dans le sélecteur de projet, en haut du menu latéral.
2. Dans le menu latéral, sélectionnez **Conversations**.
3. Sélectionnez l’onglet **Conversations** pour afficher toutes les conversations d’agent enregistrées pour votre projet.
4. Sélectionnez une conversation pour en examiner l’arborescence complète.

Pour plus d’informations sur l’onglet Conversations, voir [Afficher l’activité des agents](/fr/products/agent-lens/conversations/view-activity).

Le plugin nomme chaque conversation d’après le premier dossier du Workspace de la session. Si la session ne comporte aucun dossier de Workspace, la conversation est nommée `Antigravity`.

<h2 id="what-gets-traced">
  Ce qui est tracé
</h2>

Chaque tour de conversation correspond à une trace :

```text theme={"system"}
invoke_agent Antigravity     le tour de conversation, de votre requête jusqu’à l’arrêt de l’agent
├─ chat <model>              chaque réponse du modèle
├─ execute_tool <tool>       chaque appel d’outil et son résultat
└─ invoke_agent <subagent>   chaque sous-agent lancé par invoke_subagent
```

Les spans suivent les [conventions sémantiques GenAI d’OpenTelemetry (OTel)](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (attributs `gen_ai.*`) et leur durée est calculée à partir des horodatages des étapes de la transcription Antigravity.

<h3 id="limitations">
  Limitations
</h3>

Le plugin présente les limitations suivantes :

* La transcription d’Antigravity n’enregistre ni l’utilisation des jetons, ni les paramètres des requêtes au modèle, ni les ID de réponse : les traces n’indiquent donc ni nombres de jetons ni coûts.
* Le span `invoke_agent` d’un sous-agent contient son prompt et son résultat, mais aucun span enfant, car la transcription n’enregistre pas les appels au modèle ni les appels d’outils effectués par le sous-agent lui-même.

<h2 id="configuration-reference">
  Référence de configuration
</h2>

Configurez le plugin à l’aide de variables d’environnement définies dans l’environnement à partir duquel vous lancez `agy`.

| Variable | Par défaut | Description |
| - | - | - |
| `FORGE_TRACE_PROJECT` | Requis | Projet Agent Lens, au format `[YOUR-TEAM]/[YOUR-PROJECT]`. |
| `WANDB_API_KEY` | Entrée `~/.netrc` | Clé API Forge. |
| `FORGE_ANTIGRAVITY_INCLUDE_CONTENT` | `true` | Définissez cette variable sur `false` pour omettre les prompts, les réponses, le raisonnement, ainsi que les arguments et les résultats des outils. |

<h3 id="content-capture">
  Capture du contenu
</h3>

Avec `FORGE_ANTIGRAVITY_INCLUDE_CONTENT=false`, les spans contiennent toujours les éléments suivants :

* Les noms des modèles, des outils et des sous-agents, ainsi que les rôles des sous-agents
* Les informations de durée
* Les chemins du Workspace
* Le numéro d’exécution du Stop hook et le motif de son arrêt

Le SDK Forge ajoute également à chaque span les versions de votre système d’exploitation et de Python.

<h2 id="troubleshooting">
  Dépannage
</h2>

Si les traces n'arrivent pas dans Agent Lens, commencez par rechercher les messages du plugin à l'aide de la commande `grep`. Antigravity n'affiche la sortie des hooks ni dans son interface de terminal ni dans la sortie de `agy -p`. Il écrit les messages du hook, notamment les liens permettant de consulter les traces et les éventuelles erreurs d'exportation, dans les journaux de sa CLI :

```bash lines theme={"system"}
grep -h "forge-agent-lens-for-google-antigravity:" ~/.gemini/antigravity-cli/log/cli-*.log | tail
```

Comparez ensuite vos observations avec le tableau suivant.

| Symptôme | Points à vérifier |
| - | - |
| `install` affiche `✗ Hook command` | Installez [uv](https://docs.astral.sh/uv/getting-started/installation/) afin que `uvx` soit dans le `PATH`. |
| Le journal indique `FORGE_TRACE_PROJECT is not set` | Définissez cette variable dans l’environnement à partir duquel vous lancez `agy`, puis démarrez une nouvelle session. |
| Le journal indique `trace export failed` | La suite de la ligne précise l’erreur. Vérifiez que votre clé API est valide et que vous avez accès au projet. |
| Le journal ne contient aucune ligne du plugin | Exécutez `agy plugin list` pour vérifier que le plugin est installé, et assurez-vous que `uvx` figure dans le `PATH` avec lequel `agy` démarre. |

<h2 id="manage-the-plugin">
  Gérer le plugin
</h2>

Pour mettre à niveau le plugin, réexécutez la commande d’installation : elle remplace le plugin installé. Pour figer une version ou passer à une version donnée, installez le plugin à partir de cette version :

```bash lines theme={"system"}
uvx forge-agent-lens-for-google-antigravity@[VERSION] install
```

Désactivez, réactivez ou supprimez le plugin à l’aide de [`agy plugin`](https://antigravity.google/docs/plugins?tab=cli) :

```bash lines theme={"system"}
agy plugin disable forge-agent-lens-for-google-antigravity
agy plugin enable forge-agent-lens-for-google-antigravity
agy plugin uninstall forge-agent-lens-for-google-antigravity
```

Si vous avez installé la version `0.1.0` ou `0.1.1` avec `uv tool install`, cet exécutable n’est plus utilisé après la mise à niveau. Supprimez-le avec la commande suivante :

```bash lines theme={"system"}
uv tool uninstall forge-agent-lens-for-google-antigravity
```