Agent erstellen und verwalten

In diesem Leitfaden wird beschrieben, wie Sie benutzerdefinierte Agentenressourcen erstellen, abrufen, auflisten, aktualisieren und löschen, die die Managed Agents API auf der Agent Platform verwenden, und wie Sie die Agentenumgebung, MCP-Server-Tools (Model Context Protocol) und Skills konfigurieren.

Vorbereitung

Führen Sie vor der Konfiguration Ihrer Agents die folgenden Schritte aus:

  • Wählen Sie in der Google Google Cloud Console auf der Seite für die Projektauswahl ein Google Cloud -Projekt aus oder erstellen Sie eines.

  • Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

  • Aktivieren Sie die Gemini Enterprise Agent Platform API (aiplatform.googleapis.com) für Ihr Projekt.

  • Sie müssen eine der folgenden Rollen haben:

    • aiplatform.user: Bietet Berechtigungen für die Interaktion mit AI Platform-Ressourcen.
    • aiplatform.admin: Bietet vollständige Kontrolle über AI Platform-Ressourcen, einschließlich administrativer Aufgaben.

Agent erstellen

Verwenden Sie zum Erstellen eines neuen benutzerdefinierten Agents die Methode CreateAgent. Dies ist ein Vorgang mit langer Ausführungszeit.

Basis-Agent erstellen

Wenn Sie einen einfachen Agent mit Standardtools und einem Google Cloud Storage-Mountziel erstellen möchten, senden Sie eine POST-Anfrage:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID

  • LOCATION: Der regionale Standort Ihres Agenten. Nur die Region global wird unterstützt.

  • AGENT_ID: Die eindeutige benutzerdefinierte Kennung für Ihren neuen Agenten. Benutzerdefinierte Agent-IDs müssen die folgenden Einschränkungen erfüllen:

    • Muss zwischen 1 und 63 Zeichen lang sein.
    • Darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
    • Muss mit einem Buchstaben beginnen und mit einem Buchstaben oder einer Ziffer enden.

  • AGENT_DESCRIPTION: Eine kurze Zusammenfassung des Anwendungsbereichs des Agenten.

  • INSTRUCTIONS: Systemanweisungen oder Persona, die für den Agenten festgelegt werden sollen.

  • GCS_BUCKET: Das Ordnerpfadsegment Ihres eingebundenen Google Cloud Storage-Bucket (z. B. gs://cymbal-bucket-name).

  • network: Aus Sicherheitsgründen ist der Netzwerkzugriff in der Umgebung deaktiviert. Sie müssen eine allowlist angeben, um den Zugriff zu aktivieren. Wenn Sie * als Domain in allowlist verwenden, sind Verbindungen zu allen Domains möglich und Sie erhalten uneingeschränkten Netzwerkzugriff.

HTTP-Methode und URL

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents

JSON-Text der Anfrage:

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "system_instruction": "INSTRUCTIONS",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_BUCKET",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Befehl curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "system_instruction": "INSTRUCTIONS",
      "tools": [
          {"type": "code_execution"},
          {"type": "filesystem"},
          {"type": "google_search"},
          {"type": "url_context"}
      ],
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_BUCKET",
                  "target": "/.agent"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Beispielantwort

{
  "name": "projects/1234567890/locations/global/agents/my-first-agent/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-12T23:50:16.933752Z",
      "updateTime": "2026-05-12T23:50:16.933752Z"
    }
  }
}

Python

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    system_instruction="INSTRUCTIONS",
    tools=[
        {"type": "code_execution"},
        {"type": "google_search"},
        {"type": "url_context"},
    ],
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_BUCKET",
                "target": "/.agent",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

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

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    system_instruction: "INSTRUCTIONS",
    tools: [
        { type: "code_execution" },
        { type: "google_search" },
        { type: "url_context" },
    ],
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_BUCKET",
                target: "/.agent",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Agenten mit Google-Tools erstellen

Wenn Sie einen Agenten mit Google-Tools von Erstanbietern (z. B. Grounding mit Google Suche und URL-Kontext) erstellen möchten, fügen Sie diese Tools der Liste tools in der Agentenkonfiguration hinzu:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort Ihres Agenten. Nur die Region global wird unterstützt.

  • AGENT_ID: Die eindeutige benutzerdefinierte Kennung für Ihren neuen Agenten. Benutzerdefinierte Agent-IDs müssen die folgenden Einschränkungen erfüllen:

    • Muss zwischen 1 und 63 Zeichen lang sein.
    • Darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
    • Muss mit einem Buchstaben beginnen und mit einem Buchstaben oder einer Ziffer enden.

  • AGENT_DESCRIPTION: Eine kurze Zusammenfassung des Anwendungsbereichs des Agenten.

