Nota: Este conjunto de documentación es para las ediciones Standard, Plus, de pago por uso y Frontline de Gemini Enterprise. Para obtener la documentación de la edición Business, consulta el Centro de ayuda de Gemini Enterprise Business.

Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Referencia de la API de AlphaEvolve

Este documento sirve como referencia de la API autorizada y de nivel de producción, y como especificación del sistema para la API de Cloud de AlphaEvolve en las capas conversacionales de Google Cloud Discovery Engine. Define las jerarquías de recursos anidados precisas, los extremos de REST y gRPC, las restricciones a nivel de campo, las máquinas de estado del ciclo de vida, las matrices de diagnóstico de errores, las reglas de zona de pruebas de seguridad y los flujos de trabajo de integración necesarios para diseñar un controlador del cliente y un bucle de evaluación completamente automatizados.

Máquinas de estado de ciclo de vida unificadas

El agente de AlphaEvolve coordina dos máquinas de estado independientes para supervisar el progreso de la campaña experimental y administrar la entrega y la ejecución de mutaciones de programas individuales.

Estados del ciclo de vida de los experimentos

Un experimento representa la campaña de optimización general. Se procesa como un recurso persistente del servidor y pasa por los siguientes estados:

CREATED: Es el estado de inicialización. El recurso se declara y configura, pero aún no propagó las generaciones iniciales ni envió llamadas a la API.
RUNNING: Es el estado de evaluación activo. El motor muestrea de forma simultánea los candidatos superiores, genera mutaciones de código a través de la combinación de LLM y transmite tareas a los evaluadores.
PAUSED: Es un estado de retención temporal que se activa de forma manual o a través de un idle_timeout de protección automatizado. Se detiene la generación de código y los trabajadores existentes pausan la entrega de métricas.
COMPLETED: Es un estado terminal que indica que la búsqueda completó correctamente su asignación de destino de max_programs o alcanzó su límite de generación estructural.
FAILED: Es un estado de error terminal que indica que los problemas sistémicos del entorno, como las excepciones de credenciales de la API no detectadas, los daños en el almacén de datos o los pánicos consecutivos del ejecutor, detuvieron la ejecución del procesamiento.

Estados del programa

La secuencia de validación del entorno de ejecución se aplica a las variantes candidatas individuales.

Cada mutación de código generada se comporta como una entidad de programa aislada que pasa por una secuencia de estados operativos detallados dentro de la base de datos de la población.

INITIALIZED: Se crea la entrada del programa en la base de datos, con un seguimiento de su pedigrí ancestral y de los vínculos con el programa superior.
GENERATING: Se envía de forma activa una tarea al backend de la mezcla de modelos de lenguaje para redactar o mutar los bloques de código funcionales específicos.
EVALUATING: Un proceso de trabajador de evaluación bloquea la carga útil del código y la ejecuta dentro de un entorno de agente de pruebas aislado.
COMPLETED: Las puntuaciones de ejecución y las estadísticas estructurales descriptivas se confirman de forma segura en la base de datos evolutiva, y el programa se agrega al grupo de selección.

Mecánica de simultaneidad y bloqueo

Los bucles de trabajadores adquieren los programas con un mecanismo de token de bloqueo atómico para evitar condiciones de carrera o sobrecarga de puntuación duplicada en topologías distribuidas. El evaluador debe enviar el esquema de puntuación finalizado junto con el token de bloqueo de concordancia exacta para confirmar correctamente los resultados en la base de datos.

Esquemas de configuración

Descripción general de los parámetros de configuración, los parámetros y los valores predeterminados del esquema principal que utiliza el entorno de ejecución del motor de AlphaEvolve.

`AlphaEvolveExperimentConfig`

Define los parámetros estructurales principales y las restricciones programáticas de la ejecución del experimento evolutivo.

Nombre del campo	Tipo	Predeterminado	Restricciones / límites de valor	Descripción técnica
`title`	cadena	Obligatorio	Máx. 256 caracteres	Es el nombre visible único del experimento.
`problemDescription`	cadena	Obligatorio	Máx. 5,000 caracteres	La especificación formal del problema. Se inserta directamente en los contextos de las instrucciones para establecer reglas.
`programLanguage`	cadena	Obligatorio	Valor de formato libre	Es el idioma de destino de la base de código evolucionada (por ejemplo, `"python"`, `"cpp"`, `"verilog"`, `"cuda"`, `"julia"`, `"java"`).
`runSettings`	objeto	Obligatorio	Se asigna al esquema `RunSettings`	Parámetros de ritmo y tiempo de espera
`generationSettings`	objeto	Optional	Se asigna al esquema `GenerationSettings`	Selección de modelos y parámetros de contexto
`evolutionSettings`	objeto	Optional	Se asigna al esquema `EvolutionSettings`	Parámetros de selección de padres y diversidad.

