Managed Agents mit der Gemini API aufbauen: Ein vollständiger Entwicklerleitfaden

Autonome Agenten, die Code analysieren, schreiben und ausführen, im Web browsen und Dateien verwalten, erforderten früher wochenlange Infrastrukturarbeit. Mit der Einführung von Managed Agents in der Gemini API hat Google dieses Setup auf einen einzigen API-Aufruf reduziert. Eine Anfrage startet eine sichere, temporäre Linux-Sandbox, die von Google gehostet wird — und einen Agenten, der darin sofort echte Arbeit erledigen kann.

Dieser Leitfaden deckt alles ab, was Entwickler wissen müssen: wie der Antigravity-Agent funktioniert, wie man benutzerdefinierte Agenten erstellt und bereitstellt, wie man Umgebungen für reproduzierbare Läufe forkt, wie man Netzwerk und Anmeldedaten absichert und wie die neue Gemini CLI in einen agentenorientierten Workflow passt.

Was sind Gemini API Managed Agents?

Managed Agents sind Googles neue Entwickler-Primitive für autonome KI-Agenten auf der Gemini API. Statt Orchestrierungslogik, Codeausführungsumgebungen, Tool-Calling-Infrastruktur und Sicherheitskontrollen selbst zusammenzusetzen, übernimmt die API all das.

Ein einzelner Aufruf der Interactions API stellt eine isolierte Linux-Umgebung bereit, startet einen von Gemini betriebenen Agenten und führt Ihre Aufgabe end-to-end aus. Der Agent kann schlussfolgern und planen, Tools aufrufen, Code ausführen, Dateien verwalten und im Web browsen — alles innerhalb einer sicheren Laufzeitumgebung, die Google für Sie verwaltet.

Zwei Oberflächen machen das möglich:

• Die Interactions API — die Laufzeit-Schnittstelle. Senden Sie eine Aufgabe und erhalten Sie einen Agenten, der schlussfolgert und handelt.
• Die Agents API — die Steuerungsebene. Definieren, registrieren und verwalten Sie benannte Agenten mit benutzerdefinierten Anweisungen, Tools, Skills und Umgebungskonfigurationen.

Der Antigravity-Agent: Ein sofort einsatzbereiter Allzweck-Agent

Der erste allgemeine Managed Agent auf der Gemini API ist Antigravity. Er wird von Gemini 3.5 Flash angetrieben und läuft auf demselben Harness wie die Antigravity IDE und andere Google-First-Party-Agentenprodukte. Vor Antigravity war Deep Research der einzige verfügbare Managed Agent — ein spezialisierter Agent für mehrstufige Recherche-Workflows.

Antigravity ist das Allzweck-Pendant: ein einzelner API-Aufruf, der eine entfernte Linux-Umgebung bereitstellt und direkt loslegt.

Was Antigravity kann

Innerhalb seiner verwalteten Sandbox kann der Antigravity-Agent:

• Mit dem Gemini Agent Harness schlussfolgern und planen
• Code ausführen und Dateien in einer sicheren Linux-Umgebung verwalten
• Im Web browsen, um Live-Daten abzurufen und zu verarbeiten
• Tools wie Websuche, Codeausführung und Datei-I/O verwenden

Ihr erster Antigravity-API-Aufruf

Hier ist der einfachste mögliche Antigravity-Aufruf — ein API-Aufruf, der eine entfernte Umgebung bereitstellt, den Agenten ausführt und die Ausgabe zurückgibt:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

Das ist alles. Kein Container-Setup. Kein Sandbox-Code. Kein Tool-Calling-Gerüst. Google kümmert sich um alles.

Persistente Umgebungen: Zustandsbehaftete Multi-Turn-Agenten

Umgebungen bleiben zwischen Aufrufen erhalten. Die erste Interaktion stellt eine Sandbox bereit und gibt eine environment_id zurück. Geben Sie diese ID in Folgeanfragen an, und der Agent macht dort weiter, wo er aufgehört hat — mit allen Dateien, Paketen und dem gesamten Zustand genau so, wie der vorherige Aufruf ihn hinterlassen hat.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

Diese Zustandsbehaftung macht mehrstufige Workflows praktikabel. Ein Agent, der in einem Aufruf Pakete installiert, Dateien schreibt und Analysen ausführt, kann all das nahtlos an den nächsten Aufruf übergeben — kein erneutes Einrichten, kein erneutes Herunterladen, keine erneute Ausführung.