JSON-Text der Anfrage:

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "base_environment": {
    "type": "remote",
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Befehl curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ],
      "base_environment": {
          "type": "remote",
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Agenten mit MCP-Konfigurationen erstellen

Wenn Sie einen Agenten mit vorkonfigurierten MCP-Server-Tools erstellen möchten, fügen Sie im Abschnitt „Tools“ Details hinzu:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort Ihres Agenten. Nur die Region global wird unterstützt.

  • AGENT_ID: Die eindeutige benutzerdefinierte Kennung für Ihren neuen Agenten. Benutzerdefinierte Agent-IDs müssen die folgenden Einschränkungen erfüllen:

    • Muss zwischen 1 und 63 Zeichen lang sein.
    • Darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
    • Muss mit einem Buchstaben beginnen und mit einem Buchstaben oder einer Ziffer enden.

  • AGENT_DESCRIPTION: Eine kurze Zusammenfassung des Anwendungsbereichs des Agenten.

  • MCP_SERVER_NAME: Ein aussagekräftiger Name für das MCP-Tool.

  • MCP_SERVER_URL: Die Remote-HTTP-Gateway-URL des MCP-Servers.

  • MCP_HEADER_KEY: Optional. Der Name der Kopfzeile für die Authentifizierung (z. B. Authorization).

  • MCP_HEADER_VALUE: Optional. Das Authentifizierungs-Inhabertoken (z. B. Bearer <token>).

JSON-Text der Anfrage:

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "mcp_server",
      "name": "MCP_SERVER_NAME",
      "url": "MCP_SERVER_URL",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

Befehl curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "mcp_server",
              "name": "MCP_SERVER_NAME",
              "url": "MCP_SERVER_URL",
              "headers": {
                  "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    tools=[
        {
            "type": "mcp_server",
            "name": "MCP_SERVER_NAME",
            "url": "MCP_SERVER_URL",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
)

JavaScript

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

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

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    tools: [
        {
            type: "mcp_server",
            name: "MCP_SERVER_NAME",
            url: "MCP_SERVER_URL",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
});

Skills an einen Agenten anhängen

Wenn Sie beim Erstellen des Agents einen wiederverwendbaren Skill direkt laden möchten, binden Sie ihn in base_environment.sources ein.

Sie haben folgende Möglichkeiten, Skills anzuhängen:

  • Skill Registry:Hängen Sie einen Skill an, der in Ihrem Projekt in der Skill Registry registriert ist.

  • Google Cloud Storage:Sie können benutzerdefinierte Skills direkt aus einem Cloud Storage-Bucket anhängen.

    Als Best Practice empfehlen wir, Skills im Ordner /.agent/skills in der Umgebung zu mounten, damit sie für den Agent leichter zu finden sind.

Skill aus der Skill Registry anhängen

So laden Sie eine wiederverwendbare Skill direkt aus der Skill Registry, wenn Sie den Agent erstellen:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort für Ihren Agent. Nur die Region global wird unterstützt.
  • AGENT_ID: Die eindeutige benutzerdefinierte Kennung für Ihren neuen Agenten. Benutzerdefinierte Agent-IDs müssen die folgenden Einschränkungen erfüllen:
    • Muss zwischen 1 und 63 Zeichen lang sein.
    • Darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
    • Muss mit einem Buchstaben beginnen und mit einem Buchstaben oder einer Ziffer enden.
  • SKILL_RESOURCE_NAME: Der Ressourcenpfad des Skills oder der Liste der Skills, die eingebunden werden sollen. Sie können eines der folgenden Formate angeben:
    • Skill (Standardversion): projects/{projectID}/locations/{location}/skills/{skillName}
    • Spezifische Version: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • Liste der Skills:projects/{projectID}/locations/{location}/skills. Dadurch werden bis zu 100 Skills aus dem angegebenen project/location in die Sandbox-Umgebung eingebunden.
    Weitere Informationen finden Sie unter list skills.
JSON-Text der Anfrage:
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
Befehl curl
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "skill_registry",
                "source": "SKILL_RESOURCE_NAME",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

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

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "skill_registry",
                source: "SKILL_RESOURCE_NAME",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Skill aus Google Cloud Storage anhängen

Alternativ können Sie beim Erstellen des Agents benutzerdefinierte Skills direkt aus einem Google Cloud Storage-Bucket anhängen.

Beachten Sie die folgenden Anforderungen beim Einbinden von Skills aus Cloud Storage:

  • Anforderungen für den Upload:Sie müssen den gesamten Skill-Ordner in den Bucket hochladen.
  • Keine Inhaltsvalidierung:Das Backend validiert den Ordnerinhalt vor dem Mounten nicht. Es verhält sich wie bei einem normalen Ordner-Upload.
  • Größenbeschränkungen:Für alle angehängten Dateien gelten die Arbeitsspeicherbeschränkungen der Sandbox-Umgebung (insgesamt bis zu 4 GiB RAM).
  • Best Practices:Für eine optimale Skill-Qualität sollten Sie die Dateien in Ihrem Skill-Ordner gemäß den Konventionen auf agentskills.io/home strukturieren und vorbereiten.

So hängen Sie beim Erstellen des Agents einen Skill aus Google Cloud Storage an:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort für Ihren Agent. Nur die Region global wird unterstützt.
  • AGENT_ID: Die eindeutige benutzerdefinierte Kennung für Ihren neuen Agenten. Benutzerdefinierte Agent-IDs müssen die folgenden Einschränkungen erfüllen:
    • Muss zwischen 1 und 63 Zeichen lang sein.
    • Darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten.
    • Muss mit einem Buchstaben beginnen und mit einem Buchstaben oder einer Ziffer enden.
  • GCS_SOURCE_PATH: Der Google Cloud Storage-Bucket-Pfad, der Ihren Skill-Ordner enthält (z. B. gs://cymbal-bucket-name/my-skill-folder).
JSON-Text der Anfrage:
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
Befehl curl
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_SOURCE_PATH",
                  "target": "./skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_SOURCE_PATH",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

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

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_SOURCE_PATH",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

KI-Agenten auflisten

Wenn Sie alle gespeicherten KI-Agenten in Ihrem Projekt auflisten möchten, senden Sie eine GET-Anfrage. Mit der optionalen Paginierung können Sie die Anzahl der Ergebnisse pro Seite festlegen.

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort für die Auflistung von Agents. Nur die Region global wird unterstützt.
  • PAGE_SIZE: Optional. Die maximale Anzahl der Agents, die pro Seite zurückgegeben werden sollen. Der Standardwert ist 10 und der Höchstwert 100.
  • PAGE_TOKEN: Optional. Ein Seitentoken, das von einer vorherigen ListAgents-Antwort empfangen wurde. Geben Sie dieses Token an, um die nächste Ergebnisseite abzurufen.

Wenn die Anzahl der zurückzugebenden Kundenservicemitarbeiter größer als PAGE_SIZE ist, enthält die ListAgents-Antwort das Feld nextPageToken. Wenn Sie die nächste Seite mit Kundenservicemitarbeitern abrufen möchten, übergeben Sie den Wert von nextPageToken als Parameter PAGE_TOKEN in Ihrer nächsten ListAgents-Anfrage. Wiederholen Sie diesen Vorgang, bis das Feld nextPageToken nicht mehr in der Antwort zurückgegeben wird.

HTTP-Methode und URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

Befehl curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Beispielantwort

{
  "agents": [
    {
      "name": "projects/1234567890/locations/global/agents/my-first-agent",
      "id": "my-first-agent",
      "created": "2026-05-12T23:50:16.933Z",
      "updated": "2026-05-12T23:50:21.159Z",
      "systemInstruction": "You are a helpful assistant to user."
    }
  ],
  "nextPageToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZ=="
}

Python

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.list()

for agent in response.agents:
    print(agent)

JavaScript

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

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

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.list();

if (response.agents) {
    for (const agent of response.agents) {
        console.log(agent);
    }
}

KI-Agenten abrufen

Verwenden Sie eine GET-Anfrage, um die vollständige Konfiguration eines bestimmten Agents abzurufen.

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID

  • LOCATION: Der regionale Standort für Ihren Agent. Nur die Region global wird unterstützt.

  • AGENT_ID: Die eindeutige ID der benutzerdefinierten Agent-Konfiguration, die Sie anfordern.

HTTP-Methode und URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

Befehl curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Beispielantwort

{
  "name": "projects/vertex-agent-fishfood/locations/global/agents/my-first-agent",
  "id": "my-first-agent",
  "created": "2026-05-12T23:50:16.933Z",
  "updated": "2026-05-12T23:50:21.159Z",
  "systemInstruction": "You are a helpful assistant to user.",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "baseEnvironment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-api-sample-skills",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        {"domain": "*"}
      ]
    }
  },
  "baseAgent": "antigravity-preview-05-2026",
  "object": "agent"
}

