Agent erstellen und verwalten

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

Hinweis

Richten Sie vor dem Konfigurieren Ihrer Agenten Ihre Umgebung ein:

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  5. Wenn Sie MCP-Tools ( Cloud de Confiance by S3NS Model Context Protocol) mit Ihrem Agenten verwenden möchten, weisen Sie sowohl Ihrem Nutzerkonto als auch dem zugehörigen Dienstkonto die Rolle „MCP-Tool-Nutzer“ (roles/mcp.toolUser) zu.

Agent erstellen

Verwenden Sie die Methode CreateAgent, um einen neuen benutzerdefinierten KI-Agenten zu erstellen. Dies ist ein Vorgang mit langer Ausführungszeit.

Der Basis-Agent

Der base_agent ist die zentrale Orchestrierungsumgebung, die dem Agenten die Fähigkeit zum logischen Denken und Zugriff auf die Ausführungsumgebung bietet. Es kann Skills und Bibliotheken in die Umgebung einfügen und hat Zugriff auf dienstseitige Tools für die Codeausführung, Dateisystemvorgänge und die Suche mit Fundierung.

Beim Erstellen eines KI-Agenten wird nur ein Wert für base_agent unterstützt: antigravity-preview-05-2026.

Basis-Agent erstellen

Senden Sie eine POST-Anfrage, um einen einfachen Agenten mit Standardtools und einem Google Cloud Storage-Bereitstellungsziel zu erstellen:

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort für Ihren 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.

  • BASE_AGENT: Der Name des Basis-Agenten, der erweitert werden soll. Verwenden Sie antigravity-preview-05-2026.

  • AGENT_DESCRIPTION: Eine kurze Zusammenfassung des Bereichs des KI-Agenten.

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

  • GCS_BUCKET: Das Ordnerpfadsegment Ihres bereitgestellten Google Cloud Storage-Bucket (z. B. gs://cymbal-bucket-name). Hinweis: Wenn Sie einen Bucket aus einem anderen Projekt bereitstellen möchten, gewähren Sie dem Dienstkonto des Projekts read und write Zugriff auf den Bucket.

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

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": "BASE_AGENT",
  "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 application-default 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

Legen Sie vor dem Ausführen dieses Codes 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

Legen Sie vor dem Ausführen dieses Codes 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-eigenen Tools erstellen

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

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort für Ihren 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 Bereichs 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 application-default 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

Mit der Managed Agents API auf der Agent Platform können Sie einen KI-Agenten mit vorkonfigurierten MCP-Server-Tools erstellen.

Hinweis

Bevor Sie einen Agenten mit vorkonfigurierten MCP-Servertools erstellen, müssen Sie Folgendes tun:

  • Weisen Sie sowohl Ihrem Nutzerkonto als auch dem zugehörigen Dienstkonto die IAM-Rolle (Identity and Access Management) MCP Tool User (roles/mcp.toolUser) zu.

  • Prüfen Sie, ob die MCP-Server in Ihrer Konfiguration über Standard-HTTP POST für Toolauflistungen und ‑ausführung kommunizieren. Die Managed Agents API auf der Agent Platform erfordert, dass Remote-MCP-Server streamfähige HTTP-Server sind. Die MCP-Server müssen den MCP-Streamable-HTTP-Transport implementieren, wobei tools/list und tools/call als JSON-RPC über HTTP POST gesendet werden.

    Der verworfene HTTP+SSE-Transport mit zwei Endpunkten (ein separater langlebiger GET /sse-Stream) wird nicht unterstützt.

Von Google gehostete MCPs autorisieren

Wenn Sie ein Inhabertoken für die Autorisierung von von Google gehosteten MCP-Servern (z. B. BigQuery) verwenden, führen Sie die folgenden Schritte aus:

  1. OAuth-Bereiche hinzufügen: Hängen Sie die erforderlichen OAuth 2.0-Bereiche an Ihr Authentifizierungstoken an. Wenn Sie beispielsweise den BigQuery-MCP verwenden möchten, fügen Sie die relevanten BigQuery-Bereiche in Ihre Anfrage ein.
  2. Zugriff prüfen: Prüfen Sie, ob der MCP-Server mit den neu konfigurierten Bereichen zugänglich ist, indem Sie den Autorisierungsablauf im OAuth Playground testen.
  3. Header verwenden: Bei Google-MCPs wie BigQuery müssen Sie den Header X-Goog-User-Project, der auf Ihren Projektnamen festgelegt ist, in die Zuordnung headers einfügen.

Der JSON-Anfragetext zum Erstellen eines KI-Agenten, der das BigQuery-MCP verwendet, sieht beispielsweise so aus:

{
  "name": "projects/<projectname>/locations/global/agents/data-analyst",
  "id": "data-analyst",
  "system_instruction": "You are a data analyst. Use the provided tools and data to perform analysis.",
  "tools": [
    { "type": "code_execution" },
    { "type": "filesystem" },
    { "type": "google_search" },
    { "type": "url_context" },
    {
      "type": "mcp_server",
      "name": "bigquery-mcp",
      "url": "https://bigquery.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer ya29.a0AQyyyy",
        "X-Goog-User-Project": "project-nameyyyy"
      }
    }
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-1",
        "target": "/.agent/agents-1"
      }
    ],
    "network": {
      "allowlist": [ { "domain": "*" } ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

KI-Agenten erstellen

Wenn Sie einen KI-Agenten mit vorkonfigurierten MCP-Servertools erstellen möchten, fügen Sie im Abschnitt tools Details hinzu:

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort für Ihren 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 Bereichs des KI-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 des Headers 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 application-default 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

Legen Sie vor dem Ausführen dieses Codes 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

Legen Sie vor dem Ausführen dieses Codes 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",
            },
        },
    ],
});

