agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/import_/actions.py

@@ -0,0 +1,457 @@
+"""Starter-toolkit YAML import, `agentcore import --source` (port of commands/import/actions.ts)."""
+
+from __future__ import annotations
+
+import copy
+import os
+import shutil
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.aws import account as aws_account
+from agentcore.aws.partition import arn_prefix
+from agentcore.cli.commands.shared import vpc_utils
+from agentcore.cli.constants import ANSI
+from agentcore.lib.constants import APP_DIR
+from agentcore.lib.errors.types import NoProjectError, ValidationError, to_error
+from agentcore.lib.schemas.io.config_io import ConfigIO, to_jsonable
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.logging.exec_logger import ExecLogger
+
+from . import import_pipeline
+from .import_utils import ImportedResource, copy_dir_recursive, fix_pyproject_for_setuptools, to_stack_name
+from .template_utils import find_logical_id_by_property, find_logical_ids_by_type
+from .types import (
+    ImportResult,
+    ParsedStarterToolkitAgent,
+    ParsedStarterToolkitCredential,
+    ParsedStarterToolkitMemory,
+    ResourceToImport,
+)
+from .yaml_parser import parse_starter_toolkit_yaml
+
+
+@dataclass
+class ImportOptions:
+    source: str
+    target: str | None = None
+    yes: bool | None = None
+    on_progress: Callable[[str], None] | None = None
+
+
+def to_agent_env_spec(agent: ParsedStarterToolkitAgent) -> dict[str, Any]:
+    spec: dict[str, Any] = {
+        "name": agent.name,
+        "build": agent.build,
+        "entrypoint": os.path.basename(agent.entrypoint),
+        "codeLocation": os.path.join(APP_DIR, agent.name),
+        "runtimeVersion": agent.runtime_version or "PYTHON_3_12",
+        "protocol": agent.protocol,
+        "networkMode": agent.network_mode,
+        "instrumentation": {"enableOtel": False if agent.protocol == "MCP" else agent.enable_otel},
+    }
+    if agent.network_mode == "VPC" and agent.network_config:
+        spec["networkConfig"] = agent.network_config
+    if agent.execution_role_arn:
+        spec["executionRoleArn"] = agent.execution_role_arn
+    if agent.authorizer_type:
+        spec["authorizerType"] = agent.authorizer_type
+    if agent.authorizer_configuration:
+        spec["authorizerConfiguration"] = agent.authorizer_configuration
+    return spec
+
+
+def to_memory_spec(mem: ParsedStarterToolkitMemory) -> dict[str, Any]:
+    strategies = (
+        [{"type": "SEMANTIC"}, {"type": "SUMMARIZATION"}, {"type": "USER_PREFERENCE"}]
+        if mem.mode == "STM_AND_LTM"
+        else []
+    )
+    return {"name": mem.name, "eventExpiryDuration": max(3, min(365, mem.event_expiry_days)), "strategies": strategies}
+
+
+def to_credential_spec(cred: ParsedStarterToolkitCredential) -> dict[str, Any]:
+    if cred.provider_type == "api_key":
+        return {"authorizerType": "ApiKeyCredentialProvider", "name": cred.name}
+    # The provider already exists in Identity; discoveryUrl isn't in the YAML.
+    return {"authorizerType": "OAuthCredentialProvider", "name": cred.name, "vendor": "CustomOauth2"}
+
+
+def _minimal_pyproject(name: str) -> str:
+    return "\n".join(
+        [
+            "[build-system]",
+            'requires = ["setuptools>=68", "wheel"]',
+            'build-backend = "setuptools.build_meta"',
+            "",
+            "[project]",
+            f'name = "{name}"',
+            'version = "0.1.0"',
+            'requires-python = ">=3.10"',
+            "dependencies = []",
+            "",
+        ]
+    )
+
+
+def handle_import(options: ImportOptions) -> ImportResult:  # noqa: C901, PLR0911, PLR0912, PLR0915
+    source, on_progress = options.source, options.on_progress
+    progress = on_progress or (lambda _m: None)
+    logger = ExecLogger("import")
+    config_io: ConfigIO | None = None
+    config_snapshot: dict[str, Any] | None = None
+    config_written = False
+
+    def rollback_config() -> None:
+        if not config_written or config_io is None:
+            return
+        try:
+            config_io.write_project_spec(config_snapshot)
+            progress("Rolling back config changes due to failure...")
+            logger.log("Rolled back config to pre-import state")
+        except Exception as exc:  # noqa: BLE001
+            logger.log(f"Warning: config rollback failed: {exc}", "error")
+
+    def fail(error: BaseException) -> ImportResult:
+        logger.end_step("error", str(error))
+        logger.finalize(False)
+        return ImportResult(success=False, error=error, log_path=logger.get_relative_log_path())
+
+    def step_log(message: str, level: str | None = None) -> None:
+        logger.log(message, level) if level else logger.log(message)
+        progress(message)
+
+    try:
+        logger.start_step("Validate project context")
+        config_root = find_config_root(os.getcwd())
+        if not config_root:
+            return fail(
+                NoProjectError(
+                    "No agentcore project found in the current directory.\n"
+                    "Run `agentcore create <name>` first, then run import from inside the project."
+                )
+            )
+        project_root = os.path.dirname(config_root)
+        config_io = ConfigIO(base_dir=config_root)
+        logger.end_step("success")
+
+        logger.start_step("Read project config")
+        project_spec = to_jsonable(config_io.read_project_spec())
+        project_name = project_spec["name"]
+        step_log(f"Using existing project: {project_name}")
+        logger.end_step("success")
+        config_snapshot = copy.deepcopy(project_spec)
+
+        logger.start_step("Parse YAML")
+        step_log(f"Parsing {source}...")
+        parsed = parse_starter_toolkit_yaml(source)
+        if not parsed.agents:
+            return fail(ValidationError("No agents found in the YAML config"))
+        step_log(
+            f"Found {len(parsed.agents)} agent(s), {len(parsed.memories)} memory(ies), "
+            f"{len(parsed.credentials)} credential(s)"
+        )
+        logger.end_step("success")
+
+        has_physical_ids = any(a.physical_agent_id for a in parsed.agents) or any(
+            m.physical_memory_id for m in parsed.memories
+        )
+
+        logger.start_step("Resolve deployment target")
+        target: dict[str, Any] | None = None
+        yaml_account = parsed.aws_target.get("account")
+        yaml_region = parsed.aws_target.get("region")
+        if has_physical_ids:
+            # The YAML region is authoritative: readAWSDeploymentTargets() lets AWS_REGION override files.
+            if yaml_region:
+                os.environ["AWS_REGION"] = yaml_region
+                os.environ["AWS_DEFAULT_REGION"] = yaml_region
+            targets = [to_jsonable(t) for t in config_io.read_aws_deployment_targets()]
+            if not targets:
+                if not yaml_account or not yaml_region:
+                    return fail(
+                        ValidationError(
+                            "No deployment targets found in project and YAML has no AWS account/region info.\n"
+                            "Run `agentcore deploy` first to set up a target, then re-run import."
+                        )
+                    )
+                default_target = {"name": "default", "account": yaml_account, "region": yaml_region}
+                config_io.write_aws_deployment_targets([default_target])
+                targets = [default_target]
+                step_log(f"Created default target from YAML: {yaml_region}, {yaml_account}")
+
+            listing = "\n".join(f"  - {t['name']} ({t['region']}, {t['account']})" for t in targets)
+            if options.target:
+                target = next((t for t in targets if t["name"] == options.target), None)
+                if target is None:
+                    return fail(ValidationError(f'Target "{options.target}" not found. Available targets:\n{listing}'))
+            elif len(targets) == 1:
+                target = targets[0]
+            else:
+                return fail(
+                    ValidationError(f"Multiple deployment targets found. Specify one with --target:\n{listing}")
+                )
+
+            step_log(f"Using target: {target['name']} ({target['region']}, {target['account']})")
+            if yaml_account and yaml_account != target["account"]:
+                step_log(
+                    f"Warning: YAML account ({yaml_account}) differs from target account ({target['account']})", "warn"
+                )
+            if yaml_region and yaml_region != target["region"]:
+                step_log(
+                    f"Warning: YAML region ({yaml_region}) differs from target region ({target['region']})", "warn"
+                )
+            step_log("Validating AWS credentials...")
+            aws_account.validate_aws_credentials()
+        else:
+            # Without physical IDs the target only feeds the stack name.
+            try:
+                targets = [to_jsonable(t) for t in config_io.read_aws_deployment_targets()]
+            except Exception:  # noqa: BLE001
+                targets = []
+            if len(targets) == 1:
+                target = targets[0]
+            elif options.target:
+                target = next((t for t in targets if t["name"] == options.target), None)
+        logger.end_step("success")
+
+        logger.start_step("Merge agents and memories")
+        step_log("Merging into existing project...")
+        existing_agents = {a["name"] for a in project_spec.get("runtimes", [])}
+        added_agents: set[str] = set()
+        for agent in parsed.agents:
+            if agent.name not in existing_agents:
+                project_spec.setdefault("runtimes", []).append(to_agent_env_spec(agent))
+                added_agents.add(agent.name)
+            else:
+                step_log(f'Skipping agent "{agent.name}" (already exists in project)')
+
+        existing_memories = {m["name"] for m in project_spec.get("memories") or []}
+        added_memories: set[str] = set()
+        for mem in parsed.memories:
+            if mem.name not in existing_memories:
+                project_spec.setdefault("memories", []).append(to_memory_spec(mem))
+                added_memories.add(mem.name)
+            else:
+                step_log(f'Skipping memory "{mem.name}" (already exists in project)')
+
+        for mem in parsed.memories:
+            env_var = "MEMORY_" + mem.name.upper().replace(".", "_").replace("-", "_") + "_ID"
+            logger.log(f'Memory "{mem.name}" env var must be updated: use {env_var}', "warn")
+            progress(
+                f'Warning: Memory "{mem.name}" env var must be updated in your agent code:\n'
+                f'  {ANSI.red}- MEMORY_ID = os.getenv("BEDROCK_AGENTCORE_MEMORY_ID"){ANSI.reset}\n'
+                f'  {ANSI.green}+ MEMORY_ID = os.getenv("{env_var}"){ANSI.reset}'
+            )
+
+        existing_creds = {c["name"] for c in project_spec.get("credentials") or []}
+        for cred in parsed.credentials:
+            if cred.name not in existing_creds:
+                project_spec.setdefault("credentials", []).append(to_credential_spec(cred))
+                step_log(f'Added credential "{cred.name}" ({cred.provider_type})')
+            else:
+                step_log(f'Skipping credential "{cred.name}" (already exists in project)')
+
+        # The starter-toolkit YAML omits vpc_id; resolve it from the first subnet.
+        import_region = yaml_region or (target or {}).get("region")
+        for spec in project_spec.get("runtimes", []):
+            net = spec.get("networkConfig")
+            if (
+                spec.get("build") == "Container"
+                and spec.get("networkMode") == "VPC"
+                and net
+                and net.get("subnets")
+                and not net.get("vpcId")
+            ):
+                if not import_region:
+                    return fail(
+                        ValidationError(
+                            f'Cannot resolve VPC ID for agent "{spec["name"]}": no AWS region available. Add an '
+                            "aws.region to the YAML or set up a deployment target first."
+                        )
+                    )
+                net["vpcId"] = vpc_utils.resolve_vpc_id_from_subnets(net["subnets"], import_region)
+                step_log(f'Resolved vpcId for agent "{spec["name"]}": {net["vpcId"]}')
+
+        config_io.write_project_spec(project_spec)
+        config_written = True
+        logger.end_step("success")
+
+        logger.start_step("Copy agent source and setup Python")
+        for agent in parsed.agents:
+            if agent.name in existing_agents:
+                step_log(f'Skipping source copy for agent "{agent.name}" (already exists in project)')
+                continue
+            app_dir = os.path.join(project_root, APP_DIR, agent.name)
+            os.makedirs(app_dir, exist_ok=True)
+            if agent.source_path and os.path.exists(agent.source_path):
+                step_log(f"Copying agent source from {agent.source_path} to ./{APP_DIR}/{agent.name}")
+                copy_dir_recursive(agent.source_path, app_dir)
+                parent_pyproject = os.path.join(os.path.dirname(agent.source_path), "pyproject.toml")
+                dest_pyproject = os.path.join(app_dir, "pyproject.toml")
+                if os.path.exists(parent_pyproject) and not os.path.exists(dest_pyproject):
+                    shutil.copyfile(parent_pyproject, dest_pyproject)
+                if agent.build == "Container":
+                    dest_dockerfile = os.path.join(app_dir, "Dockerfile")
+                    if not os.path.exists(dest_dockerfile):
+                        toolkit_dockerfile = os.path.join(
+                            os.path.dirname(agent.source_path), ".bedrock_agentcore", agent.name, "Dockerfile"
+                        )
+                        if os.path.exists(toolkit_dockerfile):
+                            step_log("Copying Dockerfile from starter toolkit config")
+                            shutil.copyfile(toolkit_dockerfile, dest_dockerfile)
+                        else:
+                            from agentcore.templates.render import copy_and_render_dir
+                            from agentcore.templates.template_root import get_template_path
+
+                            step_log("Generating Dockerfile for Container build")
+                            entry_module = os.path.basename(agent.entrypoint)
+                            if entry_module.endswith(".py"):
+                                entry_module = entry_module[:-3]
+                            copy_and_render_dir(
+                                get_template_path("container", "python"),
+                                app_dir,
+                                {"entrypoint": entry_module, "enableOtel": True},
+                                exclude={".dockerignore"},
+                            )
+            else:
+                pyproject_path = os.path.join(app_dir, "pyproject.toml")
+                if not os.path.exists(pyproject_path):
+                    step_log(f"Creating minimal pyproject.toml at {app_dir}")
+                    with open(pyproject_path, "w", encoding="utf-8") as fh:
+                        fh.write(_minimal_pyproject(agent.name))
+
+            if agent.build != "Container":
+                from agentcore.operations.python.setup import setup_python_project
+
+                fix_pyproject_for_setuptools(os.path.join(app_dir, "pyproject.toml"))
+                step_log(f"Setting up Python environment for {agent.name}...")
+                result = setup_python_project(app_dir)
+                if result.status == "success":
+                    step_log(f"Python environment ready for {agent.name}")
+                elif result.status == "uv_not_found":
+                    step_log(f'Warning: uv not found — run "uv sync" manually in {APP_DIR}/{agent.name}', "warn")
+                else:
+                    step_log(f"Warning: Python setup failed for {agent.name}: {result.error or result.status}", "warn")
+        logger.end_step("success")
+
+        logger.start_step("Determine resources to import")
+        agents_to_import = [a for a in parsed.agents if a.physical_agent_id and a.name in added_agents]
+        memories_to_import = [m for m in parsed.memories if m.physical_memory_id and m.name in added_memories]
+        target_name = (target or {}).get("name") or "default"
+        stack_name = to_stack_name(project_name, target_name)
+
+        if not agents_to_import and not memories_to_import:
+            step_log(
+                "No deployed resources found to import (no agent_id or memory_id in YAML). "
+                "Run `agentcore deploy` to create new resources."
+            )
+            logger.end_step("success")
+            logger.finalize(True)
+            return ImportResult(
+                success=True,
+                project_spec=project_spec,
+                imported_agents=[],
+                imported_memories=[],
+                stack_name=stack_name,
+                log_path=logger.get_relative_log_path(),
+            )
+
+        step_log(f"Will import: {len(agents_to_import)} agent(s), {len(memories_to_import)} memory(ies)")
+        if target is None:
+            return fail(ValidationError("No deployment target available for import."))
+        logger.end_step("success")
+
+        logger.start_step("Build and import via CDK")
+        region, account = target["region"], target["account"]
+        imported = [
+            ImportedResource(
+                "runtime",
+                a.name,
+                a.physical_agent_id,
+                a.physical_agent_arn
+                or f"{arn_prefix(region)}:bedrock-agentcore:{region}:{account}:runtime/{a.physical_agent_id}",
+            )
+            for a in agents_to_import
+        ] + [
+            ImportedResource(
+                "memory",
+                m.name,
+                m.physical_memory_id,
+                m.physical_memory_arn
+                or f"{arn_prefix(region)}:bedrock-agentcore:{region}:{account}:memory/{m.physical_memory_id}",
+            )
+            for m in memories_to_import
+        ]
+
+        def build_resources(synth: dict[str, Any], deployed: dict[str, Any]) -> list[ResourceToImport]:
+            resources: list[ResourceToImport] = []
+            deployed_ids = set(deployed.get("Resources", {}).keys())
+            rt_type, mem_type = "AWS::BedrockAgentCore::Runtime", "AWS::BedrockAgentCore::Memory"
+            for agent in agents_to_import:
+                candidates = [i for i in find_logical_ids_by_type(synth, rt_type) if i not in deployed_ids]
+                logical_id = find_logical_id_by_property(
+                    synth, rt_type, "AgentRuntimeName", f"{project_name}_{agent.name}", exclude_logical_ids=deployed_ids
+                )
+                if not logical_id and len(candidates) == 1:
+                    logical_id = candidates[0]
+                if not logical_id:
+                    step_log(f"Warning: Could not find logical ID for agent {agent.name}, skipping", "warn")
+                    continue
+                resources.append(ResourceToImport(rt_type, logical_id, {"AgentRuntimeId": agent.physical_agent_id}))
+            for memory in memories_to_import:
+                candidates = [i for i in find_logical_ids_by_type(synth, mem_type) if i not in deployed_ids]
+                logical_id = find_logical_id_by_property(
+                    synth, mem_type, "Name", memory.name, exclude_logical_ids=deployed_ids
+                ) or find_logical_id_by_property(
+                    synth, mem_type, "Name", f"{project_name}_{memory.name}", exclude_logical_ids=deployed_ids
+                )
+                if not logical_id and len(candidates) == 1:
+                    logical_id = candidates[0]
+                if not logical_id:
+                    step_log(f"Warning: Could not find logical ID for memory {memory.name}, skipping", "warn")
+                    continue
+                resources.append(ResourceToImport(mem_type, logical_id, {"MemoryId": memory.physical_memory_id}))
+            return resources
+
+        pipeline = import_pipeline.execute_cdk_import_pipeline(
+            project_root=project_root,
+            stack_name=stack_name,
+            target=target,
+            config_io=config_io,
+            target_name=target_name,
+            on_progress=progress,
+            build_resources_to_import=build_resources,
+            deployed_state_entries=imported,
+        )
+        if pipeline.no_resources:
+            step_log("No resources could be matched for import")
+            logger.end_step("success")
+            logger.finalize(True)
+            return ImportResult(
+                success=True,
+                project_spec=project_spec,
+                imported_agents=[],
+                imported_memories=[],
+                stack_name=stack_name,
+                log_path=logger.get_relative_log_path(),
+            )
+        if not pipeline.success:
+            rollback_config()
+            return fail(Exception(pipeline.error))
+        logger.end_step("success")
+        logger.finalize(True)
+        return ImportResult(
+            success=True,
+            project_spec=project_spec,
+            imported_agents=[a.name for a in agents_to_import],
+            imported_memories=[m.name for m in memories_to_import],
+            stack_name=stack_name,
+            log_path=logger.get_relative_log_path(),
+        )
+    except Exception as exc:  # noqa: BLE001
+        rollback_config()
+        logger.log(str(exc), "error")
+        logger.finalize(False)
+        return ImportResult(success=False, error=to_error(exc), log_path=logger.get_relative_log_path())

