Guide de démarrage rapide sur les agents gérés

Ce guide vous explique comment créer et utiliser des agents gérés dans l'API Gemini à l'aide de l'agent Antigravity. Vous allez effectuer votre premier appel d'agent, poursuivre une conversation multitour, afficher progressivement la réponse, télécharger des fichiers depuis le bac à sable et utiliser l'agent géré Antigravity.

Exécuter votre première interaction avec un agent

Un seul appel à l'API Interactions provisionne un bac à sable Linux, exécute la boucle de l'agent et renvoie le résultat. Vous allez définir trois paramètres :

  • Transmettez le agent en tant que "antigravity-preview-05-2026", qui est la version actuelle de notre agent géré prédéfini et à usage général.
  • Définissez environment="remote" pour provisionner un nouvel environnement de bac à sable.

  • Créez une entrée pour définir ce que vous voulez que l'agent fasse.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)

# Print the agent's final output
print(f"Interaction ID: {interaction.id}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output: {interaction.output_text}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment: "remote",
});

console.log(`Interaction ID: ${interaction.id}`);
console.log(`Environment ID: ${interaction.environment_id}`);

console.log(`Output: ${interaction.output_text}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": [{"type": "text", "text": "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents."}],
    "environment": {"type": "remote"}
}'

La réponse renvoie un objet Interaction. Stockez interaction.id et interaction.environment_id pour poursuivre la conversation dans le même bac à sable. Utilisez interaction.output_text pour accéder à la réponse finale de l'agent. interaction.steps liste chaque étape effectuée par l'agent (raisonnement, appels d'outils, exécution de code).

Poursuivre la conversation (multitour)

L'API suit deux dimensions d'état indépendantes :

  • Contexte de la conversation : historique des discussions, trace de raisonnement, utilisation des outils, à l'aide de previous_interaction_id.
  • État de l'environnement : fichiers, packages installés et état du bac à sable, à l'aide de environment.

Transmettez les deux à leur place respective pour reprendre :

Python

interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    input="Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
)

print(interaction_2.output_text)

JavaScript

const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    previous_interaction_id: interaction.id,
    environment: interaction.environment_id,
    input: "Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
}, { timeout: 300_000 });

console.log(interaction2.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "previous_interaction_id": "interaction_id_from_step_1",
    "environment": "environment_id_from_step_1",
    "input": [{"type": "text", "text": "Now plot the Fibonacci sequence as a line chart and save it as chart.png."}]
}'

Les fichiers de l'étape 1 (fibonacci.txt) persistent à l'étape 2. L'agent conserve également le contexte de la conversation.

Vous pouvez les combiner indépendamment :

  • Effacer la conversation, conserver les fichiers : omettez previous_interaction_id et ne transmettez que l'ID d'environnement à l'aide de environment pour une nouvelle conversation dans le même espace de travail.
  • Conserver la conversation, nouvel espace de travail : transmettez previous_interaction_id et définissez environment="remote" pour un nouveau bac à sable.

Compression automatique du contexte

Dans les conversations de longue durée multitours, l'historique brut des étapes de raisonnement, des appels d'outils et du contenu des fichiers volumineux peut rapidement augmenter et consommer un espace de contexte important. Pour éviter les erreurs de limite de jetons et maintenir la concentration de l'agent (en évitant la "dégradation du contexte"), l'API Managed Agents comporte une étape de compression du contexte native d'environ 135 000 jetons. Ce processus est automatique.

Diffuser la réponse

Pour les tâches de longue durée, vous pouvez diffuser la réponse pour voir l'agent travailler en temps réel :

Python

from google import genai

client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    environment="remote",
    stream=True,
)

for event in stream:
    print(event)
    if event.event_type == "step.stop" and event.usage:
        print(event.usage)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    environment: "remote",
    stream: true,
});

for await (const event of stream) {
    console.log(event);
    if (event.event_type === "step.stop" && event.usage) {
        console.log(event.usage);
    }
}

REST

curl -N -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    "environment": "remote",
    "stream": true
}'

La diffusion en flux continu renvoie des deltas d'étape avec des mises à jour incrémentales. Lorsqu'une étape est terminée, l'événement step.stop inclut les statistiques d'utilisation cumulées. Pour en savoir plus, consultez le guide de diffusion en flux continu.

Télécharger des fichiers depuis l'environnement

Lorsque l'agent crée des fichiers dans le bac à sable. Téléchargez-les à l'aide de l'API Files avec une requête HTTP directe (aucune méthode SDK pour le moment) :

Python

import os
import requests
import tarfile

env_id = interaction.environment_id
api_key = os.environ["GEMINI_API_KEY"]

response = requests.get(
    f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download",
    params={"alt": "media"},
    headers={"x-goog-api-key": api_key},
    allow_redirects=True,
)

with open("snapshot.tar", "wb") as f:
    f.write(response.content)

with tarfile.open("snapshot.tar") as tar:
    tar.extractall(path="extracted_snapshot")

JavaScript