Observação:este conjunto de documentação é para as edições Standard, Plus, pagamento por uso e Frontline do Gemini Enterprise. Para a documentação da edição Business, consulte a Central de Ajuda do Gemini Enterprise - Business edition.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Referência da API AlphaEvolve

Este documento serve como referência da API oficial e de nível de produção e especificação do sistema para as APIs do Cloud AlphaEvolve nas camadas de conversação do Google CloudDiscovery Engine. Ele define as hierarquias de recursos aninhadas precisas, os endpoints REST e gRPC, as restrições no nível do campo, as máquinas de estado do ciclo de vida, as matrizes de diagnóstico de erros, as regras de sandbox de segurança e os fluxos de trabalho de integração necessários para projetar um controlador do lado do cliente e um loop de avaliação totalmente automatizados.

Máquinas de estado de ciclo de vida unificadas

O agente AlphaEvolve coordena duas máquinas de estado independentes para monitorar a progressão da campanha experimental e gerenciar a entrega e a execução de mutações de programas individuais.

Estados do ciclo de vida do experimento

Um experimento representa a campanha de otimização geral. Ele é processado como um recurso persistente do lado do servidor e passa pelos seguintes estados:

CREATED:o estado de inicialização. O recurso é declarado e configurado, mas ainda não preencheu as gerações iniciais nem enviou chamadas de API.
RUNNING:o estado de avaliação ativo. O mecanismo está simultaneamente amostrando candidatos pai, gerando mutações de código por meio da mistura de LLMs e transmitindo tarefas para avaliadores.
PAUSED:um estado de retenção temporário acionado manualmente ou por uma idle_timeout de proteção automatizada. A geração de código é interrompida, e os workers existentes pausam o envio de métricas.
COMPLETED: um estado terminal que indica que a pesquisa atendeu à meta de alocação de max_programs ou atingiu o limite de geração estrutural.
FAILED:um estado de erro terminal que indica que problemas sistêmicos do ambiente, como exceções de credenciais de API não capturadas, corrupção do repositório de dados ou pânicos consecutivos do executor, interromperam a execução do processamento.

Estados do programa

A sequência de validação do ambiente de execução é aplicada a variantes candidatas individuais.

Cada mutação de código gerada se comporta como uma entidade de programa isolada que passa por uma sequência de estados operacionais granulares no banco de dados da população.

INITIALIZED: a entrada do programa é criada no banco de dados, rastreando o pedigree ancestral e as vinculações do programa pai.
GENERATING:uma tarefa é enviada ativamente ao back-end de mistura de modelos de linguagem para elaborar ou modificar os blocos de código funcionais específicos.
EVALUATING:o payload do código é bloqueado por um processo de worker de avaliação e executado em um ambiente de arcabouço de testes isolado.
COMPLETED:as pontuações de execução e os insights estruturais descritivos são confirmados com segurança no banco de dados evolutivo, e o programa é adicionado ao pool de seleção.

Mecânicas de simultaneidade e bloqueio

Os programas são adquiridos por loops de worker usando um mecanismo de token de bloqueio atômico para evitar disputas ou sobrecarga de pontuação duplicada em topologias distribuídas. O avaliador precisa enviar o esquema de pontuação finalizado com o token de bloqueio de correspondência exata para confirmar os resultados no banco de dados.

Esquemas de configuração e definições

Visão geral das principais configurações, parâmetros e padrões de esquema usados pelo ambiente de execução do mecanismo AlphaEvolve.

`AlphaEvolveExperimentConfig`

Define os principais parâmetros estruturais e as restrições programáticas da execução do experimento evolutivo.

Nome do campo	Tipo	Padrão	Restrições / limites de valor	Descrição técnica
`title`	string	Obrigatório	Máximo de 256 caracteres	Nome de exibição exclusivo do experimento.
`problemDescription`	string	Obrigatório	Máximo de 5.000 caracteres	A especificação formal do problema. Ele é inserido diretamente nos contextos de comando para estabelecer regras.
`programLanguage`	string	Obrigatório	Valor de formato livre	Idioma de destino da base de código evoluída (por exemplo, `"python"`, `"cpp"`, `"verilog"`, `"cuda"`, `"julia"`, `"java"`).
`runSettings`	objeto	Obrigatório	Mapeia para o esquema `RunSettings`	Parâmetros de ritmo e tempo limite.
`generationSettings`	objeto	Opcional	Mapeia para o esquema `GenerationSettings`	Seleção de modelo e parâmetros de contexto.
`evolutionSettings`	objeto	Opcional	Mapeia para o esquema `EvolutionSettings`	Parâmetros de seleção de pais e diversidade.

