Kurzanleitung für verwaltete KI-Agenten

In dieser Anleitung erfahren Sie, wie Sie verwaltete KI-Agenten in der Gemini API erstellen und verwenden. Als Beispiel dient der Antigravity-Agent. Sie führen Ihren ersten Agentenaufruf aus, setzen eine Unterhaltung mit mehreren Gesprächsrunden fort, streamen die Antwort, laden Dateien aus der Sandbox herunter und arbeiten mit dem verwalteten Antigravity-Agenten.

Erste Interaktion mit dem Agenten ausführen

Ein einzelner Aufruf der Interactions API stellt eine Linux-Sandbox bereit, führt die Agentenschleife aus und gibt das Ergebnis zurück. Sie definieren drei Parameter:

  • Übergeben Sie den agent als "antigravity-preview-05-2026",. Das ist die aktuelle Version unseres vordefinierten und universell einsetzbaren verwalteten Agenten.
  • Definieren Sie environment="remote", um eine neue Sandbox-Umgebung bereitzustellen.

  • Erstellen Sie eine Eingabe, in der Sie festlegen, was der 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" \
-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. Speichern Sie 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. Unter interaction.steps sind alle Schritte aufgeführt, die der Agent ausgeführt hat (Begründung, Tool-Aufrufe, Codeausführung).

Unterhaltung fortsetzen (mehrere Gesprächsrunden)

Die API verfolgt zwei unabhängige Zustandsdimensionen:

  • Unterhaltungskontext:Chatverlauf, Begründungsablauf, Tool-Nutzung mit previous_interaction_id.
  • **Umgebungszustand**:Dateien, installierte Pakete und Sandbox-Zustand mit environment.

Übergeben Sie beide an der entsprechenden Stelle, 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" \
-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 der ersten Gesprächsrunde (fibonacci.txt) bleiben in der zweiten Gesprächsrunde erhalten. Der Agent behält auch den Unterhaltungskontext 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 behalten, neuer Arbeitsbereich: Übergeben Sie previous_interaction_id und legen Sie environment="remote" für eine neue Sandbox fest.

Automatische Kontextkomprimierung

Bei langen Unterhaltungen mit mehreren Gesprächsrunden kann der Rohverlauf von Begründungsschritten, Tool-Aufrufen und großen Dateiinhalten schnell anwachsen und viel Kontextraum beanspruchen. Um Fehler aufgrund von Tokenlimits zu vermeiden und den Fokus des Agenten beizubehalten (und damit „Kontextverfall“ zu verhindern), bietet die Managed Agents API bei etwa 135.000 Token einen nativen Schritt zur Kontextkomprimierung. Dies geschieht automatisch.

Antwort streamen

Bei Aufgaben mit langer Laufzeit können Sie die Antwort streamen, um die Arbeit des Agenten in Echtzeit zu verfolgen:

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" \
-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 Streaming wird eine iterierbare Liste von Schrittdeltas zurückgegeben. Das sind inkrementelle Text-, Begründungs-Tokens und Tool-Aufruf-Updates. Weitere Informationen zum Streamen von Antworten finden Sie im Leitfaden zum Streaming.

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 verfügbar):

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 Agenten speichern

In den vorherigen Schritten haben wir den Standard-Antigravity-Agenten verwendet und ihn inline angepasst. Sobald Sie Ihre Konfiguration (Anweisungen, Fähigkeiten, Modellauswahl und Umgebung) optimiert haben, können Sie sie als wiederverwendbaren verwalteten Agenten speichern. So können Sie ihn per ID aufrufen, ohne die Konfiguration zu wiederholen.

Wenn Sie einen Agenten speichern, sehen Sie die architektonische Symmetrie mit Inline-Interaktionen: Sie geben base_agent: "antigravity-preview-05-2026" an und können eine agent_config mit dem ausgewählten model übergeben, genau wie bei interactions.create. Sie definieren auch eine base_environment (entweder aus Quellen oder durch Forking einer vorhandenen Umgebung). Der Agent verwendet diese Umgebungs- und Modellkonfiguration 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",
    agent_config={
        "type": "antigravity",
        "model": "gemini-3.6-flash",
    },
    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",
    agent_config: {
        type: "antigravity",
        model: "gemini-3.6-flash",
    },
    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" \
-d '{
    "id": "fibonacci-analyst",
    "base_agent": "antigravity-preview-05-2026",
    "agent_config": {
        "type": "antigravity",
        "model": "gemini-3.6-flash"
    },
    "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 Agenten aufrufen

Sobald Sie einen verwalteten Agenten gespeichert haben, können Sie ihn per ID aufrufen. Bei jedem Aufruf wird die Basisumgebung geforkt, sodass jede Ausführung 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" \
-d '{
    "agent": "fibonacci-analyst",
    "environment": "remote",
    "input": "Generate the first 50 prime numbers, plot their distribution, and save a PDF report."
}'

Nächste Schritte