agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/create/action.py

@@ -0,0 +1,406 @@
+"""Project creation (port of src/cli/commands/create/action.ts and harness-action.ts).
+
+Results are ``Ok(dict)`` with upstream's camelCase keys (``projectPath``, ``agentName``, ``warnings``
+only when non-empty) or ``Err(error, warnings=...)``.
+"""
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentcore.cli.commands.create.dependencies import check_create_dependencies
+from agentcore.cli.project import create_default_project_spec
+from agentcore.lib import (
+    APP_DIR,
+    CONFIG_DIR,
+    ConfigIO,
+    DependencyCheckError,
+    GitInitError,
+    set_env_var,
+    set_session_project_root,
+)
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+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,
+    write_agent_to_project,
+)
+from agentcore.operations.init import init_git_repo, write_env_file, write_gitignore
+from agentcore.operations.node import setup_node_project
+from agentcore.operations.python import setup_python_project
+from agentcore.templates import (
+    CDKRenderer,
+    CDKRendererContext,
+    IdentityProviderRenderConfig,
+    RendererContext,
+    create_renderer,
+    get_template_profile,
+    template_needs_python_venv,
+)
+
+ProgressCallback = Callable[[str, str], None]
+CreateResult = Ok[dict[str, Any]] | Err[Exception]
+
+
+def _with_warnings(data: dict[str, Any], warnings: list[str]) -> dict[str, Any]:
+    if warnings:
+        data["warnings"] = list(warnings)
+    return data
+
+
+def _fail(error: BaseException, warnings: list[str]) -> Err[Exception]:
+    return Err(error, {"warnings": list(warnings)} if warnings else {})  # type: ignore[arg-type]
+
+
+def _progress(on_progress: ProgressCallback | None, step: str, status: str) -> None:
+    if on_progress:
+        on_progress(step, status)
+
+
+def create_project(
+    name: str,
+    cwd: str,
+    skip_git: bool = False,
+    skip_install: bool = False,
+    skip_dependency_check: bool = False,
+    on_progress: ProgressCallback | None = None,
+    directory: str | None = None,
+) -> CreateResult:
+    """Scaffold <cwd>/<directory or name>/ with agentcore/ config files, the CDK project and a git repo.
+
+    ``directory`` lets the folder differ from the project name (used by ``agentcore init``, whose
+    folder may contain characters project names don't allow).
+    """
+    if skip_install:
+        os.environ["AGENTCORE_SKIP_INSTALL"] = "1"
+    directory = directory or name
+    project_root = os.path.join(cwd, directory)
+    config_base_dir = os.path.join(project_root, CONFIG_DIR)
+
+    warnings: list[str] = []
+    if not skip_dependency_check:
+        dep_check = check_create_dependencies(None)
+        warnings = dep_check.warnings
+        if not dep_check.passed:
+            return _fail(DependencyCheckError(dep_check.errors), warnings)
+
+    try:
+        step = f"Create {directory}/ project directory"
+        _progress(on_progress, step, "start")
+        os.makedirs(project_root, exist_ok=True)
+        _progress(on_progress, step, "done")
+
+        _progress(on_progress, "Prepare agentcore/ directory", "start")
+        config_io = ConfigIO(base_dir=config_base_dir)
+        config_io.initialize_base_dir()
+        set_session_project_root(project_root)
+
+        write_gitignore(config_base_dir)
+        write_env_file(config_base_dir)
+        config_io.write_project_spec(create_default_project_spec(name))
+        config_io.write_aws_deployment_targets([])
+        config_io.write_deployed_state({"targets": {}})
+
+        CDKRenderer().render(CDKRendererContext(project_root=project_root))
+        _progress(on_progress, "Prepare agentcore/ directory", "done")
+
+        if not skip_git:
+            _progress(on_progress, "Initialize git repository", "start")
+            git = init_git_repo(project_root)
+            if git.status == "error":
+                _progress(on_progress, "Initialize git repository", "error")
+                return _fail(GitInitError(git.message or "Git initialization failed"), warnings)
+            _progress(on_progress, "Initialize git repository", "done")
+
+        return Ok(_with_warnings({"projectPath": project_root}, warnings))
+    except Exception as exc:  # noqa: BLE001
+        return _fail(to_error(exc), warnings)
+
+
+@dataclass
+class CreateWithAgentOptions:
+    name: str
+    cwd: str
+    language: str
+    memory: str = "none"
+    project_name: str | None = None
+    type: str | None = None
+    build_type: str | None = None
+    framework: str | None = None
+    model_provider: str | None = None
+    api_key: str | None = None
+    protocol: str | None = None
+    network_mode: str | None = None
+    subnets: list[str] | None = None
+    security_groups: list[str] | None = None
+    vpc_id: str | None = None
+    request_header_allowlist: list[str] | None = None
+    agent_id: str | None = None
+    agent_alias_id: str | None = None
+    region: str | 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_configuration: dict[str, Any] | None = None
+    capacity_provider_volumes: list[dict[str, Any]] = field(default_factory=list)
+    with_config_bundle: bool | None = None
+    directory: str | None = None
+    skip_git: bool = False
+    skip_install: bool = False
+    skip_python_setup: bool = False
+    on_progress: ProgressCallback | None = None
+
+
+def create_project_with_agent(options: CreateWithAgentOptions) -> CreateResult:
+    project_name = options.project_name or options.name
+    project_root = os.path.join(options.cwd, options.directory or project_name)
+    config_base_dir = os.path.join(project_root, CONFIG_DIR)
+    on_progress = options.on_progress
+
+    dep_check = check_create_dependencies(options.language)
+    warnings = list(dep_check.warnings)
+    if not dep_check.passed:
+        return _fail(DependencyCheckError(dep_check.errors), warnings)
+
+    project_result = create_project(
+        project_name,
+        options.cwd,
+        skip_git=options.skip_git,
+        skip_install=options.skip_install,
+        skip_dependency_check=True,
+        on_progress=on_progress,
+        directory=options.directory,
+    )
+    if not project_result.success:
+        merged = warnings + list(project_result.extra.get("warnings", []))
+        return _fail(project_result.error, merged)
+
+    if options.type == "import" and options.agent_id and options.agent_alias_id and options.region:
+        try:
+            from agentcore.operations.agent.import_ import ExecuteImportAgentParams, execute_import_agent
+
+            _progress(on_progress, "Import agent from Bedrock", "start")
+            imported = execute_import_agent(
+                ExecuteImportAgentParams(
+                    name=options.name,
+                    framework=options.framework or "Strands",
+                    memory=options.memory,
+                    bedrock_region=options.region,
+                    bedrock_agent_id=options.agent_id,
+                    bedrock_alias_id=options.agent_alias_id,
+                    config_base_dir=config_base_dir,
+                    efs_access_points=options.efs_access_points,
+                    s3_access_points=options.s3_access_points,
+                    capacity_provider_configuration=options.capacity_provider_configuration,
+                    capacity_provider_volumes=options.capacity_provider_volumes,
+                )
+            )
+            if not imported.success:
+                _progress(on_progress, "Import agent from Bedrock", "error")
+                return _fail(imported.error, warnings)
+            _progress(on_progress, "Import agent from Bedrock", "done")
+            return Ok(_with_warnings({"projectPath": project_root, "agentName": options.name}, warnings))
+        except Exception as exc:  # noqa: BLE001
+            return _fail(to_error(exc), warnings)
+
+    try:
+        _progress(on_progress, "Add agent to project", "start")
+        agent_name = options.name
+        is_mcp = options.protocol == "MCP"
+        framework = "Strands" if is_mcp else (options.framework or "Strands")
+        provider = "Bedrock" if is_mcp else (options.model_provider or "Bedrock")
+
+        generate_config = GenerateConfig(
+            project_name=agent_name,
+            build_type=options.build_type or "CodeZip",
+            sdk=framework,
+            model_provider=provider,
+            api_key=options.api_key,
+            memory=options.memory,
+            language=options.language,
+            protocol=options.protocol or "HTTP",
+            network_mode=options.network_mode,
+            subnets=options.subnets,
+            security_groups=options.security_groups,
+            vpc_id=options.vpc_id,
+            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 or None,
+            efs_access_points=options.efs_access_points or None,
+            s3_access_points=options.s3_access_points or None,
+            capacity_provider_configuration=options.capacity_provider_configuration,
+            capacity_provider_volumes=options.capacity_provider_volumes or None,
+            with_config_bundle=options.with_config_bundle or None,
+        )
+
+        strategy = None
+        identity_providers: list[IdentityProviderRenderConfig] = []
+        if not is_mcp and provider != "Bedrock":
+            from agentcore.primitives.credential import CredentialPrimitive
+
+            strategy = CredentialPrimitive().resolve_credential_strategy(
+                project_name, agent_name, provider, options.api_key, config_base_dir, []
+            )
+            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))
+
+        if strategy is not None:
+            write_agent_to_project(generate_config, config_base_dir=config_base_dir, credential_strategy=strategy)
+            if options.api_key:
+                set_env_var(strategy.env_var_name, options.api_key, config_base_dir)
+        else:
+            write_agent_to_project(generate_config, config_base_dir=config_base_dir)
+        _progress(on_progress, "Add agent to project", "done")
+
+        if options.with_config_bundle:
+            create_config_bundle_for_agent(agent_name, config_base_dir)
+
+        agent_dir = os.path.join(project_root, APP_DIR, options.name)
+        if (
+            options.language == "Python"
+            and template_needs_python_venv(framework)
+            and not options.skip_python_setup
+            and not options.skip_install
+        ):
+            _progress(on_progress, "Set up Python environment", "start")
+            setup_python_project(agent_dir)
+            _progress(on_progress, "Set up Python environment", "done")
+
+        if options.language == "TypeScript" and not options.skip_install:
+            _progress(on_progress, "Set up Node environment", "start")
+            node = setup_node_project(agent_dir)
+            if node.status != "success":
+                first_line = next((ln for ln in (node.error or "").split("\n") if ln.strip()), "")
+                if node.status == "npm_not_found":
+                    warnings.append(
+                        "npm not found on PATH. Install Node.js 20+ and run `npm install` in the agent directory."
+                    )
+                else:
+                    import re
+
+                    detail = re.sub(r"^npm (error|warn) ", "", first_line, flags=re.IGNORECASE)[:160]
+                    warnings.append(
+                        f"npm install failed{': ' + detail if first_line else ''}. Run `npm install` in "
+                        f"{agent_dir} to retry and see the full error."
+                    )
+            _progress(on_progress, "Set up Node environment", "done")
+
+        return Ok(_with_warnings({"projectPath": project_root, "agentName": options.name}, warnings))
+    except Exception as exc:  # noqa: BLE001
+        return _fail(to_error(exc), warnings)
+
+
+def get_dry_run_info(
+    name: str, cwd: str, language: str | None = None, framework: str | None = None, project_name: str | None = None
+) -> Ok[dict[str, Any]]:
+    root = os.path.join(cwd, project_name or name)
+    would_create = [
+        f"{root}/",
+        f"{root}/agentcore/",
+        f"{root}/agentcore/agentcore.json",
+        f"{root}/agentcore/aws-targets.json",
+        f"{root}/agentcore/.env.local",
+        f"{root}/agentcore/cdk/",
+    ]
+    if language == "Python":
+        profile = get_template_profile(framework)
+        would_create += [
+            f"{root}/app/{name}/",
+            f"{root}/app/{name}/{(profile.entrypoint if profile else None) or 'main.py'}",
+            f"{root}/app/{name}/pyproject.toml",
+        ]
+    elif language == "TypeScript":
+        would_create += [
+            f"{root}/app/{name}/",
+            f"{root}/app/{name}/main.ts",
+            f"{root}/app/{name}/package.json",
+            f"{root}/app/{name}/tsconfig.json",
+            f"{root}/app/{name}/model/load.ts",
+            f"{root}/app/{name}/mcp_client/client.ts",
+        ]
+    return Ok({"dryRun": True, "projectPath": root, "wouldCreate": would_create})
+
+
+def get_harness_dry_run_info(name: str, cwd: str, project_name: str | None = None) -> Ok[dict[str, Any]]:
+    root = os.path.join(cwd, project_name or name)
+    return Ok(
+        {
+            "dryRun": True,
+            "projectPath": root,
+            "harnessName": name,
+            "wouldCreate": [
+                f"{root}/",
+                f"{root}/agentcore/",
+                f"{root}/agentcore/agentcore.json",
+                f"{root}/agentcore/aws-targets.json",
+                f"{root}/agentcore/.env.local",
+                f"{root}/agentcore/cdk/",
+                f"{root}/app/{name}/",
+                f"{root}/app/{name}/harness.json",
+                f"{root}/app/{name}/system-prompt.md",
+            ],
+        }
+    )
+
+
+def parse_container_flag(value: str | None) -> dict[str, str]:
+    """Port of HarnessPrimitive.parseContainerFlag: Dockerfile path vs. image URI."""
+    if not value:
+        return {}
+    if value.endswith(("Dockerfile", ".dockerfile")) or value.startswith(("./", "../")):
+        return {"dockerfilePath": value}
+    return {"containerUri": value}
+
+
+def create_project_with_harness(
+    harness_options: dict[str, Any],
+    cwd: str,
+    project_name: str | None = None,
+    skip_git: bool = False,
+    skip_install: bool = False,
+    on_progress: ProgressCallback | None = None,
+) -> CreateResult:
+    """Scaffold a project, then add a harness through the harness primitive.
+
+    ``harness_options`` uses upstream's camelCase AddHarnessOptions keys (name, modelProvider, modelId,
+    ...). The harness primitive is owned by another area; it is resolved at call time.
+    """
+    name = harness_options["name"]
+    project_result = create_project(
+        project_name or name, cwd, skip_git=skip_git, skip_install=skip_install, on_progress=on_progress
+    )
+    if not project_result.success:
+        return project_result
+    warnings = list(project_result.value.get("warnings", []))
+    project_root = project_result.value["projectPath"]
+    config_base_dir = os.path.join(project_root, CONFIG_DIR)
+    try:
+        _progress(on_progress, "Add harness to project", "start")
+        result = _add_harness({**harness_options, "configBaseDir": config_base_dir})
+        if not result.success:
+            _progress(on_progress, "Add harness to project", "error")
+            return _fail(result.error, warnings)
+        _progress(on_progress, "Add harness to project", "done")
+        return Ok(_with_warnings({"projectPath": project_root, "harnessName": name}, warnings))
+    except Exception as exc:  # noqa: BLE001
+        return _fail(to_error(exc), warnings)
+
+
+def _add_harness(options: dict[str, Any]) -> Any:
+    from agentcore.primitives.registry import all_primitives
+
+    harness = next((p for p in all_primitives() if p.kind == "harness"), None)
+    if harness is None:
+        raise Exception("Harness creation is not available in this build: `add harness` is not ported yet.")
+    builder = getattr(harness, "add_options_from_dict", None)
+    return harness.add(builder(options) if callable(builder) else options)

