Kurzanleitung für verwaltete KI-Agenten

In diesem Leitfaden wird beschrieben, wie Sie verwaltete Agents in der Gemini API erstellen und verwenden. Dazu wird der Antigravity-Agent verwendet. Sie führen Ihren ersten Agent-Aufruf aus, setzen eine Unterhaltung mit mehreren Schritten fort, streamen die Antwort, laden Dateien aus der Sandbox herunter und arbeiten mit dem verwalteten Antigravity-Agent.

Erste Interaktion mit einem KI-Agenten ausführen

Bei einem einzelnen Aufruf der Interactions API wird eine Linux-Sandbox bereitgestellt, der Agent-Loop ausgeführt und das Ergebnis zurückgegeben. Sie definieren drei Parameter:

  • Übergeben Sie agent als "antigravity-preview-05-2026",. Das ist die aktuelle Version unseres vordefinierten und für allgemeine Zwecke verwalteten Agents.
  • Definieren Sie environment="remote", um eine neue, leere Sandbox-Umgebung bereitzustellen.

  • Geben Sie eine Eingabe ein, in der Sie definieren, was der KI-Agent tun soll.

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" \
-H "Api-Revision: 2026-05-20" \
-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"}
}'

Die Antwort gibt ein Interaction-Objekt zurück. Speichere interaction.id und interaction.environment_id, um die Unterhaltung in derselben Sandbox fortzusetzen. Verwenden Sie interaction.output_text, um auf die endgültige Antwort des Agenten zuzugreifen. interaction.steps listet jeden Schritt auf, den der Agent ausgeführt hat (Begründung, Tool-Aufrufe, Codeausführung).

Unterhaltung fortsetzen (Multi-Turn)

Die API erfasst zwei unabhängige Zustandsdimensionen:

  • Kontext der Unterhaltung:Chatverlauf, Begründungsablauf, Tool-Nutzung, Verwendung von previous_interaction_id.
  • Umgebungsstatus:Dateien, installierte Pakete und Sandbox-Status mit environment.

Geben Sie beide an der entsprechenden Stelle ein, um fortzufahren:

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" \
-H "Api-Revision: 2026-05-20" \
-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."}]
}'

Dateien aus Runde 1 (fibonacci.txt) sind auch in Runde 2 verfügbar. Der Agent behält auch den Gesprächskontext bei.

Sie können diese unabhängig voneinander kombinieren:

  • Unterhaltung löschen, Dateien behalten:Lassen Sie previous_interaction_id weg und übergeben Sie nur die Umgebungs-ID mit environment, um eine neue Unterhaltung im selben Arbeitsbereich zu starten.
  • Unterhaltung beibehalten, neuer Arbeitsbereich:Übergeben Sie previous_interaction_id und legen Sie environment="remote" für eine neue Sandbox fest.

Automatische Kontextverdichtung

Bei langen Unterhaltungen mit mehreren Zügen kann der Rohverlauf von Begründungsschritten, Tool-Aufrufen und großen Dateiinhalten schnell anwachsen und viel Kontextspeicherplatz belegen. Um Fehler aufgrund von Tokenlimits zu vermeiden und den Fokus des Agents aufrechtzuerhalten (um „Context Rot“ zu verhindern), enthält die Managed Agents API einen nativen Schritt zur Kontextverdichtung bei etwa 135.000 Tokens. Dies geschieht automatisch.

Antwort streamen

Bei zeitaufwendigen Aufgaben können Sie die Antwort streamen, um zu sehen, wie der Agent in Echtzeit arbeitet:

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)

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);
}

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" \
-H "Api-Revision: 2026-05-20" \
-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
}'

Beim Streamen wird ein Iterable von Schrittdeltas zurückgegeben, die inkrementelle Text-, Begründungs-Tokens und Tool-Aufruf-Aktualisierungen sind. Weitere Informationen zum Streamen von Antworten finden Sie im Streaming-Leitfaden.

Dateien aus der Umgebung herunterladen

Wenn der Agent Dateien in der Sandbox erstellt. Laden Sie sie mit der Files API über eine direkte HTTP-Anfrage herunter (noch keine SDK-Methode):

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

import fs from "fs";
import { execSync } from "child_process";

const envId = interaction.environment_id;
const apiKey = process.env.GEMINI_API_KEY || "";

const url = `https://generativelanguage.googleapis.com/v1beta/files/environment-${envId}:download?alt=media`;
const response = await fetch(url, {
    headers: {
        "x-goog-api-key": apiKey,
    },
});

if (!response.ok) {
    throw new Error(`Failed to download file: ${response.statusText}`);
}

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("snapshot.tar", buffer);

if (!fs.existsSync("extracted_snapshot")) {
    fs.mkdirSync("extracted_snapshot");
}
execSync("tar -xf snapshot.tar -C extracted_snapshot");

console.log(fs.readdirSync("extracted_snapshot"));

REST

curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/files/environment-$ENV_ID:download?alt=media" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-o snapshot.tar

tar -xf snapshot.tar -C extracted_snapshot

Verwalteten Agent speichern

In den vorherigen Schritten haben wir den Standard-Antigravity-Agent verwendet und ihn inline angepasst. Nachdem Sie die Konfiguration (Anweisungen, Skills und Umgebung) optimiert haben, können Sie sie als verwalteten Agent speichern. So können Sie sie anhand der ID aufrufen, ohne die Konfiguration zu wiederholen.

Wenn Sie einen Agent speichern, definieren Sie eine base_environment (entweder aus Quellen oder durch Forking einer vorhandenen Umgebung). Der Agent verwendet diese Umgebung für jede neue Interaktion.

Aus Quellen:Definieren Sie Quellen inline oder aus anderen Quellen wie GitHub oder Cloud Storage.

Python

agent = client.agents.create(
    id="fibonacci-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always include a chart and a summary table in your reports.",
            },
            {
                "type": "repository",
                "source": "https://github.com/your-org/skills",
                "target": ".agents/skills"
            }
        ],
    },
)

print(f"Saved agent: {agent.id}")

JavaScript

const agent = await client.agents.create({
    id: "fibonacci-analyst",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "Always include a chart and a summary table in your reports.",
            },
            {
                type: "repository",
                source: "https://github.com/your-org/skills",
                target: ".agents/skills"
            }
        ],
    },
});

console.log(`Saved agent: ${agent.id}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "id": "fibonacci-analyst",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    "base_environment": {
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always include a chart and a summary table in your reports."
            },
            {
                "type": "repository",
                "source": "https://github.com/your-org/skills",
                "target": ".agents/skills"
            }
        ]
    }
}'

Verwalteten Agent aufrufen

Nachdem Sie einen verwalteten Agent gespeichert haben, können Sie ihn anhand der ID aufrufen. Bei jedem Aufruf wird die Basisumgebung verzweigt, sodass jeder Lauf sauber beginnt:

Python

result = client.interactions.create(
    agent="fibonacci-analyst",
    input="Generate the first 50 prime numbers, plot their distribution, and save a PDF report.",
    environment="remote",
)

print(result.output_text)

JavaScript

const result = await client.interactions.create({
    agent: "fibonacci-analyst",
    input: "Generate the first 50 prime numbers, plot their distribution, and save a PDF report.",
    environment: "remote",
}, {
    timeout: 300_000,
});

console.log(result.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" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "agent": "fibonacci-analyst",
    "environment": "remote",
    "input": "Generate the first 50 prime numbers, plot their distribution, and save a PDF report."
}'

Nächste Schritte