RunSettings

Controla el ritmo de la capacidad de procesamiento, los límites de paralelización y los tiempos de espera automáticos del sistema.

Nombre del campo	Tipo	Predeterminado	Restricciones / límites de valor	Descripción técnica
`maxPrograms`	int32	100	Mín.: 2; máx.: 100, 000	Es el presupuesto total de ejecución (programas para generar y evaluar). Debe ser superior a 1.
`concurrency`	int32	1	Mín.: 1, máx.: 30	Es la cantidad de mutaciones de programas paralelas activas en la cola. No se permiten valores superiores a 30.
`maxDuration`	cadena	24 h (86,400 s)	Cadena dayTimeDuration ISO 8601 Mín.: >0, Máx.: 7 días	Es el tiempo total de reloj permitido antes de que se detenga el experimento.
`idleTimeout`	cadena	5 h (EE.UU./UE) 2 h (global)	Cadena dayTimeDuration ISO 8601 Mín.: >0 Máx.: el valor predeterminado de la ubicación	Es la duración de la inactividad antes de la transición automática a `PAUSED`. El valor predeterminado es de 2 horas en `global` y de 5 horas en ubicaciones regionales (`us`, `eu`). La duración está limitada por el valor predeterminado de la ubicación, por lo que se ignora si se especifica un valor superior al predeterminado de la ubicación (por ejemplo, 12 h en `global`) y el valor es de 2 horas (sin error).

Configuración de generación

El esquema GenerationSettings controla el ensamblaje de instrucciones, las ventanas de contexto y los parámetros de configuración del modelo para las mutaciones:

context (cadena): Es la documentación de referencia opcional proporcionada por el usuario, las APIs complementarias o las reglas. Se recomienda estrictamente mantenerse por debajo de los 200,000 tokens. Los tamaños de contexto que superan los 200,000 tokens diluyen la atención del modelo y degradan la calidad de la mutación.
includeFullProgramInPrompt (bool): El valor predeterminado es false.
- true: La instrucción de mutación incluye el EVOLVE-BLOCK mutable y el código estándar inmutable circundante (muy recomendado para el razonamiento estructural complejo).
- false: Solo se puede ver el bloque mutable, lo que ahorra contexto de tokens.
models (array de objetos): Es opcional. Cada entrada nombra un modelo y le asigna un weight opcional, que es el porcentaje de llamadas de generación de ese modelo en relación con las otras entradas. Si omites models, AlphaEvolve lo establece en el modelo predeterminado cuando crea el experimento. El valor predeterminado cambia a medida que se lanzan modelos de Gemini más nuevos. En Modelo predeterminado, se indica qué modelo se aplica en qué fecha. Para elegir el modelo por tu cuenta o mantener el mismo modelo en cada ejecución, establece models.

En el siguiente ejemplo, se envían alrededor de nueve de cada diez llamadas de generación al primer modelo y el resto al segundo. Los pesos son proporciones, por lo que no es necesario que sumen 1.
```
"models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]
```

Modelos compatibles

Establece models[].name en uno de los siguientes valores. Puedes combinar un máximo de dos modelos en un solo experimento.

Nombre del modelo	Regiones de entrega
`gemini-4-argon`	`global`, `us`, `eu`
`gemini-3.8-flash`	`global`, `us`, `eu`
`gemini-3.7-flash`	`global`, `us`, `eu`
`gemini-3.5-flash`	`global`, `us`, `eu`
`gemini-3.1-pro-preview`	`global`

AlphaEvolve valida models cuando crea el experimento y devuelve INVALID_ARGUMENT para un nombre de modelo que no está en esta tabla o que no está disponible en la región que solicitaste.

Modelo predeterminado

En la siguiente tabla, se indica el modelo que usa AlphaEvolve cuando omites models, por fecha de creación del experimento.

Se creó el experimento	Modelo predeterminado
El 26 de octubre de 2026 o después	`gemini-4-argon`
Del 29 de septiembre al 25 de octubre de 2026	`gemini-3.8-flash`
Del 30 de junio al 28 de septiembre de 2026	`gemini-3.5-flash`
Antes del 30 de junio de 2026	`gemini-2.5-flash`

Para identificar el modelo asignado a un experimento, verifica generationSettings.models en la configuración del experimento o en la respuesta de creación. Debido a que los cambios se aplican durante el día de transición, los experimentos creados en esas fechas pueden recibir el modelo predeterminado antiguo o el nuevo. Los experimentos creados sin models antes del 30 de junio de 2026 no contienen un valor para este campo.

Debido a que el modelo se almacena en cada experimento, un cambio en el valor predeterminado no afecta a los experimentos que ya existen. Para usar un modelo predeterminado más reciente, crea un experimento nuevo.

