Verwaltete Agents erstellen

Mit verwalteten Agents in der Gemini API können Sie Anweisungen, Skills und eine Umgebung in einem wiederverwendbaren Agent bündeln, den Sie dann per ID aufrufen können. Definieren Sie einen Code-Reviewer, einen Datenanalysten oder einen Bereitstellungsbot einmal und rufen Sie ihn von einem beliebigen Client aus auf, ohne die Konfiguration zu wiederholen.

Python


from google import genai

client = genai.Client()

agent = client.agents.create(
    id="code-reviewer",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
    },
)

result = client.interactions.create(
    agent="code-reviewer",
    input="Review the latest changes in /workspace/repo/src and file a summary.",
    environment="remote",
)
print(result.output_text)

JavaScript

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

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "code-reviewer",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/my-org/backend",
                target: "/workspace/repo",
            }
        ],
    },
});

const result = await client.interactions.create({
    agent: "code-reviewer",
    input: "Review the latest changes in /workspace/repo/src and file a summary.",
    environment: "remote",
}, { timeout: 300000 });

console.log(result.output_text);

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": "code-reviewer",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    "base_environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo"
            }
        ]
    }
}'

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": "code-reviewer",
    "input": "Review the latest changes in /workspace/repo/src and file a summary.",
    "environment": "remote"
}'

Verwalteten Agent erstellen

Ein verwalteter Agent kombiniert base_agent, system_instruction, base_environment und tools in einer einzigen Konfiguration, die Sie per ID aufrufen. Das Antigravity-Agent-Harness stellt die Laufzeit bereit. Bei jedem Aufruf wird die base_environment in eine neue Sandbox mit allen Funktionen der base_agent (Codeausführung, Dateiverwaltung, Webzugriff) verzweigt.

Sie können einen Agent aus Quellen wie Git, Cloud Storage oder Inline erstellen oder einen Fork einer Umgebung erstellen, die Sie bereits konfiguriert haben. Aus Quellen Geben Sie system_instruction und base_environment mit Quellen an. Bei jedem Aufruf wird eine neue Sandbox mit Ihren Dateien bereitgestellt. Unter „Umgebungen“ finden Sie die verfügbaren Quelltypen (Git, Cloud Storage, Inline).

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="data-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md", # This is appended to the system instruction
                "content": "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates",
            },
        ],
    },
)

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

JavaScript

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

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "data-analyst",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a data analyst. Always include visualizations and export results as PDF.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                type: "inline",
                target: ".agents/skills/slide-maker/SKILL.md",
                content: "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
            {
                type: "repository",
                source: "https://github.com/my-org/analysis-templates",
                target: "/workspace/templates",
            },
        ],
    },
});

console.log(`Created 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": "data-analyst",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
    "base_environment": {
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report."
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates"
            }
        ]
    }
}'

Aus einer vorhandenen Umgebung (Fork)

Wiederholen Sie den Vorgang mit dem Basis-Antigravity-Agenten, bis die Umgebung stimmt (Pakete installiert, Dateien vorhanden). Forken Sie ihn dann in einen verwalteten Agenten.

Python

from google import genai

client = genai.Client()

# Step 1: set up the environment interactively
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
    environment="remote",
)

# Step 2: fork that environment into a named agent

agent = client.agents.create(
    id="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a data analyst. Use the template at /workspace/template.py for all reports.",
    base_environment=interaction.environment_id,
)

print(f"Forked agent successfully: {agent.id}")

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
    environment: "remote",
}, { timeout: 300000 });

const agent = await client.agents.create({
    id: "my-data-analyst",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a data analyst. Use the template at /workspace/template.py for all reports.",
    base_environment: interaction.environment_id,
});

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

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": "Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
      "environment": "remote"
  }'

Netzwerkregeln konfigurieren

Mit dem Feld network können Sie ausgehenden Traffic auf bestimmte Domains beschränken. Anmeldedaten werden über den Egress-Proxy weitergeleitet und sind in der Sandbox nie sichtbar. Weitere Informationen zum Konfigurieren des Netzwerkzugriffs finden Sie in der Dokumentation zu Umgebungen unter Netzwerkkonfiguration:

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    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": "Basic YOUR_BASE64_TOKEN"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

print(f"Created issue-resolver agent successfully: {agent.id}")

JavaScript

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

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "issue-resolver",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    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": "Basic YOUR_BASE64_TOKEN"
                    },
                },
                { domain: "pypi.org" },
            ]
        }
    },
});

console.log(`Created issue-resolver agent successfully: ${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": "issue-resolver",
      "base_agent": "antigravity-preview-05-2026",
      "system_instruction": "You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
      "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": "Basic YOUR_BASE64_TOKEN"
                      }
                  },
                  {"domain": "pypi.org"}
              ]
          }
      }
  }'

