注: このドキュメントセットは、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: 実行スコアと記述的な構造的分析情報は、進化型データベースに安全にコミットされ、プログラムが選択プールに追加されます。

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

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

構成と設定のスキーマ

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（bool）: デフォルトは false です。
- true: ミューテーションプロンプトには、変更可能な EVOLVE-BLOCK と、その周辺の変更不可能なボイラープレートが含まれます（複雑な構造的推論に強く推奨されます）。
- false: 変更可能なブロックのみが表示され、トークンコンテキストが保存されます。
models（オブジェクトの配列）: 省略可。各エントリはモデルの名前を指定し、オプションの weight を指定します。これは、他のエントリに対するそのモデルの生成呼び出しの割合です。models を省略すると、AlphaEvolve はテストの作成時にデフォルトを選択します。これは、AlphaEvolve でのコード生成に Google が推奨する Gemini モデルです。この推奨事項は、新しいモデルがリリースされるたびに変更されます。2026 年 9 月 29 日以降、デフォルトは gemini-3.8-flash になります。別のモデルを使用するには、models で目的のモデルを指定します。すべての実行で同じモデルを固定するには、models を自分で設定します。

AlphaEvolve はテストの作成時にデフォルトを解決するため、デフォルトモデルの変更前に作成されたテストでは、構成に記録されたモデルが保持されます。既存のテストを Gemini 3.8 Flash に移行するには、models で指定するか、新しいテストを作成します。

次の例では、生成呼び出しの約 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-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 を返します。

進化の設定

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

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

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

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

AlphaEvolveProgramContent

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

files（AlphaEvolveSourceFile の配列）: 候補コードベースを構成するすべてのファイルのリスト。ペイロードには、少なくとも 1 つのソースファイルが含まれている必要があります。候補プログラムあたりの合計ファイル数を 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 プロジェクトは対象外です。
プロジェクトでは、ロケーションごとに同時にアクティブな（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 の一部ではないフィールド（API のプレビュー版に存在していた `notes` など）を削除します。評価は一度に 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`	プロジェクトが、ロケーションあたりの同時アクティブテストの上限（`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-START` が前に付いていない `EVOLVE-BLOCK-END` マーカーが表示されます。	すべての終了マーカーの前に、一致する開始マーカーがあることを確認します。
`Parsing error: Evolve block started but not ended.`	一致する終了 `EVOLVE-BLOCK-END` マーカーのない `EVOLVE-BLOCK-START` マーカーが見つかりました。	終了 `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>`	Google Cloud プロジェクトで Vertex AI API（`aiplatform.googleapis.com`）が有効になっていません。	`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 を追加します。ドキュメント文字列が実際の関数コードとともに存在することを確認します。EVOLVE-BLOCK 内にドキュメント文字列またはコメントのみを配置すると、空のブロックとして拒否されます。
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 診断コードマトリックス

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

「サイレントドロップ」を修復する

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

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

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

クライアントサイドランナーの保護