RunSettings

Controla o ritmo de processamento, os limites de paralelização e os tempos limite automáticos do sistema.

Nome do campo	Tipo	Padrão	Restrições / limites de valor	Descrição técnica
`maxPrograms`	int32	100	Mín.: 2, Máx.: 100.000	Orçamento total de execução (programas para gerar e avaliar). Precisa ser maior que 1.
`concurrency`	int32	1	Mín: 1, Máx: 30	Número de mutações de programa paralelas ativas na fila. Valores maiores que 30 não são permitidos.
`maxDuration`	string	24h (86.400s)	String dayTimeDuration ISO 8601 Mínimo: >0, Máximo: 7 dias	Tempo total permitido antes que o experimento seja interrompido.
`idleTimeout`	string	5h (EUA/UE) 2h (global)	String dayTimeDuration ISO 8601 Mínimo: >0 Máximo: o padrão do local	Duração da inatividade antes da transição automática para `PAUSED`. O padrão é de 2 horas em `global` e 5 horas em locais regionais (`us`, `eu`). A duração é limitada pelo padrão do local. Portanto, especificar um valor acima do padrão do local (por exemplo, 12h em `global`) é ignorado e o valor é de 2 horas (sem erro).

Configurações de geração

O esquema GenerationSettings controla a montagem do comando, as janelas de contexto e as configurações do modelo para mutações:

context (string): documentação de referência opcional fornecida pelo usuário, APIs complementares ou regras. É altamente recomendável ficar abaixo de 200.000 tokens. Tamanhos de contexto que excedem 200.000 tokens diluem a atenção do modelo e prejudicam a qualidade da mutação.
includeFullProgramInPrompt (bool): padrão false.
- true: o comando de mutação inclui o EVOLVE-BLOCK mutável e o boilerplate imutável ao redor (altamente recomendado para raciocínio estrutural complexo).
- false: somente o bloco mutável fica visível, salvando o contexto do token.
models (matriz de objetos): opcional. Cada entrada nomeia um modelo e atribui a ele um weight opcional, que é a parcela de chamadas de geração desse modelo em relação às outras entradas. Se você omitir models, o AlphaEvolve vai defini-lo como o modelo padrão ao criar o experimento. O padrão muda conforme novos modelos do Gemini são lançados. O modelo padrão lista qual modelo se aplica a qual data. Para escolher o modelo ou manter o mesmo modelo em todas as execuções, defina models.

O exemplo a seguir envia cerca de nove em cada dez chamadas de geração para o primeiro modelo e o restante para o segundo. Os pesos são proporções, então não precisam somar 1.
```
"models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]
```

Modelos compatíveis

Defina models[].name como um dos valores a seguir. É possível combinar no máximo dois modelos em um único experimento.

Nome do modelo	Regiões de veiculação
`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`

O AlphaEvolve valida models ao criar o experimento e retorna INVALID_ARGUMENT para um nome de modelo que não está nesta tabela ou que não está disponível na região solicitada.

Modelo padrão

A tabela a seguir lista o modelo que o AlphaEvolve usa quando você omite models, por data de criação do experimento.

Experimento criado	Modelo padrão
A partir de 24 de outubro de 2026	`gemini-4-argon`
De 29 de setembro de 2026 a 23 de outubro de 2026	`gemini-3.8-flash`
De 30 de junho de 2026 a 28 de setembro de 2026	`gemini-3.5-flash`
Até 30 de junho de 2026	`gemini-2.5-flash`

Para identificar o modelo atribuído a um experimento, verifique generationSettings.models na configuração do experimento ou na resposta de criação. Como as mudanças entram em vigor ao longo do dia da transição, os experimentos criados nessas datas podem receber o modelo padrão antigo ou o novo. Os experimentos criados sem models antes de 30 de junho de 2026 não contêm um valor para esse campo.

Como o modelo é armazenado em cada experimento, uma mudança no padrão não afeta os experimentos que já existem. Para usar um modelo padrão mais recente, crie um novo experimento.

Configurações do Evolution

O esquema EvolutionSettings controla a nova propagação do modelo de ilha e as probabilidades de amostragem pai:

parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (float): a probabilidade (0,0 a 1,0) de amostrar programas pai diretamente da fronteira de Pareto ativa em vez de usar a seleção padrão baseada em fitness. Esse parâmetro precisa ser definido como 0.0 (desativado) se as métricas otimizadas retornarem apenas uma única métrica escalar.

Modelos de dados de programas candidatos

Esta seção descreve os esquemas e as representações de dados usados para definir e organizar as estruturas de código candidatas no banco de dados de população.

AlphaEvolveProgramContent

Define os arquivos e a estrutura do programa candidato.

files (matriz de AlphaEvolveSourceFile): uma lista de todos os arquivos que compõem a base de código candidata. O payload precisa conter pelo menos um arquivo de origem. O Google recomenda manter o total de arquivos em 50 por programa candidato. Isso garante a atenção ideal do modelo e a eficiência da janela de contexto.
description (string): um resumo gerado automaticamente que descreve as mudanças programáticas sugeridas pelo modelo de geração (máximo de 1.000 caracteres).

AlphaEvolveSourceFile

Representa um arquivo de código-fonte individual na base de código.

path (string): o destino do caminho relativo ao espaço de trabalho (obrigatório, máximo de 256 caracteres). Cada entrada de arquivo de origem precisa especificar um caminho não vazio. Se você estiver configurando um espaço de trabalho do Python, o ponto de entrada do arquivo executável principal precisa ser nomeado exatamente como "initial_program.py".
content (string): a string de código-fonte bruta que inclui os blocos de implementação funcional. O Google recomenda manter o tamanho cumulativo da base de código em todos os arquivos abaixo de 4.000 a 5.000 linhas de código (LOC). Isso é ideal para a atenção do modelo e a performance de geração de mutações.
programLanguage (string): a tag de mapeamento do analisador de linguagem. Essa string precisa corresponder explicitamente ao idioma designado na configuração do experimento principal.
description (string): um resumo opcional que descreve a arquitetura ou o propósito individual do arquivo, que é exposto ao LLM durante as transmissões de mutação (máximo de 500 caracteres).

AlphaEvolveProgramEvaluation

O payload estruturado enviado pelas instâncias do executor do cliente de volta ao banco de dados evolutivo após a execução do ambiente de execução.

scores (AlphaEvolveScores): valores de métricas numéricas padronizados e objetivos. As práticas recomendadas sugerem restringir isso a 3 a 5 métricas de ponto flutuante distintas. Dimensões de meta excessivas prejudicam o desempenho do comparador de Pareto multiobjetivo.
insights (matriz de AlphaEvolveEvaluationInsight): rótulos semânticos de diagnóstico e traces de execução em linguagem natural transmitidos para ajudar nas tentativas subsequentes de geração de mutação do LLM (máximo recomendado de 10 itens).

Formulação de pontuação e formatos de ingestão

A regra de maximização

O AlphaEvolve opera fundamentalmente como um algoritmo de subida de colina monotônica e maximiza estritamente todas as métricas numéricas. Se o pipeline de avaliação rastrear uma meta de minimização (como minimizar a latência do aplicativo em milissegundos ou reduzir o uso da memória), será necessário negar o valor antes de enviá-lo de volta ao banco de dados: submitted_score = -latency_ms.

O ideal é que as pontuações sejam contínuas. As métricas booleanas ou altamente discretas não fornecem um sinal de gradiente suficiente para uma exploração eficaz de hill climbing.

Esquema de ingestão de objetivo único

Use o JSON a seguir quando o harness de avaliação otimizar em relação a uma única função de objetivo escalar.

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

Esquema de ingestão de vários objetivos

Use o JSON a seguir ao transmitir parâmetros de acompanhamento multiobjetivo independentes para ativar as rotinas de otimização da fronteira de Pareto do lado do 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."
      }
    ]
  }
}

Como buscar e consultar dados do programa

O sistema AlphaEvolve registra o registro do sistema, as métricas de execução e o código-fonte completo de cada mutação gerada, permitindo que os desenvolvedores consultem esse repositório de dados histórico usando a API ou a CLI para acompanhar o progresso da otimização e extrair os candidatos de código com melhor desempenho.

Recuperação de programas usando a API REST

Os recursos do programa avaliados podem ser consultados no banco de dados usando o endpoint padrão ListAlphaEvolvePrograms com parâmetros de consulta de filtragem e classificação:

Filtragem de estado: consulte programas que correspondem a um estado de ciclo de vida específico:
```
GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED
```
Classificação com base em métricas: recupere candidatos classificados com base em métricas otimizadas:
```
GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5
```