Configuración de evolución

El esquema EvolutionSettings controla la reinicialización del modelo de islas y las probabilidades de muestreo de los padres:

parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (número de punto flotante): Es la probabilidad (de 0.0 a 1.0) de muestrear programas superiores directamente desde la frontera de Pareto activa en lugar de usar la selección estándar basada en la aptitud. Este parámetro se debe establecer en 0.0 (inhabilitado) si las métricas optimizadas devuelven solo una métrica escalar.

Modelos de datos de programas de candidatos

En esta sección, se describen los esquemas y las representaciones de datos que se usan para definir y organizar las estructuras de código de los candidatos dentro de la base de datos de la población.

AlphaEvolveProgramContent

Define los archivos y la composición estructural del programa candidato.

files (array de AlphaEvolveSourceFile): Es una lista de todos los archivos que componen la base de código candidata. La carga útil debe contener al menos un archivo de origen. Google recomienda mantener el recuento total de archivos en 50 archivos por programa candidato. Esto proporciona una atención óptima del modelo y eficiencia de la ventana de contexto.
description (cadena): Es un resumen generado de forma automática que describe los cambios programáticos sugeridos por el modelo generativo (máximo de 1,000 caracteres).

AlphaEvolveSourceFile

Representa un archivo de código fuente individual en la base de código.

path (cadena): Es el destino de la ruta de acceso relativa al espacio de trabajo (obligatorio, 256 caracteres como máximo). Cada entrada de archivo de origen debe especificar una ruta de acceso no vacía. Si configuras un lugar de trabajo de Python, el punto de entrada del archivo ejecutable principal debe llamarse exactamente "initial_program.py".
content (cadena): Es la cadena de código fuente sin procesar que comprende los bloques de implementación funcionales. Google recomienda mantener el tamaño acumulativo de la base de código en todos los archivos por debajo de 4,000 a 5,000 líneas de código (LOC). Esto es óptimo para el rendimiento de la atención del modelo y la generación de mutaciones.
programLanguage (string): Es la etiqueta de asignación del analizador de lenguaje. Esta cadena debe coincidir de forma explícita con el idioma designado en la configuración del experimento superior.
description (cadena): Es un resumen opcional que describe la arquitectura o el propósito individual del archivo, que se expone al LLM durante los pases de mutación (máximo de 500 caracteres).

AlphaEvolveProgramEvaluation

Es la carga útil estructurada que las instancias de ejecutor de cliente envían de vuelta a la base de datos evolutiva después de la ejecución del entorno de ejecución.

scores (AlphaEvolveScores): Son valores de métricas numéricas objetivos y estandarizados. Las prácticas recomendadas indican que se debe restringir esto a entre 3 y 5 métricas de números de punto flotante distintas, ya que las dimensiones objetivo excesivas degradan el rendimiento del comparador de Pareto de varios objetivos.
insights (array de AlphaEvolveEvaluationInsight): Etiquetas semánticas de diagnóstico y seguimientos de ejecución en lenguaje natural que se devuelven para ayudar a los intentos posteriores de generación de mutaciones del LLM (máximo recomendado de 10 elementos).

Formulación de puntuaciones y formatos de transferencia

La regla de maximización

AlphaEvolve funciona fundamentalmente como un algoritmo de ascenso de colinas monótono y maximiza estrictamente todas las métricas numéricas. Si tu canalización de evaluación hace un seguimiento de un objetivo de minimización (como minimizar la latencia de la aplicación en milisegundos o reducir el uso de memoria), debes negar el valor antes de volver a enviarlo a la base de datos: submitted_score = -latency_ms.

Lo ideal es que las puntuaciones sean continuas. Las métricas booleanas o muy discretas no proporcionan una señal de gradiente suficiente para una exploración eficaz de ascenso de colinas.

Esquema de transferencia de un solo objetivo

Usa el siguiente JSON cuando tu sistema de evaluación realice optimizaciones en función de un solo objetivo escalar.

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

Esquema de transferencia de varios objetivos

Usa el siguiente JSON cuando pases parámetros de seguimiento de varios objetivos independientes para activar las rutinas de optimización de la frontera de Pareto del servidor.

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

Recupera y consulta datos de programas

El sistema AlphaEvolve registra el registro del sistema, las métricas de ejecución y el código fuente completo de cada mutación generada, lo que permite a los desarrolladores consultar este almacén de datos histórico con la API o la CLI para hacer un seguimiento del progreso de la optimización y extraer los candidatos de código con el mejor rendimiento.

Recuperación de programas con la API de REST

Los recursos de programas evaluados se pueden consultar desde la base de datos con el extremo ListAlphaEvolvePrograms estándar con parámetros de consulta de filtrado y ordenamiento:

