Überarbeitungen und Traffic verwalten

In der Gemini Enterprise Agent Platform können Sie unveränderliche Versionen oder Revisionen eines Agenten erstellen. Anschließend können Sie den Traffic auf die verschiedenen aktiven Überarbeitungen aufteilen. Mit der Trafficaufteilung können Sie neue Überarbeitungen testen und den Traffic schrittweise erhöhen. Außerdem können Sie den Traffic aus anderen Gründen auf Überarbeitungen aufteilen.

Die Möglichkeit, Überarbeitungen zu erstellen, ist immer aktiviert. Sie müssen die Funktion nicht aktivieren. Informationen zum Erstellen von Überarbeitungen finden Sie unter Überarbeitungen und Status.

Wenn Sie noch keine Überarbeitungen erstellt haben, müssen Sie das tun, bevor Sie sie ansehen und den Traffic zwischen ihnen konfigurieren können.

Derzeit sind Überarbeitungen und Traffic-Aufteilung über die v1beta1 API verfügbar.

Auf dieser Seite wird beschrieben, wie Sie Agent-Revisionen und die Aufteilung des Traffics verwalten.

Überarbeitungen und Status

Eine Version ist ein Snapshot eines Agenten. Wenn Sie einen Agent erstellen oder seine versionsbezogenen Felder aktualisieren, wird eine unveränderliche Revision des Agents erstellt. Eine Überarbeitung kann die folgenden Status haben:

  • Aktiv: Die Version ist für Anfragen verfügbar. Je nach Traffic-Konfiguration werden möglicherweise keine Anfragen empfangen.
  • Veraltet: Die Überarbeitung kann nicht abgefragt werden.

Sie können eine Revision anhand ihres Ressourcennamens identifizieren, den Sie durch Auflisten der Agent-Revisionen finden.

Felder mit und ohne Versionsverwaltung

In diesem Abschnitt werden die Felder in der ReasoningEngineSpec-Definition eines bereitgestellten Agenten aufgeführt, die Sie aktualisieren können, um eine Überarbeitung des Agenten zu erstellen.

Wenn Sie versionierte Felder aktualisieren,wird eine neue Überarbeitung erstellt.

Wenn Sie Felder ohne Versionsangabe oder andere Felder in der Definition eines Agents als die Felder mit Versionsangabe aktualisieren, wird der Agent in allen seinen Revisionen aktualisiert.

Das sind die versionierten Felder:

  • PackageSpec
    • pickleObjectGcsUri
    • dependencyFilesGcsUri
    • requirementsGcsUri
    • pythonVersion
  • DeploymentSpec
    • env[]
    • secretEnv[]
    • firstPartyImageOverride
    • agentServerMode
    • pscInterfaceConfig
    • minInstances
    • maxInstances
    • resourceLimits
    • containerConcurrency
  • classMethods[]
  • agentFramework
  • SourceCodeSpec
    • source
    • languageSpec
  • identityType
  • agentCard[]

Agent-Versionen auflisten

Sie können alle Revisionen eines bereitgestellten Agents auflisten, sowohl aktive als auch eingestellte.

Informationen zum Ermitteln der Ressourcen-ID für Ihren Agent finden Sie unter Ressourcen-ID des Agents abrufen.

Console

  1. Rufen Sie in der Google Agent Platform Govern > Deployments auf.

    Zu Deployments

  2. Klicken Sie auf den Namen des Agents.

  3. Wählen Sie den Tab Überarbeitungen aus.

  4. Oben auf der Seite finden Sie diese Informationen zu den Überarbeitungen:

    1. Aufteilungsmodus: Kann entweder „Manuell“ oder „Letzte“ sein. Weitere Informationen finden Sie unter „Traffic zu Überarbeitungen verwalten“.
    2. Aktive Überarbeitungen: Die Anzahl der aktiven Überarbeitungen im Vergleich zur Gesamtzahl der Überarbeitungen.
    3. Neueste Überarbeitung: Der Name der neuesten Überarbeitung und der Prozentsatz des Traffics, den sie empfängt.
    4. Primäre Version: Der Name der primären Version, die den Großteil des Traffics empfängt.

  5. In der Liste werden alle Überarbeitungen für den Agent mit den folgenden Informationen angezeigt:

    1. Name: Der Name oder die Nummer der Überarbeitung.
    2. Status: Gibt an, ob die Version bereitgestellt oder eingestellt wurde.
    3. Traffic: Der Prozentsatz des Traffics, der an die Überarbeitung weitergeleitet wird.
    4. Erstellt: Das Datum und die Uhrzeit, zu der die Version erstellt wurde.

Agent Platform SDK