Recuperação de programas usando a CLI

Para extrair os principais candidatos concluídos diretamente do terminal, execute o seguinte comando:

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

Exemplos completos de uso da CLI

A CLI do AlphaEvolve oferece aos desenvolvedores controle administrativo e monitoramento rápidos das campanhas diretamente do shell:

Liste todos os experimentos em uma sessão de conversação:
```
ae experiment list
```
Liste todos os programas candidatos mutados para um experimento específico:
```
ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"
```
Substitua EXPERIMENT_NICKNAME pelo nome do experimento.
Recupere os candidatos de código concluídos com melhor desempenho:
```
ae results best EXPERIMENT_NICKNAME --top 5
```
Substitua EXPERIMENT_NICKNAME pelo nome do experimento.
Retomar uma campanha pausada:
```
ae experiment resume EXPERIMENT_NICKNAME
```
Substitua EXPERIMENT_NICKNAME pelo nome do experimento.

Diretório de endpoint de API REST principal

Todos os endpoints são versionados em v1alpha da API Discovery Engine Google Cloud .

Padrão de caminho do recurso pai

O URI do recurso pai aninhado verdadeiro é estruturado como: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

O AlphaEvolve está disponível em global, us e eu. A criação de experimentos em outros locais retorna FAILED_PRECONDITION.
Os projetos do Assured Workloads não são compatíveis.
Um projeto é limitado a 30 experimentos AlphaEvolve ativos simultaneamente (STARTED ou RUNNING) por local. Iniciar ou retomar um experimento que excede esse limite retorna RESOURCE_EXHAUSTED.

Criar experimento (POST)

Caminho:

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

Corpo da solicitação:AlphaEvolveExperimentConfig (consulte a Seção 2.1)
Resposta:recurso AlphaEvolveExperiment que contém a campanha inicializada.
Status HTTP:200 OK

Exemplos de payload da API

Exemplo de corpo da solicitação (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
        }
      }
    }
  }
}

Exemplo de corpo de resposta (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)

Caminho:

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

Corpo da solicitação:StartExperimentRequest
Aviso de descontinuação:o campo de corpo initialProgram foi descontinuado e é ignorado.
Resposta:GoogleLongrunningOperation (LRO).
Status HTTP:200 OK (transições de estado de CREATED para RUNNING)

Exemplos de payload da API

Exemplo de corpo da solicitação
```
{
  "desiredProgramsCount": 1
}
```

Exemplo de corpo de resposta (200 OK: operação de longa duração)

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

Adquirir programas (POST)

Caminho:

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

Corpo da solicitação:AcquireProgramsRequest
- desiredProgramsCount (int32): contagem opcional de lotes de programas mutados a serem recuperados (o padrão é 1 quando não definido).
Status de resposta:
- 200 OK: retorna uma resposta que contém recursos AlphaEvolveProgram bloqueados.
- 204 No Content: a fila está vazia ou a campanha está pausada. Os executores precisam suspender (por exemplo, 15 segundos) e tentar novamente.

Exemplos de payload da API

Exemplo de corpo da solicitação
```
{
  "desiredProgramsCount": 1
}
```

Exemplo de corpo de resposta (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    ..."
          }
        ]
      }
    }
  ]
}

Exemplo de corpo de resposta (204 No Content)

O status HTTP 204 foi retornado com um contexto de payload vazio.

Enviar avaliações de programas (POST)

Caminho:

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

Corpo da solicitação:SubmitProgramsEvaluationsRequest
- evaluationSubmissions (matriz): contém o lockToken correspondente, o caminho do recurso do programa qualificado e o payload de avaliação (pontuações e insights). A API aceita exatamente um envio de avaliação por chamada. O agrupamento de várias avaliações em uma única solicitação é rejeitado com INVALID_ARGUMENT. Ao avaliar vários candidatos, envie cada programa individualmente.
Resposta:SubmitProgramsEvaluationsResponse (vazia).
Status HTTP:200 OK (salva as pontuações, libera o bloqueio ativo e registra insights)

Exemplos de payload da API

Exemplo de corpo da solicitação

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

Exemplo de corpo de resposta (200 OK)
```
{}
```

Retomar experimento (POST)

Caminho:

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

Corpo da solicitação:ResumeExperimentRequest
Resposta:GoogleLongrunningOperation (LRO).
Status HTTP:200 OK (o estado de transição muda de PAUSED de volta para RUNNING)