Filtrado por estado: Consulta los programas que coinciden con un estado específico del ciclo de vida:
```
GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED
```
Clasificación basada en métricas: Recupera candidatos ordenados según métricas optimizadas:
```
GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5
```

Recuperación de programas con la CLI

Para extraer los candidatos completados principales directamente desde la terminal, ejecuta el siguiente comando:

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

Ejemplos completos de uso de la CLI

La CLI de AlphaEvolve proporciona a los desarrolladores un control administrativo y una supervisión rápidos de las campañas directamente desde la shell:

Enumera todos los experimentos de una sesión de conversación:
```
ae experiment list
```
Enumera todos los programas candidatos mutados para un experimento específico:
```
ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"
```
Reemplaza EXPERIMENT_NICKNAME por el nombre de tu experimento.
Recupera los candidatos de código completados con mejor rendimiento:
```
ae results best EXPERIMENT_NICKNAME --top 5
```
Reemplaza EXPERIMENT_NICKNAME por el nombre de tu experimento.
Sigue estos pasos para reanudar una campaña detenida:
```
ae experiment resume EXPERIMENT_NICKNAME
```
Reemplaza EXPERIMENT_NICKNAME por el nombre de tu experimento.

Directorio de extremo de API de REST principal

Todos los extremos tienen versiones en v1alpha de la API de Discovery Engine de Google Cloud .

Patrón de la ruta de acceso del recurso superior

El URI del recurso superior anidado verdadero se estructura de la siguiente manera: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

AlphaEvolve está disponible en global, us y eu. Si creas experimentos en otras ubicaciones, se mostrará FAILED_PRECONDITION.
No se admiten los proyectos de Assured Workloads.
Un proyecto está limitado a 30 experimentos de AlphaEvolve activos de forma simultánea (STARTED o RUNNING) por ubicación. Si inicias o reanudas un experimento que supera este límite, se muestra RESOURCE_EXHAUSTED.

Crea un experimento (POST)

Path:

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

Cuerpo de la solicitud: AlphaEvolveExperimentConfig (consulta la sección 2.1)
Respuesta: Es el recurso AlphaEvolveExperiment que contiene la campaña inicializada.
Estado HTTP: 200 OK

Ejemplos de cargas útiles de la API

Ejemplo de cuerpo de la solicitud (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
        }
      }
    }
  }
}

Ejemplo de cuerpo de respuesta (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
        }
      }
    }
  }
}

Iniciar experimento (POST)

Path:

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

Cuerpo de la solicitud: StartExperimentRequest
Advertencia de baja: El campo de cuerpo initialProgram está obsoleto y se ignora.
Respuesta: GoogleLongrunningOperation (LRO).
Estado HTTP: 200 OK (el estado cambia de CREATED a RUNNING)

Ejemplos de cargas útiles de la API

Ejemplo de cuerpo de la solicitud
```
{
  "desiredProgramsCount": 1
}
```

Ejemplo de cuerpo de respuesta (200 OK: operación de larga duración)

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

Adquirir programas (POST)

Path:

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

Cuerpo de la solicitud: AcquireProgramsRequest
- desiredProgramsCount (int32): Es el recuento de lotes opcional de programas mutados que se recuperarán (el valor predeterminado es 1 cuando no se establece).
Estados de respuesta:
- 200 OK: Devuelve una respuesta que contiene recursos AlphaEvolveProgram bloqueados.
- 204 No Content: La fila está vacía o la campaña está detenida. Los ejecutores deben suspenderse (por ejemplo, 15 segundos) y volver a intentarlo.

Ejemplos de cargas útiles de la API

Ejemplo de cuerpo de la solicitud
```
{
  "desiredProgramsCount": 1
}
```

Ejemplo del cuerpo de la respuesta (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    ..."
          }
        ]
      }
    }
  ]
}

Ejemplo del cuerpo de la respuesta (204 Sin contenido)

Se devuelve el estado HTTP 204 con un contexto de carga útil vacío.

Envía evaluaciones de programas (POST)

Path:

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

Cuerpo de la solicitud: SubmitProgramsEvaluationsRequest
- evaluationSubmissions (array): Contiene el lockToken coincidente, la ruta de acceso del recurso del programa calificado y la carga útil de la evaluación (puntuaciones y estadísticas). La API acepta exactamente un envío de evaluación por llamada. El procesamiento por lotes de varias evaluaciones en una sola solicitud se rechaza con INVALID_ARGUMENT. Cuando evalúes varios candidatos, envía cada programa de forma individual.
Respuesta: SubmitProgramsEvaluationsResponse (vacía).
Estado HTTP: 200 OK (guarda las puntuaciones, libera el bloqueo activo y registra las estadísticas)

Ejemplos de cargas útiles de la API

