agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/export/__init__.py

@@ -0,0 +1,114 @@
+"""`agentcore export harness` (port of src/cli/commands/export/index.ts)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import typer
+
+from agentcore.cli.commands.export.harness_action import handle_export_harness
+from agentcore.cli.commands.export.types import ExportHarnessOptions, format_export_notes
+from agentcore.cli.constants import ANSI
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.groups import group
+from agentcore.lib.result import serialize_result
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+
+
+def _dumps(payload: Any) -> str:
+    return json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+
+
+def _serialize(result: Any) -> dict[str, Any]:
+    if result.success:
+        value = dict(result.value)
+        value["notes"] = [{"category": n.category, "message": n.message} for n in value["notes"]]
+        return {"success": True, **value}
+    return serialize_result(result)
+
+
+def export_harness(
+    name: str | None = typer.Option(None, "--name", help="In-project harness name [non-interactive]"),
+    arn: str | None = typer.Option(
+        None,
+        "--arn",
+        help="ARN of a harness created outside this project — fetched from the service [non-interactive]",
+    ),
+    target_agent_name: str | None = typer.Option(
+        None,
+        "--target-agent-name",
+        help="Name for the generated runtime agent (default: <harnessName>Agent) [non-interactive]",
+    ),
+    build: str | None = typer.Option(None, "--build", help="Build type: CodeZip or Container [non-interactive]"),
+    as_json: bool = typer.Option(False, "--json", help="Output results as JSON"),
+) -> None:
+    """Export a harness to a Python Strands runtime agent (in-project via --name, or by --arn)"""
+    if not find_config_root():
+        typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+        raise typer.Exit(1)
+
+    if not name and not arn:
+        if as_json:
+            typer.echo(_dumps({"success": False, "error": "--name or --arn is required in non-interactive mode"}))
+            raise typer.Exit(1)
+        from agentcore.cli import interactive
+        from agentcore.cli.commands.export.wizard import run_export_harness_wizard
+
+        interactive.require_tty()
+        run_export_harness_wizard()
+        return
+
+    green, red, cyan, dim, yellow, reset = ANSI.green, ANSI.red, ANSI.cyan, ANSI.dim, ANSI.yellow, ANSI.reset
+
+    def on_progress(message: str) -> None:
+        if not as_json:
+            typer.echo(f"{green}[done]{reset}  {message}")
+
+    try:
+        result = handle_export_harness(
+            ExportHarnessOptions(name=name, arn=arn, target_agent_name=target_agent_name, build=build, json=as_json),
+            on_progress,
+        )
+    except Exception as exc:  # noqa: BLE001
+        if as_json:
+            typer.echo(_dumps({"success": False, "error": {"message": get_error_message(exc)}}))
+        else:
+            sys.stderr.write(f"{get_error_message(exc)}\n")
+        raise typer.Exit(1) from None
+
+    if as_json:
+        typer.echo(_dumps(_serialize(result)))
+        raise typer.Exit(0 if result.success else 1)
+
+    if not result.success:
+        sys.stderr.write(f"\n{red}[error]{reset} Export failed: {get_error_message(result.error)}\n")
+        raise typer.Exit(1)
+
+    agent = result.value["agentName"]
+    typer.echo("")
+    typer.echo(f"{green}Exported harness {name or arn} → runtime agent {agent}{reset}")
+    typer.echo("")
+    typer.echo(f"{dim}Generated:{reset}")
+    typer.echo(f"  app/{agent}/    Python agent (Strands)")
+    typer.echo("  agentcore/agentcore.json  updated")
+    typer.echo("")
+    for line in format_export_notes(result.value["notes"], f"app/{agent}/EXPORT_NOTES.md"):
+        color = yellow if line.tone == "warn" else dim
+        typer.echo(f"{color}{line.text}{reset}")
+    typer.echo("")
+    typer.echo("Next steps:")
+    typer.echo("")
+    typer.echo(f"  {cyan}agentcore deploy{reset}     {dim}Deploy the new runtime agent{reset}")
+    typer.echo(f"  {cyan}agentcore dev{reset}        {dim}Run the agent locally{reset}")
+    typer.echo("")
+
+
+def register(app: typer.Typer) -> None:
+    group("export").command(
+        "harness", help="Export a harness to a Python Strands runtime agent (in-project via --name, or by --arn)"
+    )(export_harness)
+
+
+__all__ = ["export_harness", "register"]

agentcore/cli/commands/export/constants.py

@@ -0,0 +1,21 @@
+"""Port of src/cli/commands/export/constants.ts."""
+
+EXPORT_NOTES_FILENAME = "EXPORT_NOTES.md"
+
+DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant."
+
+CONTAINER_URI_NOTE_CATEGORY = "containerUri: verify Python in base image"
+CUSTOM_DOCKERFILE_NOTE_CATEGORY = "Custom harness Dockerfile needs the agent build layer"
+CONTAINER_URI_ECR_PULL_NOTE_CATEGORY = "containerUri base image requires ECR pull permission"
+ALLOWED_TOOLS_NOTE_CATEGORY = "allowedTools: per-invocation overrides dropped"
+PATH_SKILLS_NOTE_CATEGORY = "path skills require container filesystem"
+PATH_SKILLS_COPIED_NOTE_CATEGORY = "path skills copied into agent directory"
+PATH_SKILLS_VERIFY_BASE_IMAGE_NOTE_CATEGORY = "path skill not found locally — verify it exists in the base image"
+MCP_HEADER_CREDS_NOTE_CATEGORY = "MCP tool header credentials"
+GIT_SKILLS_CONTAINER_NOTE_CATEGORY = "git skills require git in container image"
+GATEWAY_GRANT_TYPE_NOTE_CATEGORY = "Gateway OAuth grant type not supported by generated client (M2M only)"
+BROWSER_CODZIP_NOTE_CATEGORY = "Browser tool requires Container build — excluded from CodeZip export"
+AWS_SKILLS_NOTE_CATEGORY = "AWS skills omitted — not available outside managed harness"
+MALFORMED_TOOL_ARN_NOTE_CATEGORY = "Browser/code-interpreter ARN is malformed — using AWS-managed default"
+MALFORMED_S3_SKILL_NOTE_CATEGORY = "S3 skill URI is malformed — no S3 read permission generated"
+LITELLM_NO_API_KEY_NOTE_CATEGORY = "LiteLLM model may require an API key"

agentcore/cli/commands/export/fetch_harness_spec.py

@@ -0,0 +1,234 @@
+"""Fetch a harness by ARN and map it to a local HarnessSpec (port of fetch-harness-spec.ts)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from agentcore.lib.errors.types import ValidationError
+
+
+def fetch_harness_spec_by_arn(arn: str, region: str) -> dict[str, Any]:
+    """Returns ``{"spec": <camelCase HarnessSpec>, "systemPrompt": str | None}``."""
+    from agentcore.aws.agentcore_harness import get_harness
+    from agentcore.schema import is_container_build
+
+    harness_id = harness_id_from_arn(arn)
+    harness = get_harness(region=region, harness_id=harness_id)["harness"]
+    result = map_api_harness_to_spec(harness)
+    spec = result["spec"]
+    nc = spec.get("networkConfig")
+    if (
+        is_container_build(spec)
+        and spec.get("networkMode") == "VPC"
+        and nc
+        and nc.get("subnets")
+        and not nc.get("vpcId")
+    ):
+        from agentcore.cli.commands.shared.vpc_utils import resolve_vpc_id_from_subnets
+
+        nc["vpcId"] = resolve_vpc_id_from_subnets(nc["subnets"], region)
+    return result
+
+
+def harness_id_from_arn(arn: str) -> str:
+    match = re.search(r":harness/([^/]+)$", arn)
+    if not match:
+        raise ValidationError(f'"{arn}" is not a valid harness ARN (expected …:harness/<id>).')
+    return match.group(1)
+
+
+def _clean(obj: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in obj.items() if v is not None}
+
+
+def map_api_harness_to_spec(harness: dict[str, Any]) -> dict[str, Any]:
+    model = _map_model(harness.get("model"))
+    joined = (
+        "\n".join(b.get("text", "") for b in harness.get("systemPrompt") or [])
+        if harness.get("systemPrompt") is not None
+        else None
+    )
+    system_prompt = joined if joined else None
+
+    spec: dict[str, Any] = {"name": harness.get("harnessName"), "model": model}
+    if system_prompt:
+        spec["systemPrompt"] = system_prompt
+    spec["tools"] = [_map_tool(t) for t in harness.get("tools") or []]
+    spec["skills"] = [_map_skill(s) for s in harness.get("skills") or []]
+    if harness.get("allowedTools") is not None:
+        spec["allowedTools"] = harness["allowedTools"]
+    memory = _map_memory(harness["memory"]) if harness.get("memory") is not None else None
+    if memory:
+        spec["memory"] = memory
+    for key in ("maxIterations", "maxTokens", "timeoutSeconds"):
+        if harness.get(key) is not None:
+            spec[key] = harness[key]
+    container_uri = ((harness.get("environmentArtifact") or {}).get("containerConfiguration") or {}).get("containerUri")
+    if container_uri:
+        spec["containerUri"] = container_uri
+    # The harness's executionRoleArn is deliberately NOT carried: the exported agent gets its own role.
+    if harness.get("environmentVariables") is not None:
+        spec["environmentVariables"] = harness["environmentVariables"]
+    if harness.get("tags") is not None:
+        spec["tags"] = harness["tags"]
+    if harness.get("truncation") is not None:
+        spec["truncation"] = harness["truncation"]
+    spec.update(_map_runtime_environment((harness.get("environment") or {}).get("agentCoreRuntimeEnvironment")))
+    return {"spec": spec, "systemPrompt": system_prompt}
+
+
+def _map_model(model: dict[str, Any] | None) -> dict[str, Any]:
+    model = model or {}
+    if model.get("bedrockModelConfig"):
+        c = model["bedrockModelConfig"]
+        return _clean(
+            {
+                "provider": "bedrock",
+                "modelId": c.get("modelId"),
+                "apiFormat": c.get("apiFormat"),
+                "temperature": c.get("temperature"),
+                "topP": c.get("topP"),
+                "maxTokens": c.get("maxTokens"),
+            }
+        )
+    if model.get("openAiModelConfig"):
+        c = model["openAiModelConfig"]
+        return _clean(
+            {
+                "provider": "open_ai",
+                "modelId": c.get("modelId"),
+                "apiKeyArn": c.get("apiKeyArn"),
+                "apiFormat": c.get("apiFormat"),
+                "temperature": c.get("temperature"),
+                "topP": c.get("topP"),
+                "maxTokens": c.get("maxTokens"),
+            }
+        )
+    if model.get("geminiModelConfig"):
+        c = model["geminiModelConfig"]
+        return _clean(
+            {
+                "provider": "gemini",
+                "modelId": c.get("modelId"),
+                "apiKeyArn": c.get("apiKeyArn"),
+                "temperature": c.get("temperature"),
+                "topP": c.get("topP"),
+                "topK": c.get("topK"),
+                "maxTokens": c.get("maxTokens"),
+            }
+        )
+    if model.get("liteLlmModelConfig"):
+        c = model["liteLlmModelConfig"]
+        return _clean(
+            {
+                "provider": "lite_llm",
+                "modelId": c.get("modelId"),
+                "apiKeyArn": c.get("apiKeyArn"),
+                "apiBase": c.get("apiBase"),
+                "temperature": c.get("temperature"),
+                "topP": c.get("topP"),
+                "maxTokens": c.get("maxTokens"),
+                "additionalParams": c.get("additionalParams"),
+            }
+        )
+    raise ValidationError("Fetched harness has no recognized model configuration.")
+
+
+def _map_tool(tool: dict[str, Any]) -> dict[str, Any]:
+    out = _clean({"type": tool.get("type"), "name": tool.get("name")})
+    if tool.get("config"):
+        out["config"] = tool["config"]
+    return out
+
+
+def _map_skill(skill: dict[str, Any]) -> dict[str, Any]:
+    s3 = skill.get("S3") or skill.get("s3")
+    s3_uri = (s3 or {}).get("Uri") or (s3 or {}).get("uri") if isinstance(s3, dict) else None
+    s3_uri = s3_uri or skill.get("s3Uri")
+    if s3_uri:
+        return {"s3Uri": s3_uri}
+    git = skill.get("Git") or skill.get("git")
+    git = git if isinstance(git, dict) else {}
+    git_url = git.get("Url") or git.get("url") or skill.get("gitUrl")
+    if git_url:
+        path = git.get("Path") or git.get("path") or skill.get("path")
+        auth = git.get("Auth") or git.get("auth") or skill.get("auth") or {}
+        out: dict[str, Any] = {"gitUrl": git_url}
+        if path:
+            out["path"] = path
+        credential = auth.get("credentialArn")
+        if credential:
+            out["auth"] = (
+                {"credentialName": credential, "username": auth["username"]}
+                if auth.get("username")
+                else {"credentialName": credential}
+            )
+        return out
+    path = skill.get("Path") or skill.get("path")
+    if path:
+        return {"path": path}
+    return skill
+
+
+def _map_memory(memory: dict[str, Any]) -> dict[str, Any] | None:
+    byo = memory.get("agentCoreMemoryConfiguration") or {}
+    if byo.get("arn"):
+        return _clean(
+            {
+                "mode": "existing",
+                "arn": byo["arn"],
+                "actorId": byo.get("actorId"),
+                "messagesCount": byo.get("messagesCount"),
+            }
+        )
+    managed_arn = (memory.get("managedMemoryConfiguration") or {}).get("arn")
+    if managed_arn:
+        return {"mode": "existing", "arn": managed_arn}
+    unknown = memory.get("SDK_UNKNOWN_MEMBER") or {}
+    if "managedMemoryConfiguration" in memory or unknown.get("name") == "managedMemoryConfiguration":
+        return {"mode": "managed"}
+    return None
+
+
+def _map_runtime_environment(env: dict[str, Any] | None) -> dict[str, Any]:
+    if not env:
+        return {}
+    out: dict[str, Any] = {}
+    net = env.get("networkConfiguration") or {}
+    if net.get("networkMode") == "VPC":
+        cfg = net.get("networkModeConfig") or {}
+        subnets, security_groups = cfg.get("subnets"), cfg.get("securityGroups")
+        if not subnets or not security_groups:
+            raise ValidationError(
+                "This harness runs in a VPC but its network configuration is missing explicit subnets and/or "
+                "security groups, which the exported agent requires. Re-create the harness with explicit VPC "
+                "subnets and security groups, or export a non-VPC harness."
+            )
+        out["networkMode"] = "VPC"
+        out["networkConfig"] = {"subnets": subnets, "securityGroups": security_groups}
+    lc = env.get("lifecycleConfiguration") or {}
+    if lc.get("idleRuntimeSessionTimeout") is not None or lc.get("maxLifetime") is not None:
+        out["lifecycleConfig"] = _clean(
+            {"idleRuntimeSessionTimeout": lc.get("idleRuntimeSessionTimeout"), "maxLifetime": lc.get("maxLifetime")}
+        )
+    efs: list[dict[str, str]] = []
+    s3: list[dict[str, str]] = []
+    for fs in env.get("filesystemConfigurations") or []:
+        session = fs.get("sessionStorage") or {}
+        efs_ap = fs.get("efsAccessPoint") or {}
+        s3_ap = fs.get("s3FilesAccessPoint") or {}
+        if session.get("mountPath"):
+            out["sessionStoragePath"] = session["mountPath"]
+        elif efs_ap.get("accessPointArn") and efs_ap.get("mountPath"):
+            efs.append({"accessPointArn": efs_ap["accessPointArn"], "mountPath": efs_ap["mountPath"]})
+        elif s3_ap.get("accessPointArn") and s3_ap.get("mountPath"):
+            s3.append({"accessPointArn": s3_ap["accessPointArn"], "mountPath": s3_ap["mountPath"]})
+    if efs:
+        out["efsAccessPoints"] = efs
+    if s3:
+        out["s3AccessPoints"] = s3
+    return out
+
+
+__all__ = ["fetch_harness_spec_by_arn", "harness_id_from_arn", "map_api_harness_to_spec"]