注: このドキュメントセットは、Gemini Enterprise の Standard、Plus、従量課金、Frontline エディションを対象としています。Business エディションのドキュメントについては、Gemini Enterprise - Business エディションのヘルプセンターをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

AlphaEvolve API リファレンス

このドキュメントは、 Google CloudDiscovery Engine 会話レイヤにおける AlphaEvolve Cloud API の正式な本番環境グレードの API リファレンスおよびシステム仕様として機能します。完全に自動化されたクライアントサイドコントローラと評価ループを設計するために必要な、ネストされたリソース階層、REST エンドポイントと gRPC エンドポイント、フィールドレベルの制約、ライフサイクルステートマシン、エラー診断マトリックス、セキュリティサンドボックスルール、統合ワークフローを正確に定義します。

統合されたライフサイクルステートマシン

AlphaEvolve エージェントは、2 つの独立したステートマシンを調整して、テストキャンペーンの進行状況をモニタリングし、個々のプログラムミューテーションの配信と実行を管理します。

テストのライフサイクル状態

テストは、最適化キャンペーン全体を表します。これは永続的なサーバーサイドリソースとして処理され、次の状態に移行します。

CREATED: 初期化状態。リソースは宣言され、構成されていますが、初期世代の入力や API 呼び出しのディスパッチはまだ行われていません。
RUNNING: アクティブな評価状態。このエンジンは、親候補のサンプリング、LLM 混合によるコードミューテーションの生成、評価者へのタスクのストリーミングを同時に行います。
PAUSED: 手動または自動保護 idle_timeout によってトリガーされる一時的な保留状態。コード生成が停止し、既存のワーカーが指標の配信を一時停止します。
COMPLETED: 検索が max_programs ターゲット割り当てを正常に完了したか、構造生成の上限に達したことを示すターミナル状態。
FAILED: システム環境の問題（キャッチされない API 認証情報の例外、データストアの破損、連続したランナーパニックなど）により処理の実行が停止したことを示す、ターミナルエラー状態。

プログラムの状態

ランタイム検証シーケンスは、個々の候補バリアントに適用されます。

生成されたコードミューテーションは、母集団データベース内の一連のきめ細かい運用状態を遷移する、分離されたプログラムエンティティとして動作します。

INITIALIZED: プログラムエントリがデータベースに作成され、祖先の血統と親プログラムのリンクが追跡されます。
GENERATING: タスクが言語モデル混合バックエンドにアクティブにディスパッチされ、特定の機能コードブロックがドラフトまたは変更されます。
EVALUATING: コードペイロードは評価ワーカープロセスによってロックされ、隔離されたテストハーネス環境内で実行されます。
COMPLETED: 実行スコアと記述的な構造分析情報が進化データベースに安全に commit され、プログラムが選択プールに追加されます。

同時実行とロックのメカニズム

プログラムは、アトミックロックトークンメカニズムを使用してワーカーループによって取得され、分散トポロジ全体で競合状態や重複したスコアリングオーバーヘッドを防止します。評価者は、最終的なスコアリングスキーマと、完全に一致するロックトークンを送信して、結果をデータベースに正常に commit する必要があります。

構成と設定のスキーマ

AlphaEvolve エンジンランタイムで使用されるコアスキーマの構成、パラメータ、デフォルトの概要。

`AlphaEvolveExperimentConfig`

進化型テスト実行のコア構造パラメータとプログラム上の制約を定義します。

フィールド名	種類	デフォルト	制約 / 値の範囲	技術的な説明
`title`	文字列	必須	最大 256 文字	テストの一意の表示名。
`problemDescription`	文字列	必須	最大 5,000 文字	問題の正式な仕様。これは、ルールを確立するためにプロンプトコンテキストに直接挿入されます。
`programLanguage`	文字列	必須	自由形式の値	進化したコードベースのターゲット言語（`"python"`、`"cpp"`、`"verilog"`、`"cuda"`、`"julia"`、`"java"` など）。
`runSettings`	オブジェクト	必須	`RunSettings` スキーマにマッピングされます。	ペースとタイムアウトのパラメータ。
`generationSettings`	オブジェクト	Optional	`GenerationSettings` スキーマにマッピングされます。	モデル選択とコンテキストパラメータ。
`evolutionSettings`	オブジェクト	Optional	`EvolutionSettings` スキーマにマッピングされます。	親の選択と多様性のパラメータ。

RunSettings