Ejemplo de cuerpo de la solicitud

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

Ejemplo del cuerpo de la respuesta (200 OK)
```
{}
```

Reanuda el experimento (POST)

Path:

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

Cuerpo de la solicitud: ResumeExperimentRequest
Respuesta: GoogleLongrunningOperation (LRO).
Estado HTTP: 200 OK (el estado cambia de PAUSED a RUNNING)

Ejemplos de cargas útiles de la API

Ejemplo de cuerpo de la solicitud
```
{}
```

Ejemplo de cuerpo de respuesta (200 OK: operación de larga duración)

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

Enumera programas (GET)

Path:

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

Parámetros de consulta:
- stateFilter (cadena): Opcional. Es el filtro de lista estándar, por ejemplo, stateFilter = 'COMPLETED'.
- orderBy (cadena): Opcional. Ordenamiento basado en métricas, por ejemplo, accuracy desc.
Respuesta: ListAlphaEvolveProgramsResponse.
Estado HTTP: 200 OK

Ejemplos de cargas útiles de la API

Ejemplo de URL de consulta de solicitud

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

Ejemplo del cuerpo de la respuesta (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"
}

Referencia de códigos de diagnóstico y solución de problemas

Matriz de códigos de diagnóstico de la API

Estado de HTTP	Tipo de error	Causa del sistema	Acción de solución alternativa o mitigación
400	`INVALID_ARGUMENT`	Marcadores `EVOLVE-BLOCK-START` / `EVOLVE-BLOCK-END` con formato incorrecto (por ejemplo, contenido que comparte la línea del marcador, bloques anidados o falta el marcador de finalización) Bloque de evolución vacío que solo contiene comentarios o espacios en blanco sin código editable. `maxPrograms` se estableció en menos de 2. Campos de configuración no reconocidos. Configuración de modelo no válida (más de dos modelos, entradas duplicadas, pesos no positivos o temperatura fuera de `[0.0, 2.0]`). Enviar varias evaluaciones en una sola llamada `submitProgramsEvaluations` El proyecto es de Assured Workloads.	Asegúrate de que los marcadores estén solos en su línea y que encierren al menos una línea de código que no sea un comentario. Establece `maxPrograms` en 2 o más. Quita los campos que no forman parte de la API, como `notes`, que estaba presente en la versión preliminar de la API. Envía las evaluaciones de forma individual, una por una.
403	`PERMISSION_DENIED`	El emisor no tiene el rol de editor de Discovery Engine (`roles/discoveryengine.editor`) ni el rol de administrador (`roles/discoveryengine.admin`). Nota: `roles/discoveryengine.user` no otorga permisos de AlphaEvolve y `roles/discoveryengine.viewer` no puede obtener experimentos. El emisor no tiene permiso en el recurso de sesión superior. No se asignó ninguna licencia activa de Gemini Enterprise.	Otorga `roles/discoveryengine.editor` o `roles/discoveryengine.admin` a nivel del proyecto y verifica el acceso a la sesión superior. Verificar las licencias activas de Gemini Enterprise Configura las credenciales predeterminadas de la aplicación: `gcloud auth application-default login --project=PROJECT_ID` Nota: Model Armor no es compatible con las configuraciones de AlphaEvolve.
400	`FAILED_PRECONDITION`	El token de bloqueo está inactivo o vencido, o bien el estado del programa no coincide (por ejemplo, el candidato se volvió a adquirir o se finalizó después de que venció el arrendamiento). El experimento se creó en una ubicación no admitida (fuera de `global`, `us` o `eu`). La API de Vertex AI (`aiplatform.googleapis.com`) no está habilitada en el proyecto.	Repite el `lockToken` exacto que devuelve `:acquirePrograms`. Aplica tiempos de espera del cliente (se recomiendan 30 minutos) y envía puntuaciones de penalización por error cuando se agote el tiempo de espera. Vuelve a crear el experimento en una ubicación compatible. Habilita la API de Vertex AI: `gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID`.
429	`RESOURCE_EXHAUSTED`	El proyecto alcanzó el límite de 30 experimentos activos de forma simultánea (`STARTED` / `RUNNING`) por ubicación. Se agotó la cuota de tokens de generación de modelos de backend.	Para el límite de experimentos activos: Completa o detén los experimentos en ejecución antes de iniciar uno nuevo (disminuir el valor de `concurrency` en `runSettings` no afecta este límite). Para la cuota de tokens del modelo: Reduce `concurrency` en `runSettings` e implementa la retirada exponencial.
503	`SERVICE_UNAVAILABLE`	El clasificador de seguridad de entradas no está disponible o el servicio de backend está sobrecargado temporalmente.	Implementar un bucle de reintento con retirada exponencial aleatorizada en el cliente