Wenn eine Zulassungsliste festgelegt ist, sind nur Anfragen an aufgeführte Domains zulässig. Das vollständige Schema für die Zulassungsliste und die Anmeldedatenmuster finden Sie unter Umgebungen: Netzwerkkonfiguration. Sie können Platzhalter verwenden, um Subdomains abzugleichen (z. B. {"domain": "*.example.com"}). Die Stammdomain example.com wird dadurch jedoch nicht abgeglichen und muss separat hinzugefügt werden. Wenn Sie allen anderen Traffic zulassen möchten, z. B. das Weiterleiten nicht aufgeführter Domains ohne eingefügte Header, fügen Sie {"domain": "*"} als Catch-all-Eintrag hinzu.

Referenz zur Definition des KI-Agenten

In der folgenden Tabelle werden alle konfigurierbaren Parameter eines Agents beschrieben:

Feld Typ Erforderlich Beschreibung
id String Ja Eindeutige Agent-ID. Wird zum Aufrufen des Agenten verwendet.
description String Nein Eine menschenlesbare Beschreibung des KI-Agenten.
base_agent String Ja Basis-Agent-ID (z.B. antigravity-preview-05-2026).
system_instruction String Nein Systemprompt, der Verhalten und Persona definiert.
tools String oder Objekt Nein Tools, die der Agent verwenden kann. Wenn diese Option ausgelassen wird, hat der Agent Zugriff auf code_execution, google_search und url_context.
base_environment String oder Objekt Nein "remote", ein environment_id oder ein Konfigurationsobjekt mit sources und network. Weitere Informationen finden Sie unter „Umgebungen“.

Systemanweisungen: AGENTS.md

Das Harness sucht beim Starten an zwei Stellen nach AGENTS.md:

Pfad Umfang
.agents/AGENTS.md Stammverzeichnis des aktuellen Arbeitsbereichs.
/.agents/AGENTS.md Stamm des Dateisystems.

Wenn beide vorhanden sind, werden beide als Systemanweisungen geladen.

So stellen Sie ein AGENTS.md mit einer Inline-Quelle bereit:

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="styled-writer",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "# Writing Style\n\n- Use active voice\n- Keep paragraphs under 3 sentences\n- Include code examples for every concept",
            },
        ],
    },
)

print(f"Created styled-writer agent: {agent.id}")

JavaScript

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

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "styled-writer",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "# Writing Style\n\n- Use active voice\n- Keep paragraphs under 3 sentences\n- Include code examples for every concept",
            },
        ],
    },
});