スループットのペース、並列処理の上限、自動システムタイムアウトを管理します。

フィールド名	種類	デフォルト	制約 / 値の範囲	技術的な説明
`maxPrograms`	int32	100	最小: 2、最大: 100, 000	合計実行予算（生成して評価するプログラム）。1 より大きくする必要があります。
`concurrency`	int32	1	最小: 1、最大: 30	キュー内でアクティブな並列プログラムミューテーションの数。30 を超える値は使用できません。
`maxDuration`	文字列	24 時間（86,400 秒）	ISO 8601 dayTimeDuration 文字列最小: >0、最大: 7 日	テストが停止するまでに許容される合計実時間。
`idleTimeout`	文字列	5 時間（米国/欧州） 2 時間（グローバル）	ISO 8601 dayTimeDuration 文字列最小: >0 最大: ロケーションのデフォルト	`PAUSED` への自動移行前の非アクティブ期間。デフォルトは、`global` では 2 時間、リージョンロケーション（`us`、`eu`）では 5 時間です。期間はロケーションのデフォルトによって制限されるため、ロケーションのデフォルトを超える値（`global` で 12 時間など）を指定すると、無視され、値は 2 時間になります（エラーは発生しません）。

生成設定

GenerationSettings スキーマは、ミューテーションのプロンプトアセンブリ、コンテキストウィンドウ、モデル構成を制御します。

context（文字列）: ユーザーが指定するオプションのリファレンスドキュメント、補足 API、またはルール。200,000 トークン未満に抑えることを強くおすすめします。コンテキストサイズが 200,000 トークンを超えると、モデルのアテンションが希薄になり、ミューテーションの品質が低下します。
includeFullProgramInPrompt（ブール値）: デフォルトは false。
- true: ミューテーションプロンプトには、変更可能な EVOLVE-BLOCK と、周囲の変更不可能なボイラープレートが含まれます（複雑な構造推論に強く推奨）。
- false: 変更可能なブロックのみが表示され、トークンコンテキストが保存されます。
models（オブジェクトの配列）: 省略可。各エントリはモデルに名前を付け、オプションの weight を指定します。これは、他のエントリに対するそのモデルの生成呼び出しのシェアです。models を省略すると、AlphaEvolve はテストの作成時にデフォルトのモデルに設定します。デフォルトは、新しい Gemini モデルがリリースされると変更されます。デフォルトモデルには、どのモデルがどの日付に適用されるかが一覧表示されます。モデルを自分で選択する場合、または実行ごとに同じモデルを保持する場合は、models を設定します。

次の例では、生成呼び出しの約 10 分の 9 を最初のモデルに送信し、残りを 2 番目のモデルに送信します。重みは比率であるため、合計が 1 になる必要はありません。
```
"models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]
```

サポートされているモデル

models[].name を次のいずれかの値に設定します。1 つのテストで最大 2 つのモデルを組み合わせることができます。

