agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/_jobs_common.py

@@ -0,0 +1,39 @@
+"""Helpers shared by the eval/jobs command modules (run, view, history, pause/resume, ...)."""
+
+from collections.abc import Callable
+from typing import Any
+
+import typer
+
+from agentcore.cli.commands.logs.guards import require_project
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.utils.json_format import to_json_string
+
+__all__ = ["fail_early", "print_json", "red", "require_project", "result_json"]
+
+
+def print_json(payload: dict[str, Any]) -> None:
+    """``console.log(JSON.stringify(payload))`` with undefined (None) top-level keys dropped."""
+    typer.echo(to_json_string({k: v for k, v in payload.items() if v is not None}, None))
+
+
+def red(message: str) -> None:
+    """Ink ``<Text color="red">`` (stdout)."""
+    typer.secho(message, fg=typer.colors.RED)
+
+
+def fail_early(as_json: bool, error: str) -> None:
+    """Upstream's pre-validation pattern: JSON error line or red text, then exit 1."""
+    if as_json:
+        print_json({"success": False, "error": error})
+    else:
+        red(error)
+    raise typer.Exit(1)
+
+
+def result_json(result: Ok | Err, value_key: Callable[[Any], dict] | None = None) -> dict[str, Any]:
+    from agentcore.lib import serialize_result
+
+    if result.success and value_key is not None:
+        return {"success": True, **value_key(result.value)}
+    return serialize_result(result)

agentcore/cli/commands/_run_wizards.py

