Überarbeitungen und Traffic verwalten

In der Gemini Enterprise Agent Platform können Sie unveränderliche Versionen oder Revisionen eines KI-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 sowie 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 Versionen erstellt haben, müssen Sie das tun, bevor Sie Versionen aufrufen 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.

Versionen und Status

Eine Version ist eine Momentaufnahme eines Agenten. Wenn Sie einen Agent erstellen oder seine versionsbezogenen Felder aktualisieren, wird eine unveränderliche Version des Agents erstellt. Eine Version ist Aktiv, wenn sie für Abfragen verfügbar ist. Je nach Traffic-Konfiguration werden möglicherweise keine Anfragen empfangen. Wenn eine Version archiviert wird, wird sie dauerhaft aus der Bereitstellung von Traffic entfernt und kann nicht wiederhergestellt werden. Archivierte Überarbeitungen werden nur zu Referenzzwecken aufbewahrt.

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

Versionslimits

Archivierte Versionen belegen keinen Versionsslot mehr. Wenn Sie eine Agent Gateway-Bindung ändern, wird jede vorhandene Revision archiviert (siehe Agent Gateway und Revisionen). Eine Bindungsänderung gibt also Kontingent frei, anstatt es zu verbrauchen. Archivierte Versionen können weiterhin gelöscht werden.

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 Revision des Agenten zu erstellen.

Wenn Sie versionierte Felder aktualisieren,wird eine neue Version 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 Versionen eines bereitgestellten KI-Agenten auflisten.

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

for revision in revisions:
    print(revision)

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions" | Select-Object -Expand Content

{
  "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 Version abrufen.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

print(revision)

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content

{
  "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 an die Stammressource reasoningEngine aufgeteilt werden. Wenn Sie eine Anfrage an einen bestimmten Überarbeitungsressourcenpfad richten, werden Traffic-Regeln explizit umgangen.

Der Traffic wird mit einer der folgenden Methoden verteilt:

• Nach Prozentsatz: Wenn Sie die Konfiguration nach Prozentsatz vornehmen, wird ein bestimmter Prozentsatz des Traffics an jede Agentenversion gesendet. Jeder angegebene Prozentsatz muss eine Ganzzahl sein. Die Summe der Prozentsätze muss 100 % ergeben. Auch wenn nur eine Revision aktiv ist, können Sie die Traffic-Aufteilung konfigurieren (mit 100% Weiterleitung).
• An die neueste Version: Der gesamte Traffic wird an die neueste Version weitergeleitet. Wenn eine neue Agent-Version erstellt wird, wird der Traffic automatisch an diese neue Version weitergeleitet.

Eine manuelle Aufteilung kann nur auf aktive Versionen ausgerichtet werden. Beim Benennen einer archivierten Version wird FAILED_PRECONDITION zurückgegeben:

Traffic target revision {revision} is not an active revision of this Agent Engine. Update traffic_config to reference only active revisions.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.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,
                    },
                ]
            }
        }
    },
)

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

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

{
  "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
          }
        ]
      }
    }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

Eine bestimmte Version abfragen

Sie können eine bestimmte Revision über das SDK oder die APIs abfragen. Die Version 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.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.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)

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query" | Select-Object -Expand Content

Agent Gateway und Überarbeitungen

Wenn Sie eine Agent Gateway-Bindung an einen Agenten anhängen, ändern oder trennen, wird eine neue Version erstellt und jede Version, die vor der Änderung vorhanden war, archiviert. Nur die neue Überarbeitung bleibt aktiv. Dieser Vorgang kann nicht rückgängig gemacht werden. Archivierte Überarbeitungen können nicht wiederhergestellt werden.

Da durch eine Bindungsänderung alle vorhandenen Überarbeitungen archiviert werden, ist sie nur zulässig, wenn der gesamte Traffic bereits auf der neuesten Überarbeitung liegt. Die API lehnt die Änderung ab, wenn eine manuelle Aufteilung festgelegt ist, auch wenn 100% des Traffics auf die neueste Überarbeitung entfallen. Die Ablehnung gibt FAILED_PRECONDITION zurück:

Changing spec.deployment_spec.agent_gateway_config archives every existing runtime revision, so it is only allowed while all traffic is on the latest revision. Set traffic_config.traffic_split_always_latest, or clear traffic_config, before changing the Agent Gateway configuration.

So ändern Sie das Gateway für einen Agenten, der eine manuelle Traffic-Aufteilung verwendet:

1. Sie können auf das Routing mit der jeweils neuesten Version umstellen, indem Sie traffic_config.traffic_split_always_latest festlegen oder traffic_config deaktivieren. Weitere Informationen finden Sie unter Verteilung des Traffics zwischen Versionen konfigurieren.
2. Ändern Sie spec.deployment_spec.agent_gateway_config. Dadurch wird die neue Überarbeitung erstellt und alle vorherigen werden archiviert.
3. Wenn Sie wieder eine manuelle Aufteilung benötigen, erstellen Sie sie aus den Überarbeitungen, die nach der Änderung der Bindung vorgenommen wurden.

Archivierte Überarbeitungen bleiben über die API zugänglich und ihre vollständige ReasoningEngineSpec wird beibehalten. Wenn Sie eine neue Version erstellen möchten, die einer archivierten Version entspricht, rufen Sie die Details der archivierten Version ab und stellen Sie eine neue Version mit denselben versionsbezogenen Feldern bereit. Wenn Sie denselben Container-Image-URI wiederverwenden, wird dieselbe Laufzeitumgebung reproduziert. Wenn Sie denselben Quellcode-Speicherort und dieselben Klassenmethoden wiederverwenden, wird dasselbe Verhalten reproduziert.

Überarbeitungen im Blick behalten

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

Neue Agent-Überarbeitung erstellen

Wenn Sie eine neue Version erstellen möchten, aktualisieren Sie die versionierten Felder eines bereitgestellten Agents. Eine Anleitung finden Sie unter Bereitgestellten Agent aktualisieren.

Wenn Sie versionierte Felder aktualisieren, wird automatisch eine neue Überarbeitung erstellt. Wenn Sie Felder ohne Versionsangabe aktualisieren, wird der Agent in allen vorhandenen Versionen aktualisiert, ohne dass eine neue Version erstellt wird.

Bereinigung von Überarbeitungen verwalten

In der Gemini Enterprise Agent Platform werden alte Versionen automatisch entfernt, damit Sie die Versionslimits nicht überschreiten. Sie können Revisionen auch manuell löschen.

Automatische Speicherbereinigung

Standardmäßig ist in der Gemini Enterprise Agent Platform die automatische Speicherbereinigung für alle Agenten aktiviert. Sie kann nicht deaktiviert werden. Die automatische Speicherbereinigung wird nur im Rahmen eines Agent-Updates ausgeführt, nicht als Hintergrundjob.

• Wann wird der Vorgang ausgeführt? Wenn bei einem Aktualisierungsvorgang versucht wird, das konfigurierte Revisionslimit zu überschreiten, werden mit demselben Vorgang die ältesten infrage kommenden Revisionen gelöscht, bevor die neue Revision erstellt wird. Wenn Sie das Limit senken, löscht die Gemini Enterprise Agent Platform sofort genügend der ältesten berechtigten Überarbeitungen, um das neue Limit zu erreichen.
• Berechtigte Überarbeitungen:Eine Überarbeitung kann nur gelöscht werden, wenn sie alle folgenden Bedingungen erfüllt:
  • Er befindet sich im Status ACTIVE.
  • Sie ist nicht in der Traffic-Konfiguration enthalten (erhält 0% des Traffics).
• Fehler:Wenn nicht genügend infrage kommende Versionen vorhanden sind, um Speicherplatz freizugeben, lehnt die Gemini Enterprise Agent Platform den Aktualisierungsvorgang mit einem FAILED_PRECONDITION-Fehler ab. Es werden keine Versionen gelöscht und keine neue Version erstellt. Sie müssen Versionen aus der Traffic-Konfiguration entfernen oder das Limit erhöhen, bevor Sie es noch einmal versuchen.

Limit konfigurieren

Das Limit wird durch das Feld revision_garbage_collection_strategy.keep_n_latest.max_revisions im Agent definiert. Sie können dieses Feld beim Erstellen des Agents festlegen oder es später mit einer Aktualisierungsanfrage ändern.

• Standardeinstellung für neue Kundenservicemitarbeiter:100 Überarbeitungen.
• Standard für bestehende Agents:950 Überarbeitungen.
• Zulässiger Bereich:1 bis 950. Werte von 0 oder weniger werden abgelehnt. Ein Wert über 950 wird abgelehnt, da 950 ein festes Kontingent ist, das nicht erhöht werden kann.

Manuelles Löschen

Sie können eine Agent-Revision manuell entfernen, indem Sie sie löschen. Sie können nur Versionen löschen, die nicht für die Verkehrssteuerung aktiv sind, da sie nicht für den Empfang von Traffic konfiguriert sind. Eine Anleitung dazu, ob eine Überarbeitung Traffic empfängt, finden Sie unter Trafficverteilung zwischen Überarbeitungen konfigurieren.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content