モデル名	サービス提供リージョン
`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 は、テストの作成時に models を検証し、このテーブルにないモデル名、またはリクエストしたリージョンで使用できないモデル名に対して INVALID_ARGUMENT を返します。

デフォルトモデル

次の表に、models を省略した場合に AlphaEvolve が使用するモデルを、テストの作成日別に示します。

テストが作成されました	デフォルトモデル
2026 年 10 月 24 日以降	`gemini-4-argon`
2026 年 9 月 29 日～ 2026 年 10 月 23 日	`gemini-3.8-flash`
2026 年 6 月 30 日～ 2026 年 9 月 28 日	`gemini-3.5-flash`
2026 年 6 月 30 日より前	`gemini-2.5-flash`

テストに割り当てられたモデルを特定するには、テスト構成または作成レスポンスで generationSettings.models を確認します。変更は移行日全体にわたって有効になるため、これらの日付に作成されたテストでは、古いデフォルトモデルまたは新しいデフォルトモデルのいずれかが使用される可能性があります。2026 年 6 月 30 日より前に models を指定せずに作成されたテストには、このフィールドの値は含まれません。

モデルは各テストに保存されるため、デフォルトを変更しても、既存のテストには影響しません。新しいデフォルトモデルを使用するには、新しいテストを作成します。

進化の設定

EvolutionSettings スキーマは、アイランドモデルの再シードと親のサンプリング確率を制御します。

parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability（float）: 標準の適合度ベースの選択を使用するのではなく、アクティブなパレートフロンティアから直接親プログラムをサンプリングする確率（0.0 ～ 1.0）。最適化された指標が単一のスカラー指標のみを返す場合は、このパラメータを 0.0（無効）に設定する必要があります。

候補プログラムのデータモデル

このセクションでは、母集団データベース内で候補コード構造を定義して整理するために使用されるデータスキーマと表現の概要について説明します。

AlphaEvolveProgramContent

候補プログラムのファイルと構造を定義します。

files（AlphaEvolveSourceFile の配列）: 候補コードベースを構成するすべてのファイルのリスト。ペイロードには、少なくとも 1 つのソースファイルが含まれている必要があります。Google では、候補プログラムあたりの合計ファイル数を 50 ファイルに抑えることをおすすめします。これにより、モデルのアテンションとコンテキストウィンドウの効率が最適化されます。
description（文字列）: 生成モデルによって提案されたプログラマティックな変更の概要をまとめた自動生成された概要（最大 1,000 文字）。

AlphaEvolveSourceFile

コードベース内の個々のソースコードファイルを表します。

path（文字列）: ワークスペース相対パスの宛先（必須、最大 256 文字）。各ソースファイルエントリには、空でないパスを指定する必要があります。Python ワークスペースを構成する場合、プライマリ実行可能ファイルのエントリポイントの名前は "initial_program.py" にする必要があります。
content（文字列）: 機能実装ブロックを構成する未加工のソースコード文字列。Google では、すべてのファイルにわたる累積コードベースサイズを 4,000 ～ 5,000 行のコード（LOC）未満に抑えることをおすすめします。これは、モデルのアテンションとミューテーション生成のパフォーマンスに最適です。
programLanguage（文字列）: 言語パーサーマッピングタグ。この文字列は、親テスト構成内で指定された言語と明示的に一致する必要があります。
description（文字列）: ファイルの個別のアーキテクチャまたは目的の概要を示すオプションのサマリー。ミューテーションパス中に LLM に公開されます（最大 500 文字）。

AlphaEvolveProgramEvaluation

ランタイム実行後にクライアントランナーインスタンスから進化データベースに送信される構造化ペイロード。

scores（AlphaEvolveScores）: 標準化された客観的な数値指標値。ベストプラクティスでは、これを 3 ～ 5 個の個別の浮動小数点指標に制限します。ターゲットディメンションが多すぎると、多目的パレート比較器のパフォーマンスが低下します。
insights（AlphaEvolveEvaluationInsight の配列）: LLM の後続のミューテーション生成試行を支援するために返される診断セマンティックラベルと自然言語実行トレース（推奨される最大項目数は 10）。

スコアの作成と取り込み形式

最大化ルール

AlphaEvolve は、基本的に単調な山登りアルゴリズムとして動作し、すべての数値指標を厳密に最大化します。評価パイプラインで最小化ターゲット（アプリケーションレイテンシをミリ秒単位で最小化する、メモリ使用量を削減するなど）を追跡する場合は、値をデータベースに送信する前に否定する必要があります（submitted_score = -latency_ms）。

スコアは連続していることが理想的です。ブール値または高度に離散的な指標では、効果的な山登り探索に十分な勾配シグナルが得られません。

単一目的の取り込みスキーマ

評価ハーネスが単一のスカラー目的関数に対して最適化する場合は、次の JSON を使用します。

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

多目的取り込みスキーマ

独立した多目的トラッキングパラメータを渡して、サーバーサイドのパレート最適化ルーチンを有効にする場合は、次の JSON を使用します。

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

番組データの取得とクエリ

AlphaEvolve システムは、生成されたすべてのミューテーションのテレメトリー、実行指標、完全なソースコードをシステムログに記録します。デベロッパーは、API または CLI を使用してこの履歴データストアをクエリし、最適化の進捗状況を追跡して、最もパフォーマンスの高いコード候補を抽出できます。

REST API を使用したプログラムの取得

評価されたプログラムリソースは、フィルタリングと並べ替えのクエリパラメータを指定した標準の ListAlphaEvolvePrograms エンドポイントを使用して、データベースからクエリできます。

状態フィルタリング: 特定のライフサイクル状態に一致するプログラムをクエリします。
```
GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED
```
指標ベースの並べ替え: 最適化された指標に基づいて並べ替えられた候補を取得します。
```
GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5
```

CLI を使用したプログラムの取得

完了した上位の候補をターミナルから直接取得するには、次のコマンドを実行します。

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

CLI の使用例

AlphaEvolve CLI を使用すると、デベロッパーはシェルから直接キャンペーンを迅速に管理、モニタリングできます。

会話セッション内のすべてのテストを一覧表示します。
```
ae experiment list
```
特定のテストのすべてのミューテーション候補プログラムを一覧表示します。
```
ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"
```
EXPERIMENT_NICKNAME は、テストの名前に置き換えます。
パフォーマンスの高い完成したコード候補を取得します。
```
ae results best EXPERIMENT_NICKNAME --top 5
```
EXPERIMENT_NICKNAME は、テストの名前に置き換えます。
一時停止したキャンペーンを再開する:
```
ae experiment resume EXPERIMENT_NICKNAME
```
EXPERIMENT_NICKNAME は、テストの名前に置き換えます。

Core REST API エンドポイントディレクトリ

すべてのエンドポイントは、 Google Cloud Discovery Engine API の v1alpha でバージョニングされています。

親リソースパスのパターン

真のネストされた親リソース URI は、projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session} のように構成されます。

AlphaEvolve は、global、us、eu で利用できます。他のロケーションでテストを作成すると、FAILED_PRECONDITION が返されます。
Assured Workloads プロジェクトはサポートされていません。
1 つのプロジェクトで同時にアクティブ（STARTED または RUNNING）にできる AlphaEvolve テストは、ロケーションごとに 30 個に制限されています。この上限を超えるテストを開始または再開すると、RESOURCE_EXHAUSTED が返されます。

テストを作成する（POST）

Path

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

リクエスト本文: AlphaEvolveExperimentConfig（セクション 2.1 を参照）
レスポンス: 初期化されたキャンペーンを含む AlphaEvolveExperiment リソース。
HTTP ステータス: 200 OK

API ペイロードの例

リクエスト本文の例（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
        }
      }
    }
  }
}

レスポンス本文の例（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
        }
      }
    }
  }
}

テストを開始する（POST）

Path

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

リクエストの本文: StartExperimentRequest
非推奨の警告: 本文フィールド initialProgram は非推奨となり、無視されます。
レスポンス: GoogleLongrunningOperation（LRO）。
HTTP ステータス: 200 OK（状態が CREATED から RUNNING に移行）

API ペイロードの例

リクエスト本文の例
```
{
  "desiredProgramsCount": 1
}
```

レスポンス本文の例（200 OK - 長時間実行オペレーション）

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

番組を取得する（POST）

Path

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

リクエストの本文: AcquireProgramsRequest
- desiredProgramsCount（int32）: 取得するミューテーションされたプログラムのバッチ数（省略可、未設定の場合はデフォルトで 1）。
回答ステータス:
- 200 OK: ロックされた AlphaEvolveProgram リソースを含むレスポンスを返します。
- 204 No Content: キューが空であるか、キャンペーンが一時停止されています。ランナーはスリープ（15 秒など）して再試行する必要があります。

API ペイロードの例

リクエスト本文の例
```
{
  "desiredProgramsCount": 1
}
```

レスポンス本文の例（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    ..."
          }
        ]
      }
    }
  ]
}

レスポンス本文の例（204 No Content）

HTTP ステータス 204 が返され、ペイロードコンテキストは空です。

プログラム評価を送信する（POST）

Path

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

リクエストの本文: SubmitProgramsEvaluationsRequest
- evaluationSubmissions（配列）: 一致する lockToken、修飾されたプログラムリソースパス、評価ペイロード（スコアと分析情報）が含まれます。API は、呼び出しごとに 1 つの評価送信を受け入れます。複数の評価を 1 つのリクエストにバッチ処理すると、INVALID_ARGUMENT で拒否されます。複数の候補を評価する場合は、各プログラムを個別に送信します。
レスポンス: SubmitProgramsEvaluationsResponse（空）。
HTTP ステータス: 200 OK（スコアを保存し、アクティブロックを解除して、分析情報を登録します）

API ペイロードの例

リクエスト本文の例

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

レスポンス本文の例（200 OK）
```
{}
```

テストを再開する（POST）

Path

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

リクエストの本文: ResumeExperimentRequest
レスポンス: GoogleLongrunningOperation（LRO）。
HTTP ステータス: 200 OK（状態を PAUSED から RUNNING に戻します）

API ペイロードの例

リクエスト本文の例
```
{}
```

レスポンス本文の例（200 OK - 長時間実行オペレーション）

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

プログラムの一覧表示（GET）

Path

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

クエリパラメータ:
- stateFilter（文字列）: 省略可。標準リストフィルタ（例: stateFilter = 'COMPLETED'）。
- orderBy（文字列）: 省略可。指標ベースの並べ替え（例: accuracy desc）。
回答: ListAlphaEvolveProgramsResponse
HTTP ステータス: 200 OK

API ペイロードの例

リクエストクエリ URL の例

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

レスポンス本文の例（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"
}

診断コードとトラブルシューティングのリファレンス

API 診断コードマトリックス

HTTP ステータス	エラーの種類	システムの原因	回避策または緩和策
400	`INVALID_ARGUMENT`	`EVOLVE-BLOCK-START` / `EVOLVE-BLOCK-END` マーカーの形式が正しくない（例: マーカーの行を共有するコンテンツ、ネストされたブロック、終了マーカーがない）。コメントまたは空白のみを含む空の evolve ブロック。編集可能なコードはありません。 `maxPrograms` が 2 未満に設定されています。認識できない構成フィールド。モデル構成が無効です（3 つ以上のモデル、重複するエントリ、正でない重み、`[0.0, 2.0]` 以外の温度）。 1 回の `submitProgramsEvaluations` 呼び出しで複数の評価を送信する。プロジェクトが Assured Workloads プロジェクトである。	マーカーは、その行に単独で配置し、少なくとも 1 行のコメント以外のコード行を囲むようにしてください。`maxPrograms` を 2 以上に設定します。API のプレビュー版に存在していた `notes` など、API の一部ではないフィールドを削除します。評価は 1 つずつ個別に送信してください。
403	`PERMISSION_DENIED`	呼び出し元にディスカバリーエンジン編集者のロール（`roles/discoveryengine.editor`）または管理者ロール（`roles/discoveryengine.admin`）が付与されていません。注: `roles/discoveryengine.user` には AlphaEvolve 権限が付与されず、`roles/discoveryengine.viewer` はテストを取得できません。呼び出し元に親セッションリソースに対する権限がありません。有効な Gemini Enterprise ライセンスが割り当てられていません。	プロジェクトレベルで `roles/discoveryengine.editor` または `roles/discoveryengine.admin` を付与し、親セッションへのアクセスを確認します。有効な Gemini Enterprise ライセンスを確認します。アプリケーションのデフォルト認証情報を構成します。 `gcloud auth application-default login --project=PROJECT_ID` 注: Model Armor は AlphaEvolve 構成ではサポートされていません。
400	`FAILED_PRECONDITION`	ロックトークンが古いか期限切れになっているか、プログラムの状態が一致していません（たとえば、リースの期限が切れた後に候補が再取得または確定された場合）。サポートされていないロケーション（`global`、`us`、`eu` 以外）でテストが作成された。プロジェクトで Vertex AI API（`aiplatform.googleapis.com`）が有効になっていない。	`:acquirePrograms` から返された正確な `lockToken` をエコーします。クライアントサイドのタイムアウト（30 分を推奨）を適用し、タイムアウト時に失敗ペナルティスコアを送信します。サポートされているロケーションでテストを再作成します。Vertex AI API（`gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID`）を有効にします。
429	`RESOURCE_EXHAUSTED`	プロジェクトが、ロケーションごとに同時にアクティブにできるテストの上限（30 個）に達しました（`STARTED` / `RUNNING`）。バックエンドモデル生成トークンの割り当てが使い果たされました。	有効なテストの上限: 新しいテストを開始する前に、実行中のテストを完了または停止します（`runSettings` の `concurrency` を下げても、この上限には影響しません）。モデルトークンの割り当ての場合: `runSettings` の `concurrency` を下げ、指数バックオフを実装します。
503	`SERVICE_UNAVAILABLE`	入力の安全性分類器が利用できないか、バックエンドサービスが一時的に過負荷状態になっています。	クライアント側でランダムな指数バックオフを使用して再試行ループを実装する。

一般的なエラーメッセージと解決策

次のリファレンスでは、API から返される一般的なエラーメッセージ、その根本原因、解決手順を示します。

初期プログラムと EVOLVE-BLOCK の解析エラー

エラーメッセージ	システムの原因	回避策または緩和策
`Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line.`	`EVOLVE-BLOCK-START` マーカーと `EVOLVE-BLOCK-END` マーカーの両方が同じ行に表示されます。	開始マーカーと終了マーカーは別の行に配置します。
`Parsing error: Unexpected content on the same line as <marker> in line <line_number>.`	コード、テキスト、または末尾の文字が `EVOLVE-BLOCK-START` マーカーまたは `EVOLVE-BLOCK-END` マーカーと同じ行にある。	マーカーがその行に単独で存在することを確認します（コメント接頭辞（`# EVOLVE-BLOCK-START` など）のみが前に付いている）。
`Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks.`	`EVOLVE-BLOCK-START` マーカーが、すでに開いている evolve ブロック内に表示されている。	ネストされた開始マーカーを削除します。ネストされた evolve ブロックはサポートされていません。
`Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started.`	`EVOLVE-BLOCK-END` マーカーが、前に `EVOLVE-BLOCK-START` がない状態で表示される。	すべての終了マーカーの前に、一致する開始マーカーがあることを確認します。
`Parsing error: Evolve block started but not ended.`	`EVOLVE-BLOCK-START` マーカーが見つかりましたが、対応する終了 `EVOLVE-BLOCK-END` マーカーがありません。	終了マーカー `EVOLVE-BLOCK-END` を追加します。

