AlphaEvolve API-Referenz

Dieses Dokument dient als maßgebliche API-Referenz und Systemspezifikation für die AlphaEvolve Cloud API in den Google CloudDiscovery Engine-Konversationsschichten. Sie definiert die genauen verschachtelten Ressourcenhierarchien, REST- und gRPC-Endpunkte, Einschränkungen auf Feldebene, Lebenszyklus-Zustandsautomaten, Fehlerdiagnosematrizen, Regeln für die Sicherheitssandbox und Integrationsworkflows, die für die Entwicklung eines vollständig automatisierten clientseitigen Controllers und einer Auswertungsschleife erforderlich sind.

Einheitliche Statusautomaten für den Lebenszyklus

Der AlphaEvolve-Agent koordiniert zwei unabhängige Zustandsautomaten, um den Fortschritt der Testkampagne zu überwachen und die Auslieferung und Ausführung einzelner Programmvariationen zu verwalten.

Lebenszyklusstatus von Tests

Ein Test steht für die gesamte Optimierungskampagne. Sie wird als dauerhafte serverseitige Ressource verarbeitet und durchläuft die folgenden Status:

  • CREATED:Der Initialisierungsstatus. Die Ressource wurde deklariert und konfiguriert, aber es wurden noch keine ersten Generationen erstellt oder API-Aufrufe gesendet.

  • RUNNING:Der aktive Bewertungsstatus. Die Engine führt gleichzeitig Stichproben von übergeordneten Kandidaten durch, generiert Code-Mutationen über die LLM-Mischung und streamt Aufgaben an die Evaluatoren.

  • PAUSED:Ein temporärer Haltestatus, der manuell oder durch eine automatische Schutzmaßnahme idle_timeout ausgelöst wird. Die Codegenerierung wird beendet und vorhandene Worker pausieren die Messwertübermittlung.

  • COMPLETED:Ein Endstatus, der angibt, dass die Suche ihr max_programs-Ziel erreicht oder das strukturelle Generierungslimit erreicht hat.

  • FAILED:Ein schwerwiegender Fehlerstatus, der angibt, dass die Verarbeitung aufgrund von systemischen Umgebungsproblemen beendet wurde, z. B. nicht abgefangene Ausnahmen für API-Anmeldedaten, Beschädigung des Datenspeichers oder aufeinanderfolgende Runner-Paniken.

Programmstatus

Die Laufzeitvalidierungssequenz wird auf einzelne Kandidatenvarianten angewendet.

Jede generierte Code-Mutation verhält sich wie eine isolierte Programmeinheit, die in der Bevölkerungsdatenbank eine Reihe von detaillierten Betriebsstatus durchläuft.

  1. INITIALIZED:Der Programmeintrag wird in der Datenbank erstellt und seine Herkunft und Verknüpfungen zum übergeordneten Programm werden nachverfolgt.

  2. GENERATING:Eine Aufgabe wird aktiv an das Backend mit der Mischung aus Language Models gesendet, um die spezifischen funktionalen Codeblöcke zu entwerfen oder zu ändern.

  3. EVALUATING:Die Code-Nutzlast wird von einem Evaluierungs-Worker-Prozess gesperrt und in einer isolierten Testumgebung ausgeführt.

  4. COMPLETED:Die Ausführungsergebnisse und beschreibenden strukturellen Statistiken werden sicher in der Evolutionsdatenbank gespeichert und das Programm wird dem Auswahlpool hinzugefügt.

Gleichzeitigkeit und Sperrmechanismen

Programme werden von Worker-Schleifen mithilfe eines Mechanismus für atomare Sperr-Tokens abgerufen, um Race-Bedingungen oder doppelten Scoring-Overhead in verteilten Topologien zu verhindern. Der Prüfer muss das endgültige Bewertungsschema zusammen mit dem exakt übereinstimmenden Sperrtoken einreichen, um die Ergebnisse erfolgreich in die Datenbank zu übertragen.

Konfigurations- und Einstellungsschemas

Übersicht über die wichtigsten Schemakonfigurationen, Parameter und Standardeinstellungen, die von der AlphaEvolve-Engine-Laufzeit verwendet werden.

AlphaEvolveExperimentConfig

Definiert die wichtigsten strukturellen Parameter und programmatischen Einschränkungen des evolutionären Tests.