Mensajes de error comunes y soluciones

En la siguiente referencia, se enumeran los mensajes de error comunes que devuelve la API, sus causas subyacentes y los pasos para resolverlos.

Errores de análisis del programa inicial y de EVOLVE-BLOCK

Mensaje de error	Causa del sistema	Acción de solución alternativa o mitigación
`Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line.`	Los marcadores `EVOLVE-BLOCK-START` y `EVOLVE-BLOCK-END` aparecen en la misma línea.	Coloca los marcadores de inicio y finalización en líneas separadas.
`Parsing error: Unexpected content on the same line as <marker> in line <line_number>.`	El código, el texto o los caracteres finales comparten la línea con un marcador `EVOLVE-BLOCK-START` o `EVOLVE-BLOCK-END`.	Asegúrate de que el marcador esté solo en su línea (precedido únicamente por el prefijo de comentario, como `# EVOLVE-BLOCK-START`).
`Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks.`	Aparece un marcador `EVOLVE-BLOCK-START` dentro de un bloque de evolución que ya está abierto.	Quita los marcadores de inicio anidados. No se admiten los bloques de evolución anidados.
`Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started.`	Aparece un marcador `EVOLVE-BLOCK-END` sin un `EVOLVE-BLOCK-START` anterior.	Asegúrate de que cada marcador de finalización esté precedido por un marcador de inicio coincidente.
`Parsing error: Evolve block started but not ended.`	Se encontró un marcador `EVOLVE-BLOCK-START` sin un marcador de cierre `EVOLVE-BLOCK-END` coincidente.	Agrega un marcador `EVOLVE-BLOCK-END` de cierre.

Errores de contenido y estructura del programa

Mensaje de error	Causa del sistema	Acción de solución alternativa o mitigación
`Program content must contain at least one source file.`	`program_content.source_files` está vacío.	Proporciona al menos un archivo de origen.
`source_files entries must have a non-empty path.`	Una entrada de archivo de origen tiene una cadena `path` vacía.	Especifica una ruta de acceso relativa válida para cada archivo de origen.
`source_files entry has empty content; path: <path>`	Una entrada de archivo de origen contiene contenido de cadena vacío.	Completa el contenido del archivo.
`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).`	Los bloques de Evolve solo contienen comentarios, cadenas de documentación o espacios en blanco, sin código editable.	Incluye al menos una línea de código editable (como definiciones de funciones o lógica de algoritmos) dentro del bloque.

Errores de validación de la configuración y del modelo

Mensaje de error	Causa del sistema	Acción de solución alternativa o mitigación
`unsupported model: <model_name>`	El modelo solicitado no es compatible o no está habilitado para tu proyecto.	Usa modelos compatibles. Consulta Configuración de generación.
`model '<model_name>' is not served from domain shard '<location>'.`	El modelo no está disponible en la ubicación regional especificada.	Consulta Configuración de generación para conocer los modelos y las ubicaciones compatibles.
`generation_settings.models must contain at most 2 distinct models; got <count>.`	Se especificaron más de dos parámetros de configuración del modelo en `generation_settings.models`.	Especifica, como máximo, dos modelos en la combinación.
`generation_settings.models contains duplicate entry: <model_name>`	El mismo nombre de modelo aparece más de una vez en `generation_settings.models`.	Quita las entradas de modelo duplicadas.
`generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero.`	El peso de muestreo del modelo es negativo, cero o no finito.	Establece un peso positivo o quita la entrada.
`generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>.`	La temperatura del modelo está fuera del rango válido `[0.0, 2.0]`.	Ajusta la temperatura a un valor entre `0.0` y `2.0`.
`RunSettings.max_programs is required and must be greater than 1.`	Se omitió `max_programs` o se estableció en 1 o menos.	Establece `max_programs` en 2 o más (se requiere un mínimo de 2 para admitir candidatos evolucionados).
`RunSettings.concurrency is required and must be positive.`	Se omitió `concurrency` o se estableció en 0 o menos.	Establece `concurrency` en un número entero positivo (por lo general, entre 1 y 30).
`EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>.`	`pareto_sampling_probability` está fuera de `[0.0, 1.0]`.	Establece una probabilidad entre `0.0` y `1.0`.

Requisitos previos del proyecto y errores del ciclo de vida del experimento