プログラムのコンテンツと構造のエラー

エラーメッセージ	システムの原因	回避策または緩和策
`Program content must contain at least one source file.`	`program_content.source_files` が空です。	ソースファイルを 1 つ以上指定してください。
`source_files entries must have a non-empty path.`	ソースファイルエントリの `path` 文字列が空です。	すべてのソースファイルに有効な相対パスを指定します。
`source_files entry has empty content; path: <path>`	ソースファイルのエントリに空の文字列コンテンツが含まれています。	ファイルの内容を入力します。
`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 ブロックには、コメント、docstring、空白文字のみが含まれ、編集可能なコードは含まれていません。	ブロック内に、編集可能なコード（関数定義やアルゴリズムロジックなど）を少なくとも 1 行含めます。

構成とモデルの検証エラー

エラーメッセージ	システムの原因	回避策または緩和策
`unsupported model: <model_name>`	リクエストされたモデルは、プロジェクトでサポートされていないか、有効になっていません。	サポートされているモデルを使用します。生成設定をご覧ください。
`model '<model_name>' is not served from domain shard '<location>'.`	指定されたリージョンのロケーションでモデルを使用できない。	サポートされているモデルとロケーションについては、生成設定をご覧ください。
`generation_settings.models must contain at most 2 distinct models; got <count>.`	`generation_settings.models` に 3 つ以上のモデル構成が指定されています。	混合モデルで最大 2 つのモデルを指定します。
`generation_settings.models contains duplicate entry: <model_name>`	同じモデル名が `generation_settings.models` に複数回出現します。	重複するモデルエントリを削除します。
`generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero.`	モデルのサンプリングの重みが負、ゼロ、または有限ではありません。	正の重みを設定するか、エントリを削除してください。
`generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>.`	モデルの温度が有効な範囲 `[0.0, 2.0]` 外です。	温度を `0.0`～`2.0` の範囲で調整してください。
`RunSettings.max_programs is required and must be greater than 1.`	`max_programs` が省略されているか、1 以下に設定されています。	`max_programs` を 2 以上に設定します（進化した候補を承認するには、2 以上にする必要があります）。
`RunSettings.concurrency is required and must be positive.`	`concurrency` が省略されているか、0 以下に設定されています。	`concurrency` を正の整数（通常は 1 ～ 30）に設定します。
`EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>.`	`pareto_sampling_probability` は `[0.0, 1.0]` の外にあります。	`0.0`～`1.0` の確率を設定します。

プロジェクトの前提条件とテストのライフサイクルエラー

エラーメッセージ	システムの原因	回避策または緩和策
`AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id>`	Vertex AI API（`aiplatform.googleapis.com`）が Google Cloud プロジェクトで有効になっていません。	`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.`	プロジェクトが、そのロケーションで同時にアクティブな（`STARTED` または `RUNNING`）テストの割り当て（30）に達している。	新しいテストを開始または再開する前に、既存のテストを停止または完了してください。
`Cannot <action> experiment from state <current_state>`	無効な状態遷移が試行されました（例: すでに実行中のテストを開始しようとした、新しく作成したテストを再開しようとした）。	テストが標準のライフサイクル遷移（`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.`	前の開始オペレーションまたは再開オペレーションがまだ進行中です。	保留中の配信が完了するまで待つか、`STOP` を呼び出して保留中のメッセージをドレインします。
`AlphaEvolve is not available for this project.`	プロジェクトがブロックされているか、サポートされていないコンプライアンスプロファイルです。	コンプライアンスとセキュリティプロファイルを参照してください。

プログラムの取得と評価のエラー

エラーメッセージ	システムの原因	回避策または緩和策
`Exactly one evaluation submission is required.`	複数の評価送信が 1 つの `submitProgramsEvaluations` リクエストにバッチ処理されました。	評価を個別に送信します（API 呼び出しごとに 1 つ）。
`Program is required for each evaluation submission.`/`submission.program is required.`	評価の送信に `program` リソースパスが指定されていません。	プログラムの完全なリソースパスを渡します。
`Lock token is required for each evaluation submission.`/`submission.lock_token is required.`	`acquirePrograms` 中に返された `lock_token` は省略されました。	プログラムの取得時に返された正確な `lock_token` 文字列を渡します。
`Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>'`	送信されたロックトークンが、アクティブなサーバーリースと一致しません（たとえば、リースが期限切れになり、別のワーカーが取得したか、正しくないトークンが提供された）。	`acquirePrograms` からの正確な `lockToken` をエコーし、クライアントのタイムアウト前に結果を送信します。
`Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state>`	このプログラムはすでに評価、キャンセル、または `EVALUATION_IN_PROGRESS` から移行されています。	古い評価を破棄するか、候補を再取得します（可能な場合）。
`The request was rejected by a safety policy.`	入力された問題の説明、初期コード、または評価指標が、安全性分類ポリシーをトリガーしました。	プロンプトテキストと問題の説明をサニタイズして、機密性の高いキーワードやトレースを削除します。
`The input safety classifier is currently unavailable.`	安全性分類サービスが一時的にアクセスできないか、過負荷状態になっている（フェイルクローズ）。	指数バックオフの再試行ロジックを実装する。