agentcore/cli/commands/import_/constants.py

@@ -0,0 +1,45 @@
+"""Port of commands/import/constants.ts."""
+
+import re
+from typing import Final
+
+# Name validation regex used by all import handlers.
+NAME_REGEX: Final = re.compile(r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$")
+
+# CloudFormation resource type to identifier key mapping for IMPORT.
+CFN_RESOURCE_IDENTIFIERS: Final[dict[str, list[str]]] = {
+    "AWS::BedrockAgentCore::Runtime": ["AgentRuntimeId"],
+    "AWS::BedrockAgentCore::Memory": ["MemoryId"],
+    "AWS::BedrockAgentCore::Gateway": ["GatewayIdentifier"],
+    "AWS::BedrockAgentCore::GatewayTarget": ["GatewayIdentifier", "TargetId"],
+    "AWS::BedrockAgentCore::Evaluator": ["EvaluatorId"],
+    "AWS::BedrockAgentCore::OnlineEvaluationConfig": ["OnlineEvaluationConfigId"],
+    "AWS::BedrockAgentCore::Harness": ["HarnessId"],
+}
+
+# CloudFormation resource types that are primary (importable) resources. Everything else is a companion.
+PRIMARY_RESOURCE_TYPES: Final[tuple[str, ...]] = (
+    "AWS::BedrockAgentCore::Runtime",
+    "AWS::BedrockAgentCore::Memory",
+    "AWS::BedrockAgentCore::Gateway",
+    "AWS::BedrockAgentCore::GatewayTarget",
+    "AWS::BedrockAgentCore::Evaluator",
+    "AWS::BedrockAgentCore::OnlineEvaluationConfig",
+    "AWS::BedrockAgentCore::RuntimeEndpoint",
+    "AWS::BedrockAgentCore::WorkloadIdentity",
+    "AWS::BedrockAgentCore::BrowserCustom",
+    "AWS::BedrockAgentCore::BrowserProfile",
+    "AWS::BedrockAgentCore::CodeInterpreterCustom",
+    "AWS::BedrockAgentCore::Policy",
+    "AWS::BedrockAgentCore::PolicyEngine",
+    "AWS::BedrockAgentCore::Harness",
+)
+
+# Map from starter toolkit runtime_type to CLI runtimeVersion.
+RUNTIME_TYPE_MAP: Final[dict[str, str]] = {
+    "PYTHON_3_10": "PYTHON_3_10",
+    "PYTHON_3_11": "PYTHON_3_11",
+    "PYTHON_3_12": "PYTHON_3_12",
+    "PYTHON_3_13": "PYTHON_3_13",
+    "PYTHON_3_14": "PYTHON_3_14",
+}

agentcore/cli/commands/import_/import_evaluator.py

@@ -0,0 +1,140 @@
+"""`agentcore import evaluator` (port of commands/import/import-evaluator.ts)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from agentcore.aws import agentcore_control
+from agentcore.aws._aws_errors import is_not_found_error
+from agentcore.cli.constants import ANSI
+from agentcore.lib.errors.types import ValidationError
+from agentcore.lib.result import Err, Ok
+
+from .import_runtime import print_failure, print_success
+from .import_utils import ImportedResource, fail_result, parse_and_validate_arn, strip_reserved_tags
+from .resource_import import execute_resource_import
+from .types import BeforeWriteContext, ImportResourceOptions, ImportResourceResult, ResourceImportDescriptor
+
+
+def to_evaluator_spec(detail: dict[str, Any], local_name: str) -> Ok[dict[str, Any]] | Err[Exception]:
+    """Map a GetEvaluator response to the local Evaluator spec (``Ok({"evaluator": ...})``)."""
+    level = detail.get("level") or "SESSION"
+    cfg = detail.get("evaluatorConfig") or {}
+    if cfg.get("llmAsAJudge"):
+        llm = cfg["llmAsAJudge"]
+        judge: dict[str, Any] = {}
+        if llm.get("modelProvider"):
+            judge["modelProvider"] = llm["modelProvider"]
+        judge.update(
+            {"model": llm.get("model"), "instructions": llm.get("instructions"), "ratingScale": llm.get("ratingScale")}
+        )
+        config: dict[str, Any] = {"llmAsAJudge": judge}
+    elif cfg.get("codeBased"):
+        config = {"codeBased": {"external": {"lambdaArn": cfg["codeBased"].get("lambdaArn")}}}
+    else:
+        return Err(
+            ValidationError(
+                f'Evaluator "{detail.get("evaluatorName")}" has no recognizable config. '
+                "Only LLM-as-a-Judge and code-based evaluators can be imported."
+            )
+        )
+    evaluator: dict[str, Any] = {"name": local_name, "level": level}
+    if detail.get("description"):
+        evaluator["description"] = detail["description"]
+    evaluator["config"] = config
+    if detail.get("kmsKeyArn"):
+        evaluator["kmsKeyArn"] = detail["kmsKeyArn"]
+    tags = strip_reserved_tags(detail.get("tags"))
+    if tags:
+        evaluator["tags"] = tags
+    return Ok({"evaluator": evaluator})
+
+
+def _add(detail: Any, local_name: str, spec: dict[str, Any]) -> ImportResourceResult:
+    result = to_evaluator_spec(detail, local_name)
+    if not result.success:
+        return ImportResourceResult(
+            success=False, error=result.error, resource_type="evaluator", resource_name=local_name
+        )
+    spec.setdefault("evaluators", []).append(result.value["evaluator"])
+    return ImportResourceResult(success=True, resource_type="evaluator", resource_name=local_name)
+
+
+def _before_write(c: BeforeWriteContext[Any]) -> ImportResourceResult | None:
+    # CFN IMPORT of an evaluator locked by an online eval config always fails.
+    c.logger.start_step("Check for online eval config references")
+    c.on_progress("Checking if evaluator is referenced by an online eval config...")
+    region = c.target["region"]
+    summaries = agentcore_control.list_all_online_evaluation_configs(region=region)
+    details = []
+    for s in summaries:
+        try:
+            details.append(
+                agentcore_control.get_online_evaluation_config(region=region, config_id=s["onlineEvaluationConfigId"])
+            )
+        except Exception as exc:
+            if is_not_found_error(exc):  # deleted between list and get
+                continue
+            raise
+    referencing = next((d for d in details if c.detail["evaluatorId"] in (d.get("evaluatorIds") or [])), None)
+    if referencing:
+        return fail_result(
+            c.logger,
+            f'Evaluator "{c.local_name}" is referenced by online eval config "{referencing["configName"]}" and cannot '
+            "be imported directly (locked by CloudFormation).\n"
+            "To import this evaluator along with its online eval config, run:\n"
+            f"  agentcore import online-eval --arn {referencing['configArn']}",
+            "evaluator",
+            c.local_name,
+        )
+    c.logger.end_step("success")
+    return None
+
+
+EVALUATOR_DESCRIPTOR: ResourceImportDescriptor[Any, Any] = ResourceImportDescriptor(
+    resource_type="evaluator",
+    display_name="evaluator",
+    log_command="import-evaluator",
+    list_resources=lambda region: agentcore_control.list_all_evaluators(region=region),
+    get_detail=lambda region, eid: agentcore_control.get_evaluator(region=region, evaluator_id=eid),
+    parse_resource_id=lambda arn, target: parse_and_validate_arn(arn, "evaluator", target).resource_id,
+    extract_summary_id=lambda s: s["evaluatorId"],
+    format_list_item=lambda s, i: (
+        f"  {ANSI.dim}[{i + 1}]{ANSI.reset} {s['evaluatorName']} — {s['status']}\n"
+        f"       {ANSI.dim}{s['evaluatorArn']}{ANSI.reset}"
+    ),
+    format_auto_select_message=lambda s: (
+        f"Found 1 evaluator: {s['evaluatorName']} ({s['evaluatorId']}). Auto-selecting."
+    ),
+    extract_detail_name=lambda d: d["evaluatorName"],
+    extract_detail_arn=lambda d: d["evaluatorArn"],
+    ready_status="ACTIVE",
+    extract_detail_status=lambda d: d["status"],
+    get_existing_names=lambda spec: [e["name"] for e in spec.get("evaluators") or []],
+    add_to_project_spec=_add,
+    cfn_resource_type="AWS::BedrockAgentCore::Evaluator",
+    cfn_name_property="EvaluatorName",
+    cfn_identifier_key="EvaluatorId",
+    build_deployed_state_entry=lambda name, eid, d: ImportedResource("evaluator", name, eid, d["evaluatorArn"]),
+    before_config_write=_before_write,
+)
+
+
+def handle_import_evaluator(options: ImportResourceOptions) -> ImportResourceResult:
+    return execute_resource_import(EVALUATOR_DESCRIPTOR, options)
+
+
+def register_import_evaluator(import_app: typer.Typer) -> None:
+    @import_app.command("evaluator", help="Import an existing AgentCore Evaluator from your AWS account")
+    def import_evaluator(
+        arn: str | None = typer.Option(None, "--arn", help="Evaluator ARN to import"),
+        name: str | None = typer.Option(None, "--name", help="Local name for the imported evaluator"),
+        yes: bool = typer.Option(False, "-y", "--yes", help="Auto-confirm prompts"),
+    ) -> None:
+        result = handle_import_evaluator(ImportResourceOptions(arn=arn, name=name, yes=yes or None))
+        if result.success:
+            print_success("Evaluator", result, [])
+        else:
+            print_failure(result)