ae-experiment

ae-experiment

AE CLI（ae-cli）は、experiment ドメインを通じて Atlas AB Experiment の機能を提供します。

グローバルルール

• Atlas AB Experiment の操作には、ae-cli experiment <command> を優先して使用します。
• プロジェクトにスコープされたコマンドには、--project-id / -p を使用します。
• 複雑な保存、ステータス、削除 DTO には、--req JSON を使用します。
• 実験 ID、トラフィックレイヤー ID、バケット ID、Feature キー、メトリクス ID、ペイロードのフィールド名を作り出してはいけません。
• experiment metric list が返すメトリクス ID のみをバインドします。不足しているメトリクスがある場合は、実験の保存前に作成し、確認します。
• ID を確認した後は、読み取りコマンドを直接実行できます。
• 書き込みコマンドには、ユーザーの明示的な意図が必要です。通常は確認プロンプトを維持します。JSON を作成するときは、書き込みコマンドの実行前に --dry-run を使用します。

名前付けとレスポンスの境界：

• CLI のコマンドセグメントとフラグには、kebab-case を使用します。
• 外側の Capability 入力とすべてのレスポンスキーには、snake_case を使用します。
• --req を通じて渡すネストされたビジネス DTO では、ネイティブの camelCase フィールドを維持します。
• 重要： save build-guide / save validate のレスポンスでは、example_args.req が再帰的に snake_case に変換されます。これらのキーを --req にコピーしてはいけません。camelCase（expName、metricId など）を使用します。正しい名前の確認先： ae-cli capability inspect experiment.experiment.save（または対応する最終保存 ID） → input_schema.properties.req。save validate の valid: true は、最終保存用スキーマの検証に合格したことを意味しません。snake_case の req は experiment … save で引き続き失敗する可能性があります。
• オーディエンス QP は CLI の境界で意味的に変換されます。書き込み時は targeting.definitionRequest、読み取り時は targeting.definition_request を使用します。targetConfig を生成または送信してはいけません。
• メトリクス QP は CLI の境界で意味的に変換されます。書き込み時は metricDefinition、読み取り時は metric_definition を使用します。metricConfig、calcType、Axxx コードを生成または送信してはいけません。
• イベントプロパティの比較は、metricDefinition.filters 内で {relation,items:[{field,operator,values}]} を使用して指定します。比較フィールドを metricDefinition に直接含めたり、生の filts、calcuSymbol、ftv フィールドを送信したりしてはいけません。
• メトリクスの集計 sum / avg / max / distinct_count では、metricDefinition.property が必須です。Analysis メタデータで利用可能な具体的なイベントプロパティを指定する必要があります。property を指定せずにプロパティ集計を作成してはいけません（例：metric_avg_no_property_*）。
• プリセットのイベント集計 total_count / user_count / active_days では、property を省略します。
• 実験メトリクスの作成では、avg_per_user / A105 はサポートされていません。
• 意味的な定義を保存する前に、Analysis メタデータでイベント名とプロパティ名を確認します。
• リストは data.items と data.total を返し、詳細コマンドは data.item を返します。
• 準備状況は data.readiness、レポートは data.report、保存ガイドは data.guide、保存のドライラン検証は data.validation、書き込みは data.result を返します。
• クエリのキャンセルは data.success を返します。

一般的なワークフロー

1. 再利用可能なアセットを確認します：
   • experiment bucket list
   • experiment traffic-layer list
   • experiment feature list
   • experiment metric list
2. 必要に応じて不足しているアセットを作成します：
   • 保存の検証に失敗した場合、またはリクエストの形式が不明な場合は、experiment save build-guide --operation-mode save_metric を実行します
   • 失敗した保存を再試行する前に、experiment save validate --operation-mode save_metric --req '{...}' を実行します
   • experiment traffic-layer save
   • experiment feature save
   • experiment metric save
