agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/online_eval_config.py

@@ -0,0 +1,365 @@
+"""Online eval config add/remove (port of src/cli/primitives/OnlineEvalConfigPrimitive.ts)."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import typer
+
+from agentcore.aws import agentcore_control as control
+from agentcore.aws import region as _region
+from agentcore.aws.account import validate_aws_credentials
+from agentcore.cli import interactive
+from agentcore.cli.commands.add._common import first_issue
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.naming import generate_unique_name
+from agentcore.cli.run_command import run_cli_command
+from agentcore.cli.variadic import variadic
+from agentcore.lib import ResourceNotFoundError, find_config_root, serialize_result
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.operations.jobs.shared.format import parse_float
+from agentcore.primitives.base import BasePrimitive, RemovableResource, RemovalPreview, SchemaChange, emit_json
+from agentcore.schema import OnlineEvalConfigName
+
+DEFAULT_SAMPLING_RATE = 10
+
+
+def validate_sampling_rate_text(value: str) -> str | None:
+    rate = parse_float(value)
+    if rate is None:
+        return "Must be a number"
+    if rate < 0.01 or rate > 100:
+        return "Must be between 0.01 and 100"
+    return None
+
+
+def check_endpoint(project: dict[str, Any], agent: str, endpoint: str) -> None:
+    runtime = next((r for r in project.get("runtimes") or [] if r.get("name") == agent), None)
+    if runtime is None:
+        raise Exception(f'Runtime "{agent}" not found in project.')
+    endpoints = runtime.get("endpoints")
+    if not (endpoints or {}).get(endpoint):
+        available = ", ".join(endpoints) if endpoints else "(none)"
+        raise Exception(f'Endpoint "{endpoint}" not found on runtime "{agent}". Available endpoints: {available}')
+
+
+def format_number(value: float) -> str:
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+@dataclass
+class AddOnlineEvalConfigOptions:
+    name: str
+    agent: str
+    evaluators: list[str]
+    sampling_rate: float
+    enable_on_create: bool | None = None
+    endpoint: str | None = None
+    log_group_names: list[str] | None = None
+    service_names: list[str] | None = field(default=None)
+
+
+class OnlineEvalConfigPrimitive(BasePrimitive):
+    kind = "online-eval"
+    label = "Online Eval Config"
+    article = "an"
+
+    def _project(self) -> dict[str, Any]:
+        return to_jsonable(self.read_project_spec())
+
+    def add(self, options: AddOnlineEvalConfigOptions) -> Ok | Err:
+        try:
+            project = self._project()
+            self.check_duplicate(
+                [RemovableResource(c["name"]) for c in project["onlineEvalConfigs"]], options.name, "Online eval config"
+            )
+            if options.endpoint and options.agent:
+                check_endpoint(project, options.agent, options.endpoint)
+            config: dict[str, Any] = {"name": options.name}
+            if options.agent:
+                config["agent"] = options.agent
+            config["evaluators"] = options.evaluators
+            config["samplingRate"] = options.sampling_rate
+            if options.enable_on_create is not None:
+                config["enableOnCreate"] = options.enable_on_create
+            if options.endpoint:
+                config["endpoint"] = options.endpoint
+            if options.log_group_names:
+                config["logGroupNames"] = options.log_group_names
+            if options.service_names:
+                config["serviceNames"] = options.service_names
+            project["onlineEvalConfigs"].append(config)
+            self.write_project_spec(project)
+            return Ok({"configName": options.name})
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def remove(self, name: str) -> Ok | Err:
+        try:
+            project = self._project()
+            index = next((i for i, c in enumerate(project["onlineEvalConfigs"]) if c["name"] == name), -1)
+            if index == -1:
+                return Err(ResourceNotFoundError(f'Online eval config "{name}" not found.'))
+            project["onlineEvalConfigs"].pop(index)
+            self.write_project_spec(project)
+            return Ok(None)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def preview_remove(self, name: str) -> RemovalPreview:
+        project = self._project()
+        config = next((c for c in project["onlineEvalConfigs"] if c["name"] == name), None)
+        if config is None:
+            raise Exception(f'Online eval config "{name}" not found.')
+        summary = [f"Removing online eval config: {name}"]
+        if config.get("evaluators"):
+            summary.append(f"Uses evaluators: {', '.join(config['evaluators'])}")
+        if config.get("insights"):
+            summary.append(f"Uses insights: {', '.join(config['insights'])}")
+        after = {**project, "onlineEvalConfigs": [c for c in project["onlineEvalConfigs"] if c["name"] != name]}
+        return RemovalPreview(summary, [], [SchemaChange("agentcore/agentcore.json", project, after)])
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [RemovableResource(c["name"]) for c in self._project()["onlineEvalConfigs"]]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_all_names(self) -> list[str]:
+        return [r.name for r in self.get_removable()]
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:
+        @add_app.command(
+            "online-eval",
+            help="Add an online eval config to the project",
+            cls=variadic("-e", "--evaluator", "--evaluator-arn", "--log-group-name", "--service-name"),
+        )
+        def add_online_eval(
+            name: str | None = typer.Option(None, "--name", help="Config name [non-interactive]"),
+            runtime: str | None = typer.Option(None, "-r", "--runtime", help="Runtime to monitor [non-interactive]"),
+            evaluator: list[str] | None = typer.Option(
+                None, "-e", "--evaluator", help="Evaluator name(s), Builtin.* IDs, or ARNs [non-interactive]"
+            ),
+            evaluator_arn: list[str] | None = typer.Option(
+                None, "--evaluator-arn", help="Evaluator ARN(s) [non-interactive]"
+            ),
+            sampling_rate: str | None = typer.Option(
+                None, "--sampling-rate", help="Sampling percentage (0.01-100) [non-interactive]"
+            ),
+            endpoint: str | None = typer.Option(
+                None, "--endpoint", help="Runtime endpoint name to scope monitoring [non-interactive]"
+            ),
+            log_group_name: list[str] | None = typer.Option(
+                None,
+                "--log-group-name",
+                help="CloudWatch log group name(s) for custom data sources (1-5) [non-interactive]",
+            ),
+            service_name: list[str] | None = typer.Option(
+                None,
+                "--service-name",
+                help="Service name(s) to filter traces for custom data sources [non-interactive]",
+            ),
+            enable_on_create: bool = typer.Option(
+                False, "--enable-on-create", help="Enable evaluation immediately after deploy [non-interactive]"
+            ),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+            if not (name or as_json):
+                try:
+                    interactive.require_tty()
+                    self.add_interactive()
+                except typer.Exit:
+                    raise
+                except Exception as exc:  # noqa: BLE001
+                    typer.echo(get_error_message(exc), err=True)
+                    raise typer.Exit(1) from None
+                raise typer.Exit(0)
+
+            all_evaluators = [*(evaluator or []), *(evaluator_arn or [])]
+
+            def run() -> None:
+                if runtime and log_group_name:
+                    raise Exception(
+                        "Error: --runtime and --log-group-name are mutually exclusive. Use --runtime (+ optional "
+                        "--endpoint) for AgentCore agents, or --log-group-name/--service-name for custom data sources."
+                    )
+                if log_group_name:
+                    if not name or not all_evaluators or not sampling_rate:
+                        raise Exception(
+                            "--name, --log-group-name, --evaluator (and/or --evaluator-arn), and --sampling-rate are "
+                            "all required in non-interactive mode"
+                        )
+                    if len(log_group_name) > 5:
+                        raise Exception("--log-group-name accepts at most 5 log group names")
+                elif not name or not runtime or not all_evaluators or not sampling_rate:
+                    raise Exception(
+                        "--name, --runtime, --evaluator (and/or --evaluator-arn), and --sampling-rate are all "
+                        "required in non-interactive mode"
+                    )
+                rate = parse_float(sampling_rate)
+                if rate is None or rate < 0.01 or rate > 100:
+                    raise Exception(
+                        f'Invalid --sampling-rate "{sampling_rate}". Must be a percentage between 0.01 and 100'
+                    )
+                result = self.add(
+                    AddOnlineEvalConfigOptions(
+                        name=name,
+                        agent=runtime or "",
+                        evaluators=all_evaluators,
+                        sampling_rate=rate,
+                        enable_on_create=True if enable_on_create else None,
+                        endpoint=endpoint,
+                        log_group_names=log_group_name or None,
+                        service_names=service_name or None,
+                    )
+                )
+                if not result.success:
+                    raise result.error
+                if as_json:
+                    emit_json(serialize_result(result))
+                else:
+                    typer.echo(f"Added online eval config '{result.value['configName']}'")
+
+            run_cli_command(as_json, run)
+
+        self.register_remove_subcommand(remove_app)
+
+    def add_interactive(self) -> None:
+        """Prompt flow mirroring tui/screens/online-eval/AddOnlineEvalFlow + AddOnlineEvalScreen."""
+        try:
+            validate_aws_credentials()
+        except Exception as exc:  # noqa: BLE001
+            typer.echo("AWS credentials required", err=True)
+            typer.echo(get_error_message(exc), err=True)
+            raise typer.Exit(1) from None
+        region = _region.detect_region().region
+        project = self._project()
+        evaluators = control.list_evaluators(region=region)["evaluators"]
+        runtimes = project.get("runtimes") or []
+        agent_names = [r["name"] for r in runtimes]
+        existing = self.get_all_names()
+        choice = interactive.Choice
+
+        def validate_name(value: str) -> str | None:
+            issue = first_issue(OnlineEvalConfigName, value)
+            if issue:
+                return issue
+            return "Config name already exists" if value in existing else None
+
+        name = interactive.text(
+            "Config name", default=generate_unique_name("MyOnlineEval", existing), validate=validate_name
+        )
+        source = interactive.select(
+            "Select data source type",
+            [
+                choice("AgentCore Runtime", "agentcore-runtime", "Monitor a managed AgentCore agent"),
+                choice("CloudWatch Logs", "cloudwatch-logs", "Provide custom log groups for 3rd-party agents"),
+            ],
+        )
+        agent = ""
+        endpoint = None
+        log_groups: list[str] | None = None
+        services: list[str] | None = None
+        if source == "agentcore-runtime":
+            if len(agent_names) == 1:
+                agent = agent_names[0]
+            elif agent_names:
+                agent = interactive.select("Select agent to monitor", [choice(n, n) for n in agent_names])
+            runtime = next((r for r in runtimes if r["name"] == agent), {})
+            endpoints = runtime.get("endpoints") or {}
+            if endpoints:
+                picked = interactive.select(
+                    "Select endpoint to monitor",
+                    [choice("DEFAULT", "DEFAULT")]
+                    + [choice(ep, ep, f"v{info.get('version')}") for ep, info in endpoints.items()],
+                )
+                endpoint = None if picked == "DEFAULT" else picked
+        else:
+            typer.echo(
+                "Enter CloudWatch log group names (1-5). Press Enter to add each name. Submit an empty value when done."
+            )
+            log_groups = []
+            while len(log_groups) < 5:
+                entry = interactive.text(
+                    f"Log group name {len(log_groups) + 1}",
+                    validate=lambda v: (
+                        "At least one log group name is required" if v == "" and not log_groups else None
+                    ),
+                )
+                if entry == "":
+                    break
+                log_groups.append(entry)
+            typer.echo("Enter service names separated by spaces (optional). Leave empty to skip.")
+            raw = interactive.text("Service names (space-separated)")
+            services = raw.split() if raw.strip() else None
+
+        selected = interactive.checkbox(
+            "Select evaluators",
+            [
+                choice(
+                    e["evaluatorName"],
+                    e["evaluatorArn"],
+                    "Built-in evaluator"
+                    if e.get("evaluatorType") == "Builtin"
+                    else (e.get("description") or "Custom evaluator"),
+                )
+                for e in evaluators
+            ],
+        )
+        typer.echo(
+            "Percentage of agent requests that will be evaluated. Higher rates give better coverage but increase LLM "
+            "costs from evaluator invocations."
+        )
+        rate_text = interactive.text(
+            "Sampling rate (0.01-100%)", default=str(DEFAULT_SAMPLING_RATE), validate=validate_sampling_rate_text
+        )
+        rate = parse_float(rate_text)
+        enable = interactive.select(
+            "Enable on deploy?",
+            [
+                choice("Yes", True, "Enable evaluation immediately after deploy"),
+                choice("No", False, "Deploy paused — enable later with `agentcore resume online-eval`"),
+            ],
+        )
+        rows = [("Name", name)]
+        if agent:
+            rows.append(("Agent", agent))
+        if endpoint:
+            rows.append(("Endpoint", endpoint))
+        if log_groups:
+            rows.append(("Log Groups", ", ".join(log_groups)))
+        rows += [
+            ("Evaluators", ", ".join(selected) or "None"),
+            ("Rate", f"{format_number(rate or 0)}%"),
+            ("Enable", "Yes" if enable else "No"),
+        ]
+        for label, value in rows:
+            typer.echo(f"  {label}: {value}")
+        if not interactive.confirm("Add this online eval config?", default=True):
+            typer.echo("Cancelled.")
+            return
+        result = self.add(
+            AddOnlineEvalConfigOptions(
+                name=name,
+                agent=agent,
+                evaluators=selected,
+                sampling_rate=rate or DEFAULT_SAMPLING_RATE,
+                enable_on_create=enable,
+                endpoint=endpoint,
+                log_group_names=log_groups or None,
+                service_names=services,
+            )
+        )
+        if not result.success:
+            typer.echo("Failed to add online eval config", err=True)
+            typer.echo(get_error_message(result.error), err=True)
+            raise typer.Exit(1)
+        typer.echo(f"Added online eval config: {name}")
+        typer.echo("Online eval config added to project in `agentcore/agentcore.json`. Deploy with `agentcore deploy`.")
+
+
+PRIMITIVE = OnlineEvalConfigPrimitive()

agentcore/primitives/online_insights.py

@@ -0,0 +1,275 @@
+"""Online insights config add/remove (port of src/cli/primitives/OnlineInsightsPrimitive.ts).
+
+Online insights configs are online eval configs that use ``insights`` instead of evaluators.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+import typer
+
+from agentcore.cli import interactive
+from agentcore.cli.commands.add._common import first_issue
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.naming import generate_unique_name
+from agentcore.cli.run_command import run_cli_command
+from agentcore.cli.variadic import variadic
+from agentcore.lib import ResourceNotFoundError, ValidationError, find_config_root, serialize_result
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.operations.jobs.shared.format import parse_float
+from agentcore.primitives.base import BasePrimitive, RemovableResource, RemovalPreview, SchemaChange, emit_json
+from agentcore.primitives.online_eval_config import check_endpoint, format_number
+from agentcore.schema import OnlineEvalConfigName
+
+DEFAULT_INSIGHTS_SAMPLING_RATE = 100
+AVAILABLE_INSIGHTS = (
+    ("Builtin.Insight.FailureAnalysis", "Failure Analysis", "Analyze failure patterns and root causes across sessions"),
+    ("Builtin.Insight.UserIntent", "User Intent", "Classify and cluster user intents from session transcripts"),
+    (
+        "Builtin.Insight.ExecutionSummary",
+        "Execution Summary",
+        "Summarize execution patterns and tool usage across sessions",
+    ),
+)
+CLUSTERING_FREQUENCIES = (("DAILY", "Daily"), ("WEEKLY", "Weekly"), ("MONTHLY", "Monthly"))
+
+
+def validate_insight_ids(insights: list[str]) -> None:
+    """Each insight must be a Builtin.Insight.* identifier or a full ARN."""
+    for insight in insights:
+        if not insight.startswith("Builtin.Insight.") and not insight.startswith("arn:"):
+            raise ValidationError(
+                f'Invalid insight "{insight}". Must be a Builtin.Insight.* identifier '
+                "(e.g. Builtin.Insight.FailureAnalysis) or a full ARN."
+            )
+
+
+def _has_insights(config: dict[str, Any]) -> bool:
+    return bool(config.get("insights"))
+
+
+@dataclass
+class AddOnlineInsightsOptions:
+    name: str
+    agent: str
+    insights: list[str]
+    sampling_rate: float
+    clustering_frequencies: list[str] | None = None
+    enable_on_create: bool | None = None
+    endpoint: str | None = None
+
+
+class OnlineInsightsPrimitive(BasePrimitive):
+    kind = "online-insights"
+    label = "Online Insights Config"
+    article = "an"
+
+    def _project(self) -> dict[str, Any]:
+        return to_jsonable(self.read_project_spec())
+
+    def add(self, options: AddOnlineInsightsOptions) -> Ok | Err:
+        try:
+            project = self._project()
+            self.check_duplicate(
+                [RemovableResource(c["name"]) for c in project["onlineEvalConfigs"]],
+                options.name,
+                "Online insights config",
+            )
+            validate_insight_ids(options.insights)
+            if options.endpoint:
+                check_endpoint(project, options.agent, options.endpoint)
+            config: dict[str, Any] = {
+                "name": options.name,
+                "agent": options.agent,
+                "insights": options.insights,
+                "samplingRate": options.sampling_rate,
+            }
+            if options.clustering_frequencies:
+                config["clusteringConfig"] = {"frequencies": options.clustering_frequencies}
+            if options.enable_on_create is not None:
+                config["enableOnCreate"] = options.enable_on_create
+            if options.endpoint:
+                config["endpoint"] = options.endpoint
+            project["onlineEvalConfigs"].append(config)
+            self.write_project_spec(project)
+            return Ok({"configName": options.name})
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def remove(self, name: str) -> Ok | Err:
+        try:
+            project = self._project()
+            index = next(
+                (i for i, c in enumerate(project["onlineEvalConfigs"]) if c["name"] == name and _has_insights(c)), -1
+            )
+            if index == -1:
+                return Err(ResourceNotFoundError(f'Online insights config "{name}" not found.'))
+            project["onlineEvalConfigs"].pop(index)
+            self.write_project_spec(project)
+            return Ok(None)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def preview_remove(self, name: str) -> RemovalPreview:
+        project = self._project()
+        config = next((c for c in project["onlineEvalConfigs"] if c["name"] == name and _has_insights(c)), None)
+        if config is None:
+            raise Exception(f'Online insights config "{name}" not found.')
+        summary = [f"Removing online insights config: {name}", f"Uses insights: {', '.join(config['insights'])}"]
+        after = {**project, "onlineEvalConfigs": [c for c in project["onlineEvalConfigs"] if c["name"] != name]}
+        return RemovalPreview(summary, [], [SchemaChange("agentcore/agentcore.json", project, after)])
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [RemovableResource(c["name"]) for c in self._project()["onlineEvalConfigs"] if _has_insights(c)]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_all_names(self) -> list[str]:
+        return [r.name for r in self.get_removable()]
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:
+        @add_app.command(
+            "online-insights",
+            help="Add an online insights config to the project",
+            cls=variadic("--insights", "--clustering-frequency"),
+        )
+        def add_online_insights(
+            name: str | None = typer.Option(None, "--name", help="Config name [non-interactive]"),
+            runtime: str | None = typer.Option(None, "-r", "--runtime", help="Runtime to monitor [non-interactive]"),
+            insights: list[str] | None = typer.Option(
+                None, "--insights", help="Insight IDs (e.g. Builtin.Insight.FailureAnalysis) [non-interactive]"
+            ),
+            sampling_rate: str | None = typer.Option(
+                None, "--sampling-rate", help="Sampling percentage (0.01-100) [non-interactive]"
+            ),
+            clustering_frequency: list[str] | None = typer.Option(
+                None, "--clustering-frequency", help="Clustering frequencies: DAILY, WEEKLY, MONTHLY [non-interactive]"
+            ),
+            endpoint: str | None = typer.Option(
+                None, "--endpoint", help="Runtime endpoint name to scope monitoring [non-interactive]"
+            ),
+            enable_on_create: bool = typer.Option(
+                False, "--enable-on-create", help="Enable insights immediately after deploy [non-interactive]"
+            ),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+            if not (name or as_json):
+                try:
+                    interactive.require_tty()
+                    self.add_interactive()
+                except typer.Exit:
+                    raise
+                except Exception as exc:  # noqa: BLE001
+                    typer.echo(get_error_message(exc), err=True)
+                    raise typer.Exit(1) from None
+                raise typer.Exit(0)
+
+            def run() -> None:
+                if not name or not runtime or not insights or not sampling_rate:
+                    raise Exception(
+                        "--name, --runtime, --insights, and --sampling-rate are all required in non-interactive mode"
+                    )
+                rate = parse_float(sampling_rate)
+                if rate is None or rate < 0.01 or rate > 100:
+                    raise Exception(
+                        f'Invalid --sampling-rate "{sampling_rate}". Must be a percentage between 0.01 and 100'
+                    )
+                result = self.add(
+                    AddOnlineInsightsOptions(
+                        name=name,
+                        agent=runtime,
+                        insights=insights,
+                        sampling_rate=rate,
+                        clustering_frequencies=clustering_frequency or None,
+                        enable_on_create=True if enable_on_create else None,
+                        endpoint=endpoint,
+                    )
+                )
+                if not result.success:
+                    raise result.error
+                if as_json:
+                    emit_json(serialize_result(result))
+                else:
+                    typer.echo(f"Added online insights config '{result.value['configName']}'")
+
+            run_cli_command(as_json, run)
+
+        self.register_remove_subcommand(remove_app)
+
+    def add_interactive(self) -> None:
+        """Prompt flow mirroring tui/screens/online-insights (agent, insights, rate, clustering, name)."""
+        project = self._project()
+        agent_names = [r["name"] for r in project.get("runtimes") or []]
+        if not agent_names:
+            typer.echo("No runtimes found in project. Add an agent first with `agentcore add agent`.", err=True)
+            raise typer.Exit(1)
+        choice = interactive.Choice
+        agent = interactive.select("Select agent to monitor", [choice(n, n) for n in agent_names])
+        insights = interactive.checkbox("Select insights", [choice(t, i, d) for i, t, d in AVAILABLE_INSIGHTS])
+        while not insights:
+            typer.echo("Select at least one insight.", err=True)
+            insights = interactive.checkbox("Select insights", [choice(t, i, d) for i, t, d in AVAILABLE_INSIGHTS])
+
+        def validate_rate(value: str) -> str | None:
+            rate = parse_float(value)
+            if rate is None:
+                return "Must be a number"
+            return None if 0.01 <= rate <= 100 else "Must be between 0.01 and 100"
+
+        rate = parse_float(
+            interactive.text(
+                "Sampling rate (0.01–100%)", default=str(DEFAULT_INSIGHTS_SAMPLING_RATE), validate=validate_rate
+            )
+        )
+        frequencies = interactive.checkbox(
+            "Select clustering frequencies (optional)", [choice(t, i) for i, t in CLUSTERING_FREQUENCIES]
+        )
+        existing = [c["name"] for c in project["onlineEvalConfigs"]]
+
+        def validate_name(value: str) -> str | None:
+            issue = first_issue(OnlineEvalConfigName, value)
+            if issue:
+                return issue
+            return "Config name already exists" if value in existing else None
+
+        name = interactive.text(
+            "Config name", default=generate_unique_name("MyInsights", existing), validate=validate_name
+        )
+        for label, value in (
+            ("Agent", agent),
+            ("Insights", ", ".join(insights)),
+            ("Rate", f"{format_number(rate or 0)}%"),
+            ("Clustering", ", ".join(frequencies) or "None"),
+            ("Name", name),
+        ):
+            typer.echo(f"  {label}: {value}")
+        if not interactive.confirm("Add this online insights config?", default=True):
+            typer.echo("Cancelled.")
+            return
+        result = self.add(
+            AddOnlineInsightsOptions(
+                name=name,
+                agent=agent,
+                insights=insights,
+                sampling_rate=rate or DEFAULT_INSIGHTS_SAMPLING_RATE,
+                clustering_frequencies=frequencies or None,
+                enable_on_create=True,
+            )
+        )
+        if not result.success:
+            typer.echo("Failed to add online insights config", err=True)
+            typer.echo(get_error_message(result.error), err=True)
+            raise typer.Exit(1)
+        typer.echo(f"Added online insights config: {name}")
+        typer.echo(
+            "Online insights config added to project in `agentcore/agentcore.json`. Deploy with `agentcore deploy`."
+        )
+
+
+PRIMITIVE = OnlineInsightsPrimitive()