Der folgende Code listet den Überarbeitungsverlauf für einen angegebenen bereitgestellten Agenten auf. Wenn Sie Revisionen auflisten möchten, müssen Sie die eindeutige Ressourcen-ID Ihres Agenten angeben.

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revisions = client.agent_engines.runtimes.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

for revision in revisions:
    print(revision)

Ersetzen Sie die folgenden Variablen im Code:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten

REST

Rufen Sie die Methode reasoningEngineRuntimeRevisions.list auf.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: Die Ressourcen-ID des bereitgestellten Agenten.

HTTP-Methode und URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "reasoningEngineRuntimeRevisions": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
        "spec": {
          // Revision-specific config attributes (e.g., package specs, requirements)
        },
        "createTime": "2026-05-01T13:26:01Z",
        "state": "ACTIVE"
      }...
    ]
}

Details einer Version abrufen

Sie können die Details für eine bestimmte Überarbeitung abrufen.

Agent Platform SDK

Mit dem folgenden Code werden Ressourcendetails für eine bestimmte bereitgestellte Agent-Version abgerufen:

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

print(revision)

Ersetzen Sie die folgenden Variablen im Code:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID: die eindeutige ID für eine bestimmte Laufzeitrevision

REST

Rufen Sie die Methode reasoningEngineRuntimeRevisions.get auf.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID: die eindeutige ID für eine bestimmte Laufzeitrevision

HTTP-Methode und URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
  "spec": {
    // Revision-specific config attributes (e.g., package specs, requirements)
  },
  "createTime": "2026-05-06T13:05:24Z",
  "state": "ACTIVE"
}

Verteilung des Traffics zwischen Überarbeitungen konfigurieren

Sie können festlegen, wie Traffic auf aktive Überarbeitungen verteilt wird. Beachten Sie, dass nur Anfragen, die an die Stammressource reasoningEngine gerichtet sind, aufgeteilt werden. Wenn Sie eine Anfrage an einen bestimmten Überarbeitungsressourcenpfad richten, werden Traffic-Regeln explizit umgangen.

Der Traffic wird mit einer von zwei Methoden verteilt:

  • Nach Prozentsatz: Wenn Sie die Konfiguration nach Prozentsatz vornehmen, wird ein bestimmter Prozentsatz des Traffics an jede Agent-Version gesendet. Jeder angegebene Prozentsatz muss eine ganze Zahl sein. Die Summe der Prozentsätze muss 100 % ergeben. Auch wenn nur eine Version aktiv ist, können Sie die Aufteilung des Traffics konfigurieren (wobei 100% dorthin weitergeleitet werden).

  • An die neueste Version: Der gesamte Traffic wird an die neueste Version weitergeleitet. Wenn eine neue Agent-Revision erstellt wird, wird der Traffic automatisch an diese neue Revision weitergeleitet.

Console

So konfigurieren Sie die Trafficverwaltung:

  1. Rufen Sie Govern > Deployments auf.

    Zu Deployments

  2. Klicken Sie auf den Namen des Agents.

  3. Rufen Sie den Tab Überarbeitungen auf.

  4. Klicken Sie auf der Detailseite für Überarbeitungen auf Traffic verwalten.

  5. Wählen Sie unter Aufteilungsmodus eine der folgenden Optionen aus:

    1. Manuell: Geben Sie den Prozentsatz des Traffics an, der an die einzelnen Überarbeitungen gesendet werden soll.
    2. Immer die neueste Version: In diesem Fall wird der gesamte Traffic an die neueste (zuletzt erstellte) Überarbeitung weitergeleitet.

  6. Wählen Sie Speichern aus, um die Änderungen zu speichern.

Agent Platform SDK

Der folgende Code zeigt ein Beispiel für die Konfiguration der prozentualen Verteilung des Traffics.

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "traffic_config": {
            "trafficSplitManual": {
                "targets": [
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
                        "percent": 50,
                    },
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
                        "percent": 50,
                    },
                ]
            }
        }
    },
)

Ersetzen Sie die folgenden Variablen im Code:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID_1: Die Revisions-ID für die erste Revision
  • REVISION_ID_2: die Überarbeitungs-ID für die zweite Überarbeitung

REST

Wenn Sie konfigurieren möchten, dass der Traffic immer an die neueste Revision gesendet wird (Standardeinstellung), aktualisieren Sie die ReasoningEngine-Ressource mit dem Feld traffic_config und geben Sie trafficSplitAlwaysLatest an:

{
  "trafficConfig": {
    "trafficSplitAlwaysLatest": {}
  }
}