Python

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.get(id="AGENT_ID")
print(agent)

JavaScript

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

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

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.get("AGENT_ID");
console.log(agent);

KI-Agenten aktualisieren

Wenn Sie die Konfiguration eines vorhandenen Agents aktualisieren möchten, senden Sie eine PATCH-Anfrage. Die ID des Agents ist zwar unveränderlich, Sie können aber Parameter wie Anweisungen, Tools und Umgebungsvariablen ändern. Verwenden Sie den Abfrageparameter update_mask, um genau anzugeben, welche Felder aktualisiert werden sollen. So wird sichergestellt, dass nur die Felder geändert werden, die Sie ändern möchten, und andere Konfigurationen beibehalten werden.

Basis-Agent aktualisieren

Wenn Sie die Systemanweisungen eines Agenten aktualisieren möchten, senden Sie eine PATCH-Anfrage mit update_mask=system_instruction:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort des Agents. Nur die Region global wird unterstützt.
  • AGENT_ID: Ziel-Agent-Konfiguration für das Patch-Update.
  • NEW_INSTRUCTIONS: Die aktualisierte Struktur oder Beschreibung der Anleitung, die ersetzt werden soll.

HTTP-Methode und URL

PATCH https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction

JSON-Text der Anfrage:

{
  "name": "AGENT_ID",
  "system_instruction": "NEW_INSTRUCTIONS"
}

