agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/agent.py

@@ -0,0 +1,817 @@
+"""Agent add/remove (port of src/cli/primitives/AgentPrimitive.tsx).
+
+Three add paths, as upstream: ``create`` (render a framework template), ``byo`` (register existing
+code) and ``import`` (translate a Bedrock Agent). The interactive wizard (``add_interactive``) ports
+tui/screens/agent/AddAgentScreen + the generate wizard and feeds the same paths.
+"""
+
+import json
+import os
+import shutil
+from dataclasses import dataclass, field
+from typing import Any
+
+import typer
+
+from agentcore.cli import interactive
+from agentcore.cli.commands.add.validate import validate_add_agent_options
+from agentcore.cli.commands.shared.header_utils import parse_and_normalize_headers
+from agentcore.cli.commands.shared.vpc_utils import VPC_ENDPOINT_WARNING, parse_comma_separated_list
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.run_command import run_cli_command
+from agentcore.lib import (
+    APP_DIR,
+    ConfigIO,
+    ConflictError,
+    NoProjectError,
+    ResourceNotFoundError,
+    ValidationError,
+    find_config_root,
+    serialize_result,
+    set_env_var,
+)
+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.agent.config_bundle_defaults import create_config_bundle_for_agent
+from agentcore.operations.agent.generate import (
+    GenerateConfig,
+    map_generate_config_to_render_config,
+    map_model_provider_to_credentials,
+    write_agent_to_project,
+)
+from agentcore.operations.python import setup_python_project
+from agentcore.primitives.auth_utils import (
+    JwtConfigOptions,
+    build_authorizer_config_from_jwt_config,
+    create_managed_oauth_credential,
+)
+from agentcore.primitives.base import BasePrimitive, RemovableResource, RemovalPreview, SchemaChange, emit_json
+from agentcore.primitives.credential import CredentialPrimitive
+from agentcore.primitives.credential_utils import compute_default_credential_env_var_name
+from agentcore.schema import (
+    CREDENTIAL_PROVIDERS,
+    DEFAULT_PYTHON_VERSION,
+    LIFECYCLE_TIMEOUT_MAX,
+    LIFECYCLE_TIMEOUT_MIN,
+    is_capacity_provider_arn,
+)
+from agentcore.templates import RendererContext, create_renderer, template_needs_python_venv
+
+_HEADER_ALLOWLIST_HELP = (
+    "Comma-separated list of header names to allow. X-prefixed names (e.g. Authorization, X-Api-Key, "
+    "X-Custom-Signature) pass through unchanged; bare names without X- prefix are auto-prefixed with "
+    "X-Amzn-Bedrock-AgentCore-Runtime-Custom- for backward compatibility. [non-interactive]"
+)
+
+
+def _split_csv(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    return [s.strip() for s in value.split(",") if s.strip()]
+
+
+@dataclass
+class AddAgentOptions:
+    """Options for adding an agent (upstream AddAgentOptions; mounts are camelCase dicts)."""
+
+    name: str
+    type: str = "create"
+    build_type: str = "CodeZip"
+    language: str = "Python"
+    framework: str = "Strands"
+    model_provider: str = "Bedrock"
+    api_key: str | None = None
+    memory: str | None = None
+    protocol: str | None = None
+    request_header_allowlist: list[str] | None = None
+    code_location: str | None = None
+    entrypoint: str | None = None
+    dockerfile: str | None = None
+    bedrock_agent_id: str | None = None
+    bedrock_alias_id: str | None = None
+    bedrock_region: str | None = None
+    network_mode: str | None = None
+    subnets: str | None = None
+    security_groups: str | None = None
+    vpc_id: str | None = None
+    authorizer_type: str | None = None
+    discovery_url: str | None = None
+    allowed_audience: str | None = None
+    allowed_clients: str | None = None
+    allowed_scopes: str | None = None
+    custom_claims: list[Any] | None = None
+    client_id: str | None = None
+    client_secret: str | None = None
+    # Set by the interactive wizard (carries client credentials and private endpoints).
+    jwt_config: JwtConfigOptions | None = None
+    idle_timeout: int | None = None
+    max_lifetime: int | None = None
+    session_storage_mount_path: str | None = None
+    efs_access_points: list[dict[str, Any]] = field(default_factory=list)
+    s3_access_points: list[dict[str, Any]] = field(default_factory=list)
+    capacity_provider: str | None = None
+    capacity_provider_volumes: list[dict[str, Any]] = field(default_factory=list)
+    with_config_bundle: bool | None = None
+
+
+def _jwt_config(options: AddAgentOptions, include_client: bool) -> JwtConfigOptions | None:
+    if options.jwt_config is not None:
+        return options.jwt_config
+    if options.authorizer_type != "CUSTOM_JWT" or not options.discovery_url:
+        return None
+    return JwtConfigOptions(
+        discovery_url=options.discovery_url,
+        allowed_audience=_split_csv(options.allowed_audience),
+        allowed_clients=_split_csv(options.allowed_clients),
+        allowed_scopes=_split_csv(options.allowed_scopes),
+        custom_claims=options.custom_claims,
+        client_id=options.client_id if include_client else None,
+        client_secret=options.client_secret if include_client else None,
+    )
+
+
+def build_capacity_provider_configuration(value: str | None) -> dict[str, Any] | None:
+    """`arn:` prefix -> external CP by ARN; anything else -> in-project sibling by name."""
+    if not value:
+        return None
+    return {"capacityProviderArn": value} if is_capacity_provider_arn(value) else {"capacityProviderName": value}
+
+
+def _copy_dockerfile(project_root: str, dockerfile: str | None, dest_dir: str) -> str | None:
+    """A Dockerfile given as a path is copied into the agent directory; returns the file name."""
+    if not dockerfile or "/" not in dockerfile:
+        return dockerfile
+    source = os.path.abspath(os.path.join(project_root, dockerfile))
+    if not os.path.exists(source):
+        raise Exception(f"Dockerfile not found at {source}")
+    os.makedirs(dest_dir, exist_ok=True)
+    shutil.copyfile(source, os.path.join(dest_dir, os.path.basename(source)))
+    return os.path.basename(source)
+
+
+class AgentPrimitive(BasePrimitive):
+    kind = "agent"
+    label = "Agent"
+    article = "an"
+
+    def __init__(self, config_io: ConfigIO | None = None):
+        super().__init__(config_io)
+        self.credential_primitive = CredentialPrimitive()
+
+    # --- add ----------------------------------------------------------------------------
+
+    def add(self, options: AddAgentOptions, config_base_dir: str | None = None) -> Ok[dict[str, Any]] | Err[Exception]:
+        try:
+            base_dir = config_base_dir or find_config_root()
+            if not base_dir:
+                return Err(NoProjectError())
+            config_io = ConfigIO(base_dir=base_dir)
+            if not config_io.config_exists("project"):
+                return Err(NoProjectError())
+            project = to_jsonable(config_io.read_project_spec())
+            if any(r["name"] == options.name for r in project["runtimes"]):
+                return Err(
+                    ConflictError(
+                        f'Agent "{options.name}" already exists. To update its configuration, edit '
+                        "agentcore/agentcore.json directly."
+                    )
+                )
+            if options.type == "import":
+                return self.handle_import_path(options, base_dir)
+            if options.type == "byo":
+                return self.handle_byo_path(options, base_dir)
+            return self.handle_create_path(options, base_dir)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def to_generate_config(self, options: AddAgentOptions) -> GenerateConfig:
+        return GenerateConfig(
+            project_name=options.name,
+            build_type=options.build_type,
+            dockerfile=options.dockerfile,
+            sdk=options.framework,
+            model_provider=options.model_provider,
+            api_key=options.api_key,
+            memory=options.memory or "none",
+            language=options.language,
+            protocol=options.protocol or "HTTP",
+            network_mode=options.network_mode,
+            subnets=parse_comma_separated_list(options.subnets),
+            security_groups=parse_comma_separated_list(options.security_groups),
+            vpc_id=options.vpc_id,
+            authorizer_type=options.authorizer_type,
+            jwt_config=_jwt_config(options, include_client=False) if options.authorizer_type == "CUSTOM_JWT" else None,
+            request_header_allowlist=options.request_header_allowlist,
+            idle_runtime_session_timeout=options.idle_timeout,
+            max_lifetime=options.max_lifetime,
+            session_storage_mount_path=options.session_storage_mount_path,
+            efs_access_points=list(options.efs_access_points),
+            s3_access_points=list(options.s3_access_points),
+            capacity_provider_configuration=build_capacity_provider_configuration(options.capacity_provider),
+            capacity_provider_volumes=list(options.capacity_provider_volumes),
+            with_config_bundle=options.with_config_bundle,
+        )
+
+    def handle_create_path(self, options: AddAgentOptions, config_base_dir: str) -> Ok[dict[str, Any]]:
+        """Render the framework template into app/<name>/ and register it."""
+        project_root = os.path.dirname(config_base_dir)
+        config_io = ConfigIO(base_dir=config_base_dir)
+        project = to_jsonable(config_io.read_project_spec())
+        generate_config = self.to_generate_config(options)
+        agent_path = os.path.join(project_root, APP_DIR, options.name)
+
+        strategy = None
+        identity_providers = []
+        if options.protocol != "MCP" and options.model_provider != "Bedrock":
+            strategy = self.credential_primitive.resolve_credential_strategy(
+                project["name"],
+                options.name,
+                options.model_provider,
+                options.api_key,
+                config_base_dir,
+                project["credentials"],
+            )
+            from agentcore.templates import IdentityProviderRenderConfig
+
+            identity_providers = [
+                IdentityProviderRenderConfig(name=strategy.credential_name, env_var_name=strategy.env_var_name)
+            ]
+
+        render_config = map_generate_config_to_render_config(generate_config, identity_providers, config_base_dir)
+        create_renderer(render_config).render(RendererContext(output_dir=project_root))
+
+        # Wizard only: a Dockerfile path is copied over the template default.
+        generate_config.dockerfile = _copy_dockerfile(project_root, generate_config.dockerfile, agent_path)
+
+        if strategy is not None:
+            write_agent_to_project(generate_config, config_base_dir=config_base_dir, credential_strategy=strategy)
+            # Always write the env var (empty when skipped) so users can find and fill it in.
+            env_var_name = strategy.env_var_name or compute_default_credential_env_var_name(
+                f"{project['name']}{options.model_provider}"
+            )
+            set_env_var(env_var_name, options.api_key or "", config_base_dir)
+        else:
+            write_agent_to_project(generate_config, config_base_dir=config_base_dir)
+
+        jwt = options.jwt_config
+        if options.authorizer_type == "CUSTOM_JWT" and jwt and jwt.client_id and jwt.client_secret:
+            create_managed_oauth_credential(
+                options.name, jwt, config_io.write_project_spec, config_io.read_project_spec, config_base_dir
+            )
+
+        if options.language == "Python" and template_needs_python_venv(options.framework):
+            setup_python_project(agent_path)
+
+        if options.with_config_bundle:
+            create_config_bundle_for_agent(options.name, config_base_dir)
+
+        return Ok({"agentName": options.name, "agentPath": agent_path})
+
+    def handle_import_path(self, options: AddAgentOptions, config_base_dir: str) -> Ok[Any] | Err[Exception]:
+        from agentcore.operations.agent.import_ import ExecuteImportAgentParams, execute_import_agent
+
+        jwt = _jwt_config(options, include_client=True)
+        return execute_import_agent(
+            ExecuteImportAgentParams(
+                name=options.name,
+                framework=options.framework,
+                memory=options.memory or "none",
+                bedrock_region=options.bedrock_region or "",
+                bedrock_agent_id=options.bedrock_agent_id or "",
+                bedrock_alias_id=options.bedrock_alias_id or "",
+                config_base_dir=config_base_dir,
+                authorizer_type=options.authorizer_type if options.jwt_config else None,
+                jwt_config=jwt if options.jwt_config else None,
+                idle_timeout=options.idle_timeout,
+                max_lifetime=options.max_lifetime,
+                session_storage_mount_path=options.session_storage_mount_path,
+                efs_access_points=list(options.efs_access_points),
+                s3_access_points=list(options.s3_access_points),
+                capacity_provider_configuration=build_capacity_provider_configuration(options.capacity_provider),
+                capacity_provider_volumes=list(options.capacity_provider_volumes),
+            )
+        )
+
+    def map_byo_agent(self, options: AddAgentOptions, code_location: str) -> dict[str, Any]:
+        protocol = options.protocol or "HTTP"
+        cp_config = build_capacity_provider_configuration(options.capacity_provider)
+        # A capacity provider supplies its own network topology: no networkMode/networkConfig then.
+        network_mode = None if cp_config else (options.network_mode or "PUBLIC")
+        subnets = parse_comma_separated_list(options.subnets)
+        security_groups = parse_comma_separated_list(options.security_groups)
+        jwt = _jwt_config(options, include_client=False)
+
+        agent: dict[str, Any] = {"name": options.name, "build": options.build_type}
+        if options.dockerfile:
+            agent["dockerfile"] = options.dockerfile
+        agent["entrypoint"] = options.entrypoint or "main.py"
+        agent["codeLocation"] = code_location
+        agent["runtimeVersion"] = DEFAULT_PYTHON_VERSION
+        agent["protocol"] = protocol
+        if network_mode is not None:
+            agent["networkMode"] = network_mode
+        if network_mode == "VPC" and subnets and security_groups:
+            network_config: dict[str, Any] = {"subnets": subnets, "securityGroups": security_groups}
+            if options.vpc_id:
+                network_config["vpcId"] = options.vpc_id
+            agent["networkConfig"] = network_config
+        if protocol == "MCP":
+            agent["instrumentation"] = {"enableOtel": False}
+        if options.request_header_allowlist:
+            agent["requestHeaderAllowlist"] = options.request_header_allowlist
+        if options.authorizer_type:
+            agent["authorizerType"] = options.authorizer_type
+        if options.authorizer_type == "CUSTOM_JWT" and jwt:
+            agent["authorizerConfiguration"] = build_authorizer_config_from_jwt_config(jwt)
+        if options.idle_timeout is not None or options.max_lifetime is not None:
+            lifecycle: dict[str, Any] = {}
+            if options.idle_timeout is not None:
+                lifecycle["idleRuntimeSessionTimeout"] = options.idle_timeout
+            if options.max_lifetime is not None:
+                lifecycle["maxLifetime"] = options.max_lifetime
+            agent["lifecycleConfiguration"] = lifecycle
+        if cp_config:
+            agent["capacityProviderConfiguration"] = cp_config
+        from agentcore.cli.commands.shared.filesystem_utils import build_filesystem_configurations
+
+        agent.update(
+            build_filesystem_configurations(
+                options.session_storage_mount_path,
+                list(options.efs_access_points),
+                list(options.s3_access_points),
+                list(options.capacity_provider_volumes),
+            )
+        )
+        return agent
+
+    def handle_byo_path(self, options: AddAgentOptions, config_base_dir: str) -> Ok[dict[str, Any]]:
+        """Register existing code at --code-location (the directory is created if missing)."""
+        raw_location = options.code_location or ""
+        code_location = raw_location if raw_location.endswith("/") else f"{raw_location}/"
+        project_root = os.path.dirname(config_base_dir)
+        code_dir = os.path.join(project_root, code_location.rstrip("/"))
+        os.makedirs(code_dir, exist_ok=True)
+        options.dockerfile = _copy_dockerfile(project_root, options.dockerfile, code_dir)
+
+        config_io = ConfigIO(base_dir=config_base_dir)
+        project = to_jsonable(config_io.read_project_spec())
+        project["runtimes"].append(self.map_byo_agent(options, code_location))
+
+        env_update: tuple[str, str] | None = None
+        if options.protocol != "MCP" and options.model_provider != "Bedrock":
+            strategy = self.credential_primitive.resolve_credential_strategy(
+                project["name"],
+                options.name,
+                options.model_provider,
+                options.api_key,
+                config_base_dir,
+                project["credentials"],
+            )
+            if not strategy.reuse:
+                credentials = map_model_provider_to_credentials(options.model_provider, project["name"])
+                if credentials:
+                    credentials[0]["name"] = strategy.credential_name
+                    project["credentials"].extend(credentials)
+            env_var_name = strategy.env_var_name or compute_default_credential_env_var_name(
+                f"{project['name']}{options.model_provider}"
+            )
+            env_update = (env_var_name, options.api_key or "")
+
+        config_io.write_project_spec(project)
+        if env_update:
+            set_env_var(env_update[0], env_update[1], config_base_dir)
+
+        jwt = options.jwt_config or _jwt_config(options, include_client=True)
+        if (
+            options.authorizer_type == "CUSTOM_JWT"
+            and jwt
+            and jwt.client_id
+            and jwt.client_secret
+            and jwt.discovery_url
+        ):
+            create_managed_oauth_credential(
+                options.name, jwt, config_io.write_project_spec, config_io.read_project_spec, config_base_dir
+            )
+
+        return Ok({"agentName": options.name})
+
+    # --- remove -------------------------------------------------------------------------
+
+    def remove(self, name: str) -> Ok[None] | Err[Exception]:
+        try:
+            config_io = self.config_io
+            project = to_jsonable(config_io.read_project_spec())
+            index = next((i for i, r in enumerate(project["runtimes"]) if r["name"] == name), -1)
+            if index == -1:
+                return Err(ResourceNotFoundError(f'Agent "{name}" not found.'))
+            # Credentials are preserved for potential reuse.
+            project["runtimes"].pop(index)
+            config_io.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 = to_jsonable(self.config_io.read_project_spec())
+        if not any(r["name"] == name for r in project["runtimes"]):
+            raise Exception(f'Agent "{name}" not found.')
+        after = {**project, "runtimes": [r for r in project["runtimes"] if r["name"] != name]}
+        return RemovalPreview(
+            [f"Removing agent: {name}"], [], [SchemaChange("agentcore/agentcore.json", project, after)]
+        )
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [RemovableResource(r["name"]) for r in to_jsonable(self.config_io.read_project_spec())["runtimes"]]
+        except Exception:  # noqa: BLE001
+            return []
+
+    @staticmethod
+    def get_agent_scoped_credentials(project_name: str, agent_name: str, credentials: list[Any]) -> list[Any]:
+        """Credentials named {projectName}{agentName}{provider}."""
+        prefix = f"{project_name}{agent_name}"
+        result = []
+        for c in credentials:
+            name = c["name"] if isinstance(c, dict) else c.name
+            if name.startswith(prefix) and name[len(prefix) :] in CREDENTIAL_PROVIDERS:
+                result.append(c)
+        return result
+
+    # --- CLI ----------------------------------------------------------------------------
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:
+        @add_app.command("agent", help="Add an agent to the project")
+        def add_agent(
+            name: str | None = typer.Option(
+                None,
+                "--name",
+                help="Agent name (start with letter, alphanumeric + underscores, max 48 chars) [non-interactive]",
+            ),
+            agent_type: str = typer.Option(
+                "create", "--type", help="Agent type: create, byo, or import [non-interactive]"
+            ),
+            build: str | None = typer.Option(
+                None, "--build", help="Build type: CodeZip or Container (default: CodeZip) [non-interactive]"
+            ),
+            language: str | None = typer.Option(
+                None,
+                "--language",
+                help="Language: Python (create), or Python/TypeScript/Other (BYO) [non-interactive]",
+            ),
+            framework: str | None = typer.Option(
+                None,
+                "--framework",
+                help="Framework: Strands, LangChain_LangGraph, GoogleADK, OpenAIAgents, VercelAI, "
+                "BedrockManagedAgents [non-interactive]",
+            ),
+            model_provider: str | None = typer.Option(
+                None, "--model-provider", help="Model provider: Bedrock, Anthropic, OpenAI, Gemini [non-interactive]"
+            ),
+            api_key: str | None = typer.Option(
+                None, "--api-key", help="API key for non-Bedrock providers [non-interactive]"
+            ),
+            memory: str | None = typer.Option(
+                None, "--memory", help="Memory: none, shortTerm, longAndShortTerm (create path only) [non-interactive]"
+            ),
+            protocol: str | None = typer.Option(
+                None, "--protocol", help="Protocol: HTTP, MCP, A2A, AGUI (default: HTTP) [non-interactive]"
+            ),
+            code_location: str | None = typer.Option(
+                None, "--code-location", help="Path to existing code (BYO path only) [non-interactive]"
+            ),
+            entrypoint: str | None = typer.Option(
+                None,
+                "--entrypoint",
+                help="Entry file relative to code-location (BYO, default: main.py) [non-interactive]",
+            ),
+            agent_id: str | None = typer.Option(
+                None, "--agent-id", help="Bedrock Agent ID (import path only) [non-interactive]"
+            ),
+            agent_alias_id: str | None = typer.Option(
+                None, "--agent-alias-id", help="Bedrock Agent Alias ID (import path only) [non-interactive]"
+            ),
+            region: str | None = typer.Option(
+                None, "--region", help="AWS region for Bedrock Agent (import path only) [non-interactive]"
+            ),
+            network_mode: str | None = typer.Option(
+                None, "--network-mode", help="Network mode (PUBLIC, VPC) [non-interactive]"
+            ),
+            subnets: str | None = typer.Option(
+                None, "--subnets", help="Comma-separated subnet IDs (required for VPC mode) [non-interactive]"
+            ),
+            security_groups: str | None = typer.Option(
+                None,
+                "--security-groups",
+                help="Comma-separated security group IDs (required for VPC mode) [non-interactive]",
+            ),
+            vpc_id: str | None = typer.Option(
+                None, "--vpc-id", help="VPC ID (required for Container builds with VPC mode) [non-interactive]"
+            ),
+            authorizer_type: str | None = typer.Option(
+                None, "--authorizer-type", help="Inbound auth: AWS_IAM or CUSTOM_JWT [non-interactive]"
+            ),
+            discovery_url: str | None = typer.Option(
+                None, "--discovery-url", help="OIDC discovery URL (for CUSTOM_JWT) [non-interactive]"
+            ),
+            allowed_audience: str | None = typer.Option(
+                None, "--allowed-audience", help="Comma-separated allowed audiences (for CUSTOM_JWT) [non-interactive]"
+            ),
+            allowed_clients: str | None = typer.Option(
+                None, "--allowed-clients", help="Comma-separated allowed client IDs (for CUSTOM_JWT) [non-interactive]"
+            ),
+            allowed_scopes: str | None = typer.Option(
+                None, "--allowed-scopes", help="Comma-separated allowed scopes (for CUSTOM_JWT) [non-interactive]"
+            ),
+            custom_claims: str | None = typer.Option(
+                None,
+                "--custom-claims",
+                help="Custom claim validations as JSON array (for CUSTOM_JWT) [non-interactive]",
+            ),
+            client_id: str | None = typer.Option(
+                None, "--client-id", help="OAuth client ID for agent bearer token [non-interactive]"
+            ),
+            client_secret: str | None = typer.Option(
+                None, "--client-secret", help="OAuth client secret [non-interactive]"
+            ),
+            request_header_allowlist: str | None = typer.Option(
+                None, "--request-header-allowlist", help=_HEADER_ALLOWLIST_HELP
+            ),
+            idle_timeout: str | None = typer.Option(
+                None,
+                "--idle-timeout",
+                help=f"Idle session timeout in seconds ({LIFECYCLE_TIMEOUT_MIN}-{LIFECYCLE_TIMEOUT_MAX}) "
+                "[non-interactive]",
+            ),
+            max_lifetime: str | None = typer.Option(
+                None,
+                "--max-lifetime",
+                help=f"Max instance lifetime in seconds ({LIFECYCLE_TIMEOUT_MIN}-{LIFECYCLE_TIMEOUT_MAX}) "
+                "[non-interactive]",
+            ),
+            session_storage_mount_path: str | None = typer.Option(
+                None,
+                "--session-storage-mount-path",
+                help="Absolute mount path for session filesystem storage (e.g. /mnt/session-storage) [non-interactive]",
+            ),
+            efs_access_point_arn: list[str] = typer.Option(
+                [],
+                "--efs-access-point-arn",
+                help="EFS access point ARN (repeatable, paired with --efs-mount-path) [non-interactive]",
+            ),
+            efs_mount_path: list[str] = typer.Option(
+                [],
+                "--efs-mount-path",
+                help="EFS mount path (e.g. /mnt/tools, paired with --efs-access-point-arn) [non-interactive]",
+            ),
+            s3_access_point_arn: list[str] = typer.Option(
+                [],
+                "--s3-access-point-arn",
+                help="S3 Files access point ARN (repeatable, paired with --s3-mount-path) [non-interactive]",
+            ),
+            s3_mount_path: list[str] = typer.Option(
+                [],
+                "--s3-mount-path",
+                help="S3 Files mount path (e.g. /mnt/datasets, paired with --s3-access-point-arn) [non-interactive]",
+            ),
+            capacity_provider: str | None = typer.Option(
+                None,
+                "--capacity-provider",
+                help="Attach to a capacity provider — an in-project capacity-provider name or an external CP ARN "
+                "[non-interactive]",
+            ),
+            cp_volume_name: list[str] = typer.Option(
+                [],
+                "--cp-volume-name",
+                help="Capacity provider volume name to mount (repeatable, paired with --cp-volume-mount-path) "
+                "[non-interactive]",
+            ),
+            cp_volume_mount_path: list[str] = typer.Option(
+                [],
+                "--cp-volume-mount-path",
+                help="Capacity provider volume mount path (e.g. /mnt/models, paired with --cp-volume-name) "
+                "[non-interactive]",
+            ),
+            with_config_bundle: bool = typer.Option(
+                False,
+                "--with-config-bundle",
+                help="Create a config bundle wired into the agent template [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 framework 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)
+
+            cli: dict[str, Any] = {
+                "name": name,
+                "type": agent_type,
+                "build": build,
+                "language": language,
+                "framework": framework,
+                "modelProvider": model_provider,
+                "apiKey": api_key,
+                "memory": memory,
+                "protocol": protocol,
+                "codeLocation": code_location,
+                "entrypoint": entrypoint,
+                "agentId": agent_id,
+                "agentAliasId": agent_alias_id,
+                "region": region,
+                "networkMode": network_mode,
+                "subnets": subnets,
+                "securityGroups": security_groups,
+                "vpcId": vpc_id,
+                "authorizerType": authorizer_type,
+                "discoveryUrl": discovery_url,
+                "allowedAudience": allowed_audience,
+                "allowedClients": allowed_clients,
+                "allowedScopes": allowed_scopes,
+                "customClaims": custom_claims,
+                "clientId": client_id,
+                "clientSecret": client_secret,
+                "requestHeaderAllowlist": request_header_allowlist,
+                "idleTimeout": idle_timeout,
+                "maxLifetime": max_lifetime,
+                "sessionStorageMountPath": session_storage_mount_path,
+                "efsAccessPointArn": list(efs_access_point_arn),
+                "efsMountPath": list(efs_mount_path),
+                "s3AccessPointArn": list(s3_access_point_arn),
+                "s3MountPath": list(s3_mount_path),
+                "capacityProvider": capacity_provider,
+                "cpVolumeName": list(cp_volume_name),
+                "cpVolumeMountPath": list(cp_volume_mount_path),
+                "withConfigBundle": with_config_bundle or None,
+            }
+            run_cli_command(as_json, lambda: self._run_add_cli(cli, as_json))
+
+        self.register_remove_subcommand(remove_app)
+
+    def _run_add_cli(self, cli: dict[str, Any], as_json: bool) -> None:
+        from agentcore.cli.commands.shared import filesystem_utils as fs
+
+        validation = validate_add_agent_options(cli)
+        if not validation.valid:
+            raise ValidationError(validation.error or "")
+
+        efs_arns, efs_paths = cli["efsAccessPointArn"], cli["efsMountPath"]
+        s3_arns, s3_paths = cli["s3AccessPointArn"], cli["s3MountPath"]
+        efs_pairs = fs.zip_access_point_pairs(efs_arns, efs_paths, "EFS")
+        if not efs_pairs.success:
+            raise Exception(efs_pairs.error)
+        s3_pairs = fs.zip_access_point_pairs(s3_arns, s3_paths, "S3 Files")
+        if not s3_pairs.success:
+            raise Exception(s3_pairs.error)
+        check = fs.validate_access_point_mounts(efs_pairs.mounts, fs.validate_efs_access_point_arn)
+        if not check.success:
+            raise Exception(check.error)
+        check = fs.validate_access_point_mounts(s3_pairs.mounts, fs.validate_s3_files_access_point_arn)
+        if not check.success:
+            raise Exception(check.error)
+        cp_pairs = fs.zip_capacity_provider_volume_pairs(cli["cpVolumeName"], cli["cpVolumeMountPath"])
+        if not cp_pairs.success:
+            raise Exception(cp_pairs.error)
+        check = fs.validate_capacity_provider_volume_mounts(cp_pairs.mounts)
+        if not check.success:
+            raise Exception(check.error)
+        if cp_pairs.mounts and not cli["capacityProvider"]:
+            raise Exception(
+                "Capacity provider volume mounts (--cp-volume-name / --cp-volume-mount-path) require attaching the "
+                "runtime to a capacity provider (--capacity-provider <name-or-arn>)."
+            )
+        if cli["capacityProvider"] and cli["networkMode"] is not None:
+            raise Exception(
+                "--network-mode cannot be set when attaching a capacity provider (--capacity-provider) — the "
+                "capacity provider supplies the network topology. Remove --network-mode."
+            )
+        has_byo_fs = bool(efs_arns or s3_arns)
+        if has_byo_fs and cli["networkMode"] != "VPC":
+            raise Exception(
+                "EFS and S3 Files filesystem mounts require VPC network mode. Add --network-mode VPC --subnets <ids> "
+                "--security-groups <ids>."
+            )
+        if has_byo_fs:
+            self._validate_filesystem(cli, efs_pairs.mounts, s3_pairs.mounts)
+
+        custom_claims = json.loads(cli["customClaims"]) if cli["customClaims"] else None
+        headers = parse_and_normalize_headers(cli["requestHeaderAllowlist"]) if cli["requestHeaderAllowlist"] else None
+        result = self.add(
+            AddAgentOptions(
+                name=cli["name"],
+                type=cli["type"] or "create",
+                build_type=cli["build"] or "CodeZip",
+                language=cli["language"],
+                framework=cli["framework"],
+                model_provider=cli["modelProvider"],
+                api_key=cli["apiKey"],
+                memory=cli["memory"],
+                protocol=cli["protocol"],
+                network_mode=cli["networkMode"],
+                subnets=cli["subnets"],
+                security_groups=cli["securityGroups"],
+                vpc_id=cli["vpcId"],
+                request_header_allowlist=headers,
+                code_location=cli["codeLocation"],
+                entrypoint=cli["entrypoint"],
+                bedrock_agent_id=cli["agentId"],
+                bedrock_alias_id=cli["agentAliasId"],
+                bedrock_region=cli["region"],
+                authorizer_type=cli["authorizerType"],
+                discovery_url=cli["discoveryUrl"],
+                allowed_audience=cli["allowedAudience"],
+                allowed_clients=cli["allowedClients"],
+                allowed_scopes=cli["allowedScopes"],
+                custom_claims=custom_claims,
+                client_id=cli["clientId"],
+                client_secret=cli["clientSecret"],
+                idle_timeout=int(cli["idleTimeout"]) if cli["idleTimeout"] else None,
+                max_lifetime=int(cli["maxLifetime"]) if cli["maxLifetime"] else None,
+                session_storage_mount_path=cli["sessionStorageMountPath"],
+                efs_access_points=efs_pairs.mounts,
+                s3_access_points=s3_pairs.mounts,
+                capacity_provider=cli["capacityProvider"],
+                capacity_provider_volumes=cp_pairs.mounts,
+                with_config_bundle=cli["withConfigBundle"],
+            )
+        )
+        if not result.success:
+            raise result.error
+        if as_json:
+            emit_json(serialize_result(result))
+        else:
+            typer.echo(f"Added agent '{result.value['agentName']}'")
+            if result.value.get("agentPath"):
+                typer.echo(f"Agent code: {result.value['agentPath']}")
+            if cli["networkMode"] == "VPC":
+                typer.echo(f"\x1b[33mNote: {VPC_ENDPOINT_WARNING}\x1b[0m")
+
+    @staticmethod
+    def _validate_filesystem(cli: dict[str, Any], efs_mounts: list[dict], s3_mounts: list[dict]) -> None:
+        """Async filesystem checks (Level 1-3) against AWS, as upstream."""
+        from agentcore.aws.account import create_aws_client
+        from agentcore.cli.commands.shared import filesystem_utils as fs
+
+        subnet_ids = parse_comma_separated_list(cli["subnets"]) or []
+        sg_ids = parse_comma_separated_list(cli["securityGroups"]) or []
+        root = find_config_root()
+        targets = ConfigIO(base_dir=root).resolve_aws_deployment_targets() if root else []
+        first = to_jsonable(targets[0]) if targets else {}
+        region = (
+            first.get("region") or os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or "us-east-1"
+        )
+        agent_vpc_id = None
+        if subnet_ids:
+            try:
+                resp = create_aws_client("ec2", region).describe_subnets(SubnetIds=subnet_ids)
+                agent_vpc_id = (resp.get("Subnets") or [{}])[0].get("VpcId")
+            except Exception:  # noqa: BLE001 - non-fatal: skip Level 2
+                pass
+        result = fs.validate_filesystem_mounts_configuration(
+            efs_mounts=efs_mounts,
+            s3_files_mounts=s3_mounts,
+            agent_vpc_id=agent_vpc_id,
+            agent_subnet_ids=subnet_ids,
+            agent_security_group_ids=sg_ids,
+            region=region,
+        )
+        if not result.success:
+            raise Exception(result.error)
+
+    def add_interactive(self) -> None:
+        """Prompt flow mirroring tui/screens/agent/AddAgentScreen (+ the generate wizard)."""
+        from agentcore.cli.commands.add.agent_wizard import run_add_agent_wizard
+
+        root = find_config_root()
+        config_io = ConfigIO(base_dir=root) if root else ConfigIO()
+        project = to_jsonable(config_io.read_project_spec())
+        options = run_add_agent_wizard(
+            existing_agent_names=[r["name"] for r in project["runtimes"]],
+            project_name=project["name"],
+            capacity_provider_names=[c["name"] for c in project.get("capacityProviders", [])],
+            project_root=os.path.dirname(root) if root else os.getcwd(),
+        )
+        if options is None:
+            typer.echo("Cancelled.")
+            return
+        result = self.add(options, root)
+        if not result.success:
+            typer.echo(get_error_message(result.error), err=True)
+            raise typer.Exit(1)
+        typer.echo(f"✓ Created agent: {result.value['agentName']}")
+        if result.value.get("agentPath"):
+            typer.echo(f"Agent code: {result.value['agentPath']}")
+        typer.echo("Next: run `agentcore dev` to test locally, or `agentcore deploy` to deploy.")
+
+
+PRIMITIVE = AgentPrimitive()