「サイレントドロップ」の修正

安全フィルタのインターセプト（サイレントドロップ）は、サーバーサイドの言語モデルが、機密性の高い表現や安全ルールのトリガーにより、ミューテーションされた候補プロンプトにフラグを立ててドロップしたときに発生します。サーバーが出力をサイレントモードにすると、キューは空のレスポンスを返し、クライアントランナーは無期限に待機する可能性があります。

回避策の修正:

コンテキストをサニタイズする: problemDescription から、感情的な表現やセキュリティに配慮が必要なフレーズを削除します。
分析情報をフィルタする: insights ペイロード内の未加工の例外トレースまたはターミナル stderr ログを解析して切り捨て、下流のフィルタをトリガーする安全でないシステムコンテンツのエコーを防ぎます。
データセットをローカライズする: トレーニングレコードや大規模なテキストコーパスをプロンプト内に配置しないでください。評価ループの実行中にクライアント環境にローカルに読み込みます。

クライアントサイド評価のベストプラクティス

「スパゲッティコード」のボトルネック

ソースの形式が最適でないと、最適化の品質が低下します。「スパゲッティコード == ノイズの多い検索空間」。EVOLVE-BLOCK マーカーを配置する前に:

変数と関数シグネチャに明確な名前が付けられるように、コードブロックをリファクタリングします。
各関数または変数の機能と理由を説明する、簡潔でわかりやすい docstring を追加します。docstring が実際の機能コードと一緒に配置されていることを確認します。EVOLVE-BLOCK 内に docstring またはコメントのみを配置すると、空のブロックとして拒否されます。
EVOLVE-BLOCK-START コメントマーカーと EVOLVE-BLOCK-END コメントマーカーは、先頭の空白文字とコメント接頭辞（# や // など）を除き、それぞれの行に単独で配置されていることを確認してください。
外部の不変の依存関係（ヘルパーモジュールのインポートや静的データの読み込みなど）が EVOLVE-BLOCK の外部に存在することを確認します。