Befehl curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

JavaScript

Agent mit Google-Tools aktualisieren

Wenn Sie einen Agent aktualisieren möchten, um Google-Tools von Erstanbietern (1P) wie die Fundierung mit der Google Suche und den URL-Kontext zu aktivieren, senden Sie eine PATCH-Anfrage mit update_mask=tools:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort des Agents. Nur die Region global wird unterstützt.
  • AGENT_ID: Ziel-Agent-ID.

JSON-Text der Anfrage:

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ]
}

Befehl curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

Agent mit MCP-Konfigurationen aktualisieren

Wenn Sie die MCP-Tools ändern möchten, die an Ihren Agenten angehängt sind, senden Sie eine PATCH-Anfrage mit update_mask=tools:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort des Agents. Nur die Region global wird unterstützt.
  • AGENT_ID: Ziel-Agent-ID.
  • NEW_MCP_SERVER_NAME: Aktualisiertes Label Ihrer MCP-Tools.
  • NEW_MCP_SERVER_URL: Der neue URL-Endpunktparameter des Servers.
  • NEW_MCP_HEADER_KEY: Optional. Der Name der Kopfzeile für die Authentifizierung (z. B. Authorization).
  • NEW_MCP_HEADER_VALUE: Optional. Das Authentifizierungs-Bearer-Token (z. B. Bearer <token>).

JSON-Text der Anfrage:

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "mcp_server",
      "name": "NEW_MCP_SERVER_NAME",
      "url": "NEW_MCP_SERVER_URL",
      "headers": {
        "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
      }
    }
  ]
}