agentcore/cli/commands/create/dependencies.py

@@ -0,0 +1,91 @@
+"""Create-time CLI tool checks (port of checkCreateDependencies from src/cli/external-requirements).
+
+Kept local to `create`: the rest of external-requirements belongs to deploy.
+"""
+
+import os
+from dataclasses import dataclass, field
+
+from agentcore.lib import check_subprocess, is_windows, run_subprocess_capture
+
+AWS_CLI_MIN_VERSION = "2.32.0"
+AWS_CLI_INSTALL_URL = "https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html"
+
+
+@dataclass
+class CliToolCheck:
+    binary: str
+    severity: str
+    available: bool
+    install_hint: str | None = None
+
+
+@dataclass
+class CliToolsCheckResult:
+    passed: bool
+    checks: list[CliToolCheck] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def check_binary_available(binary: str) -> bool:
+    checks = (
+        lambda: check_subprocess("where" if is_windows else "which", [binary]),
+        lambda: check_subprocess(binary, ["--version"]),
+        lambda: check_subprocess(binary, ["-v"]),
+    )
+    return any(check() for check in checks)
+
+
+def format_npm_cache_error(cache_dir: str, owner: str) -> str:
+    return (
+        f"npm cache directory ({cache_dir}) is owned by '{owner}' instead of the current user. "
+        "This was likely caused by a previous 'sudo npm install'. "
+        f"Fix: sudo chown -R $(whoami) {cache_dir}"
+    )
+
+
+def check_npm_cache_ownership() -> tuple[bool, str | None, str]:
+    """(satisfied, owner, cache_dir): ~/.npm must be owned by the current user."""
+    cache_dir = os.path.join(os.path.expanduser("~"), ".npm")
+    if is_windows or not hasattr(os, "getuid"):
+        return True, None, cache_dir
+    try:
+        uid = os.stat(cache_dir).st_uid
+    except OSError:
+        return True, None, cache_dir
+    if uid != os.getuid():
+        result = run_subprocess_capture("id", ["-un", str(uid)])
+        owner = result.stdout.strip() if result.code == 0 else f"uid={uid}"
+        return False, owner, cache_dir
+    return True, None, cache_dir
+
+
+def check_create_dependencies(language: str | None = None) -> CliToolsCheckResult:
+    """uv (Python only, error), npm (error), npm cache ownership (error), aws (warning)."""
+    result = CliToolsCheckResult(passed=True)
+    if language == "Python":
+        uv = check_binary_available("uv")
+        result.checks.append(
+            CliToolCheck("uv", "error", uv, "Install from https://github.com/astral-sh/uv#installation")
+        )
+        if not uv:
+            result.errors.append(
+                "'uv' is required for Python projects. Install from https://github.com/astral-sh/uv#installation"
+            )
+    npm = check_binary_available("npm")
+    result.checks.append(CliToolCheck("npm", "error", npm, "Install Node.js from https://nodejs.org/"))
+    if not npm:
+        result.errors.append("'npm' is required. Install Node.js from https://nodejs.org/")
+    else:
+        satisfied, owner, cache_dir = check_npm_cache_ownership()
+        if not satisfied:
+            result.errors.append(format_npm_cache_error(cache_dir, owner or ""))
+    aws = check_binary_available("aws")
+    result.checks.append(CliToolCheck("aws", "warn", aws, "Install from https://aws.amazon.com/cli/"))
+    if not aws:
+        result.warnings.append(
+            f"'aws' CLI not found. Required for 'aws login'. Install v{AWS_CLI_MIN_VERSION}+ from {AWS_CLI_INSTALL_URL}"
+        )
+    result.passed = not result.errors
+    return result