Feldname Typ Standard Einschränkungen / Wertgrenzen Technische Beschreibung
title String Erforderlich Max. 256 Zeichen Eindeutiger Anzeigename des Tests.
problemDescription String Erforderlich Max. 5.000 Zeichen Die formale Spezifikation des Problems. Sie werden direkt in Prompt-Kontexte eingefügt, um Regeln festzulegen.
programLanguage String Erforderlich Freiformwert Zielsprache des weiterentwickelten Quellcodes (z. B. "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings Objekt Erforderlich Wird dem RunSettings-Schema zugeordnet Parameter für Taktung und Zeitüberschreitung
generationSettings Objekt Optional Wird dem GenerationSettings-Schema zugeordnet Modellauswahl und Kontextparameter.
evolutionSettings Objekt Optional Wird dem EvolutionSettings-Schema zugeordnet Parameter für die Auswahl der Eltern und die Vielfalt.

RunSettings

Steuert die Durchsatzsteuerung, Parallelisierungslimits und automatischen System-Timeouts.

Feldname Typ Standard Einschränkungen / Wertgrenzen Technische Beschreibung
maxPrograms int32 100 Min.: 2, Max.: 100.000 Gesamtbudget für die Ausführung (Programme zum Generieren und Bewerten). Muss größer als 1 sein.
concurrency int32 1 Min.: 1, Max.: 30 Anzahl der parallelen Programmänderungen, die in der Warteschlange aktiv sind. Werte über 30 sind nicht zulässig.
maxDuration String 24 Stunden (86.400 Sekunden) ISO 8601-String für die Dauer von Tag und Uhrzeit
Min.: >0, Max.: 7 Tage		 Die insgesamt zulässige Zeit, bevor der Test beendet wird.
idleTimeout String 5 Stunden (USA/EU)
2 Stunden (weltweit)		 ISO 8601-String für die Dauer von Tag und Uhrzeit
Min.: >0
Max.: Standardwert des Standorts		 Dauer der Inaktivität vor der automatischen Umstellung auf PAUSED. Die Standardeinstellung ist 2 Stunden in global und 5 Stunden an regionalen Standorten (us, eu). Die Dauer ist durch die Standardeinstellung des Standorts begrenzt. Wenn Sie also einen Wert angeben, der über der Standardeinstellung des Standorts liegt (z. B. 12 Stunden in global), wird er ignoriert und der Wert ist 2 Stunden (ohne Fehler).

Einstellungen für die Generierung

Das GenerationSettings-Schema steuert die Prompt-Zusammenstellung, Kontextfenster und Modellkonfigurationen für Mutationen:

  • context (String): Optionale vom Nutzer bereitgestellte Referenzdokumentation, zusätzliche APIs oder Regeln. Es wird dringend empfohlen,unter 200.000 Tokens zu bleiben. Kontextgrößen von mehr als 200.000 Tokens schwächen die Aufmerksamkeit des Modells und beeinträchtigen die Qualität der Mutationen.

  • includeFullProgramInPrompt (bool): Standardwert false.

    • true: Der Mutations-Prompt enthält die veränderbare EVOLVE-BLOCK und den umgebenden unveränderlichen Boilerplate-Text (sehr empfehlenswert für komplexe strukturelle Begründungen).

    • false: Nur der veränderliche Block ist sichtbar, wodurch der Tokenkontext erhalten bleibt.

  • models (Array von Objekten): Optional. Jeder Eintrag enthält den Namen eines Modells und einen optionalen weight-Wert, der den Anteil der Generierungsaufrufe dieses Modells im Verhältnis zu den anderen Einträgen angibt. Wenn Sie models weglassen, wählt AlphaEvolve beim Erstellen des Tests das Standardmodell aus: das Gemini-Modell, das Google für die Codegenerierung mit AlphaEvolve empfiehlt. Diese Empfehlung ändert sich, wenn neuere Modelle veröffentlicht werden. Ab dem 29. September 2026 ist gemini-3.8-flash die Standardeinstellung. Wenn Sie ein anderes Modell verwenden möchten, geben Sie das gewünschte Modell in models an. Wenn Sie dasselbe Modell bei jedem Lauf anpinnen möchten, legen Sie models selbst fest.

    Da AlphaEvolve den Standardwert beim Erstellen des Tests auflöst, behalten Tests, die vor der Änderung des Standardmodells erstellt wurden, das in ihrer Konfiguration aufgezeichnete Modell bei. Wenn Sie einen vorhandenen Test auf Gemini 3.8 Flash umstellen möchten, geben Sie ihn in models an oder erstellen Sie einen neuen Test.

    Im folgenden Beispiel werden etwa neun von zehn Generierungsaufrufen an das erste Modell und der Rest an das zweite Modell gesendet. Gewichte sind Verhältnisse, müssen also nicht 1 ergeben.

    "models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]

Unterstützte Modelle

Legen Sie für models[].name einen der folgenden Werte fest. Sie können maximal zwei Modelle in einem Test kombinieren.

Modellname Bereitstellungsregionen
gemini-3.8-flash (Standard) global, us, eu
gemini-3.7-flash global, us, eu
gemini-3.5-flash global, us, eu
gemini-3.1-pro-preview global

AlphaEvolve validiert models beim Erstellen des Tests und gibt INVALID_ARGUMENT für einen Modellnamen zurück, der nicht in dieser Tabelle enthalten ist oder in der angeforderten Region nicht verfügbar ist.

Einstellungen für die Entwicklung

Das EvolutionSettings-Schema steuert die Wahrscheinlichkeiten für das erneute Seeding von Inselmodellen und das Sampling von übergeordneten Elementen:

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (Gleitkommazahl): Die Wahrscheinlichkeit (0,0 bis 1,0), übergeordnete Programme direkt aus der aktiven Pareto-Grenze zu ziehen, anstatt die standardmäßige fitnessbasierte Auswahl zu verwenden. Dieser Parameter muss auf 0.0 (deaktiviert) festgelegt werden, wenn die optimierten Messwerte nur einen einzelnen skalaren Messwert zurückgeben.

Datenmodelle für Kandidatenprogramme

In diesem Abschnitt werden die Datenschemas und Darstellungen beschrieben, die zum Definieren und Organisieren von Kandidatencodestrukturen in der Bevölkerungsdatenbank verwendet werden.

AlphaEvolveProgramContent

Definiert die Dateien und die strukturelle Zusammensetzung des Kandidatenprogramms.

  • files (Array von AlphaEvolveSourceFile): Eine Liste aller Dateien, aus denen die Kandidaten-Codebasis besteht. Die Nutzlast muss mindestens eine Quelldatei enthalten. Google empfiehlt, die Gesamtzahl der Dateien auf 50 Dateien pro Kandidatenprogramm zu beschränken, um eine optimale Modellaufmerksamkeit und Effizienz des Kontextfensters zu erreichen.

  • description (string): Eine automatisch generierte Zusammenfassung der programmatischen Änderungen,die vom Generierungsmodell vorgeschlagen werden (maximal 1.000 Zeichen).

AlphaEvolveSourceFile

Stellt eine einzelne Quellcodedatei in der Codebasis dar.

  • path (String): Der arbeitsbereichsrelative Zielpfad (erforderlich, max. 256 Zeichen). Für jeden Eintrag in der Quelldatei muss ein Pfad angegeben werden, der nicht leer ist. Wenn Sie einen Python-Arbeitsbereich konfigurieren, muss der primäre ausführbare Dateieinstiegspunkt genau "initial_program.py" heißen.

  • content (String): Der Rohquellcode-String, der die funktionalen Implementierungsblöcke umfasst. Google empfiehlt, die kumulative Größe der Codebasis über alle Dateien hinweg auf unter 4.000 bis 5.000 Codezeilen zu beschränken. Dies ist optimal für die Modellaufmerksamkeit und die Leistung bei der Generierung von Mutationen.

  • programLanguage (String): Das Tag für die Zuordnung des Sprachparsers. Dieser String muss exakt mit der Sprache übereinstimmen, die in der Konfiguration des übergeordneten Tests angegeben ist.

  • description (String): Eine optionale Zusammenfassung, in der die individuelle Architektur oder der Zweck der Datei beschrieben wird. Sie wird der LLM während der Mutationsdurchläufe zur Verfügung gestellt (maximal 500 Zeichen).

AlphaEvolveProgramEvaluation

Die strukturierte Nutzlast, die von Client-Runner-Instanzen nach der Laufzeitausführung an die Evolutionsdatenbank zurückgesendet wird.

  • scores (AlphaEvolveScores): Standardisierte, objektive numerische Messwerte. Best Practices empfehlen, die Anzahl auf 3 bis 5 unterschiedliche Gleitkomma-Messwerte zu beschränken. Zu viele Zieldimensionen beeinträchtigen die Leistung des Pareto-Vergleichs für mehrere Zielvorhaben.

  • insights (Array von AlphaEvolveEvaluationInsight): Semantische Diagnoselabels und Ausführungstraces in natürlicher Sprache, die zurückgegeben werden, um die nachfolgenden Versuche des LLM zur Generierung von Mutationen zu unterstützen (empfohlenes Maximum: 10 Elemente).

Formulierung von Scores und Aufnahmeformate

Maximierungsregel

AlphaEvolve funktioniert im Grunde als monotoner Hill-Climbing-Algorithmus und maximiert alle numerischen Messwerte. Wenn in Ihrer Auswertungspipeline ein Minimierungsziel verfolgt wird (z. B. die Minimierung der Anwendungs-Latenz in Millisekunden oder die Reduzierung der Arbeitsspeichernutzung), müssen Sie den Wert negieren, bevor Sie ihn an die Datenbank zurücksenden: submitted_score = -latency_ms.

Die Werte sollten idealerweise kontinuierlich sein. Boolesche oder sehr diskrete Messwerte liefern kein ausreichendes Gradientensignal für eine effektive Hill-Climbing-Exploration.

Aufnahmeschema für ein einzelnes Zielvorhaben

Verwenden Sie den folgenden JSON-Code, wenn Ihr Test-Harness für eine einzelne skalare Zielfunktion optimiert wird.

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "validation",
        "text": "Passed syntax and basic compilation."
      }
    ]
  }
}