3. experiment experiment save で実験の下書きを作成または更新します。 指標の紐付けを置き換える場合や、ガードレールの役割を割り当てる場合は、experiment experiment update-metrics を使用します。
4. 外部実験の場合は、代わりに experiment external-experiment save-submit を使用します。これは直接送信するため、Features、トラフィックレイヤー、割り当て、ターゲティング、実験サイクルは使用しません。
5. experiment experiment ready-check で準備状況を確認します。
6. ミューテックスでないトラフィックレイヤーの場合は、送信前に experiment experiment conflict-check を実行します（コンテキストまたは experiment get から feature_key_list が必要です）。
7. experiment experiment manage でステータスを変更します。
8. experiment report summary、experiment report sample-size、experiment report metric-trend でレポートを照会します。

実験の保存で error_code: METRIC_NOT_FOUND が返された場合は、同じプロジェクトの指標を一覧表示します。再試行する前に指標を作成して検証してください。別の推測した ID で再試行してはいけません。有効な実験の紐付けが存在する間、指標の削除は error_code: METRIC_IN_USE を返します。

パラメーターの規則

• 実験の保存ペイロードでは、2 つの割り当てフィールドを区別します：実験レベルの req.allocation（整数のみ、小数不可）と、グループレベルの req.groups[].allocation（整数のみ、合計は正確に 100 である必要があります）。
• 公開されている実験指標の役割は primary、secondary、guardrail です。内部用の observation 役割は現在、保存時に利用できません。Guardrail は紐付けの役割です。指標を更新すると、紐付けリスト全体が置き換えられます。

ae-cli experiment experiment get --project-id 1 --exp-id exp_123
ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_gold_sum","metricName":"Payment gold sum","createType":"event","goalDirection":"up","metricDesc":"Gold sum for payments above 10","metricDefinition":{"type":"event","event":"payment","aggregation":"sum","property":"gold","filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}}' --dry-run
ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07

任意のグローバルパラメーターは、他のドメインと同様に使用できます：--host、--mcp-url、--format、--jq、--dry-run、--yes。

参照資料

コマンドを使用する前に、特に書き込み操作や JSON ペイロードを扱う場合は、references/ 内の該当ファイルを開いてください。

保存ヘルパー

experiment save build-guide、experiment save validate

保存コマンドが next_tool: experiment.save.build-guide を返した場合は、まずガイドを呼び出し、次に experiment save validate を実行してから、最終的な保存機能を再試行してください。

これらのヘルパーを使用する前に、save_build_guide.md と save_validate.md をお読みください。inspect / スキルの参照資料をもとに --req を camelCase で再構築し、example_args.req を貼り付けないでください。

実験

experiment experiment save、experiment experiment update-metrics、experiment external-experiment save-submit、capability run experiment.experiment.save-submit、experiment experiment list、experiment experiment list-archived、experiment experiment get、experiment experiment ready-check、experiment experiment conflict-check、experiment experiment manage、experiment experiment update-group、experiment experiment batch-delete、experiment operation-log query

指標の役割を割り当てる、または置き換える前に、manage_guardrail_metrics.md をお読みください。

外部実験

experiment external-experiment save-submit

外部実験を作成または更新する前に、save_submit_external_experiment.md をお読みください。

トラフィックレイヤーとバケット

experiment traffic-layer save、experiment traffic-layer get、experiment traffic-layer list、experiment traffic-layer batch-delete、experiment bucket list

レポート

experiment report summary、experiment report sample-size、experiment report metric-trend、capability run experiment.query.cancel

メトリクスとフィーチャー

experiment metric save、experiment metric get、experiment metric list、experiment metric delete、experiment feature save、experiment feature update-status、experiment feature get、experiment feature list、experiment feature version-list、experiment feature operation-log query、experiment feature batch-delete、experiment feature whitelist list、experiment feature whitelist save、experiment feature whitelist update-status、experiment feature whitelist batch-delete

Feature のホワイトリストルールを照会または変更する前に、manage_feature_whitelist.md をお読みください。