Exemplos de payload da API

Exemplo de corpo da solicitação
```
{}
```

Exemplo de corpo de resposta (200 OK: operação de longa duração)

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

Listar programas (GET)

Caminho:

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

Parâmetros de consulta:
- stateFilter (string): opcional. Filtro de lista padrão, por exemplo, stateFilter = 'COMPLETED'.
- orderBy (string): opcional. Classificação com base em métricas, por exemplo, accuracy desc.
Resposta:ListAlphaEvolveProgramsResponse.
Status HTTP:200 OK

Exemplos de payload da API

Exemplo de URL de consulta de solicitação

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

Exemplo de corpo de resposta (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"
}

Código de diagnóstico e referência para solução de problemas

Matriz de códigos de diagnóstico da API

Status HTTP	Tipo de erro	Causa do sistema	Solução alternativa ou ação de mitigação
400	`INVALID_ARGUMENT`	Marcadores `EVOLVE-BLOCK-START` / `EVOLVE-BLOCK-END` malformados (por exemplo, conteúdo que compartilha a linha do marcador, blocos aninhados ou marcador final ausente). Bloco de evolução vazio que contém apenas comentários ou espaços em branco sem código editável. `maxPrograms` definido como menos de 2. Campos de configuração não reconhecidos. Configuração de modelo inválida (mais de dois modelos, entradas duplicadas, pesos não positivos ou temperatura fora de `[0.0, 2.0]`). Envio de várias avaliações em uma única chamada `submitProgramsEvaluations`. O projeto é do Assured Workloads.	Verifique se os marcadores estão sozinhos na linha e se incluem pelo menos uma linha de código que não seja um comentário. Defina `maxPrograms` como 2 ou mais. Remova os campos que não fazem parte da API, como `notes`, que estava presente na versão de pré-lançamento da API. Envie as avaliações individualmente, uma por vez.
403	`PERMISSION_DENIED`	O autor da chamada não tem o papel de editor do Discovery Engine (`roles/discoveryengine.editor`) ou de administrador (`roles/discoveryengine.admin`). Observação: `roles/discoveryengine.user` não concede permissões do AlphaEvolve, e `roles/discoveryengine.viewer` não pode receber experimentos. O autor da chamada não tem permissão no recurso de sessão pai. Nenhuma licença ativa do Gemini Enterprise foi atribuída.	Conceda `roles/discoveryengine.editor` ou `roles/discoveryengine.admin` no nível do projeto e verifique o acesso à sessão pai. Verifique as licenças ativas do Gemini Enterprise. Configure as credenciais padrão do aplicativo: `gcloud auth application-default login --project=PROJECT_ID` Observação:o Model Armor não é compatível com as configurações do AlphaEvolve.
400	`FAILED_PRECONDITION`	Token de bloqueio desatualizado ou expirado ou incompatibilidade de estado do programa (por exemplo, o candidato foi readquirido ou finalizado após o término do contrato). O experimento foi criado em um local não aceito (fora de `global`, `us` ou `eu`). A API Vertex AI (`aiplatform.googleapis.com`) não está ativada no projeto.	Retorne o `lockToken` exato retornado por `:acquirePrograms`. Aplique tempos limite do lado do cliente (recomendamos 30 minutos) e envie pontuações de penalidade de falha após o tempo limite. Recrie o experimento em um local compatível. Ative a API Vertex AI: `gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID`.
429	`RESOURCE_EXHAUSTED`	O projeto atingiu o limite de 30 experimentos ativos simultaneamente (`STARTED` / `RUNNING`) por local. A cota de tokens de geração do modelo de back-end foi esgotada.	Para o limite de experimentos ativos: conclua ou interrompa os experimentos em execução antes de iniciar um novo. Reduzir `concurrency` em `runSettings` não afeta esse limite. Para a cota de tokens do modelo: reduza `concurrency` em `runSettings` e implemente a espera exponencial.
503	`SERVICE_UNAVAILABLE`	O classificador de segurança de entrada está indisponível ou o serviço de back-end está temporariamente sobrecarregado.	Implementar um loop de repetição com espera exponencial aleatória no lado do cliente.

Mensagens de erro comuns e soluções

A referência a seguir lista mensagens de erro comuns retornadas pela API, as causas subjacentes e as etapas de resolução.

Erros de análise do programa inicial e do EVOLVE-BLOCK