Aufnahmeschema für mehrere Ziele

Verwenden Sie den folgenden JSON-Code, um unabhängige Parameter für die Multi-Objective-Analyse zu übergeben und serverseitige Pareto-Grenzoptimierungsroutinen zu aktivieren.

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      },
      {
        "metric": "latency",
        "score": -42.5
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "verification",
        "text": "Passed 5 out of 5 unit tests."
      },
      {
        "label": "latency_warning",
        "text": "Latency regression of 3% observed on large dataset."
      }
    ]
  }
}

Programmdaten abrufen und abfragen

Das AlphaEvolve-System protokolliert die Telemetrie, Ausführungsstatistiken und den vollständigen Quellcode jeder generierten Mutation. So können Entwickler diesen historischen Datenspeicher über die API oder CLI abfragen, um den Optimierungsfortschritt zu verfolgen und die leistungsstärksten Codekandidaten zu extrahieren.

Abrufen von Programmen über die REST API

Bewertete Programmressourcen können über den Standardendpunkt ListAlphaEvolvePrograms mit Filter- und Sortierabfrageparametern aus der Datenbank abgerufen werden:

  • Nach Status filtern: Programme abfragen, die einem bestimmten Lebenszyklusstatus entsprechen:

    GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED

  • Messwertbasierte Sortierung: Sortierte Kandidaten basierend auf optimierten Messwerten abrufen:

    GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5