agentcore/cli/commands/create/harness_validate.py

@@ -0,0 +1,82 @@
+"""`create` harness-path validation (port of src/cli/commands/create/harness-validate.ts)."""
+
+import os
+from typing import Any, Final
+
+from agentcore.cli.commands.add._common import ValidationResult, first_issue
+from agentcore.cli.commands.create.validate import validate_folder_not_exists, validate_mount_pairs
+from agentcore.cli.commands.shared.vpc_utils import validate_vpc_options
+from agentcore.schema import HarnessName, ProjectName, validate_api_format
+
+MODEL_PROVIDER_MAPPING: Final = {
+    "bedrock": "bedrock",
+    "Bedrock": "bedrock",
+    "open_ai": "open_ai",
+    "openai": "open_ai",
+    "OpenAI": "open_ai",
+    "anthropic": "bedrock",
+    "Anthropic": "bedrock",
+    "gemini": "gemini",
+    "Gemini": "gemini",
+    "lite_llm": "lite_llm",
+    "litellm": "lite_llm",
+    "LiteLLM": "lite_llm",
+}
+
+DEFAULT_HARNESS_MODEL_IDS: Final = {
+    "bedrock": "global.anthropic.claude-sonnet-4-6",
+    "open_ai": "gpt-5",
+    "gemini": "gemini-2.5-flash",
+    "lite_llm": "anthropic/claude-sonnet-4-5",
+}
+
+
+def normalize_harness_model_provider(raw: str) -> str | None:
+    return MODEL_PROVIDER_MAPPING.get(raw)
+
+
+def validate_create_harness_options(options: dict[str, Any], cwd: str | None = None) -> ValidationResult:
+    if not options.get("name"):
+        return ValidationResult(False, "--name is required")
+    project_name = options.get("projectName") or options["name"]
+    issue = first_issue(ProjectName, project_name)
+    if issue:
+        return ValidationResult(False, issue)
+    issue = first_issue(HarnessName, options["name"])
+    if issue:
+        return ValidationResult(False, issue)
+    folder = validate_folder_not_exists(project_name, cwd or os.getcwd())
+    if folder is not True:
+        return ValidationResult(False, folder)  # type: ignore[arg-type]
+
+    if options.get("modelProvider"):
+        normalized = normalize_harness_model_provider(options["modelProvider"])
+        if not normalized:
+            return ValidationResult(
+                False,
+                f"Invalid model provider: {options['modelProvider']}. Use bedrock, open_ai, gemini, or lite_llm",
+            )
+        options["modelProvider"] = normalized
+    if not options.get("modelProvider"):
+        options["modelProvider"] = "bedrock"
+    if options.get("modelId") is None:
+        options["modelId"] = DEFAULT_HARNESS_MODEL_IDS.get(
+            options["modelProvider"], "global.anthropic.claude-sonnet-4-6"
+        )
+
+    if options["modelProvider"] not in ("bedrock", "lite_llm") and not options.get("apiKeyArn"):
+        return ValidationResult(False, f"--api-key-arn is required for {options['modelProvider']} provider")
+
+    if options.get("apiFormat"):
+        result = validate_api_format(options["apiFormat"], options["modelProvider"] or "bedrock")
+        if not result.get("valid"):
+            return ValidationResult(False, result.get("error"))
+
+    if failure := validate_mount_pairs(options):
+        return failure
+
+    # Any --container value is a container build, so --vpc-id is required in VPC mode.
+    vpc = validate_vpc_options(options, "Container" if options.get("container") else None)
+    if not vpc.valid:
+        return ValidationResult(False, vpc.error)
+    return ValidationResult(True)