Wenn Sie den Traffic zwischen Laufzeitversionen eines Agents aufteilen möchten, aktualisieren Sie die ReasoningEngine-Ressource mit dem Feld traffic_config und geben Sie eine Liste mit Traffic-Zielen und den entsprechenden Prozentzahlen an. Im Folgenden wird gezeigt, wie Sie die manuelle Aufteilung über zwei Überarbeitungen hinweg festlegen.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID_1: Die Revisions-ID für die erste Revision
  • REVISION_ID_2: die Überarbeitungs-ID für die zweite Überarbeitung
  • TRAFFIC_PERCENTAGE_1: der gewünschte Traffic-Prozentsatz für die erste Überarbeitung
  • TRAFFIC_PERCENTAGE_2: der Prozentsatz des Traffics, den Sie für die zweite Überarbeitung wünschen

HTTP-Methode und URL: 

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config

JSON-Text anfordern:

{
  "trafficConfig": {
    "trafficSplitManual": {
      "targets": [
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
            "percent": TRAFFIC_PERCENTAGE_1
          },
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
            "percent": TRAFFIC_PERCENTAGE_2
          }
        ]
      }
    }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Mit dieser Anfrage wird ein Vorgang mit langer Ausführungszeit (Long-Running Operation, LRO) gestartet. Zuerst erhalten Sie eine Standardvorgangsantwort. Sobald die Konfigurationsänderungen abgeschlossen sind, wird in der Antwort done angezeigt und Ihre Konfigurationseinstellungen werden wiederholt. 
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

Eine bestimmte Version abfragen

Sie können eine bestimmte Überarbeitung über das SDK oder die APIs abfragen. Die Überarbeitung muss aktiv sein, damit sie abgefragt werden kann. Wenn Sie Anfragen direkt an eine bestimmte Version senden, werden die Regeln für die Traffic-Verteilung umgangen.

Agent Platform SDK

Mit dem folgenden Code wird eine bestimmte aktive Version abgefragt:

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

response = revision.query(
    input={"your_input_key": "your_input_value"},
    config={"class_method": "your_class_method"},
)

print(response)

Ersetzen Sie die folgenden Variablen im Code:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID: die eindeutige ID für eine bestimmte Laufzeitrevision

REST

Rufen Sie die Methode reasoningEngineRuntimeRevisions.query auf.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID: die eindeutige ID für eine bestimmte Laufzeitrevision

HTTP-Methode und URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

 

Überarbeitungen im Blick behalten

Überwachen Sie Revisionen auf Aktivitäten und Probleme, indem Sie die Revisionsnummer als Metadaten in Logs erfassen. Informationen zum Einrichten des Loggings finden Sie unter Logging einrichten.

Version aktualisieren

Folgen Sie der Anleitung unter Bereitgestellten KI-Agent aktualisieren, um bereitgestellte Agents zu aktualisieren. Sie können versionierte oder nicht versionierte Felder aktualisieren. Wenn Sie versionierte Felder aktualisieren, wird eine neue Version erstellt.

Agent-Revision löschen

Sie können eine Agent-Überarbeitung entfernen, indem Sie sie löschen. Sie können nur Überarbeitungen löschen, die nicht für die Verkehrsverwaltung aktiv sind, da sie entweder eingestellt wurden oder nicht für den Empfang von Traffic konfiguriert sind. Eine Anleitung zum Konfigurieren, ob eine Revision Traffic erhält, finden Sie unter Trafficverteilung zwischen Revisionen konfigurieren.

Console

So löschen Sie eine Überarbeitung für einen Agent:

  1. Rufen Sie Govern > Deployments auf.

    Zu Deployments

  2. Klicken Sie auf den Namen des Agents.

  3. Rufen Sie den Tab Überarbeitungen auf.

  4. Klicken Sie auf der Detailseite für Überarbeitungen auf den Namen der Überarbeitung.

  5. Suchen Sie die Zeile für die Überarbeitung, die Sie entfernen möchten.

  6. Klicken Sie auf das Symbol Löschen (Papierkorb).

  7. Bestätigen Sie bei entsprechender Aufforderung das Löschen der Überarbeitung.

Agent Platform SDK

Mit dem folgenden Code wird eine bestimmte Agent-Version gelöscht:

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.runtimes.revisions.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

Ersetzen Sie die folgenden Variablen im Code:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID: die eindeutige ID für eine bestimmte Laufzeitrevision

REST

Rufen Sie die Methode reasoningEngineRuntimeRevisions.delete auf.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • LOCATION: eine unterstützte Region
  • RESOURCE_ID: die Ressourcen-ID des bereitgestellten Agenten
  • REVISION_ID: die eindeutige ID für eine bestimmte Laufzeitrevision

HTTP-Methode und URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

 

Beschränkungen

  • Agent Gateway wird nicht für Agent Runtime-Agents unterstützt, die Versionen verwenden. Sie können keine versionsbezogenen Funktionen wie die Konfiguration der Trafficaufteilung und die Abfrage pro Revision verwenden, wenn ein Agent Gateway an die Konfiguration eines Agents angehängt ist.