Programmabruf über die Befehlszeile

Wenn Sie die besten abgeschlossenen Kandidaten direkt aus Ihrem Terminal abrufen möchten, führen Sie den folgenden Befehl aus:

ae results best <experiment-nickname> --top 5

Vollständige Beispiele für die CLI-Nutzung

Mit der AlphaEvolve-Befehlszeile können Entwickler Kampagnen schnell direkt über die Shell verwalten und überwachen:

  • Alle Tests in einer dialogbasierten Sitzung auflisten:

    ae experiment list

  • Alle mutierten Kandidatenprogramme für ein bestimmtes Experiment auflisten:

    ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen Ihres Tests.

  • Die leistungsstärksten Kandidaten für vollständigen Code abrufen:

    ae results best EXPERIMENT_NICKNAME --top 5

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen Ihres Tests.

  • So setzen Sie eine pausierte Kampagne fort:

    ae experiment resume EXPERIMENT_NICKNAME

    Ersetzen Sie EXPERIMENT_NICKNAME durch den Namen Ihres Tests.

Verzeichnis der wichtigsten REST API-Endpunkt

Alle Endpunkte sind unter v1alpha der Google Cloud Discovery Engine API versioniert.

Muster für übergeordneten Ressourcenpfad

Der URI der echten verschachtelten übergeordneten Ressource ist so aufgebaut: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • AlphaEvolve ist in global, us und eu verfügbar. Wenn Sie Tests an anderen Standorten erstellen, wird FAILED_PRECONDITION zurückgegeben.
  • Assured Workloads-Projekte werden nicht unterstützt.
  • Pro Standort sind maximal 30 gleichzeitig aktive (STARTED oder RUNNING) AlphaEvolve-Tests pro Projekt zulässig. Wenn Sie einen Test starten oder fortsetzen, der dieses Limit überschreitet, wird RESOURCE_EXHAUSTED zurückgegeben.

Test erstellen (POST)

  • Pfad:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/alphaEvolveExperiments

  • Anfragetext: AlphaEvolveExperimentConfig (siehe Abschnitt 2.1)

  • Antwort:Die AlphaEvolveExperiment-Ressource mit der initialisierten Kampagne.

  • HTTP-Status:200 OK

Beispiele für API-Nutzlast

  1. Beispiel für Anfragetext (POST /alphaEvolveExperiments)

    {
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

  2. Beispiel für Antworttext (200 OK)

    {
  "name": "projects/.../sort-opt-01",
  "state": "CREATED",
  "createTime": "2026-06-23T13:30:00Z",
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

Test starten (POST)

  • Pfad:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:start

  • Anfragetext: StartExperimentRequest

  • Warnung zu veralteten Versionen:Das Feld „body“ initialProgram ist veraltet und wird ignoriert.

  • Antwort: GoogleLongrunningOperation (LRO).

  • HTTP-Status:200 OK (Übergang vom Status CREATED zum Status RUNNING)

Beispiele für API-Nutzlast

  1. Beispiel für Anfragetext

    {
  "desiredProgramsCount": 1
}

  2. Beispiel für Antworttext (200 OK – Vorgang mit langer Ausführungszeit)

    {
  "name": "projects/.../operations/start-op-7788",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveStartExperimentMetadata",
    "createTime": "2026-06-23T13:31:00Z"
  },
  "done": false
}

Programme erwerben (POST)

  • Pfad:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:acquirePrograms

  • Anfragetext: AcquireProgramsRequest

    • desiredProgramsCount (int32): Optionale Batchanzahl der geänderten Programme, die abgerufen werden sollen (Standardwert ist 1, wenn nicht festgelegt).

  • Antwortstatus:

    • 200 OK: Gibt eine Antwort mit gesperrten AlphaEvolveProgram-Ressourcen zurück.

    • 204 No Content: Die Warteschlange ist leer oder die Kampagne ist pausiert. Runner müssen beispielsweise 15 Sekunden warten und es dann noch einmal versuchen.

Beispiele für API-Nutzlast

  1. Beispiel für Anfragetext

    {
  "desiredProgramsCount": 1
}

  2. Beispiel für Antworttext (200 OK)

    {
  "programs": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "lockToken": "token_uuid_8877_x99",
      "state": "EVALUATING",
      "createTime": "2026-06-23T13:32:00Z",
      "content": {
        "description": "Mutated candidate program.",
        "files": [
          {
            "path": "initial_program.py",
            "programLanguage": "python",
            "description": "Primary sorting executable.",
            "content": "def custom_heuristic(arr, _):\n    ..."
          }
        ]
      }
    }
  ]
}

  3. Beispiel für Antworttext (204 No Content)

HTTP-Status 204 wurde mit einem leeren Nutzlastkontext zurückgegeben.

Programmbewertungen einreichen (POST)

  • Pfad:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:submitProgramsEvaluations

  • Anfragetext: SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (Array): Enthält übereinstimmende lockToken, den qualifizierten Programmressourcenpfad und die Nutzlast für die Auswertung (Ergebnisse und Statistiken). Die API akzeptiert genau eine Bewertungsübermittlung pro Aufruf. Das Zusammenfassen mehrerer Auswertungen in einer einzelnen Anfrage wird mit INVALID_ARGUMENT abgelehnt. Wenn Sie mehrere Kandidaten bewerten, reichen Sie jedes Programm einzeln ein.

  • Antwort:SubmitProgramsEvaluationsResponse (leer).

  • HTTP-Status:200 OK (Speichert Ergebnisse, gibt die aktive Sperre frei und registriert Statistiken)