Mensaje de error	Causa del sistema	Acción de solución alternativa o mitigación
`AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id>`	La API de Vertex AI (`aiplatform.googleapis.com`) no está habilitada en el proyecto Google Cloud .	Ejecuta `gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID`.
`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.`	El proyecto alcanzó la cuota de 30 experimentos activos de forma simultánea (`STARTED` o `RUNNING`) en esa ubicación.	Detén o completa los experimentos existentes antes de iniciar o reanudar uno nuevo.
`Cannot <action> experiment from state <current_state>`	Se intentó realizar una transición de estado no válida (por ejemplo, iniciar un experimento que ya se está ejecutando o reanudar un experimento recién creado).	Asegúrate de que los experimentos sigan las transiciones estándar del ciclo de vida: `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.`	Aún se está ejecutando una operación de inicio o reanudación anterior.	Espera a que se complete la entrega pendiente o llama a `STOP` para vaciar los mensajes pendientes.
`AlphaEvolve is not available for this project.`	El proyecto está bloqueado o es un perfil de cumplimiento no compatible.	Consulta Perfil de cumplimiento y seguridad.

Errores de adquisición y evaluación de programas

Mensaje de error	Causa del sistema	Acción de solución alternativa o mitigación
`Exactly one evaluation submission is required.`	Se agruparon varios envíos de evaluación en una sola solicitud `submitProgramsEvaluations`.	Envía las evaluaciones de forma individual, una por llamada a la API.
`Program is required for each evaluation submission.`/`submission.program is required.`	No se proporcionó la ruta de acceso del recurso `program` en el envío de la evaluación.	Pasa la ruta de acceso completa del recurso del programa.
`Lock token is required for each evaluation submission.`/`submission.lock_token is required.`	Se omitió el `lock_token` que se devolvió durante `acquirePrograms`.	Pasa la cadena `lock_token` exacta que se devolvió cuando se adquirió el programa.
`Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>'`	El token de bloqueo enviado en el envío no coincide con el arrendamiento activo del servidor (por ejemplo, el arrendamiento venció y otro trabajador lo adquirió, o se proporcionó un token incorrecto).	Repite el `lockToken` exacto de `acquirePrograms` y envía los resultados antes de que se agote el tiempo de espera del cliente.
`Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state>`	El programa ya se evaluó, se canceló o se retiró de `EVALUATION_IN_PROGRESS`.	Descarta la evaluación inactiva o vuelve a adquirir el candidato si está disponible.
`The request was rejected by a safety policy.`	La descripción del problema de entrada, el código inicial o las métricas de evaluación activaron las políticas de clasificación de seguridad.	Limpia el texto de las instrucciones y las descripciones de los problemas para quitar las palabras clave o los rastros sensibles.
`The input safety classifier is currently unavailable.`	No se puede acceder al servicio de clasificación de seguridad temporalmente o está sobrecargado (falla cerrado).	Implementa la lógica de reintentos de retirada exponencial.

Corrige las "pérdidas silenciosas"

Una intercepción de filtro de seguridad (descarte silencioso) se produce cuando los modelos de lenguaje del servidor marcan y descartan instrucciones candidatas mutadas debido a frases sensibles o activadores de reglas de seguridad. El servidor silencia el resultado, lo que hace que la cola devuelva respuestas vacías, y los ejecutores del cliente pueden esperar de forma indefinida.

Solución alternativa:

Limpia el contexto: Quita las frases con carga emocional o sensibles para la seguridad del problemDescription.
Filtra las estadísticas: Analiza y trunca los seguimientos de excepciones sin procesar o los registros de stderr de la terminal en la carga útil de insights para evitar que se repita el contenido no seguro del sistema que activa los filtros downstream.
Localiza conjuntos de datos: No coloques registros de entrenamiento ni corpus lingüísticos grandes en las instrucciones; cárgalos de forma local en el entorno del cliente durante la ejecución del bucle de evaluación.

Prácticas recomendadas para la evaluación del cliente

El cuello de botella del "código espagueti"

El formato de origen subóptimo degrada la calidad de la optimización: "Código espagueti == Espacio de búsqueda ruidoso". Antes de colocar marcadores de EVOLVE-BLOCK, haz lo siguiente:

Refactoriza los bloques de código para que las variables y las firmas de funciones tengan nombres claros.
Agrega docstrings descriptivas y concisas que expliquen qué hace cada función o variable y por qué. Asegúrate de que las docstrings residan junto con el código funcional real; colocar solo una docstring o comentarios dentro de un EVOLVE-BLOCK se rechaza como un bloque vacío.
Asegúrate de que los marcadores de comentarios EVOLVE-BLOCK-START y EVOLVE-BLOCK-END se coloquen solos en sus respectivas líneas, excepto los espacios en blanco iniciales y los prefijos de comentarios (como # o //).
Asegúrate de que las dependencias externas e inmutables (como importar módulos auxiliares o cargar datos estáticos) se encuentren fuera de EVOLVE-BLOCK.

Asignación de la ventana de contexto

Para maximizar la creatividad de las mutaciones, limita la carga útil de código que se envía a la API. El contexto total del programa debe permanecer por debajo de 150,000 a 200,000 tokens. Los bloques grandes de código estándar estático e inmutable consumen la atención del modelo y disminuyen el rendimiento. Mueve las secuencias de comandos de utilidad, las canalizaciones de transferencia de datos y las bibliotecas de validación pesadas por completo al evaluador del cliente.

Prepara el programa inicial primero

Antes de ejecutar AlphaEvolve, usa un agente de programación estándar para depurar tu base de código inicial y tu evaluador:

Prepara la semilla: Corrige errores de sintaxis obvios, problemas de compilación y casos extremos.
Verifica la puntuación inicial: Verifica que la puntuación de referencia sea razonable y que el evaluador sea completamente determinístico (mismo código + misma entrada = misma puntuación).
Prueba con entradas no válidas: Ejecuta el evaluador con funciones dañadas de forma intencional para confirmar que detecta problemas del compilador, controla los bucles infinitos de forma correcta y devuelve puntuaciones de penalización negativas altas.

Evita los modelos de referencia demasiado optimizados

No pases un programa de referencia que ya esté muy optimizado como semilla. Si tu programa inicial ya es casi óptimo, AlphaEvolve tendrá dificultades para realizar la búsqueda de ascenso de colinas porque hay muy poco margen de mejora. Comienza con un modelo de referencia razonable, pero no optimizado al máximo. Esto le da a AlphaEvolve espacio para explorar y realizar la búsqueda local.

Protecciones del ejecutor del cliente

Los evaluadores del cliente deben aplicar protecciones estrictas para evitar que los candidatos maliciosos, que consumen muchos recursos o que no responden, detengan a los trabajadores paralelos:

Tiempos de espera estrictos: Aplica un límite de ejecución estricto de 30 minutos (o menos, según la estructura del espacio de búsqueda).
Envío de penalización por tiempo de espera: Si una variante del programa candidato supera el límite de tiempo de espera, finaliza su subproceso de ejecución de inmediato. No permitas que falle el proceso del candidato. En su lugar, compila y envía de inmediato una puntuación de penalización por falla grave (por ejemplo, -100000.0) junto con una estadística de depuración descriptiva al servidor para liberar el bloqueo de la cola del programa.
Filtros de seguridad de AST: Ejecuta siempre una verificación de inspección del árbol de sintaxis abstracta (AST) en la carga útil del código fuente entrante antes de la compilación. Anula de inmediato la ejecución y aplica una penalización por falla grave si se detectan primitivas de reflexión o ejecución restringidas (como eval, exec, getattr o setattr).

Recursos adicionales

Para obtener más información, consulta los siguientes recursos:

Referencia de la API de AlphaEvolve Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Máquinas de estado de ciclo de vida unificadas

Estados del ciclo de vida de los experimentos

Estados del programa

Mecánica de simultaneidad y bloqueo

Esquemas de configuración

AlphaEvolveExperimentConfig

RunSettings

Configuración de generación

Modelos compatibles

Modelo predeterminado

Configuración de evolución

Modelos de datos de programas de candidatos

AlphaEvolveProgramContent

AlphaEvolveSourceFile

AlphaEvolveProgramEvaluation

Formulación de puntuaciones y formatos de transferencia

La regla de maximización

Esquema de transferencia de un solo objetivo

Esquema de transferencia de varios objetivos

Recupera y consulta datos de programas

Recuperación de programas con la API de REST

Recuperación de programas con la CLI

Ejemplos completos de uso de la CLI

Directorio de extremo de API de REST principal

Patrón de la ruta de acceso del recurso superior

Crea un experimento (POST)

Ejemplos de cargas útiles de la API

Iniciar experimento (POST)

Ejemplos de cargas útiles de la API

Adquirir programas (POST)

Ejemplos de cargas útiles de la API

Envía evaluaciones de programas (POST)

Ejemplos de cargas útiles de la API

Reanuda el experimento (POST)

Ejemplos de cargas útiles de la API

Enumera programas (GET)

Ejemplos de cargas útiles de la API

Referencia de códigos de diagnóstico y solución de problemas

Matriz de códigos de diagnóstico de la API

Mensajes de error comunes y soluciones

Errores de análisis del programa inicial y de EVOLVE-BLOCK

Errores de contenido y estructura del programa

Errores de validación de la configuración y del modelo

Requisitos previos del proyecto y errores del ciclo de vida del experimento

Errores de adquisición y evaluación de programas

Corrige las "pérdidas silenciosas"

Prácticas recomendadas para la evaluación del cliente

El cuello de botella del "código espagueti"

Asignación de la ventana de contexto

Prepara el programa inicial primero

Evita los modelos de referencia demasiado optimizados

Protecciones del ejecutor del cliente

Recursos adicionales

Referencia de la API de AlphaEvolve

`AlphaEvolveExperimentConfig`