コンテキストウィンドウの割り当て

ミューテーションの創造性を最大限に高めるには、API に送信されるコードペイロードを制限します。プログラムのコンテキストの合計は、150,000 ～ 200,000 トークン未満にする必要があります。静的で不変のボイラープレートの大きなブロックは、モデルのアテンションを消費し、パフォーマンスを低下させます。ユーティリティスクリプト、データの取り込みパイプライン、重い検証ライブラリをクライアントサイドの評価ツールに完全に移行します。

最初に初期プログラムをプライミングする

AlphaEvolve を実行する前に、標準のコーディングエージェントを使用して、シードコードベースとエバリュエータの両方をデバッグします。

シードを準備する: 明らかな構文バグ、コンパイルの問題、エッジケースを修正します。
開始スコアを確認する: ベースラインスコアが妥当であり、評価ツールが完全に決定的（同じコード + 同じ入力 = 同じスコア）であることを確認します。
無効な入力でテストする: 意図的に破損した関数を使用して評価ツールを実行し、コンパイラの問題をキャッチし、無限ループを適切に処理して、高い負のペナルティスコアを返すことを確認します。

過度に最適化されたベースラインを避ける

すでに高度に最適化されたベースラインプログラムをシードとして渡さないでください。初期プログラムがすでに最適に近い場合、改善の余地がほとんどないため、AlphaEvolve はヒルクライムが困難になります。妥当ではあるものの、最大限に最適化されていないベースラインから始めます。これにより、AlphaEvolve は探索と山登り法を行うことができます。