Fähigkeiten an einen Agenten anhängen

Wenn Sie einen wiederverwendbaren Skill direkt beim Erstellen des KI-Agenten laden möchten, hängen Sie ihn in base_environment.sources an.

Sie können Skills mit einer der folgenden Methoden anhängen:

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

  • Google Cloud Storage: Benutzerdefinierte Skills direkt aus einem Cloud Storage-Bucket anhängen.

    Als Best Practice empfehlen wir, Skills im Ordner /.agent/skills in der Umgebung bereitzustellen, damit sie für den Agenten leichter auffindbar sind.

CLI-Kenntnisse

Entwickler können auch spezielle Skills in der gewünschten Befehlszeile installieren, um Agenten und Interaktionen programmatisch zu verwalten:

Skill aus der Skill Registry anhängen

So laden Sie einen wiederverwendbaren Skill direkt aus der Skill Registry, wenn Sie den Agenten erstellen:

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort für Ihren Agenten. Nur die Region global wird unterstützt.
  • AGENT_ID: Die eindeutige benutzerdefinierte Kennung für Ihren neuen Agenten. Benutzerdefinierte Agenten-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 bereitgestellt 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 der angegebenen project/location in der Sandbox-Umgebung bereitgestellt.
    Weitere Informationen finden Sie unter Skills auflisten.
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 application-default 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

Legen Sie vor dem Ausführen dieses Codes 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

Legen Sie vor dem Ausführen dieses Codes 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 benutzerdefinierte Skills direkt aus einem Google Cloud Storage-Bucket anhängen, wenn Sie den Agent erstellen.

Beachten Sie die folgenden Anforderungen, wenn Sie Skills aus Cloud Storage bereitstellen:

  • 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 Bereitstellen nicht. Es verhält sich wie ein Standardordner-Upload.
  • Größenbeschränkungen: Alle angehängten Dateien unterliegen den 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 auf agentskills.io/home beschriebenen Konventionen strukturieren und vorbereiten.

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

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort für Ihren Agenten. Nur die Region global wird unterstützt.
  • AGENT_ID: Die eindeutige benutzerdefinierte Kennung für Ihren neuen Agenten. Benutzerdefinierte Agenten-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 application-default 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

Legen Sie vor dem Ausführen dieses Codes 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

Legen Sie vor dem Ausführen dieses Codes 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 steuern.

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort für das Auflisten von KI-Agenten. Nur die Region global wird unterstützt.
  • PAGE_SIZE: Optional. Die maximale Anzahl von KI-Agenten, 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 nachfolgende Ergebnisseite abzurufen.

Wenn die Anzahl der zurückzugebenden Agenten größer als PAGE_SIZE ist, enthält die ListAgents-Antwort ein nextPageToken-Feld. Wenn Sie die nächste Seite mit Agenten abrufen möchten, übergeben Sie den Wert dieses 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 application-default 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

Legen Sie vor dem Ausführen dieses Codes 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

Legen Sie vor dem Ausführen dieses Codes 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

Wenn Sie die vollständige Konfiguration eines bestimmten KI-Agenten abrufen möchten, verwenden Sie eine GET-Anfrage.

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID

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

  • AGENT_ID: Die eindeutige ID der angeforderten benutzerdefinierten Agentenkonfiguration.

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 application-default 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

Legen Sie vor dem Ausführen dieses Codes 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

Legen Sie vor dem Ausführen dieses Codes 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