Mensagem de erro	Causa do sistema	Solução alternativa ou ação de mitigação
`Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line.`	Os marcadores `EVOLVE-BLOCK-START` e `EVOLVE-BLOCK-END` aparecem na mesma linha.	Coloque os marcadores de início e fim em linhas separadas.
`Parsing error: Unexpected content on the same line as <marker> in line <line_number>.`	Código, texto ou caracteres à direita compartilham a linha com um marcador `EVOLVE-BLOCK-START` ou `EVOLVE-BLOCK-END`.	Verifique se o marcador está sozinho na linha (precedido apenas pelo prefixo de comentário, como `# EVOLVE-BLOCK-START`).
`Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks.`	Um marcador `EVOLVE-BLOCK-START` aparece dentro de um bloco de evolução já aberto.	Remova os marcadores de início aninhados. Blocos de evolução aninhados não são compatíveis.
`Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started.`	Um marcador `EVOLVE-BLOCK-END` aparece sem um `EVOLVE-BLOCK-START` anterior.	Verifique se cada marcador de fim é precedido por um marcador de início correspondente.
`Parsing error: Evolve block started but not ended.`	Um marcador `EVOLVE-BLOCK-START` foi encontrado sem um marcador de fechamento `EVOLVE-BLOCK-END` correspondente.	Adicione um marcador de fechamento `EVOLVE-BLOCK-END`.

Erros de conteúdo e estrutura do programa

Mensagem de erro	Causa do sistema	Solução alternativa ou ação de mitigação
`Program content must contain at least one source file.`	`program_content.source_files` está vazio.	Forneça pelo menos um arquivo de origem.
`source_files entries must have a non-empty path.`	Uma entrada de arquivo de origem tem uma string `path` vazia.	Especifique um caminho relativo válido para cada arquivo de origem.
`source_files entry has empty content; path: <path>`	Uma entrada de arquivo de origem contém conteúdo de string vazio.	Preencha o conteúdo do arquivo.
`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).`	Os blocos de evolução contêm apenas comentários, docstrings ou espaços em branco, sem código editável.	Inclua pelo menos uma linha de código editável (como definições de função ou lógica de algoritmo) dentro do bloco.

Erros de validação de configuração e modelo

Mensagem de erro	Causa do sistema	Solução alternativa ou ação de mitigação
`unsupported model: <model_name>`	O modelo solicitado não é compatível ou não está ativado para seu projeto.	Use modelos compatíveis. Consulte as Configurações de geração.
`model '<model_name>' is not served from domain shard '<location>'.`	O modelo não está disponível no local regional especificado.	Consulte as configurações de geração para saber quais modelos e locais são compatíveis.
`generation_settings.models must contain at most 2 distinct models; got <count>.`	Mais de duas configurações de modelo foram especificadas em `generation_settings.models`.	Especifique no máximo dois modelos na combinação.
`generation_settings.models contains duplicate entry: <model_name>`	O mesmo nome de modelo aparece mais de uma vez em `generation_settings.models`.	Remova as 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.`	O peso de amostragem do modelo é negativo, zero ou não finito.	Defina um peso positivo ou remova a entrada.
`generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>.`	A temperatura do modelo está fora do intervalo válido `[0.0, 2.0]`.	Ajuste a temperatura para um valor entre `0.0` e `2.0`.
`RunSettings.max_programs is required and must be greater than 1.`	`max_programs` foi omitido ou definido como 1 ou menos.	Defina `max_programs` como 2 ou mais (um mínimo de 2 é necessário para admitir candidatos evoluídos).
`RunSettings.concurrency is required and must be positive.`	`concurrency` foi omitido ou definido como 0 ou menos.	Defina `concurrency` como um número inteiro positivo (normalmente de 1 a 30).
`EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>.`	`pareto_sampling_probability` está fora de `[0.0, 1.0]`.	Defina uma probabilidade entre `0.0` e `1.0`.

Pré-requisitos do projeto e erros no ciclo de vida do experimento

Mensagem de erro	Causa do sistema	Solução alternativa ou ação de mitigação
`AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id>`	A API Vertex AI (`aiplatform.googleapis.com`) não está ativada no projeto Google Cloud .	Execute `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.`	O projeto atingiu a cota de 30 experimentos ativos simultaneamente (`STARTED` ou `RUNNING`) nesse local.	Interrompa ou conclua os experimentos atuais antes de iniciar ou retomar um novo.
`Cannot <action> experiment from state <current_state>`	Tentativa de uma transição de estado inválida (por exemplo, iniciar um experimento que já está em execução ou retomar um experimento recém-criado).	Verifique se os experimentos seguem as transições padrão do 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.`	Uma operação de início ou retomada anterior ainda está em andamento.	Aguarde a conclusão da entrega pendente ou chame `STOP` para drenar as mensagens pendentes.
`AlphaEvolve is not available for this project.`	O projeto está bloqueado ou é um perfil de compliance sem suporte.	Consulte Perfil de compliance e segurança.

