Experimentation best practices

To get started with experimentation on AlphaEvolve, we recommend the following workflow:

1. Complete environment initialization

   Use the Get Started page to complete all prerequisites and initialize your environment.

2. Perform foundational verification

   Complete the Get Started with AlphaEvolve on Google Cloud codelab before proceeding. This step ensures that your transport layers, block syntax, and local runtime verification execute smoothly without errors before you move on to domain-specific targets.

3. Execute your experiment design

   Choose between an agentic or manual integration pathway:

   • Agentic integration: If you use agentic coding tools, execute the built-in Skills pipeline to walk through your setup and experiment design programmatically.

   • Manual integration: If you are not using agentic tools, reference the codelabs and manually construct your experiment by performing the following actions:

     • Prepare the seed code baseline

       Create the initial baseline code following program guidelines, placing explicit EVOLVE-BLOCK comment markers strictly around the specific logic segments or subroutines targeted for refactoring by using the placement strategy.

     • Build the evaluator harness function

       Write a client-side or server-side execution loop to receive the mutated code blocks from AlphaEvolve, run them securely, and compute business metrics. The evaluator must return a structured dictionary of one or more metrics to provide an explicit search gradient direction to AlphaEvolve. Use the core guidelines listed in the Evaluator design page.

     • Document the problem definition

       Define a precise problem statement within your configuration, specifying background details, relevant domain context rules, and hard operational system constraints. Use the guidelines from the Context and prompt configuration guidelines page.

     • Choose your experiment configuration

       Specify your runtime hyperparameter configuration, including targeted LLM mixtures, maximum program generation limits, and optimal execution concurrency thresholds. Use the guidelines from the data and concurrency page.

4. Monitor execution

   Launch the optimization experiment and track real-time fitness scores across successive generations. Recommended evaluation budgets start at ~100 programs and scale up to thousands for hard problems. If your evaluation metrics fail to show a clear trajectory after ~1500 candidate program evaluations, pause the execution loop to refine your problem definition context or adjust soft penalty constraints.

   Note: Hard problems can plateau for an extended number of generations before a sudden breakthrough, so a plateau does not necessarily mean the search has converged.

5. Integrate into production

   After successful search convergence, retrieve the optimal program candidate (or the n-th best variant depending on multi-metric operational tradeoffs) from the history tables and implement it directly into your system architecture.

As optimization complexity, dependency stacks, and scale requirements expand, switch from your local process space to the cluster toolkit-based infrastructure setup to handle advanced enterprise-scale computing needs.