Befehl curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "mcp_server",
              "name": "NEW_MCP_SERVER_NAME",
              "url": "NEW_MCP_SERVER_URL",
              "headers": {
                  "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

JavaScript

Skills an einen Agenten anhängen

Wenn Sie Skills in base_environment.sources während einer Agent-Aktualisierung anhängen oder ändern möchten, senden Sie eine PATCH-Anfrage mit update_mask=base_environment.

Sie haben folgende Möglichkeiten, Skills anzuhängen:

  • Skill Registry:Hängen Sie einen Skill an, der in Ihrem Projekt in der Skill Registry registriert ist.

  • Google Cloud Storage:Sie können benutzerdefinierte Skills direkt aus einem Cloud Storage-Bucket anhängen.

Skill aus der Skill Registry anhängen

So hängen Sie einen in der Skill Registry registrierten Skill an:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort des Agents. Nur die Region global wird unterstützt.
  • AGENT_ID: Ziel-Agent-ID.
  • NEW_SKILL_RESOURCE_NAME: Der Ressourcenpfad des Skills oder der Liste der Skills, die eingebunden werden sollen. Sie können eines der folgenden Formate angeben:
    • Skill (Standardversion): projects/{projectID}/locations/{location}/skills/{skillName}
    • Skill-Version (an eine bestimmte Version anpinnen): projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (Alle Skills einbinden): projects/{projectID}/locations/{location}/skills. Dadurch werden bis zu 100 Skills im Projekt/am Standort in die Sandbox-Umgebung eingebunden.
    Weitere Informationen zum Ermitteln des name-Werts für NEW_SKILL_RESOURCE_NAME finden Sie unter List skills.
JSON-Text der Anfrage:
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "NEW_SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
Befehl curl
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "NEW_SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

Skill aus Google Cloud Storage anhängen

Alternativ können Sie beim Erstellen des Agents benutzerdefinierte Skills direkt aus einem Google Cloud Storage-Bucket anhängen.

Beachten Sie die folgenden Anforderungen beim Einbinden von Skills aus Cloud Storage:

  • Anforderungen für den Upload:Sie müssen den gesamten Skill-Ordner in den Bucket hochladen.
  • Keine Inhaltsvalidierung:Das Backend validiert den Ordnerinhalt vor dem Mounten nicht. Es verhält sich wie bei einem normalen Ordner-Upload.
  • Größenbeschränkungen:Für alle angehängten Dateien gelten die Arbeitsspeicherbeschränkungen der Sandbox-Umgebung (insgesamt bis zu 4 GiB RAM).
  • Best Practices:Für eine optimale Skill-Qualität sollten Sie die Dateien in Ihrem Skill-Ordner gemäß den Konventionen auf agentskills.io/home strukturieren und vorbereiten.

So hängen Sie einen Skill aus Google Cloud Storage an:

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort des Agents. Nur die Region global wird unterstützt.
  • AGENT_ID: Ziel-Agent-ID.
  • NEW_GCS_SOURCE_PATH: Der Google Cloud Storage-Bucket-Pfad, der Ihren Skill-Ordner enthält (z. B. gs://cymbal-bucket-name/my-skill-folder).
JSON-Text der Anfrage:
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "NEW_GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
Befehl curl
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "NEW_GCS_SOURCE_PATH",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

KI-Agent löschen

Wenn Sie eine bestimmte benutzerdefinierte Agent-Konfiguration löschen möchten, senden Sie eine DELETE-Anfrage. Dies ist ein Vorgang mit langer Ausführungszeit, bei dem die Konfiguration dauerhaft gelöscht wird.

Wenn Sie einen Agent löschen, geben Sie alle erforderlichen Informationen in der URL an und fügen Sie keinen JSON-Anfragetext ein.

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Die Region des Agents. Nur die Region global wird unterstützt.
  • AGENT_ID: Die ID des Agenten, den Sie löschen.

HTTP-Methode und URL

DELETE https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

Befehl curl

curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Beispielantwort

{
  "name": "projects/1234567890/locations/global/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-13T02:15:45.936287Z",
      "updateTime": "2026-05-13T02:15:45.936287Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Python

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.delete(id="AGENT_ID")
print(response)

JavaScript

Bevor Sie diesen Code ausführen, legen Sie die auf dem Tab „REST“ beschriebenen Variablen fest.

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

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.delete("AGENT_ID");
console.log(response);

Details eines Vorgangs mit langer Ausführungszeit abrufen

Vorgänge wie CreateAgent, UpdateAgent und DeleteAgent sind asynchron. Die erste API-Antwort enthält das Feld name mit der Vorgangs-ID. Verwenden Sie GetOperation für diese ID, um den Fortschritt abzufragen.

REST

Anfragevariablen

Bevor Sie die API aufrufen, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: Der regionale Standort des Vorgangs. Nur die Region global wird unterstützt.
  • OPERATION_ID: Die Vorgangs-ID, die aus dem Feld name in der ursprünglichen LRO-Antwort extrahiert wurde.

HTTP-Methode und URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

Befehl curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Python

JavaScript

Netzwerkzugriff konfigurieren

Standardmäßig wird der Netzwerkzugriff in der Sandbox deaktiviert, wenn Sie Agents mit der Agents API erstellen. Wenn Sie unbeschränkten Zugriff zulassen möchten, verwenden Sie *.

Wenn Sie beispielsweise * in allowlist verwenden, wie im folgenden Code gezeigt, erhalten Sie Zugriff auf alle Domains:

"base_environment": {
    "type": "remote",
    "sources": [
        {
            "type": "skill_registry",
            "source": "SKILL_RESOURCE_NAME",
            "target": "./skills"
        }
    ],
    "network": {
        "allowlist": [{"domain": "*"}]
    }
}

Nächste Schritte

Leitfaden

Hier erfahren Sie, wie Sie zur Laufzeit mit Agents interagieren, den Sitzungsstatus verwalten und Konfigurationen dynamisch überschreiben.