Erros de aquisição e avaliação do programa

Mensagem de erro	Causa do sistema	Solução alternativa ou ação de mitigação
`Exactly one evaluation submission is required.`	Vários envios de avaliação foram agrupados em uma única solicitação `submitProgramsEvaluations`.	Envie as avaliações individualmente, uma por chamada de API.
`Program is required for each evaluation submission.` / `submission.program is required.`	O caminho do recurso `program` não foi fornecido no envio da avaliação.	Transmita o caminho completo do recurso do programa.
`Lock token is required for each evaluation submission.` / `submission.lock_token is required.`	O `lock_token` retornado durante `acquirePrograms` foi omitido.	Transmita a string `lock_token` exata retornada quando o programa foi adquirido.
`Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>'`	O token de bloqueio enviado no envio não corresponde à concessão do servidor ativo (por exemplo, a concessão expirou e outro worker a adquiriu ou um token incorreto foi fornecido).	Retorne o `lockToken` exato de `acquirePrograms` e envie os resultados antes que o tempo limite do cliente se esgote.
`Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state>`	O programa já foi avaliado, cancelado ou transferido de `EVALUATION_IN_PROGRESS`.	Descarte a avaliação desatualizada ou adquira o candidato novamente, se disponível.
`The request was rejected by a safety policy.`	A descrição do problema de entrada, o código inicial ou as métricas de avaliação acionaram políticas de classificação de segurança.	Limpe o texto do comando e as descrições de problemas para remover palavras-chave ou rastros sensíveis.
`The input safety classifier is currently unavailable.`	O serviço de classificação de segurança está temporariamente inacessível ou sobrecarregado (falha fechada).	Implemente a lógica de repetição de espera exponencial.

Como corrigir "quedas silenciosas"

Uma interceptação de filtro de segurança (descarte silencioso) ocorre quando os modelos de linguagem do lado do servidor sinalizam e descartam comandos candidatos modificados devido a frases sensíveis ou acionadores de regras de segurança. O servidor silencia a saída, fazendo com que a fila retorne respostas vazias, e os executores do cliente podem esperar indefinidamente.

Remediação alternativa:

Limpar o contexto:remova frases com carga emocional ou sensíveis à segurança do problemDescription.
Filtrar insights:analise e trunque rastreamentos de exceção brutos ou registros stderr de terminal no payload insights para evitar a repetição de conteúdo de sistema não seguro que aciona filtros downstream.
Localize conjuntos de dados:não coloque registros de treinamento ou grandes corpora de texto em comandos. Carregue-os localmente no ambiente do cliente durante a execução do loop de avaliação.

Práticas recomendadas de avaliação do lado do cliente

O gargalo do "código espaguete"

A formatação de origem abaixo do ideal degrada a qualidade da otimização: "Código espaguete == espaço de pesquisa ruidoso". Antes de colocar marcadores EVOLVE-BLOCK:

Refatore os blocos de código para que as variáveis e as assinaturas de função sejam nomeadas com clareza.
Adicione docstrings descritivas e concisas explicando o que cada função ou variável faz e por quê. Verifique se as docstrings estão ao lado do código funcional real. Colocar apenas uma docstring ou comentários dentro de um EVOLVE-BLOCK é rejeitado como um bloco vazio.
Verifique se os marcadores de comentário EVOLVE-BLOCK-START e EVOLVE-BLOCK-END estão sozinhos nas respectivas linhas, exceto por espaços em branco à esquerda e prefixos de comentário (como # ou //).
Verifique se todas as dependências externas e imutáveis (como a importação de módulos auxiliares ou o carregamento de dados estáticos) estão fora do EVOLVE-BLOCK.

Alocação da janela de contexto

Para maximizar a criatividade da mutação, limite o payload de código enviado à API. O contexto total do programa precisa permanecer abaixo de 150.000 a 200.000 tokens. Grandes blocos de código boilerplate estático e imutável consomem a atenção do modelo e prejudicam o desempenho. Mova scripts de utilitários, pipelines de ingestão de dados e bibliotecas de validação pesadas inteiramente para o avaliador do lado do cliente.

Primeiro, prepare o programa inicial

Antes de executar o AlphaEvolve, use um agente de programação padrão para depurar a base de código inicial e o avaliador:

Preparar a semente:corrija bugs de sintaxe óbvios, problemas de compilação e casos extremos.
Verifique a pontuação inicial:confira se a pontuação de referência é razoável e se o avaliador é totalmente determinista (mesmo código + mesma entrada = mesma pontuação).
Teste com entradas inválidas:execute o avaliador com funções intencionalmente corrompidas para confirmar se ele detecta problemas do compilador, lida com loops infinitos de maneira adequada e retorna pontuações de penalidade negativas altas.

Evite valores de referência excessivamente otimizados

Não transmita um programa de referência já altamente otimizado como semente. Se o programa inicial já estiver quase ideal, o AlphaEvolve terá dificuldade para fazer o hill climbing porque há pouco espaço para melhorias. Comece com um valor de referência razoável, mas não otimizado ao máximo. Isso dá ao AlphaEvolve espaço para explorar e fazer hill-climbing.

Proteções do executor do lado do cliente

Os avaliadores do lado do cliente precisam aplicar proteções rígidas para evitar que candidatos mal-intencionados, com uso intensivo de recursos ou que não respondem interrompam os workers paralelos:

Tempos limite estritos:aplique um limite de execução estrito de 30 minutos (ou menos, dependendo da estrutura do espaço de pesquisa).
Envio de penalidade de tempo limite:se uma variante do programa candidato exceder o limite de tempo limite, encerre a linha de execução imediatamente. Não permita que o processo candidato falhe. Em vez disso, compile e envie instantaneamente uma pontuação de penalidade de falha grave (por exemplo, -100000.0) com um insight descritivo de depuração de volta ao servidor para liberar o bloqueio de fila do programa.
Filtros de segurança de AST:sempre execute uma verificação de inspeção de árvore de sintaxe abstrata (AST, na sigla em inglês) no payload do código-fonte recebido antes da compilação. Interrompa imediatamente a execução e aplique uma penalidade de falha grave se primitivas de reflexão ou execução restritas (como eval, exec, getattr ou setattr) forem detectadas.

Outros recursos

Para saber mais, acesse os recursos a seguir:

Referência da API AlphaEvolve Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Máquinas de estado de ciclo de vida unificadas

Estados do ciclo de vida do experimento

Estados do programa

Mecânicas de simultaneidade e bloqueio

Esquemas de configuração e definições

AlphaEvolveExperimentConfig

RunSettings

Configurações de geração

Modelos compatíveis

Modelo padrão

Configurações do Evolution

Modelos de dados de programas candidatos

AlphaEvolveProgramContent

AlphaEvolveSourceFile

AlphaEvolveProgramEvaluation

Formulação de pontuação e formatos de ingestão

A regra de maximização

Esquema de ingestão de objetivo único

Esquema de ingestão de vários objetivos

Como buscar e consultar dados do programa

Recuperação de programas usando a API REST

Recuperação de programas usando a CLI

Exemplos completos de uso da CLI

Diretório de endpoint de API REST principal

Padrão de caminho do recurso pai

Criar experimento (POST)

Exemplos de payload da API

Iniciar experimento (POST)

Exemplos de payload da API

Adquirir programas (POST)

Exemplos de payload da API

Enviar avaliações de programas (POST)

Exemplos de payload da API

Retomar experimento (POST)

Exemplos de payload da API

Listar programas (GET)

Exemplos de payload da API

Código de diagnóstico e referência para solução de problemas

Matriz de códigos de diagnóstico da API

Mensagens de erro comuns e soluções

Erros de análise do programa inicial e do EVOLVE-BLOCK

Erros de conteúdo e estrutura do programa

Erros de validação de configuração e modelo

Pré-requisitos do projeto e erros no ciclo de vida do experimento

Erros de aquisição e avaliação do programa

Como corrigir "quedas silenciosas"

Práticas recomendadas de avaliação do lado do cliente

O gargalo do "código espaguete"

Alocação da janela de contexto

Primeiro, prepare o programa inicial

Evite valores de referência excessivamente otimizados

Proteções do executor do lado do cliente

Outros recursos

Referência da API AlphaEvolve

`AlphaEvolveExperimentConfig`