クライアントサイドランナーの安全保護対策

クライアントサイドの評価者は、悪意のある候補、リソースを大量に消費する候補、応答しない候補が並列ワーカーを停止させないように、厳格な安全保護対策を適用する必要があります。

厳格なタイムアウト: 30 分（検索空間の構造によってはそれ以下）の厳格な実行カットオフを適用します。
タイムアウトペナルティの送信: 候補プログラムバリアントがタイムアウトの上限を超えた場合は、実行スレッドを直ちに終了します。候補プロセスが失敗しないようにします。代わりに、重大な障害ペナルティスコア（-100000.0 など）を、わかりやすいデバッグ分析情報とともにすぐにコンパイルしてサーバーに送信し、プログラムのキューロックを解除します。
AST セキュリティフィルタ: コンパイル前に、受信したソースコードペイロードに対して常に抽象構文ツリー（AST）検査チェックを実行します。制限付きのリフレクションまたは実行プリミティブ（eval、exec、getattr、setattr など）が検出された場合は、直ちに実行を中止し、重大な失敗ペナルティを適用します。

その他のリソース

詳しくは、次のリソースをご覧ください。

AlphaEvolve API リファレンス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

統合されたライフサイクル ステート マシン

テストのライフサイクル状態

プログラムの状態

同時実行とロックのメカニズム