Umgebungen akzeptieren beim Start auch externe Daten: Git-Repositories, Google-Cloud-Storage-Objekte oder Inline-Inhalte können vor dem Start des Agenten in die Sandbox eingebunden werden.

Benutzerdefinierte Managed Agents erstellen

Der Antigravity-Agent deckt allgemeine Aufgaben gut ab. Produktionsfälle benötigen jedoch fast immer benutzerdefiniertes Verhalten — spezifische Anweisungen, Domänenwissen, proprietäre Tools oder kuratierte Datenquellen. Dafür ist die Agents API da.

Mit Gemini Managed Agents können Sie Anweisungen, Skills, Tools und eine Umgebung zu einem benannten Agenten bündeln, den Sie per ID aufrufen. Statt komplexen Orchestrierungscode zu schreiben, definieren Sie alles deklarativ — in Markdown-Dateien wie AGENTS.md und SKILL.md — und registrieren es einmalig.

Einen Agenten aus Quellen definieren

Erstellen Sie einen Agenten von Grund auf, indem Sie Systemanweisungen und Quellen angeben. Quellen können GitHub-Repositories, Google-Cloud-Storage-Pfade oder Inline-Inhalte sein. Die Plattform stellt bei jedem Aufruf eine frische Sandbox mit Ihren Dateien bereit.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

Nach der Registrierung ist data-analyst ein dauerhafter Agent, den Sie per Name aufrufen können. Jeder Lauf stellt eine saubere Umgebung mit Ihrer exakten Konfiguration bereit — kein State-Leak zwischen den Aufrufen.

Eine bestehende Umgebung forken

Manchmal ist der schnellste Weg zu einem benutzerdefinierten Agenten die Iteration. Arbeiten Sie zunächst interaktiv mit dem Basis-Antigravity-Agenten — Pakete installieren, Templates erstellen, die Umgebung konfigurieren — und forken Sie dann diesen Umgebungs-Snapshot in einen wiederverwendbaren benannten Agenten.

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

Nach dem Speichern forkt jeder spätere Aufruf von my-data-analyst von diesem Basis-Snapshot ab — und startet jedes Mal von einem sauberen, vorkonfigurierten Zustand.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

Das Fork-and-Register-Muster ist besonders effektiv für Agenten, die von einem aufwendigen Setup abhängen: komplexe Abhängigkeitsgraphen, große Modell-Artefakte oder vorkompilierte Templates, deren erneuter Aufbau bei jedem Aufruf zu lange dauern würde.

Sicheres Networking und Credentials Proxy

Produktionsagenten müssen fast immer externe Dienste erreichen — GitHub, interne APIs, Paket-Registries — und das fast immer, ohne sensible Anmeldedaten in der Sandbox offenzulegen. Managed Agents lösen beides mit einem konfigurierbaren Egress-Proxy.

Die Netzwerkkonfiguration erfüllt zwei Zwecke:

1. Allowlists beschränken ausgehende Verbindungen auf explizit erlaubte Domains und verhindern, dass ein Agent auf unbeabsichtigte externe Dienste zugreift.
2. Header-Transforms injizieren Anmeldedaten serverseitig, sodass API-Tokens und Secrets niemals in die Sandbox-Umgebung selbst gelangen.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

In dieser Konfiguration kann der Agent nur api.github.com und pypi.org erreichen. Jeder Versuch, eine Verbindung zu einer anderen Domain herzustellen, wird blockiert. GitHub-Anfragen werden automatisch so transformiert, dass der Authorization-Header enthalten ist — der Sandbox-Code sieht das Token nie direkt.

Diese Architektur ist unverzichtbar für Agenten, die gegen interne Code-Repositories, proprietäre APIs oder jede Umgebung eingesetzt werden, in der ein sauberer Umgang mit Anmeldedaten eine Compliance-Anforderung ist.

Die Gemini API CLI: Eine entwicklerorientierte, agentenfokussierte Experience

Zusätzlich zur API hat Google eine experimentelle Open-Source-Gemini API CLI veröffentlicht, die für Coding-Agenten entwickelt wurde, um strukturiert und agentenfreundlich mit der Gemini API zu interagieren.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