Senden Sie eine PATCH-Anfrage, um die Konfiguration eines vorhandenen KI-Agenten zu aktualisieren. Die ID des KI-Agenten ist unveränderlich, aber Sie können Parameter wie Anweisungen, Tools und Umgebungsvariablen ändern. Verwenden Sie den update_mask Suchparameter, um genau anzugeben, welche Felder aktualisiert werden sollen. So wird sichergestellt, dass nur die Felder betroffen sind, die Sie ändern möchten, und andere Konfigurationen beibehalten werden.

Basis-Agenten aktualisieren

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

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort des KI-Agenten. Nur die Region global wird unterstützt.
  • AGENT_ID: Ziel-Agent-Konfiguration für das Patch-Update.
  • NEW_INSTRUCTIONS: Die aktualisierte Anweisungsstruktur oder Beschreibung, 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 application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

JavaScript

KI-Agenten mit Google-eigenen Tools aktualisieren

Wenn Sie einen Agenten aktualisieren möchten, um Google-eigene Tools (wie Fundierung mit der Google Suche und URL-Kontext) zu aktivieren, senden Sie eine PATCH-Anfrage mit update_mask=tools:

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort des KI-Agenten. 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 application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

KI-Agenten mit MCP-Konfigurationen aktualisieren

Wenn Sie die mit Ihrem Agenten verknüpften MCP-Tools ändern möchten, senden Sie eine PATCH-Anfrage mit update_mask=tools:

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort des KI-Agenten. Nur die Region global wird unterstützt.
  • AGENT_ID: ID des Ziel-KI-Agenten.
  • 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 des Headers für die Authentifizierung (z. B. Authorization).
  • NEW_MCP_HEADER_VALUE: Optional. Das Authentifizierungs-Inhabertoken (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 application-default 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

Fähigkeiten an einen Agenten anhängen

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

Sie können Skills mit einer der folgenden Methoden anhängen:

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

  • Google Cloud Storage: 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

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort des KI-Agenten. Nur die Region global wird unterstützt.
  • AGENT_ID: ID des Ziel-KI-Agenten.
  • NEW_SKILL_RESOURCE_NAME: Der Ressourcenpfad des Skills oder der Liste der Skills, die bereitgestellt 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 bereitstellen): projects/{projectID}/locations/{location}/skills. Dadurch werden bis zu 100 Skills im Projekt/Standort in der Sandbox-Umgebung bereitgestellt.
    Weitere Informationen zum Ermitteln des name-Werts für NEW_SKILL_RESOURCE_NAME finden Sie unter Fähigkeiten auflisten.
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 application-default 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 benutzerdefinierte Skills direkt aus einem Google Cloud Storage-Bucket anhängen, wenn Sie den Agent erstellen.

Beachten Sie die folgenden Anforderungen, wenn Sie Skills aus Cloud Storage bereitstellen:

  • 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 Bereitstellen nicht. Es verhält sich wie ein Standardordner-Upload.
  • Größenbeschränkungen: Alle angehängten Dateien unterliegen den 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 auf agentskills.io/home beschriebenen Konventionen strukturieren und vorbereiten.

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

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Der regionale Standort des KI-Agenten. Nur die Region global wird unterstützt.
  • AGENT_ID: ID des Ziel-KI-Agenten.
  • 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 application-default 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 endgültig gelöscht wird. Wenn Sie die Agent Runtime löschen, wird die Agentenidentität ungültig. In allen IAM Unified Access Policies (UAPs), die diesem Hauptkonto Berechtigungen gewähren, bleibt das nicht mehr vorhandene Hauptkonto in den Regeln enthalten. Außerdem bleibt die Richtlinienbindung aktiv. Wenn Sie ein nicht mehr vorhandenes Hauptkonto entfernen möchten, aktualisieren Sie die UAP, um das Hauptkonto aus den Regeln zu entfernen. Wenn die Richtlinie keine aktiven Hauptkonten mehr enthält, löschen Sie die Richtlinienbindung.

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

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS Projekt-ID
  • LOCATION: Die Region des KI-Agenten. Nur die Region global wird unterstützt.
  • AGENT_ID: Die ID des KI-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 application-default 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

Legen Sie vor dem Ausführen dieses Codes 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

Legen Sie vor dem Ausführen dieses Codes 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 ein name-Feld mit der Vorgangs-ID. Verwenden Sie GetOperation für diese ID, um den Fortschritt abzufragen.

REST

Anfragevariablen

Ersetzen Sie vor dem Aufrufen der API die folgenden Werte:

  • PROJECT_ID: Ihre Cloud de Confiance by S3NS 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 application-default print-access-token)"

Python

JavaScript

Netzwerkzugriff konfigurieren

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

Wenn Sie beispielsweise * in der 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

Anleitung

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