構成と設定のスキーマ

AlphaEvolveExperimentConfig

RunSettings

生成設定

サポートされているモデル

デフォルト モデル

進化の設定

候補プログラムのデータモデル

AlphaEvolveProgramContent

AlphaEvolveSourceFile

AlphaEvolveProgramEvaluation

スコアの作成と取り込み形式

最大化ルール

単一目的の取り込みスキーマ

多目的取り込みスキーマ

番組データの取得とクエリ

REST API を使用したプログラムの取得

CLI を使用したプログラムの取得

CLI の使用例

Core REST API エンドポイント ディレクトリ

親リソースパスのパターン

テストを作成する（POST）

API ペイロードの例

テストを開始する（POST）

API ペイロードの例

番組を取得する（POST）

API ペイロードの例

プログラム評価を送信する（POST）

API ペイロードの例

テストを再開する（POST）

API ペイロードの例

プログラムの一覧表示（GET）

API ペイロードの例

診断コードとトラブルシューティングのリファレンス

API 診断コード マトリックス

一般的なエラー メッセージと解決策

初期プログラムと EVOLVE-BLOCK の解析エラー

プログラムのコンテンツと構造のエラー

構成とモデルの検証エラー

プロジェクトの前提条件とテストのライフサイクル エラー

プログラムの取得と評価のエラー

「サイレント ドロップ」の修正

クライアントサイド評価のベスト プラクティス

「スパゲッティ コード」のボトルネック

コンテキスト ウィンドウの割り当て

最初に初期プログラムをプライミングする

過度に最適化されたベースラインを避ける

クライアントサイド ランナーの安全保護対策

その他のリソース

AlphaEvolve API リファレンス

統合されたライフサイクルステートマシン

`AlphaEvolveExperimentConfig`

デフォルトモデル

Core REST API エンドポイントディレクトリ

API 診断コードマトリックス

一般的なエラーメッセージと解決策

プロジェクトの前提条件とテストのライフサイクルエラー

「サイレントドロップ」の修正

クライアントサイド評価のベストプラクティス

「スパゲッティコード」のボトルネック

コンテキストウィンドウの割り当て

クライアントサイドランナーの安全保護対策