Lernpfad
KI-Agent-Grundlagen
6 Std.
Anfang dieser Woche hat Google auf der Entwicklerkonferenz Google’s I/O 2026 die Gemini Managed Agents vorgestellt. Das Tool vereinfacht das Bereitstellen autonomer KI-Agenten, sodass Entwicklerinnen und Entwickler mit einem einzigen API-Aufruf Agenten starten können, die in einer isolierten, temporären Linux-Umgebung eigenständig denken, planen, im Web browsen und Code ausführen.
In diesem Tutorial erfährst du, was Gemini Managed Agents sind, wie sie funktionieren und wie du ihre API nutzt, um einen Data-Analyst-Agenten zu erstellen, der beliebige Daten analysieren kann.
Neu in der Welt agentischer KI? Starte mit unserem Kurs Introduction to AI Agents!
Was sind Managed Agents in der Gemini API?
Stell dir einen Agenten als autonomen Mitarbeitenden vor, der Zugriff auf einen eigenen, isolierten Rechner hat. Bekommst du eine Aufgabe wie die Analyse eines Datensatzes, schreibt und führt der Agent selbstständig den Code aus, der für die Lösung nötig ist. Nach Abschluss kannst du auf den Workspace des Agenten zugreifen und die Ergebnisse abholen.
Managed Agents können weit mehr als nur Code schreiben: Sie interagieren mit dem Internet, verwalten Dateien und nutzen eine Vielzahl an Tools, um Aufgaben effizient auszuführen.
Diese Agenten werden von Googles Antigravity-Agent angetrieben, einem generischen Agenten-Framework für Gemini-Modelle.
Es stellt im Runtime-Umfeld einen vorkonfigurierten Satz betrieblicher Werkzeuge bereit, sodass keine manuelle Einrichtung nötig ist. Dazu gehört eine isolierte Laufzeit für Codeausführung in Bash, Python und Node.js, mit der der Agent lokal Code schreiben, debuggen und ausführen kann.
Außerdem gibt es Dateiverwaltung über ein persistentes Dateisystem im Remote-Container. Der Agent kann so über mehrere Schritte hinweg Dateien lesen, schreiben, bearbeiten und durchsuchen.
Und dank Web-Integration hat er direkten Zugriff auf Google Search für aktuelle Informationen sowie auf Tools zum Abrufen und Parsen unstrukturierter Online-Daten.
Beispielanwendung
Angenommen, wir betreiben ein Café und möchten unsere Verkäufe analysieren. Wir können einen Managed Agent so konfigurieren, dass er auf unsere Verkaufsdatenbank zugreift.
Immer wenn wir einen Bericht brauchen, formulieren wir einfach auf Englisch die Analyseanfrage. Der Agent schreibt und führt selbstständig den Python-Code aus, erstellt einen Kurzbericht und speichert ihn im Dateisystem, damit wir ihn prüfen können.
Einführung in KI-Agenten
Lerne die Grundlagen von KI-Agenten, ihre Komponenten und ihre Anwendung in der Praxis - ohne Programmierkenntnisse.
Was kosten Managed Agents in der Gemini API?
Die Preisgestaltung der Gemini Managed Agents hat mehrere Komponenten, weshalb exakte Kostenschätzungen schwierig sind. Im Kern bestimmen vier Faktoren die Kosten:
- Modellnutzung (Tokens): Abgerechnet wird nach der Anzahl der verarbeiteten Eingabe- und Ausgabe-Tokens des zugrunde liegenden Gemini-Modells. Dazu zählen auch Tokens aus Zwischenergebnissen. Wenn der Agent zum Beispiel ein Python-Skript für einen Bericht generiert, werden auch die Tokens für dieses Skript berechnet.
- Infrastruktur- & Plattformgebühren: Managed Agents laufen in Googles integrierter Umgebung. Dafür fallen Servicegebühren für die Plattform-Tools (wie Vertex AI Agent Builder) an, mit denen die Agenten verwaltet und bereitgestellt werden.
- Context Caching: Wenn Agenten häufig dieselben Daten wiederverwenden, können sie Context Caching nutzen. Das senkt die Kosten in der Regel deutlich im Vergleich zur Standard-Token-Bepreisung.
- Grounding: Wenn der Agent Google-Dienste wie Google Search oder Google Maps nutzt, werden diese separat abgerechnet – meist mit einem Freikontingent und anschließenden Kosten pro 1.000 Anfragen (typischerweise etwa $14/1.000 Anfragen).
In diesem Tutorial bauen wir einen Agenten auf Basis des antigravity-preview-05-2026-Agenten, der von dGemini 3.5 Flash angetrieben wird. Die Token-Kosten von Gemini 3.5 Flash sind wie folgt:
So baust du Managed Agents in der Gemini API
In diesem Leitfaden erstellen wir mit der Gemini API und Python einen Managed Agent. Da Managed Agents eine neue, aktuell noch im Beta-Stadium befindliche Funktion sind, können sich einzelne Implementierungsdetails noch ändern.
Den gesamten Code aus diesem Tutorial findest du in diesem GitHub-Repository. Darüber teilen wir auch Daten mit dem Data-Analyst-Agenten.
API-Einrichtung
Um einen KI-Schlüssel zu erstellen, gehe zum Google AI Studio und klicke oben rechts auf “Create API Key”.
API-Schlüssel müssen einem Google-Cloud-Projekt zugeordnet sein. Du kannst ein bestehendes wählen oder ein neues erstellen. Hier habe ich eines namens gemini-managed-agents angelegt.
Nach dem Erstellen kopieren wir den Schlüssel. Dann legen wir im Ordner, in dem wir unsere Agenten erstellen, eine Datei namens .env an und fügen den Schlüssel in folgendem Format ein:
GEMINI_API_KEY=<paste_your_api_key_here>Bevor wir Google AI Studio schließen, müssen wir noch die Abrechnung für den soeben erstellten API-Schlüssel einrichten. Andernfalls werden unsere Anfragen abgelehnt, da Google uns nicht abrechnen kann. Klicke dazu auf “Set up billing”.
Python-Umgebung einrichten
Wir nutzen Anaconda, um eine Python-Umgebung für dieses Projekt aufzusetzen. Erstelle die Umgebung mit:
conda create --name gemini_agents python=3.12 -yDamit erzeugst du eine Umgebung namens gemini_agents mit Python 3.12. Der Parameter -y bestätigt alle Rückfragen automatisch.
Als Nächstes aktivieren wir sie:
conda activate gemini_agentsZum Schluss installieren wir die benötigten Abhängigkeiten. So geht’s:
pip install google-genai requests python-dotenvEine einfache Interaktion mit einem Managed Agent
Jetzt ist alles bereit für unseren ersten Agentenlauf. Dieser erste Agent macht noch nicht viel: Er installiert matplotlib und meldet die installierte Version zurück.
Hier ist die Schritt-für-Schritt-Erklärung, wie wir mit einem Managed Agent interagieren (den vollständigen Code findest du im Skript simple_interaction.py im Repository):
Zuerst importieren wir die benötigten Pakete und laden den API-Schlüssel aus der zuvor erstellten .env-Datei:
from dotenv import load_dotenv
from google import genai
# Load secure environment variables
load_dotenv()Als Nächstes initialisieren wir den Gemini-Client und starten eine Interaktion mit dem Basis-Agenten, der aktuell antigravity-preview-05-2026 heißt. Wir bitten ihn, matplotlib zu installieren:
# Initialize the GenAI Client
client = genai.Client()
# Create a basic interaction with a managed agent
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Install the matplotlib package, verify its version, and report back.",
environment="remote"
)Zum Schluss lesen wir die Ausgabe des Agenten über die Eigenschaften status, environment_id und output_text:
# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")Das Ergebnis sieht so aus:
Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.
Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9Sandbox-Lebenszyklus
Im obigen Beispiel haben wir die Kennung der Agenten-Umgebung ausgegeben:
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6Dieser Wert ist wichtig, da er die Umgebung identifiziert, in der der Agent ausgeführt wurde. Agenteninteraktionen werden in einer kurzlebigen Umgebung gespeichert, die bis zu 7 Tage nach der letzten Aktivität erhalten bleibt und dann gelöscht wird.
Die folgende Grafik zeigt den Lebenszyklus der Sandbox, in der der Agent während einer Interaktion ausgeführt wird.
Solange die Umgebung nicht gelöscht ist, können wir sie über die Umgebungs-ID weiter aufrufen und zusätzliche Interaktionen ausführen.
Mehrere Interaktionen durchführen
Im nächsten Beispiel zeigen wir, wie mehrere Interaktionen hintereinander ablaufen. Den vollständigen Code findest du in der Datei multiple_interactions.py aus dem Repository.
# First interaction
inter1 = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Write a Python script sum.py that adds all integers from 1 to 100.",
environment="remote"
)
# Second interaction
inter2 = client.interactions.create(
agent="antigravity-preview-05-2026",
previous_interaction_id=inter1.id, # Passes the conversation history
environment=inter1.environment_id, # Keeps the same filesystem state
input="Execute 'sum.py' using Python and display the standard output."
)
# Output the status of the agent
print(f"Output:\n{inter2.output_text}")In der zweiten Interaktion haben wir zwei Parameter ergänzt:
-
previous_interaction_id: Die Kennung der vorherigen Interaktion, damit der Agent den Gesprächsverlauf kennt. -
environment: Die Umgebungs-ID, damit der Agent weiß, in welcher Sandbox er ausführen soll.
Dateien mit einem Agenten teilen
Ohne Datenzugriff lässt sich kein Data-Analyst-Agent bauen. Es gibt mehrere Möglichkeiten, Daten mit einem Agenten zu teilen:
- Inline-Daten: Dateiinhalt als String laden und während der Interaktion mitsenden.
- Gehostete Datei: Daten über eine öffentliche URL bereitstellen, die der Agent herunterladen kann.
- GitHub-Repository: Dem Agenten eine öffentliche GitHub-URL übergeben.
- Google Cloud Bucket: Datei in einem Google-Cloud-Storage-Bucket hosten und das Projekt so konfigurieren, dass der Agent Zugriff hat.
Wir behandeln hier nicht alle Varianten. Wir zeigen das Senden von Inline-Daten durch Laden einer lokalen Datei in einen String sowie das Teilen eines GitHub-Repos. Erstere Option eignet sich für kleine lokale Dateien (bis 1 MB pro Datei, insgesamt 2 MB über alle Dateien), letztere für größere Dateien wie Datensätze.
Inline-Daten teilen
So stellst du Inline-Daten bereit (voller Code in inline_example.py):
inter = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Add all the numbers in the /workspace/numbers.txt file.",
environment={
"type": "remote",
"sources": [
{
"type": "inline",
# The file where to store the data in the agent environment
"target": "/workspace/numbers.txt",
# Assumes that the file data/numbers.txt exists
"content": utils.read_text_file("data/numbers.txt")
}
]
}
)Daten werden über den Parameter sources in der environment-Konfiguration bereitgestellt. target definiert den Speicherort im Agenten-Umfeld. Dateien sollten im Ordner workspace liegen. Hier heißt die Datei number.txt.
Der Parameter content enthält den Dateiinhalt. Bei inline-Quellen ist das einfach ein String, den wir hier mit der Funktion read_text_file() aus der Datei utils.py lesen.
Ein GitHub-Repository teilen
Für größere Dateien können wir eine GitHub-Repo-URL angeben. So geht’s:
inter = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Add all the numbers in the /workspace/repository/numbers.txt file.",
environment={
"type": "remote",
"sources": [
{
"type": "repository",
"source": "https://github.com/fran-aubry/gemini-agents-tutorial",
"target": "/workspace/repository"
}
]
}
)Im obigen Beispiel wird das Repository unter https://github.com/fran-aubry/gemini-agents-tutorial in einen Ordner namens repository im Workspace des Agenten geklont.
Die Umgebung eines Agenten herunterladen
Wir wissen nun, wie wir mit Managed Agents interagieren und ihnen Dateien bereitstellen. Um unseren Data-Analyst-Agenten zu bauen, müssen wir als Letztes lernen, wie wir die Umgebung eines Agenten herunterladen. So kommen wir an die vom Agenten erzeugten Diagramme und Ergebnisse.
Jeder Workspace kann unter folgender URL heruntergeladen werden:
https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:downloadErsetze <env_id> durch die Kennung der Umgebung, die du herunterladen möchtest.
Hier ist eine Python-Funktion, die mit dem Paket requests ein Paket herunterlädt (diese Funktion ist Teil der Datei utils.py):
def download_env(env_id, path="environments"):
download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
try:
request_params = {"alt": "media"} # Retrieves raw media binary
request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
# Download the environment
print(f"Downloading environment: {env_id}")
response = requests.get(
download_url,
params=request_params,
headers=request_headers,
allow_redirects=True
)
response.raise_for_status()
# Save the compressed workspace archive locally
archive_name = f"{env_id}.tar"
output_path = os.path.join(path, archive_name)
with open(output_path, "wb") as archive_file:
archive_file.write(response.content)
print(f"Successfully downloaded workspace snapshot archive: {output_path}")
except requests.exceptions.RequestException as error:
print(f"Failed to download sandbox workspace via HTTP request: {error}")
except tarfile.TarError as archive_error:
print(f"Failed to unpack download tarball: {archive_error}")Einen Data-Analyst-Agenten bauen
In diesem Abschnitt erstellen wir einen Agenten für Datenanalysen. Zum Testen nutzen wir diesen Netflix-Datensatz von Kaggle, der auch im Ordner data unseres Repos liegt.
In allen bisherigen Beispielen haben wir direkt mit dem Basis-Agenten antigravity-preview-05-2026 interagiert. Jetzt erstellen wir zuerst einen Agenten mit der Funktion client.agents.create().
Einen Agenten erstellen
So erstellen wir den Agenten:
agent = client.agents.create(
id=”data-analyst”,
base_agent="antigravity-preview-05-2026",
base_environment={
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/AGENTS.md",
"content": read_text_file(".agents/AGENTS.md")
},
# Explicitly load the skill
{
"type": "inline",
"target": ".agents/skills/csv-aggregator/SKILL.md",
"content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
},
{
"type": "repository",
"source": "https://github.com/fran-aubry/gemini-agents-tutorial",
"target": "/workspace/repository"
}
]
}Die Parameter im Überblick:
-
id: Der Name des Agenten, hierdata-analyst. Diese Kennung verwenden wir inclient.interactions.create()stattantigravity-preview-05-2026, das wir bislang genutzt haben. -
base_agent: Der zugrunde liegende Agent. Wir bauen also aufantigravity-preview-05-2026auf. -
base_environment: Wie zuvor ermöglicht das, dem Agenten Dateien bereitzustellen. Wir haben zwei spezielle Dateien übergeben:.agents/AGENTS.mdund.agents/skills/csv-aggregator/SKILL.md. Darin definieren wir das Verhalten des Agenten. Die DateiAGENTS.mdbeschreibt das allgemeine Verhalten, währendSKILL.mdeine konkrete Fähigkeit definiert. Zusätzlich hat der Agent Zugriff auf das Repository mit den zu analysierenden Daten.
AGENTS.md verstehen
Diese Datei fungiert wie ein System-Prompt. Sie ist unsere zentrale Anleitung für den Agenten. Hier definieren wir klar die Rolle des Agenten, seine Hauptziele und die Grenzen, innerhalb derer er arbeiten soll.
Außerdem ist es der beste Ort, um festzuhalten, auf welche Tools oder Datenquellen der Agent zugreifen darf, und Beispiele für die gewünschte Kommunikation oder Aufgabenausführung zu geben.
Wenn wir die Anweisungen einfach und gut strukturiert halten, versteht der Agent, wie er sich verhalten soll und welche Ergebnisse erwartet werden.
Die Datei sollte im Agenten-Umfeld unter .agents/AGENTS.md liegen.
SKILL.md verstehen
Die Skill-Dateien statten den Agenten mit konkreten Fähigkeiten aus. Ein Agent kann mehrere Skills haben. Jede Fähigkeit wird in einer Datei SKILL.md unter .agents/skills/<skill_name>/SKILL.md beschrieben, wobei <skill_name> durch den Namen des Skills ersetzt wird.
Der Aufbau einer Skill-Datei ist:
---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>Zur Veranschaulichung haben wir den Agenten data-analyst mit einem Skill namens csv-aggregator ausgestattet, der hier definiert ist. Dieser Skill kommt zum Einsatz, wenn wir Zeilen einer CSV nach einer Spalte gruppieren und dabei eine andere Spalte aufsummieren möchten.
Im Netflix-Datensatz wollen wir beispielsweise wissen, welche Genres die meisten Views haben. Dafür gruppieren wir nach Genre und summieren die Werte in der Spalte Viewership. Die Skill-Datei erklärt dem Agenten, wie er diese Aufgabe umsetzt.
Den Agenten laden
Da Agenten persistent sind, erhalten wir einen Fehler, wenn wir die Erstellung doppelt ausführen. Daher haben wir in der Datei utils.py die Funktion load_or_create_agent() implementiert. Sie versucht, den Agenten zu erstellen, und lädt ihn andernfalls per client.agents.load().
Alles zusammenführen
Jetzt testen wir unseren Data-Analyst-Agenten und lassen ihn die Netflix-Genres analysieren.
Wir beginnen wie zuvor mit dem Import der Bibliotheken, dem Laden des API-Schlüssels und der Initialisierung des Clients:
from dotenv import load_dotenv
from google import genai
import utils
load_dotenv()
client = genai.Client()Dann erstellen (oder laden, falls nicht der erste Lauf) wir den Agenten data-analyst mit utils.load_or_create_agent():
data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")Jetzt interagieren wir wie zuvor mit dem Agenten. Einziger Unterschied: Im Parameter agent übergeben wir nun unseren Agenten statt antigravity-preview-05-2026.
Zunächst bitten wir den Agenten, das Paket matplotlib zu installieren:
inter1 = client.interactions.create(
agent=data_analyst.id,
input="Install the matplotlib package.",
environment="remote"
)Da die Umgebung bereits auf Agentenebene konfiguriert wurde, müssen wir keine Dateien mehr übergeben und setzen einfach den String ”remote”.
Als Nächstes fordern wir ihn auf, das Tool csv-aggregator zu nutzen, um die Netflix-Daten nach Genres zu analysieren und die meistgesehenen Genres zu plotten:
inter2 = client.interactions.create(
agent=data_analyst.id,
input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
environment=inter1.environment_id
)Dabei übergeben wir die Umgebungs-ID der vorherigen Interaktion, damit der Agent darauf aufbauen kann.
Abschließend bitten wir den Agenten, die Daten zu plotten, indem er das im vorherigen Schritt erstellte Skript genres.py ausführt (die SKILL.md weist den Agenten an, dieses Skript zu erzeugen):
inter3 = client.interactions.create(
agent=data_analyst.id,
input="Execute the genres.py script using python.",
environment=inter2.environment_id
)Nach dieser Interaktion sollte der Plot erzeugt sein. Wir laden ihn lokal herunter, indem wir die Umgebung speichern:
utils.download_env(inter3.environment_id)So sieht das Ergebnis aus:
Den vollständigen Code der Agenteninteraktion findest du in analyze_netflix_genres.py.
Fazit
Komplexe Agenten mit einem einzigen API-Aufruf zu erstellen, ohne selbst aufwendige Cloud-Infrastruktur für Sandboxes betreiben zu müssen, ist äußerst leistungsfähig. Dadurch lassen sich starke Agenten schnell aufsetzen, ohne sich um die Ausführungsumgebung zu kümmern.
In diesem Tutorial haben wir die Grundlagen der Gemini Managed Agents behandelt, aber noch keine wirklich komplexen Agenten gebaut. Ich ermutige dich, weiter einzutauchen und auf dieser Basis aufzubauen, um deine Kompetenzen zu schärfen.