Der Workflow agents init / agents test / agents create spiegelt einen Wandel darin wider, wie Google erwartet, dass Entwickler auf der Gemini API aufbauen: Agentenverhalten in Dateien definieren, lokal testen, als benannten Managed Agent bereitstellen — dasselbe Muster, das man aus Infrastructure-as-Code-Tools kennt.

Ergänzende Tools

Über die CLI hinaus sorgen zwei Ergänzungen dafür, dass Coding-Agenten mit der Gemini API auf dem neuesten Stand bleiben:

• Gemini API Docs MCP server — bietet über MCP Live-Zugriff auf die Gemini-Dokumentation, SDKs und Modellinformationen. Coding-Agenten können die Docs direkt abfragen, statt sich auf veraltete Trainingsdaten zu verlassen.
• gemini-interactions-api Skill — speist Interactions-API-Muster und Best Practices automatisch in den Kontext eines Agenten ein, sodass mit Gemini Managed Agents gebaute Agenten von Anfang an idiomatischen Interactions-Code schreiben.

Warum Managed Agents für Production-Use-Cases wichtig sind

Die zentrale Wette hinter Managed Agents ist, dass der Großteil der harten Arbeit in der Agentenentwicklung nicht das Modell ist — sondern die Infrastruktur darum herum. Sandboxing, Tool-Integration, Anmeldedatenverwaltung, Reproduzierbarkeit von Umgebungen und Netzwerksicherheit sind alles Probleme, die jedes Team, das Agenten ausliefert, selbst lösen muss. Managed Agents machen daraus Googles Problem.

Dieser Wandel hat praktische Auswirkungen auf Production-Deployments:

Reproduzierbare Runs. Geforkte Umgebungen stellen sicher, dass jeder Agentenaufruf von derselben Ausgangsbasis startet — kein Dependency Drift, keine Zustandsverschmutzung zwischen Läufen.

Reduzierte Angriffsfläche. Anmeldedaten gelangen nie in die Sandbox. Der Netzwerk-Egress ist allowlist-beschränkt. Die Ausführungsumgebung ist temporär und isoliert. Das sind keine optionalen Härtungsschritte; sie sind der Standard.

Schnellere Iteration. Der Fork-and-Register-Workflow ermöglicht es Teams, interaktiv zu experimentieren, eine Konfiguration zu stabilisieren und sie in einen benannten Agenten zu überführen — ohne die Infrastruktur zwischen Prototyp und Produktion neu zu schreiben.

Framework-Kompatibilität. Managed Agents funktionieren mit den Orchestrierungs-Frameworks, die Teams bereits nutzen. Zu den Launch-Partnern gehören Vercel AI SDK, LiteLLM, Agno, Eigent und LlamaIndex — bestehende Workflows müssen also nicht vollständig neu geschrieben werden, um von verwalteter Infrastruktur zu profitieren.

Managed Agents für Unternehmen

Für Unternehmen, die benutzerdefinierte Managed Agents in großem Maßstab betreiben müssen, bietet Google die Gemini Enterprise Agent Platform — dieselben APIs, ergänzt um Governance, zentrale Transparenz und organisationsweite Richtlinienkontrollen.

Managed Agents in der Gemini API sind derzeit in der Preview verfügbar. Enterprise-Teams können über die Enterprise Agent Platform auf dieselben Managed-Agent-Primitive zugreifen, mit zusätzlichen Kontrollen für Audit, DLP-Durchsetzung und Governance über mehrere Teams hinweg.

Wichtige Erkenntnisse

Der Start von Gemini API Managed Agents gibt Entwicklern drei Dinge, die bisher schwer gemeinsam zu bekommen waren: einen leistungsfähigen Allzweck-Agenten (Antigravity), der direkt einsatzbereit ist, eine saubere API zum Definieren und Bereitstellen benutzerdefinierter Agenten mit produktionsreifer Sicherheit und eine Developer Experience — CLI, MCP-Server, Skills —, die dafür gemacht ist, dass Agenten Agenten bauen.

Die Infrastruktur-Entscheidungen sind stimmig: persistente Umgebungen, Environment Forking, Egress-Allowlists und serverseitige Injektion von Anmeldedaten sind die richtigen Primitive für Produktions-Deployments von Agenten. Die Open-Source-CLI und der Skill zeigen, dass Google erkannt hat, dass die Developer Experience für Agenten genauso wichtig ist wie die zugrunde liegenden Modellfähigkeiten.

