agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/export/harness_action.py

@@ -0,0 +1,385 @@
+"""`export harness` logic (port of src/cli/commands/export/harness-action.ts).
+
+Generates a Python Strands runtime agent under ``app/<target>/`` from a harness, adds it to
+``agentcore.json`` and writes ``EXPORT_NOTES.md``. Results are ``Ok({agentName, agentPath,
+notesPath, notes})`` or ``Err(error)``.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import re
+import shutil
+from collections.abc import Callable
+from typing import Any
+
+from agentcore.cli.commands.export.constants import (
+    CUSTOM_DOCKERFILE_NOTE_CATEGORY,
+    EXPORT_NOTES_FILENAME,
+    PATH_SKILLS_COPIED_NOTE_CATEGORY,
+    PATH_SKILLS_VERIFY_BASE_IMAGE_NOTE_CATEGORY,
+)
+from agentcore.cli.commands.export.fetch_harness_spec import fetch_harness_spec_by_arn
+from agentcore.cli.commands.export.harness_mapper import is_path_skill, map_harness_to_export_config
+from agentcore.cli.commands.export.harness_resolver import PrefetchedHarness, resolve_harness_context
+from agentcore.cli.commands.export.types import ExportHarnessOptions, ExportNote, ResolvedHarnessContext
+from agentcore.cli.errors import get_error_message
+from agentcore.lib import set_env_var
+from agentcore.lib.errors.types import AgentAlreadyExistsError, ExportHarnessError, ValidationError, to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import ConfigIO, to_jsonable
+from agentcore.lib.utils.subprocess import run_subprocess
+from agentcore.operations.harness.orphan import region_from_harness_arn
+from agentcore.templates import RendererContext
+from agentcore.templates.renderers import StrandsRenderer
+
+ExportResult = Ok[dict[str, Any]] | Err[Exception]
+HARNESS_SKIP_FILES = frozenset({"harness.json", "system-prompt.md"})
+
+
+def handle_export_harness(
+    options: ExportHarnessOptions, on_progress: Callable[[str], None] | None = None
+) -> ExportResult:
+    def log(message: str) -> None:
+        if on_progress:
+            on_progress(message)
+
+    if bool(options.name) == bool(options.arn):
+        return Err(ValidationError("Specify exactly one of --name (local harness) or --arn (fetched harness)."))
+
+    build_override = options.build
+    if build_override and build_override not in ("CodeZip", "Container"):
+        return Err(ValidationError(f'Invalid --build value "{build_override}". Expected CodeZip or Container.'))
+
+    prefetched: PrefetchedHarness | None = None
+    if options.arn:
+        log("Fetching harness from service")
+        region = resolve_export_region(options.arn)
+        if not region:
+            return Err(
+                ValidationError(
+                    "No AWS region configured. Pass an ARN that includes a region, configure a deployment "
+                    "target (agentcore/aws-targets.json), or set AWS_REGION before exporting by ARN."
+                )
+            )
+        try:
+            fetched = fetch_harness_spec_by_arn(options.arn, region)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+        prefetched = PrefetchedHarness(spec=fetched["spec"], system_prompt=fetched.get("systemPrompt"))
+
+    harness_name = options.name or (prefetched.spec["name"] if prefetched else "")
+    target = options.target_agent_name or f"{harness_name}Agent"
+    from agentcore.cli.commands.add._common import first_issue
+    from agentcore.schema import AgentName
+
+    issue = first_issue(AgentName, target)
+    if issue:
+        return Err(ValidationError(f'Invalid --target-agent-name "{target}": {issue}'))
+
+    log("Reading harness configuration")
+    try:
+        context = resolve_harness_context(harness_name, target, None, prefetched)
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))
+
+    log("Mapping to Strands template config")
+    # Mapping errors (e.g. a container harness exported as CodeZip) propagate to the command boundary.
+    mapping = map_harness_to_export_config(context, build_override)
+    render_config = mapping.render_config
+
+    agent_dir = os.path.join(context.project_root, "app", target)
+
+    def cleanup() -> None:
+        shutil.rmtree(agent_dir, ignore_errors=True)
+
+    spec = context.spec
+    harness_dir = os.path.join(context.project_root, "app", harness_name)
+    if spec.get("dockerfile"):
+        dockerfile_src = os.path.join(harness_dir, spec["dockerfile"])
+        if os.path.exists(dockerfile_src):
+            os.makedirs(agent_dir, exist_ok=True)
+            shutil.copyfile(dockerfile_src, os.path.join(agent_dir, spec["dockerfile"]))
+            context.export_notes.append(build_custom_dockerfile_note(spec["dockerfile"], target))
+        else:
+            context.export_notes.append(build_missing_dockerfile_note(spec["dockerfile"], harness_name, target))
+        if os.path.exists(harness_dir):
+            shutil.copytree(
+                harness_dir,
+                agent_dir,
+                dirs_exist_ok=True,
+                ignore=lambda _d, names: [n for n in names if n in HARNESS_SKIP_FILES],
+            )
+
+    if not spec.get("dockerfile") and render_config.build_type == "Container":
+        copied: list[str] = []
+        unresolved: list[str] = []
+        for skill in spec.get("skills") or []:
+            if not is_path_skill(skill) or not skill.get("path"):
+                continue
+            skill_path = skill["path"]
+            src = os.path.join(harness_dir, skill_path)
+            escapes = os.path.isabs(skill_path) or not os.path.abspath(src).startswith(
+                os.path.abspath(harness_dir) + os.sep
+            )
+            if not escapes and os.path.exists(src):
+                dest = os.path.join(agent_dir, skill_path)
+                os.makedirs(dest, exist_ok=True)
+                if os.path.isdir(src):
+                    shutil.copytree(src, dest, dirs_exist_ok=True)
+                else:
+                    shutil.copyfile(src, dest)
+                copied.append(skill_path)
+            else:
+                unresolved.append(skill_path)
+        if copied:
+            context.export_notes.append(build_path_skills_copied_note(copied, target))
+        if unresolved:
+            context.export_notes.append(build_path_skills_verify_note(unresolved, target))
+
+    if spec.get("containerUri") and render_config.build_type == "Container":
+        os.makedirs(agent_dir, exist_ok=True)
+        _write_dockerfile_stub(agent_dir, spec["containerUri"])
+
+    log("Rendering agent code")
+    try:
+        StrandsRenderer(render_config).render(RendererContext(output_dir=context.project_root))
+    except Exception as exc:  # noqa: BLE001
+        cleanup()
+        error = ExportHarnessError(f'Failed to render agent code for "{target}": {get_error_message(exc)}')
+        error.__cause__ = exc
+        return Err(error)
+
+    if render_config.build_type == "Container":
+        log("Generating uv.lock for container build")
+        try:
+            run_subprocess("uv", ["lock"], cwd=agent_dir, stdio="pipe")
+        except Exception:  # noqa: BLE001 - uv missing or failed: note it and continue
+            context.export_notes.append(
+                ExportNote(
+                    "uv.lock missing — run `uv lock` before deploying",
+                    f"The container Dockerfile requires a uv.lock file. Run `uv lock` in app/{target}/ before "
+                    "running `agentcore deploy`.",
+                )
+            )
+
+    log("Updating agentcore.json")
+    try:
+        _write_exported_agent_to_project(context, mapping)
+    except Exception as exc:  # noqa: BLE001
+        cleanup()
+        return Err(to_error(exc))
+
+    for entry in mapping.mcp_credential_entries:
+        set_env_var(entry.env_var_name, entry.value, context.config_base_dir)
+    for name, value in context.local_env_vars.items():
+        set_env_var(name, value, context.config_base_dir)
+    for file_name, policy in context.generated_policy_files.items():
+        os.makedirs(agent_dir, exist_ok=True)
+        with open(os.path.join(agent_dir, file_name), "w", encoding="utf-8") as fh:
+            fh.write(json.dumps(policy, indent=2) + "\n")
+
+    log("Writing EXPORT_NOTES.md")
+    _write_export_notes(context.export_notes, harness_name, target, agent_dir)
+
+    return Ok(
+        {
+            "agentName": target,
+            "agentPath": agent_dir,
+            "notesPath": os.path.join(agent_dir, EXPORT_NOTES_FILENAME),
+            "notes": context.export_notes,
+        }
+    )
+
+
+def resolve_export_region(arn: str) -> str | None:
+    """ARN region, else the first deployment target, else AWS_REGION / AWS_DEFAULT_REGION."""
+    region = region_from_harness_arn(arn)
+    if region:
+        return region
+    try:
+        targets = to_jsonable(ConfigIO().read_aws_deployment_targets())
+        if targets and targets[0].get("region"):
+            return targets[0]["region"]
+    except Exception:  # noqa: BLE001
+        pass
+    return os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or None
+
+
+def _write_exported_agent_to_project(context: ResolvedHarnessContext, mapping: Any) -> None:
+    config_io = ConfigIO(base_dir=context.config_base_dir)
+    project = to_jsonable(config_io.read_project_spec())
+    agent = mapping.agent_env_spec
+    if any(r["name"] == agent["name"] for r in project.get("runtimes") or []):
+        raise AgentAlreadyExistsError(agent["name"])
+    project.setdefault("runtimes", []).append(agent)
+    credentials = project.setdefault("credentials", [])
+
+    def add(credential: dict[str, Any]) -> None:
+        if not any(c["name"] == credential["name"] for c in credentials):
+            credentials.append(credential)
+
+    if mapping.credential_entry:
+        add(mapping.credential_entry)
+    for entry in mapping.mcp_credential_entries:
+        add(entry.credential)
+    for credential in mapping.git_credential_entries:
+        add(credential)
+    config_io.write_project_spec(project)
+
+
+# ============================================================================
+# Notes
+# ============================================================================
+
+
+def build_custom_dockerfile_note(dockerfile: str, target: str) -> ExportNote:
+    return ExportNote(
+        CUSTOM_DOCKERFILE_NOTE_CATEGORY,
+        f'The harness used a custom Dockerfile ("{dockerfile}") that describes its execution '
+        f"environment. It has been copied to app/{target}/{dockerfile} unchanged, but "
+        "the exported agent will NOT run as-is: a harness Dockerfile has no dependency install, code copy, or "
+        "startup command (the harness runtime supplied those). Add the Strands agent build layer to the end "
+        f"of app/{target}/{dockerfile} before `agentcore deploy` "
+        "(adjust if your base image is not Python 3.12+/uv, or already sets WORKDIR/USER). "
+        "First refresh the base image and its OS packages using the appropriate package manager, "
+        "with the privileges required by that base. Adjust the global Python path below to match "
+        "the interpreter used to install uv; retain uv if your custom application requires it at runtime:\n\n"
+        "  WORKDIR /app\n"
+        "  RUN pip install --no-cache-dir uv\n"
+        '  ENV UV_NO_CACHE=1 PATH="/app/.venv/bin:$PATH"\n'
+        "  COPY pyproject.toml uv.lock ./\n"
+        "  RUN uv sync --frozen --no-dev --no-install-project\n"
+        "  COPY --chown=bedrock_agentcore:bedrock_agentcore . .\n"
+        "  RUN uv sync --frozen --no-dev && /usr/local/bin/python -m pip uninstall -y uv\n"
+        "  USER bedrock_agentcore\n"
+        "  EXPOSE 8080 8000 9000\n"
+        '  CMD ["opentelemetry-instrument", "python", "-m", "main"]\n\n'
+        "Also ensure the build sets the runtime entrypoint to the generated main.py rather than "
+        "the harness's overridden entrypoint.",
+    )
+
+
+def build_missing_dockerfile_note(dockerfile: str, harness_name: str, target: str) -> ExportNote:
+    return ExportNote(
+        f"Dockerfile not found — create {dockerfile} before deploying",
+        f'The harness references dockerfile: "{dockerfile}" but no such file exists in '
+        f"app/{harness_name}/. Create a Dockerfile at app/{target}/{dockerfile} "
+        "before running `agentcore deploy`.",
+    )
+
+
+def build_path_skills_copied_note(paths: list[str], target: str) -> ExportNote:
+    one = len(paths) == 1
+    quoted = ", ".join(f'"{p}"' for p in paths)
+    return ExportNote(
+        PATH_SKILLS_COPIED_NOTE_CATEGORY,
+        f"The following path-skill {'directory was' if one else 'directories were'} copied into "
+        f"app/{target}/ so the generated Dockerfile's `COPY . .` step bundles {'it' if one else 'them'} "
+        f"into the image — no manual step required: {quoted}.",
+    )
+
+
+def build_path_skills_verify_note(paths: list[str], target: str) -> ExportNote:
+    one = len(paths) == 1
+    quoted = ", ".join(f'"{p}"' for p in paths)
+    return ExportNote(
+        PATH_SKILLS_VERIFY_BASE_IMAGE_NOTE_CATEGORY,
+        f"The following path {'skill was' if one else 'skills were'} not found locally under the "
+        f"harness directory, so {'it was' if one else 'they were'} NOT copied into app/{target}/: "
+        f"{quoted}. The exported agent loads {'this path' if one else 'these paths'} "
+        f"at runtime — ensure {'it exists' if one else 'they exist'} on the container filesystem (e.g. installed "
+        "in your base image or added via a Dockerfile COPY) before `agentcore deploy`.",
+    )
+
+
+def _read_strands_version(agent_dir: str) -> str:
+    try:
+        with open(os.path.join(agent_dir, "pyproject.toml"), encoding="utf-8") as fh:
+            match = re.search(r"strands-agents\s*(>=\s*[\d.]+)", fh.read())
+        return f"strands-agents {match.group(1)}" if match else "strands-agents (version unknown)"
+    except OSError:
+        return "strands-agents (version unknown)"
+
+
+def _write_export_notes(notes: list[ExportNote], harness_name: str, agent_name: str, agent_dir: str) -> None:
+    today = datetime.datetime.now(datetime.UTC).date().isoformat()
+    lines = [
+        f"# Export Notes — {harness_name} → {agent_name}",
+        "",
+        f"Exported on: {today}",
+        f"Strands version: {_read_strands_version(agent_dir)}",
+        f"Source harness: agentcore/app/{harness_name}/harness.json",
+        f"Generated agent: app/{agent_name}/",
+        "",
+    ]
+    if not notes:
+        lines.append("No manual steps required.")
+    else:
+        lines.append("## Items requiring manual follow-up")
+        for note in notes:
+            lines += ["", f"### {note.category}", note.message]
+    lines.append("")
+    with open(os.path.join(agent_dir, EXPORT_NOTES_FILENAME), "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines))
+
+
+def _write_dockerfile_stub(agent_dir: str, container_uri: str) -> None:
+    content = "\n".join(
+        [
+            f"# Base image from the source harness: {container_uri}",
+            "# The generated Strands agent is layered on top. If the base image does not",
+            "# include Python 3.12+, add install steps before the COPY/RUN below.",
+            "# Refresh the base image and its OS packages with the appropriate package manager.",
+            "# Run those updates with the privileges required by your base image.",
+            "# Adjust /usr/local/bin/python below to the global interpreter used to install uv.",
+            "# Retain uv if your custom application requires it at runtime.",
+            f"FROM {container_uri}",
+            "",
+            "RUN pip install --no-cache-dir uv",
+            "",
+            "WORKDIR /app",
+            "",
+            "ARG UV_DEFAULT_INDEX",
+            "ARG UV_INDEX",
+            "",
+            "ENV UV_SYSTEM_PYTHON=1 \\",
+            "    UV_NO_CACHE=1 \\",
+            "    UV_COMPILE_BYTECODE=1 \\",
+            "    UV_NO_PROGRESS=1 \\",
+            "    PYTHONUNBUFFERED=1 \\",
+            "    DOCKER_CONTAINER=1 \\",
+            "    UV_DEFAULT_INDEX=${UV_DEFAULT_INDEX} \\",
+            "    UV_INDEX=${UV_INDEX} \\",
+            '    PATH="/app/.venv/bin:$PATH"',
+            "",
+            "RUN useradd -m -u 1000 bedrock_agentcore",
+            "",
+            "COPY pyproject.toml uv.lock ./",
+            "RUN uv sync --frozen --no-dev --no-install-project",
+            "",
+            "COPY --chown=bedrock_agentcore:bedrock_agentcore . .",
+            "RUN uv sync --frozen --no-dev && /usr/local/bin/python -m pip uninstall -y uv",
+            "",
+            "USER bedrock_agentcore",
+            "",
+            "EXPOSE 8080 8000 9000",
+            "",
+            'CMD ["opentelemetry-instrument", "python", "-m", "main"]',
+            "",
+        ]
+    )
+    with open(os.path.join(agent_dir, "Dockerfile"), "w", encoding="utf-8") as fh:
+        fh.write(content)
+
+
+__all__ = [
+    "build_custom_dockerfile_note",
+    "build_missing_dockerfile_note",
+    "build_path_skills_copied_note",
+    "build_path_skills_verify_note",
+    "handle_export_harness",
+    "resolve_export_region",
+]