Beispiele für API-Nutzlast

  1. Beispiel für Anfragetext

    {
  "evaluationSubmissions": [
    {
      "lockToken": "token_uuid_8877_x99",
      "program": "projects/.../alphaEvolvePrograms/prog-102",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": evaluation_payload["score"]
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ]
}

  2. Beispiel für Antworttext (200 OK)

    {}

Test fortsetzen (POST)

  • Pfad:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:resume

  • Anfragetext: ResumeExperimentRequest

  • Antwort: GoogleLongrunningOperation (LRO).

  • HTTP-Status:200 OK (Übergang vom Status PAUSED zurück zu RUNNING)

Beispiele für API-Nutzlast

  1. Beispiel für Anfragetext

    {}

  2. Beispiel für Antworttext (200 OK – Vorgang mit langer Ausführungszeit)

    {
  "name": "projects/.../operations/resume-op-9900",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveResumeExperimentMetadata",
    "createTime": "2026-06-23T13:45:00Z"
  },
  "done": false
}

Programme auflisten (GET)

  • Pfad:

    GET v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}/alphaEvolvePrograms

  • Abfrageparameter:

    • stateFilter (String): Optional. Standard-Listenfilter, z. B. stateFilter = 'COMPLETED'.

    • orderBy (String): Optional. Messwertbasierte Sortierung, z. B. accuracy desc.

  • Antwort: ListAlphaEvolveProgramsResponse.

  • HTTP-Status:200 OK

Beispiele für API-Nutzlast

  1. Beispiel für eine Anfrage-URL

    GET v1alpha/projects/.../alphaEvolveExperiments/sort-opt-01/
  alphaEvolvePrograms?stateFilter=COMPLETED&orderBy=latency_performance%20desc
  &pageSize=1

  2. Beispiel für Antworttext (200 OK)

    {
  "alphaEvolvePrograms": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "state": "COMPLETED",
      "createTime": "2026-06-23T13:32:00Z",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": -12.45
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ],
  "nextPageToken": "token_page_1_next"
}

Diagnosecode und Referenz zur Fehlerbehebung

API-Diagnosecode-Matrix

HTTP-Status Fehlertyp Systemursache Problemumgehung oder Abhilfemaßnahme
400 INVALID_ARGUMENT
  • Falsch formatierte EVOLVE-BLOCK-START- oder EVOLVE-BLOCK-END-Markierungen (z. B. Inhalte, die sich in derselben Zeile wie die Markierung befinden, verschachtelte Blöcke oder fehlende Endmarkierung).
  • Leerer Evolve-Block, der nur Kommentare oder Leerzeichen ohne bearbeitbaren Code enthält.
  • maxPrograms ist auf weniger als 2 festgelegt.
  • Unbekannte Konfigurationsfelder.
  • Ungültige Modellkonfiguration (mehr als zwei Modelle, doppelte Einträge, nicht positive Gewichte oder Temperatur außerhalb von [0.0, 2.0]).
  • Mehrere Bewertungen in einem einzigen submitProgramsEvaluations-Aufruf einreichen.
  • Das Projekt ist ein Assured Workloads-Projekt.
 Achten Sie darauf, dass sich Markierungen in einer eigenen Zeile befinden und mindestens eine Zeile mit Code ohne Kommentar einschließen. Legen Sie maxPrograms auf 2 oder höher fest. Entfernen Sie Felder, die nicht Teil der API sind, z. B. notes, das in der Vorschauversion der API vorhanden war. Reichen Sie Bewertungen einzeln ein.
403 PERMISSION_DENIED
  • Der Aufrufer hat nicht die Rolle „Discovery Engine-Bearbeiter“ (roles/discoveryengine.editor) oder „Administrator“ (roles/discoveryengine.admin). Hinweis: Mit roles/discoveryengine.user werden keine AlphaEvolve-Berechtigungen gewährt und roles/discoveryengine.viewer kann keine Tests erhalten.
  • Der Aufrufer hat keine Berechtigung für die übergeordnete Sitzungsressource.
  • Es ist keine aktive Gemini Enterprise-Lizenz zugewiesen.
 Gewähren Sie roles/discoveryengine.editor oder roles/discoveryengine.admin auf Projektebene und prüfen Sie den Zugriff auf die übergeordnete Sitzung. Aktive Gemini Enterprise-Lizenzen prüfen. Standardanmeldedaten für Anwendungen konfigurieren:

gcloud auth application-default login --project=PROJECT_ID