console.log(`Created styled-writer 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": "styled-writer",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/AGENTS.md",
                  "content": "# Writing Style\n\n- Use active voice\n- Keep paragraphs under 3 sentences\n- Include code examples for every concept"
              }
          ]
      }
  }'

Skills: SKILL.md

Skills sind Dateien, die die Funktionen des Agenten erweitern. Platzieren Sie sie unter .agents/skills/<skill-name>/SKILL.md. Das Harness erkennt und registriert sie dann automatisch.

.agents/
├── AGENTS.md
└── skills/
    └── slide-maker/
        └── SKILL.md

So stellen Sie einen Skill mit Inline-Quelle bereit:

Python

from google import genai

client = genai.Client()

agent = client.agents.create(
    id="presenter",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You create presentations from data.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
            },
        ],
    },
)

print(f"Created presenter: {agent.id}")

JavaScript

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

const client = new GoogleGenAI({});

const agent = await client.agents.create({
    id: "presenter",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You create presentations from data.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/skills/slide-maker/SKILL.md",
                content: "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
            },
        ],
    },
});

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

REST

# Create agent with skill
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": "presenter",
      "base_agent": "antigravity-preview-05-2026",
      "system_instruction": "You create presentations from data.",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "inline",
                  "target": ".agents/skills/slide-maker/SKILL.md",
                  "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html"
              }
          ]
      }
  }'

Agent aufrufen

Rufen Sie client.interactions.create mit Ihrer Agent-ID auf, um Ihren benutzerdefinierten verwalteten Agent aufzurufen. Bei jedem Aufruf wird die Basisumgebung verzweigt, sodass jeder Lauf sauber beginnt.

Python

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

print(result.output_text)

JavaScript

const result = await client.interactions.create({
    agent: "data-analyst",
    input: "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
    environment: "remote",
}, { timeout: 300000 });

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": "data-analyst",
      "input": "Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
      "environment": "remote"
  }'

Informationen zu Konversationen mit mehreren Durchgängen und Streaming finden Sie in der Kurzanleitung. Für verwaltete Agents gelten dieselben previous_interaction_id- und environment-Muster.

Konfiguration beim Aufruf überschreiben

Sie können die Standardwerte für system_instruction und tools des Agents überschreiben, wenn Sie eine Interaktion erstellen. So können Sie das Verhalten oder die Funktionen des Agents für einen bestimmten Lauf ändern, ohne die gespeicherte Agentdefinition zu ändern.

Python

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
    system_instruction="You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
    tools=[{"type": "code_execution"}], # Override to only use code execution
    environment="remote",
)
print(result.output_text)

JavaScript

const result = await client.interactions.create({
    agent: "data-analyst",
    input: "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
    system_instruction: "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
    tools: [{ type: "code_execution" }], // Override to only use code execution
    environment: "remote",
}, { timeout: 300000 });

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": "data-analyst",
      "input": "Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
      "system_instruction": "You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
      "tools": [{"type": "code_execution"}],
      "environment": "remote"
  }'

KI-Agenten verwalten

Sie können KI-Agenten auflisten, abrufen und löschen.

Agents auflisten

Python

agents = client.agents.list()
for a in agents.agents:
    print(f"{a.id}: {a.description}")

JavaScript

const agents = await client.agents.list();
if (agents.agents) {
    for (const a of agents.agents) {
        console.log(`${a.id}: ${a.description}`);
    }
}

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

KI-Agenten abrufen

Python

agent = client.agents.get(id="data-analyst")
print(agent)

JavaScript

const agent = await client.agents.get("data-analyst");
console.log(agent);

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

KI-Agent löschen

Durch das Löschen wird die Konfiguration entfernt. Vorhandene Umgebungen und Interaktionen, die vom Agent erstellt wurden, sind davon nicht betroffen.

Python

client.agents.delete(id="data-analyst")

JavaScript

await client.agents.delete("data-analyst");

REST

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/agents/data-analyst" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Workflow für Iterationen

  1. Prototyp mit dem Basis-Antigravity-Agenten. Testen Sie Anleitungen, Skills und die Einrichtung der Umgebung interaktiv.
  2. Stabilisieren Sie die Umgebung. Installieren Sie Pakete, stellen Sie Quellen bereit und prüfen Sie, ob alles funktioniert.
  3. Persist als verwalteter Agent mit client.agents.create, entweder aus Quellen oder durch Forking der Umgebung.
  4. Aktualisieren Sie die Definition des KI-Agenten. Ändern Sie system_instruction, tauschen Sie Skills aus oder fügen Sie Quellen hinzu. Beim nächsten Aufruf wird die neue Konfiguration übernommen.

Beschränkungen

  • Vorschaustatus: Verwaltete Agents sind in der Vorschau. Funktionen und Schemas können sich ändern.
  • Basis-KI-Agent: Nur antigravity-preview-05-2026 wird als base_agent unterstützt.
  • Keine Versionsverwaltung: Die Agent-Versionsverwaltung und das Rollback sind noch nicht verfügbar.
  • Keine Sub-Agent-Verschachtelung: Die Sub-Agent-Delegierung wird noch nicht unterstützt.
  • Sie können jederzeit bis zu 1.000 verwaltete Agents pro Projekt haben.

Nächste Schritte

  • Übersicht über Agents: Hier finden Sie Informationen zu den wichtigsten Konzepten von verwalteten Agents.
  • Kurzanleitung: Multi-Turn-Unterhaltungen und Streaming nutzen
  • Antigravity Agent: Hier finden Sie Informationen zu Funktionen, Tools und Preisen für den Standard-Agenten.
  • Agent Environments (Agent-Umgebungen): Konfigurieren Sie Sandboxes, Quellen und Netzwerke.