@@ -0,0 +1,639 @@
+"""Prompt-based replacements for the `run` TUI flows.
+
+Question order follows tui/screens/run-eval/RunBatchEvalFlow.tsx, tui/screens/recommendation/*
+and tui/screens/run-ab-test/RunABTestFlow.tsx.
+"""
+
+import json
+import os
+import re
+from typing import Any
+
+import typer
+
+from agentcore.aws import agentcore_control as control
+from agentcore.aws import agentcore_datasets as datasets_api
+from agentcore.aws import region as _region
+from agentcore.aws.account import validate_aws_credentials
+from agentcore.cli import interactive
+from agentcore.cli.errors import get_error_message
+from agentcore.lib import ConfigIO
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.operations import resolve_agent as _resolve_agent
+from agentcore.operations.dataset.resolve_dataset import resolve_dataset
+from agentcore.operations.eval.run_eval import discover_sessions
+from agentcore.operations.jobs import create_job_engine, run_dataset_phase1
+from agentcore.operations.jobs.shared.format import parse_int, parse_js_date
+from agentcore.schema import is_valid_kms_key_arn
+
+Choice = interactive.Choice
+DEFAULT_LOOKBACK_DAYS = 7
+_KMS_INVALID = "Invalid KMS key ARN (e.g. arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012)"
+
+
+def _require_creds() -> None:
+    try:
+        validate_aws_credentials()
+    except Exception as exc:  # noqa: BLE001
+        typer.secho("AWS credentials required", fg=typer.colors.RED, err=True)
+        typer.echo(get_error_message(exc), err=True)
+        raise typer.Exit(1) from None
+
+
+def _error(message: str, detail: str | None = None) -> None:
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    if detail:
+        typer.echo(detail, err=True)
+    raise typer.Exit(1)
+
+
+def _evaluator_choices(evaluators: list[dict[str, Any]]) -> list[Choice]:
+    return [
+        Choice(
+            e["evaluatorName"],
+            e["evaluatorArn"],
+            "Built-in evaluator"
+            if e.get("evaluatorType") == "Builtin"
+            else (e.get("description") or "Custom evaluator"),
+        )
+        for e in evaluators
+    ]
+
+
+def _validate_days(value: str) -> str | None:
+    days = parse_int(value)
+    if days is None:
+        return "Must be a number"
+    return None if 1 <= days <= 90 else "Must be between 1 and 90"
+
+
+def _validate_kms(value: str) -> str | None:
+    return None if not value or is_valid_kms_key_arn(value) else _KMS_INVALID
+
+
+def _session_label(session: dict[str, Any]) -> tuple[str, str]:
+    parsed = parse_js_date(session.get("firstSeen")) if session.get("firstSeen") else None
+    date = ""
+    if parsed is not None:
+        local = parsed.astimezone()
+        hour12 = local.hour % 12 or 12
+        months = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+        date = f"{months[local.month - 1]} {local.day}, {hour12:02d}:{local.minute:02d} {'AM' if local.hour < 12 else 'PM'}"
+    return session["sessionId"], f"{session.get('spanCount', 0)} spans · {date}"
+
+
+def _pick_sessions(runtime_id: str, region: str, days: int, title: str) -> list[str]:
+    typer.echo("Discovering sessions...")
+    sessions = discover_sessions(runtime_id=runtime_id, region=region, lookback_days=days)
+    if not sessions:
+        _error(f"No sessions found in the last {days} day(s). Invoke the agent first and wait for traces to propagate.")
+    count = len(sessions)
+    typer.echo(f"Found {count} session{'' if count == 1 else 's'} — select one or more")
+    while True:
+        picked = interactive.checkbox(
+            title, [Choice(_session_label(s)[0], s["sessionId"], _session_label(s)[1]) for s in sessions]
+        )
+        if picked:
+            return picked
+        typer.echo("Select at least one session.", err=True)
+
+
+def _ground_truth(session_ids: list[str]) -> list[dict[str, Any]] | None:
+    mode = interactive.select(
+        "Ground truth (optional)",
+        [
+            Choice("Skip", "skip", "No ground truth"),
+            Choice("Load from file", "file", "JSON file with session metadata and ground truth"),
+            Choice("Enter manually", "inline", "Type assertions, trajectory, and expected response"),
+        ],
+    )
+    if mode == "skip":
+        return None
+    if mode == "file":
+        typer.echo("Select a JSON file with session ground truth (assertions, expected trajectory, turns).")
+        while True:
+            path = interactive.text("path/to/ground-truth.json")
+            try:
+                with open(os.path.abspath(os.path.expanduser(path.strip())), encoding="utf-8") as fh:
+                    parsed = json.load(fh)
+                metadata = parsed if isinstance(parsed, list) else (parsed or {}).get("sessionMetadata")
+                if not isinstance(metadata, list):
+                    typer.secho('File must be a JSON array or contain a "sessionMetadata" array', fg="red")
+                    continue
+                return metadata
+            except Exception as exc:  # noqa: BLE001
+                typer.secho(f"Failed to load file: {exc}", fg="red")
+    label = session_ids[0] if len(session_ids) == 1 else f"{len(session_ids)} sessions"
+    typer.echo(f"Session: {label}")
+    typer.echo("All fields are optional. Press Enter on empty to skip to next section.")
+    assertions = _collect_lines("Assertions:")
+    trajectory = _collect_lines("Expected trajectory:")
+    response = interactive.text("Expected response (targets last trace):")
+    inline: dict[str, Any] = {}
+    if assertions:
+        inline["assertions"] = [{"text": a} for a in assertions]
+    if trajectory:
+        inline["expectedTrajectory"] = {"toolNames": trajectory}
+    if response:
+        inline["turns"] = [{"input": {"prompt": ""}, "expectedResponse": {"text": response}}]
+    return [{"sessionId": sid, "groundTruth": {"inline": inline}} for sid in session_ids]
+
+
+def _collect_lines(label: str) -> list[str]:
+    values: list[str] = []
+    while True:
+        value = interactive.text(f"{label} ({len(values) + 1})")
+        if not value:
+            return values
+        values.append(value)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Batch evaluation
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def run_batch_eval_wizard() -> None:
+    _require_creds()
+    context = _resolve_agent.load_deployed_project_config()
+    targets = context.aws_targets or []
+    region = (targets[0].region if targets else None) or _region.detect_region().region
+    evaluators = control.list_evaluators(region=region)["evaluators"]
+    deployed = to_jsonable(context.deployed_state)
+    deployed_names: set[str] = set()
+    runtime_ids: dict[str, str] = {}
+    for target in (deployed.get("targets") or {}).values():
+        for name, state in (((target or {}).get("resources") or {}).get("runtimes") or {}).items():
+            deployed_names.add(name)
+            runtime_ids[name] = state["runtimeId"]
+    project = to_jsonable(context.project)
+    agents = [r for r in project.get("runtimes") or [] if r["name"] in deployed_names]
+    if not agents:
+        _error(
+            "No agents found in project. Run `agentcore add agent` first."
+            if not project.get("runtimes")
+            else "No deployed agents found. Run `agentcore deploy` first."
+        )
+    if not evaluators:
+        _error("No evaluators found in your account. Create an evaluator first.")
+
+    source = interactive.select(
+        "Evaluation source:",
+        [
+            Choice("Dataset", "dataset", "Invoke agent with dataset scenarios"),
+            Choice("Historical traces", "traces", "Evaluate existing sessions"),
+        ],
+    )
+    dataset = dataset_version = None
+    if source == "dataset":
+        datasets = project.get("datasets") or []
+        labels = {
+            "AGENTCORE_EVALUATION_PREDEFINED_V1": "Predefined Turns",
+            "AGENTCORE_EVALUATION_SIMULATED_V1": "Actor Simulator",
+        }
+        if len(datasets) == 1:
+            dataset = datasets[0]["name"]
+        elif datasets:
+            dataset = interactive.select(
+                "Select dataset:",
+                [Choice(d["name"], d["name"], labels.get(d["schemaType"], d["schemaType"])) for d in datasets],
+            )
+        if dataset:
+            versions = [Choice("Local file", "local", "fastest iteration, no push required")]
+            try:
+                resolved = resolve_dataset(dataset)
+                listed = datasets_api.list_dataset_versions(region=resolved.region, dataset_id=resolved.dataset_id)
+                versions.append(Choice("DRAFT", "DRAFT", "latest pushed content"))
+                for v in sorted(listed.get("versions") or [], key=lambda v: v.get("createdAt") or 0, reverse=True):
+                    versions.append(
+                        Choice(
+                            f"Version {v['datasetVersion']}", v["datasetVersion"], f"{v.get('exampleCount')} examples"
+                        )
+                    )
+            except Exception:  # noqa: BLE001, S110 - not deployed yet: local only
+                pass
+            picked = interactive.select(f"Select version for {dataset}:", versions)
+            dataset_version = None if picked == "local" else picked
+
+    agent = agents[0]["name"]
+    if len(agents) > 1:
+        agent = interactive.select(
+            "Select agent to evaluate", [Choice(a["name"], a["name"], a.get("build")) for a in agents]
+        )
+    while True:
+        chosen = interactive.checkbox("Select evaluators", _evaluator_choices(evaluators))
+        if chosen:
+            break
+        typer.echo("Select at least one evaluator.", err=True)
+    names = [e["evaluatorName"] for e in evaluators if e["evaluatorArn"] in chosen]
+
+    days = DEFAULT_LOOKBACK_DAYS
+    session_ids: list[str] = []
+    session_metadata = None
+    if source == "traces":
+        typer.echo("Note: Traces may take 5–10 min to appear after agent invocations.")
+        days = (
+            parse_int(
+                interactive.text("Lookback window (days)", default=str(DEFAULT_LOOKBACK_DAYS), validate=_validate_days)
+            )
+            or DEFAULT_LOOKBACK_DAYS
+        )
+        session_ids = _pick_sessions(runtime_ids[agent], region, days, "Select sessions to evaluate")
+        session_metadata = _ground_truth(session_ids)
+    kms = interactive.text("KMS key ARN for encryption (optional, press Enter to skip)", validate=_validate_kms)
+    typer.echo("Optional — leave blank for auto-generated name.")
+    name = interactive.text("Batch evaluation name")
+
+    rows = [("Agent", agent), ("Evaluators", ", ".join(names))]
+    if source == "dataset":
+        rows.append(("Dataset", f"{dataset}@{dataset_version or 'LOCAL'}"))
+    else:
+        rows += [("Lookback", f"{days} days"), ("Sessions", str(len(session_ids)))]
+    if kms:
+        rows.append(("KMS Key", kms))
+    rows.append(("Name", name or "(auto-generated)"))
+    for label, value in rows:
+        typer.echo(f"  {label}: {value}")
+    if not interactive.confirm("Start batch evaluation?", default=True):
+        typer.echo("Cancelled.")
+        return
+
+    if source == "dataset":
+        phase1 = run_dataset_phase1(
+            agent=agent,
+            dataset_name=dataset or "",
+            dataset_version=dataset_version,
+            on_progress=lambda _p, m: typer.echo(m),
+        )
+        if not phase1.success:
+            _error("Batch evaluation failed", str(phase1.error))
+        session_ids = phase1.value["sessionIds"]
+        session_metadata = phase1.value["sessionMetadata"]
+
+    engine = create_job_engine(ConfigIO())
+    result = engine.start(
+        "batch-evaluation",
+        {
+            "agent": agent,
+            "evaluators": chosen,
+            "name": name or None,
+            "sessionIds": session_ids or None,
+            "lookbackDays": days,
+            "sessionMetadata": session_metadata,
+            "source": "dataset" if dataset else "traces",
+            "dataset": {"id": dataset, "version": dataset_version or "LOCAL"} if dataset else None,
+            "kmsKeyArn": kms or None,
+        },
+    )
+    if not result.success:
+        _error("Batch evaluation failed", str(result.error))
+    record = result.value
+    typer.secho(f"✓ {record['id']} ({record['status']})", fg=typer.colors.GREEN)
+    typer.echo(f"Agent: {agent}  Evaluators: {', '.join(names)}")
+    typer.echo("\nWhen it completes, view it in Batch Eval Jobs.")
+    typer.echo(f"Next: agentcore view batch-evaluation {record['id']}")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Recommendation
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def collect_string_fields(obj: Any, prefix: str, json_path_prefix: str) -> list[dict[str, str]]:
+    """All non-empty string leaves with dot paths and JSONPath equivalents (RecommendationFlow)."""
+    fields: list[dict[str, str]] = []
+    if not isinstance(obj, dict):
+        return fields
+    for key, value in obj.items():
+        path = f"{prefix}.{key}" if prefix else key
+        jp = f"{json_path_prefix}.{key}" if json_path_prefix else key
+        if isinstance(value, str) and value.strip():
+            fields.append({"path": path, "jsonPath": jp, "value": value})
+        elif isinstance(value, dict):
+            fields.extend(collect_string_fields(value, path, jp))
+    return fields
+
+
+def _bundle_items(deployed: dict[str, Any], project: dict[str, Any]) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for target in (deployed.get("targets") or {}).values():
+        for name, state in (((target or {}).get("resources") or {}).get("configBundles") or {}).items():
+            if name in seen:
+                continue
+            seen.add(name)
+            spec = next((b for b in project.get("configBundles") or [] if b["name"] == name), None)
+            items.append(
+                {
+                    "name": name,
+                    "bundleArn": state["bundleArn"],
+                    "versionId": state.get("versionId"),
+                    "fields": collect_string_fields((spec or {}).get("components"), "", "$") if spec else [],
+                }
+            )
+    return items
+
+
+def _field_title(path: str) -> str:
+    segments = path.split(".")
+    if "configuration" in segments:
+        return ".".join(segments[segments.index("configuration") :])
+    return ".".join(segments[-2:])
+
+
+def run_recommendation_wizard() -> None:
+    _require_creds()
+    config_io = ConfigIO()
+    region = _region.detect_region().region
+    deployed = to_jsonable(config_io.read_deployed_state())
+    agents: dict[str, dict[str, Any]] = {}
+    for target in (deployed.get("targets") or {}).values():
+        for name, state in (((target or {}).get("resources") or {}).get("runtimes") or {}).items():
+            agents.setdefault(name, state)
+    if not agents:
+        _error("No deployed agents found. Run `agentcore deploy` first.")
+    evaluators = control.list_evaluators(region=region)["evaluators"]
+    project = to_jsonable(config_io.read_project_spec())
+    bundles = _bundle_items(deployed, project)
+
+    rec_type = interactive.select(
+        "What do you want to optimize?",
+        [
+            Choice(
+                "System Prompt", "SYSTEM_PROMPT_RECOMMENDATION", "Optimize your agent's system prompt based on traces"
+            ),
+            Choice(
+                "Tool Description",
+                "TOOL_DESCRIPTION_RECOMMENDATION",
+                "Optimize tool descriptions for better tool selection",
+            ),
+        ],
+    )
+    is_sys = rec_type == "SYSTEM_PROMPT_RECOMMENDATION"
+    agent = interactive.select("Select agent", [Choice(n, n, f"Runtime: {s['runtimeId']}") for n, s in agents.items()])
+    chosen_evaluators: list[str] = []
+    if is_sys:
+        chosen_evaluators = [
+            interactive.select(
+                "Select evaluator",
+                [
+                    Choice(
+                        e["evaluatorName"],
+                        e["evaluatorArn"] or e["evaluatorName"],
+                        e.get("description") or e.get("evaluatorType"),
+                    )
+                    for e in evaluators
+                ],
+            )
+        ]
+    input_choices = (
+        [
+            Choice("Enter inline", "inline", "Type or paste content directly"),
+            Choice("Load from file", "file", "Read content from a file path"),
+            Choice("Config bundle", "config-bundle", "Use system prompt from a deployed config bundle"),
+        ]
+        if is_sys
+        else [
+            Choice("Enter inline", "inline", "Type tool name:description pairs directly"),
+            Choice("Config bundle", "config-bundle", "Read tool descriptions from a deployed config bundle"),
+        ]
+    )
+    input_source = interactive.select(
+        "How do you want to provide the system prompt?" if is_sys else "How do you want to provide tool descriptions?",
+        input_choices,
+    )
+    content = tools = ""
+    bundle_arn = bundle_version = prompt_path = None
+    tool_paths: list[dict[str, str]] = []
+    if input_source == "config-bundle":
+        if not bundles:
+            _error("No deployed config bundles found. Run `agentcore add config-bundle` and `agentcore deploy` first.")
+        bundle_arn = interactive.select(
+            "Select config bundle", [Choice(b["name"], b["bundleArn"], b.get("versionId")) for b in bundles]
+        )
+        bundle = next(b for b in bundles if b["bundleArn"] == bundle_arn)
+        bundle_version = bundle.get("versionId")
+        fields = bundle["fields"]
+        if not fields:
+            _error("No text fields found in this config bundle's configuration.")
+        field_choices = [
+            Choice(_field_title(f["path"]), f["path"], f["value"][:80] + "…" if len(f["value"]) > 80 else f["value"])
+            for f in fields
+        ]
+        if is_sys:
+            picked = interactive.select("Which field contains the system prompt?", field_choices)
+            prompt_path = next(f["jsonPath"] for f in fields if f["path"] == picked)
+        else:
+            if len(fields) == 1:
+                picked_paths = [interactive.select("Which field contains the tool description?", field_choices)]
+            else:
+                picked_paths = []
+                while not picked_paths:
+                    picked_paths = interactive.checkbox("Which fields contain tool descriptions?", field_choices)
+            tool_paths = [
+                {"toolName": f["path"].split(".")[-1], "toolDescriptionJsonPath": f["jsonPath"]}
+                for f in fields
+                if f["path"] in picked_paths
+            ]
+    elif is_sys and input_source == "file":
+        content = interactive.text(
+            "/path/to/prompt.txt",
+            validate=lambda v: None if os.path.isfile(os.path.expanduser(v)) else "File not found",
+        )
+        content = os.path.abspath(os.path.expanduser(content))
+    elif is_sys:
+        content = interactive.text("System prompt")
+    else:
+        typer.echo("Enter tool names and descriptions as comma-separated toolName:description pairs.")
+        tools = interactive.text("Tools")
+
+    trace_source = interactive.select(
+        "How do you want to source agent traces?",
+        [
+            Choice("CloudWatch Logs", "cloudwatch", "Discover traces from agent runtime logs"),
+            Choice("Session IDs", "sessions", "Provide specific session IDs manually"),
+        ],
+    )
+    days = (
+        parse_int(
+            interactive.text("Lookback window (days)", default=str(DEFAULT_LOOKBACK_DAYS), validate=_validate_days)
+        )
+        or DEFAULT_LOOKBACK_DAYS
+    )
+    session_ids: list[str] = []
+    if trace_source == "sessions":
+        session_ids = _pick_sessions(agents[agent]["runtimeId"], region, days, "Select sessions to analyze")
+    kms = interactive.text("KMS key ARN for encryption (optional, press Enter to skip)", validate=_validate_kms)
+
+    rows = [("Type", "System Prompt" if is_sys else "Tool Description"), ("Agent", agent)]
+    if chosen_evaluators:
+        rows.append(("Evaluator", chosen_evaluators[0]))
+    rows += [("Source", input_source), ("Traces", trace_source), ("Lookback", f"{days} days")]
+    if kms:
+        rows.append(("KMS Key", kms))
+    for label, value in rows:
+        typer.echo(f"  {label}: {value}")
+    if not interactive.confirm("Start recommendation?", default=True):
+        typer.echo("Cancelled.")
+        return
+
+    engine = create_job_engine(config_io)
+    result = engine.start(
+        "recommendation",
+        {
+            "type": rec_type,
+            "agent": agent,
+            "evaluators": chosen_evaluators,
+            "inputSource": input_source,
+            "inlineContent": content if input_source == "inline" else None,
+            "promptFile": content if input_source == "file" else None,
+            "bundleName": bundle_arn,
+            "bundleVersion": bundle_version,
+            "systemPromptJsonPath": prompt_path,
+            "toolDescJsonPaths": tool_paths or None,
+            "tools": [t.strip() for t in re.split(r",(?=[a-zA-Z0-9_\-.]+:)", tools) if t.strip()] if tools else None,
+            "traceSource": trace_source,
+            "lookbackDays": days,
+            "sessionIds": session_ids or None,
+            "kmsKeyArn": kms or None,
+        },
+    )
+    if not result.success:
+        _error("Recommendation failed", str(result.error))
+    record = result.value
+    typer.secho(f"✓ {record['id']} ({record['status']})", fg=typer.colors.GREEN)
+    typer.echo(
+        "When it completes, view it in Recommendation Jobs — the new config bundle (if any) will be applied to "
+        "agentcore.json automatically."
+    )
+    typer.echo(f"Next: agentcore view recommendation {record['id']}")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# A/B test
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _load_ab_resources() -> dict[str, Any]:
+    config_io = ConfigIO()
+    project = to_jsonable(config_io.read_project_spec())
+    deployed = to_jsonable(config_io.read_deployed_state())
+    bundles: list[str] = []
+    gateways: dict[str, None] = {}
+    evals: dict[str, None] = {}
+    for target in (deployed.get("targets") or {}).values():
+        resources = (target or {}).get("resources") or {}
+        bundles += list((resources.get("configBundles") or {}).keys())
+        gateways.update(dict.fromkeys(((resources.get("mcp") or {}).get("gateways") or {}).keys()))
+        gateways.update(dict.fromkeys((resources.get("gateways") or {}).keys()))
+        evals.update(dict.fromkeys((resources.get("onlineEvalConfigs") or {}).keys()))
+    targets: dict[str, None] = {}
+    for gw in project.get("agentCoreGateways") or []:
+        for t in gw.get("targets") or []:
+            if t.get("targetType") == "httpRuntime":
+                targets[t["name"]] = None
+    return {"gateways": list(gateways), "bundles": bundles, "targets": list(targets), "onlineEvalConfigs": list(evals)}
+
+
+def _variant(variant: str, mode: str, resources: dict[str, Any], default_weight: int) -> dict[str, Any]:
+    typer.echo(f"{variant} Variant")
+    typer.echo("─" * 30)
+    out: dict[str, Any] = {}
+    if mode == "config-bundle":
+        out["bundle"] = interactive.select("Select config bundle:", [Choice(b, b) for b in resources["bundles"]])
+        typer.echo("Bundle version (or LATEST):")
+        out["version"] = interactive.text("Version", default="LATEST") or "LATEST"
+    else:
+        out["target"] = interactive.select("Select gateway target:", [Choice(t, t) for t in resources["targets"]])
+        out["eval"] = interactive.select(
+            "Select online eval (scoped to this endpoint):", [Choice(c, c) for c in resources["onlineEvalConfigs"]]
+        )
+    typer.echo("Traffic weight (0-100):")
+    out["weight"] = parse_int(
+        interactive.text(
+            "Weight",
+            default=str(default_weight),
+            validate=lambda v: (
+                None if (w := parse_int(v)) is not None and 0 <= w <= 100 else "Must be between 0 and 100"
+            ),
+        )
+    )
+    return out
+
+
+def run_ab_test_wizard() -> None:
+    _require_creds()
+    resources = _load_ab_resources()
+    if not resources["gateways"]:
+        _error("No deployed gateway found. Run `agentcore add gateway` and `agentcore deploy` first.")
+    mode = interactive.select(
+        "Variant mode",
+        [
+            Choice("Config bundle", "config-bundle", "Compare two configuration bundle versions"),
+            Choice("Target based", "target-based", "Compare two gateway-target runtime endpoints"),
+        ],
+    )
+    gateway = interactive.select("Select gateway", [Choice(g, g) for g in resources["gateways"]])
+    control_v = _variant("Control", mode, resources, 50)
+    treatment_v = _variant("Treatment", mode, resources, 100 - (control_v["weight"] or 50))
+    treatment_weight = treatment_v["weight"] or 0
+    control_weight = 100 - treatment_weight
+    online_eval = None
+    if mode == "config-bundle":
+        online_eval = interactive.select(
+            "Shared online eval config", [Choice(c, c) for c in resources["onlineEvalConfigs"]]
+        )
+    typer.echo("Gateway filter (optional)")
+    typer.echo('Restrict the test to one gateway target path pattern (e.g. "/orders/*").')
+    typer.echo("Leave blank to have no gateway filter.")
+    gateway_filter = interactive.text("Gateway filter").strip()
+    typer.echo("A short name for this A/B test.")
+    name = interactive.text("A/B test name", validate=lambda v: None if v.strip() else "Name is required").strip()
+
+    rows = [("Name", name), ("Mode", mode), ("Gateway", gateway)]
+    if mode == "config-bundle":
+        rows += [
+            ("Control", f"{control_v['bundle']} @ {control_v['version']} (weight {control_weight})"),
+            ("Treatment", f"{treatment_v['bundle']} @ {treatment_v['version']} (weight {treatment_weight})"),
+            ("Online eval", online_eval or ""),
+        ]
+    else:
+        rows += [
+            ("Control", f"{control_v['target']} — eval: {control_v['eval']} (weight {control_weight})"),
+            ("Treatment", f"{treatment_v['target']} — eval: {treatment_v['eval']} (weight {treatment_weight})"),
+        ]
+    rows.append(("Gateway filter", gateway_filter or "none"))
+    for label, value in rows:
+        typer.echo(f"  {label}: {value}")
+    if not interactive.confirm("Start A/B test?", default=True):
+        typer.echo("Cancelled.")
+        return
+    cb = mode == "config-bundle"
+    engine = create_job_engine(ConfigIO())
+    result = engine.start(
+        "ab-test",
+        {
+            "name": name,
+            "mode": mode,
+            "gateway": gateway,
+            "controlBundle": control_v.get("bundle") if cb else None,
+            "controlVersion": control_v.get("version") if cb else None,
+            "treatmentBundle": treatment_v.get("bundle") if cb else None,
+            "treatmentVersion": treatment_v.get("version") if cb else None,
+            "controlTarget": None if cb else control_v.get("target"),
+            "treatmentTarget": None if cb else treatment_v.get("target"),
+            "onlineEval": online_eval if cb else None,
+            "controlOnlineEval": None if cb else control_v.get("eval"),
+            "treatmentOnlineEval": None if cb else treatment_v.get("eval"),
+            "gatewayFilter": gateway_filter or None,
+            "controlWeight": control_weight,
+            "treatmentWeight": treatment_weight,
+            "enableOnCreate": True,
+            "onProgress": lambda _s, m: typer.echo(m),
+        },
+    )
+    if not result.success:
+        _error("A/B test failed", str(result.error))
+    record = result.value
+    typer.secho(f"✓ {record['id']} ({record['status']})", fg=typer.colors.GREEN)
+    typer.echo(f"Next: agentcore view ab-test {record['id']}")