Hinweis:Model Armor wird in AlphaEvolve-Konfigurationen nicht unterstützt.
400 FAILED_PRECONDITION
  • Das Schloss-Token ist veraltet oder abgelaufen oder der Programmstatus stimmt nicht überein (z. B. wurde der Kandidat nach Ablauf des Leases neu erworben oder finalisiert).
  • Der Test wurde an einem nicht unterstützten Standort erstellt (außerhalb von global, us oder eu).
  • Die Vertex AI API (aiplatform.googleapis.com) ist für das Projekt nicht aktiviert.
 Gib genau die lockToken wieder, die von :acquirePrograms zurückgegeben wurde. Erzwingen Sie clientseitige Zeitlimits (empfohlen: 30 Minuten) und senden Sie bei Zeitüberschreitung Strafpunktzahlen für Fehler. Erstellen Sie den Test an einem unterstützten Standort neu. Aktivieren Sie die Vertex AI API: gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • Das Projekt hat das Limit von 30 gleichzeitig aktiven Tests (STARTED / RUNNING) pro Standort erreicht.
  • Das Tokenkontingent für die Backend-Modellgenerierung ist aufgebraucht.
 Für das Limit für aktive Tests: Schließen Sie laufende Tests ab oder stoppen Sie sie, bevor Sie einen neuen starten. Eine niedrigere concurrency in runSettings hat keine Auswirkungen auf dieses Limit. Für das Kontingent für Modell-Tokens: Senken Sie concurrency in runSettings und implementieren Sie den exponentiellen Backoff.
503 SERVICE_UNAVAILABLE Der Sicherheitsklassifikator für Eingaben ist nicht verfügbar oder der Backend-Dienst ist vorübergehend überlastet. Implementieren Sie auf der Clientseite eine Wiederholungsschleife mit randomisiertem exponentiellen Backoff.

Häufige Fehlermeldungen und Lösungen

In der folgenden Referenzliste finden Sie häufige Fehlermeldungen, die von der API zurückgegeben werden, die zugrunde liegenden Ursachen und Schritte zur Fehlerbehebung.

Parsing-Fehler bei der ersten Programm- und EVOLVE-BLOCK-Analyse

Fehlermeldung Systemursache Problemumgehung oder Abhilfemaßnahme
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. Die Markierungen EVOLVE-BLOCK-START und EVOLVE-BLOCK-END werden in derselben Zeile angezeigt. Platzieren Sie Start- und Endmarkierungen in separaten Zeilen.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. Code, Text oder nachgestellte Zeichen befinden sich in derselben Zeile wie eine EVOLVE-BLOCK-START- oder EVOLVE-BLOCK-END-Markierung. Das Markierungselement muss in einer eigenen Zeile stehen und darf nur von einem Kommentarpräfix wie # EVOLVE-BLOCK-START gefolgt werden.
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. Eine EVOLVE-BLOCK-START-Markierung wird in einem bereits geöffneten Evolve-Block angezeigt. Entfernen Sie geschachtelte Startmarkierungen. Geschachtelte Evolve-Blöcke werden nicht unterstützt.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Eine EVOLVE-BLOCK-END-Markierung wird ohne vorherige EVOLVE-BLOCK-START angezeigt. Jeder Endmarker muss ein passender Startmarker vorangestellt werden.
Parsing error: Evolve block started but not ended. Es wurde ein EVOLVE-BLOCK-START-Marker ohne passenden schließenden EVOLVE-BLOCK-END-Marker gefunden. Fügen Sie eine EVOLVE-BLOCK-END-Schlussmarkierung hinzu.

Fehler bei Programminhalten und ‑struktur