Für Teams, die auf Eigent's modellagnostischer Plattform aufbauen, sind Gemini Managed Agents ein überzeugendes Deployment-Ziel — eines, das gut zu Eigents Fähigkeit passt, Aufgaben intelligent über Modellanbieter hinweg zu routen, während Google die isolierte Ausführungsschicht übernimmt.

Um loszulegen, testen Sie den Antigravity-Agenten im AI Studio Playground, lesen Sie die Managed Agents-Dokumentation und installieren Sie das Python SDK oder das JavaScript SDK.

Häufig gestellte Fragen

Was sind Gemini API Managed Agents?

Gemini API Managed Agents sind autonome KI-Agenten, die in von Google gehosteten, isolierten Linux-Umgebungen laufen. Ein einzelner Aufruf der Interactions API stellt die Sandbox bereit, startet einen von Gemini betriebenen Agenten und führt Ihre Aufgabe aus — einschließlich Codeausführung, Web-Browsing und Dateiverwaltung — ganz ohne Infrastruktur-Setup von Ihrer Seite.

Was ist der Antigravity-Agent?

Antigravity ist Googles Allzweck-Managed-Agent in der Gemini API, angetrieben von Gemini 3.5 Flash. Er kann in einer sicheren entfernten Linux-Umgebung schlussfolgern und planen, Code ausführen, Dateien verwalten und im Web browsen. Er verwendet denselben Agenten-Harness, der auch die Antigravity IDE und andere Google-First-Party-Agentenprodukte antreibt.

Wie funktionieren persistente Umgebungen?

Der erste Interactions-Aufruf mit environment="remote" stellt eine neue Sandbox bereit und gibt eine environment_id zurück. Wenn Sie diese ID in nachfolgenden Aufrufen übergeben, setzt der Agent in derselben Umgebung fort — mit allen Dateien, installierten Paketen und dem erhaltenen Zustand. So werden zustandsbehaftete Multi-Turn-Workflows möglich, ohne zwischen den Aufrufen neu einrichten zu müssen.

Wie erstelle ich einen benutzerdefinierten Managed Agent?

Verwenden Sie die Agents API, um einen benannten Agenten zu definieren, indem Sie einen Basis-Agenten, Anweisungen und Quellen (GitHub-Repos, GCS-Objekte oder Inline-Inhalte) angeben. Nach der Registrierung rufen Sie Ihren Agenten per Name über die Interactions API auf. Alternativ können Sie mit Antigravity interaktiv iterieren und anschließend die resultierende Umgebung mit client.agents.create() und einem base_environment, das auf eine bestehende environment_id verweist, in einen benannten Agenten forken.

Wie funktioniert der Credentials Proxy?

Der Egress-Proxy des Managed Agents sitzt zwischen der Sandbox und dem Internet. Sie konfigurieren eine allowlist der erlaubten Domains und optional pro Domain Header-transform-Regeln. Der Proxy injiziert Header wie Authorization: Bearer <token> automatisch in passende ausgehende Requests — sodass der Sandbox-Code nie direkten Zugriff auf die Tokenwerte hat.

Welche Frameworks sind mit Gemini Managed Agents kompatibel?

Gemini Managed Agents funktionieren zum Launch out of the box mit Vercel AI SDK, LiteLLM, Agno, Eigent und LlamaIndex. Da die Interactions API REST-basiert ist, kann sich jedes Orchestrierungs-Framework mit HTTP-Unterstützung integrieren.

Was ist die Gemini API CLI?

Die Gemini API CLI ist ein experimentelles Open-Source-Tool, das für Coding-Agenten entwickelt wurde, um mit der Gemini API zu interagieren. Sie unterstützt das Ausführen von Prompts, das Generieren von Bildern und Audio sowie die Verwaltung des gesamten Managed-Agent-Lifecycles — init, test, create und run — direkt über die Kommandozeile.

Sind Gemini Managed Agents für den Unternehmenseinsatz verfügbar?

Ja. Dieselben Managed-Agents-APIs sind über die Gemini Enterprise Agent Platform verfügbar, mit zusätzlichen Governance-Kontrollen, zentraler Transparenz, DLP-Durchsetzung und organisationsweiter Richtlinienverwaltung. Managed Agents in der Gemini API sind derzeit in der Preview verfügbar.