Fehlermeldung Systemursache Problemumgehung oder Abhilfemaßnahme
Program content must contain at least one source file. program_content.source_files ist leer. Geben Sie mindestens eine Quelldatei an.
source_files entries must have a non-empty path. Ein Eintrag in der Quelldatei enthält einen leeren path-String. Geben Sie für jede Quelldatei einen gültigen relativen Pfad an.
source_files entry has empty content; path: <path> Ein Eintrag in der Quelldatei enthält einen leeren String. Füllen Sie die Datei mit Inhalten.
Program content must contain at least one EVOLVE-BLOCK-START / EVOLVE-BLOCK-END region with editable code between the markers (whitespace and comment-only regions don't count -- AlphaEvolve has nothing to mutate). Evolve-Blöcke enthalten nur Kommentare, Docstrings oder Leerzeichen, aber keinen bearbeitbaren Code. Der Block muss mindestens eine Zeile mit bearbeitbarem Code enthalten, z. B. Funktionsdefinitionen oder Algorithmuslogik.

Fehler bei der Konfiguration und Modellvalidierung

Fehlermeldung Systemursache Problemumgehung oder Abhilfemaßnahme
unsupported model: <model_name> Das angeforderte Modell wird nicht unterstützt oder ist für Ihr Projekt nicht aktiviert. Unterstützte Modelle verwenden Weitere Informationen finden Sie unter Einstellungen für die Generierung.
model '<model_name>' is not served from domain shard '<location>'. Das Modell ist am angegebenen regionalen Standort nicht verfügbar. Informationen zu unterstützten Modellen und Standorten finden Sie unter Einstellungen für die Generierung.
generation_settings.models must contain at most 2 distinct models; got <count>. In generation_settings.models wurden mehr als zwei Modellkonfigurationen angegeben. Geben Sie maximal zwei Modelle in der Mischung an.
generation_settings.models contains duplicate entry: <model_name> Derselbe Modellname kommt in generation_settings.models mehr als einmal vor. Entfernen Sie doppelte Modelleinträge.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. Das Gewicht für die Modellstichprobenerhebung ist negativ, null oder nicht endlich. Legen Sie ein positives Gewicht fest oder entfernen Sie den Eintrag.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. Die Modelltemperatur liegt außerhalb des gültigen Bereichs [0.0, 2.0]. Stelle die Temperatur auf einen Wert zwischen 0.0 und 2.0 ein.
RunSettings.max_programs is required and must be greater than 1. max_programs wurde weggelassen oder auf 1 oder weniger festgelegt. Setzen Sie max_programs auf 2 oder höher. Mindestens 2 sind erforderlich, um weiterentwickelte Kandidaten zuzulassen.
RunSettings.concurrency is required and must be positive. concurrency wurde weggelassen oder auf 0 oder weniger festgelegt. Setzen Sie concurrency auf eine positive Ganzzahl (in der Regel 1–30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability liegt außerhalb von [0.0, 1.0]. Legen Sie eine Wahrscheinlichkeit zwischen 0.0 und 1.0 fest.

Projektvoraussetzungen und Fehler im Testlebenszyklus

Fehlermeldung Systemursache Problemumgehung oder Abhilfemaßnahme
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> Die Vertex AI API (aiplatform.googleapis.com) ist für das Projekt Google Cloud nicht aktiviert. Führen Sie gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID aus.
Project has reached the limit of 30 concurrently active AlphaEvolve experiments in location <location>. Stop or wait for a running experiment to finish before starting or resuming another. Das Projekt hat das Kontingent von 30 gleichzeitig aktiven (STARTED- oder RUNNING-)Tests an diesem Standort erreicht. Stoppen Sie laufende Tests oder schließen Sie sie ab, bevor Sie einen neuen Test starten oder fortsetzen.
Cannot <action> experiment from state <current_state> Es wurde versucht, einen ungültigen Statusübergang durchzuführen, z. B. einen bereits laufenden Test zu starten oder einen neu erstellten Test fortzusetzen. Achten Sie darauf, dass die Lebenszyklusübergänge von Tests standardmäßig erfolgen: CREATED → START, PAUSED/COMPLETED → RESUME, STARTED/RUNNING → STOP.
Cannot resume experiment: a start or watchdog message is already pending. Stop the experiment first to drain it, or wait for the pending delivery to complete. Ein vorheriger Start- oder Fortsetzungsvorgang wird noch ausgeführt. Warten Sie, bis die ausstehende Zustellung abgeschlossen ist, oder rufen Sie STOP an, um ausstehende Nachrichten zu leeren.
AlphaEvolve is not available for this project. Das Projekt ist blockiert oder es handelt sich um ein nicht unterstütztes Compliance-Profil. Weitere Informationen finden Sie unter Compliance- und Sicherheitsprofil.

Fehler bei der Programmauswahl und ‑bewertung

Fehlermeldung Systemursache Problemumgehung oder Abhilfemaßnahme
Exactly one evaluation submission is required. Mehrere Einreichungen für die Bewertung wurden in einer einzigen submitProgramsEvaluations-Anfrage zusammengefasst. Senden Sie Auswertungen einzeln, eine pro API-Aufruf.
Program is required for each evaluation submission./submission.program is required. Der Ressourcenpfad program wurde bei der Einreichung der Bewertung nicht angegeben. Übergeben Sie den vollständigen Ressourcenpfad des Programms.
Lock token is required for each evaluation submission./submission.lock_token is required. Der während acquirePrograms zurückgegebene lock_token wurde ausgelassen. Übergeben Sie den genauen lock_token-String, der beim Erwerb des Programms zurückgegeben wurde.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' Das im Beitrag gesendete Sperrtoken stimmt nicht mit dem aktiven Server-Lease überein. Das Lease ist beispielsweise abgelaufen und ein anderer Worker hat es übernommen oder es wurde ein falsches Token angegeben. Gib genau lockToken aus acquirePrograms wieder und sende die Ergebnisse, bevor der Client eine Zeitüberschreitung meldet.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> Das Programm wurde bereits evaluiert, eingestellt oder aus EVALUATION_IN_PROGRESS herausgelöst. Verwerfen Sie die alte Bewertung oder fordern Sie den Kandidaten noch einmal an, falls verfügbar.
The request was rejected by a safety policy. Die Eingabeproblembeschreibung, der ursprüngliche Code oder die Bewertungsmetriken haben Sicherheitsklassifizierungsrichtlinien ausgelöst. Bereinigen Sie Prompt-Text und Problembeschreibungen, um sensible Keywords oder Spuren zu entfernen.
The input safety classifier is currently unavailable. Der Dienst zur Sicherheitsklassifizierung ist vorübergehend nicht erreichbar oder überlastet (Fails Closed). Implementieren Sie eine Wiederholungslogik mit exponentiellem Backoff.

„Stille“ App-Entfernungen beheben

Ein Sicherheitsfilter-Intercept (stiller Drop) tritt auf, wenn serverseitige Sprachmodelle mutierte Kandidaten-Prompts aufgrund sensibler Formulierungen oder Auslöser von Sicherheitsregeln kennzeichnen und löschen. Der Server unterdrückt die Ausgabe, sodass in der Warteschlange leere Antworten zurückgegeben werden und Client-Runner möglicherweise unbegrenzt warten.

Workaround-Lösung:

  • Kontext bereinigen:Entfernen Sie emotional aufgeladene oder sicherheitssensible Formulierungen aus dem problemDescription.

  • Insights filtern:Rohausnahmetraces oder Terminal-stderr-Logs in der insights-Nutzlast parsen und kürzen, um zu verhindern, dass unsichere Systeminhalte, die Downstream-Filter auslösen, wiedergegeben werden.

  • Datasets lokalisieren:Platzieren Sie keine Trainingsdatensätze oder großen Textkorpora in Prompts, sondern laden Sie sie während der Ausführung der Evaluationsschleife lokal in der Clientumgebung.

Best Practices für die clientseitige Auswertung

Der Engpass „Spaghetti-Code“

Eine suboptimale Quellformatierung beeinträchtigt die Optimierungsqualität: „Spaghetticode == Rauschen im Suchraum“. Bevor Sie EVOLVE-BLOCK-Markierungen platzieren:

  • Codeblöcke so umgestalten, dass Variablen und Funktionssignaturen eindeutig benannt sind.

  • Fügen Sie aussagekräftige, prägnante Docstrings hinzu, in denen Sie erklären, was jede Funktion oder Variable tut und warum. Docstrings müssen sich neben dem tatsächlichen funktionalen Code befinden. Wenn Sie nur einen Docstring oder Kommentare in ein EVOLVE-BLOCK einfügen, wird dies als leerer Block abgelehnt.

  • Achten Sie darauf, dass die Kommentarzeichen EVOLVE-BLOCK-START und EVOLVE-BLOCK-END allein in ihren jeweiligen Zeilen stehen, mit Ausnahme von führenden Leerzeichen und Kommentarpräfixen (z. B. # oder //).

  • Alle externen, unveränderlichen Abhängigkeiten (z. B. das Importieren von Hilfsmodulen oder das Laden statischer Daten) müssen sich außerhalb von EVOLVE-BLOCK befinden.

Zuweisung des Kontextfensters

Um die Kreativität der Mutationen zu maximieren, sollten Sie die an die API gesendete Code-Nutzlast begrenzen. Der gesamte Programmkontext sollte zwischen 150.000 und 200.000 Tokens liegen. Große Blöcke mit statischem, unveränderlichem Boilerplate-Text beanspruchen die Aufmerksamkeit des Modells und beeinträchtigen die Leistung. Verschieben Sie Hilfsskripts, Pipelines für die Datenaufnahme und umfangreiche Validierungsbibliotheken vollständig in den clientseitigen Evaluator.

Zuerst das ursprüngliche Programm vorbereiten

Bevor Sie AlphaEvolve ausführen, sollten Sie einen Standard-Coding-Agent verwenden, um sowohl Ihre Seed-Codebasis als auch Ihren Evaluator zu debuggen:

  • Seed vorbereiten:Beheben Sie offensichtliche Syntaxfehler, Kompilierungsprobleme und Grenzfälle.

  • Ausgangspunkt überprüfen:Prüfen Sie, ob der Ausgangswert angemessen ist und ob der Evaluator vollständig deterministisch ist (derselbe Code + dieselbe Eingabe = derselbe Wert).

  • Mit ungültigen Eingaben testen:Führen Sie den Evaluator mit absichtlich fehlerhaften Funktionen aus, um zu bestätigen, dass er Compilerprobleme erkennt, Endlosschleifen ordnungsgemäß behandelt und hohe negative Strafpunktzahlen zurückgibt.

Überoptimierte Baselines vermeiden

Verwenden Sie kein bereits stark optimiertes Baseline-Programm als Ausgangspunkt. Wenn Ihr ursprüngliches Programm bereits nahezu optimal ist, kann AlphaEvolve nur schwer eine Steigerung erzielen, da es nur wenig Spielraum für Verbesserungen gibt. Beginnen Sie mit einer angemessenen, aber nicht maximal optimierten Baseline. So hat AlphaEvolve die Möglichkeit, verschiedene Ideen zu entwickeln und zu optimieren.

Clientseitige Runner-Sicherheitsmaßnahmen

Clientseitige Evaluatoren müssen strenge Sicherheitsmaßnahmen erzwingen, um zu verhindern, dass böswillige, ressourcenintensive oder nicht reagierende Kandidaten parallele Worker zum Stillstand bringen:

  • Strenge Zeitüberschreitungen:Erzwingen Sie eine strenge Ausführungszeit von 30 Minuten (oder weniger, je nach Struktur des Suchbereichs).

  • Einreichung mit Zeitüberschreitung: Wenn eine Kandidatenprogrammvariante das Zeitlimit überschreitet, beenden Sie den Ausführungsthread sofort. Lassen Sie den Kandidatenprozess nicht fehlschlagen. Kompiliere und sende stattdessen sofort einen schweren Fehler-Penalty-Score (z. B. -100000.0) zusammen mit einer aussagekräftigen Debug-Information zurück an den Server, um die Warteschlangensperre des Programms aufzuheben.

  • AST-Sicherheitsfilter:Führen Sie vor der Kompilierung immer eine AST-Prüfung (Abstract Syntax Tree) für die eingehende Quellcode-Nutzlast durch. Die Ausführung wird sofort abgebrochen und eine schwere Fehlerstrafe wird angewendet, wenn eingeschränkte Reflexions- oder Ausführungsprimitive (z. B. eval, exec, getattr oder setattr) erkannt werden.

Weitere Ressourcen

Weitere Informationen finden Sie in den folgenden Ressourcen: