@aws/agentcore 1.0.0-preview.9 → 1.0.0-rc.3

package/dist/assets/templates/export-harness-python/model/load.py

@@ -0,0 +1,249 @@
+{{#if (eq modelProvider "Bedrock")}}
+{{#if bedrockMantle}}
+import os
+
+from aws_bedrock_token_generator import provide_token
+{{#if (eq mantleApiFormat "chat_completions")}}
+from strands.models.openai import OpenAIModel
+{{else}}
+{{#if mantleProprietary}}
+from strands.models.openai_responses import OpenAIResponsesModel
+{{else}}
+from model.mantle_compat import MantleCompatResponsesModel
+{{/if}}
+{{/if}}
+
+MODEL_ID = "{{modelId}}"
+
+
+def load_model():
+    """
+    Get a Bedrock Mantle model client. These OpenAI-compatible models (e.g. openai.gpt-5.5,
+    openai.gpt-oss-120b) are served via the Bedrock Mantle endpoint, NOT the Converse API — so they
+    are invoked through an OpenAI-style client authenticated with a short-lived Bedrock bearer token.
+    Region is read from AWS_REGION (set by the AgentCore runtime).
+    """
+    region = os.environ.get("AWS_REGION", os.environ.get("AWS_DEFAULT_REGION", "us-east-1"))
+    token = provide_token(region=region)
+    {{#if mantleProprietary}}
+    # Proprietary OpenAI models only work on the /openai/v1 Mantle path.
+    base_url = f"https://bedrock-mantle.{region}.api.aws/openai/v1"
+    {{else}}
+    # Open-source OpenAI models (gpt-oss-*) only work on the /v1 Mantle path.
+    base_url = f"https://bedrock-mantle.{region}.api.aws/v1"
+    {{/if}}
+    client_args = {"api_key": token, "base_url": base_url}
+
+    params = {}
+    {{#if modelMaxTokens}}
+    {{#if (eq mantleApiFormat "chat_completions")}}
+    params["max_completion_tokens"] = {{modelMaxTokens}}
+    {{else}}
+    params["max_output_tokens"] = {{modelMaxTokens}}
+    {{/if}}
+    {{/if}}
+    {{#if modelTemperature}}
+    params["temperature"] = {{modelTemperature}}
+    {{/if}}
+    {{#if modelTopP}}
+    params["top_p"] = {{modelTopP}}
+    {{/if}}
+    {{#if (eq mantleApiFormat "chat_completions")}}
+    return OpenAIModel(client_args=client_args, model_id=MODEL_ID, params=params)
+    {{else}}
+    # Responses API: Mantle does not persist responses, so disable server-side storage.
+    params["store"] = False
+    {{#if mantleProprietary}}
+    return OpenAIResponsesModel(client_args=client_args, model_id=MODEL_ID, params=params)
+    {{else}}
+    return MantleCompatResponsesModel(client_args=client_args, model_id=MODEL_ID, params=params)
+    {{/if}}
+    {{/if}}
+{{else}}
+from strands.models.bedrock import BedrockModel
+
+
+def load_model() -> BedrockModel:
+    """Get Bedrock model client using IAM credentials."""
+    return BedrockModel(
+        model_id="{{#if modelId}}{{modelId}}{{else}}global.anthropic.claude-sonnet-4-5-20250929-v1:0{{/if}}",
+{{#if modelMaxTokens}}
+        max_tokens={{modelMaxTokens}},
+{{/if}}
+{{#if modelTemperature}}
+        temperature={{modelTemperature}},
+{{/if}}
+{{#if modelTopP}}
+        top_p={{modelTopP}},
+{{/if}}
+    )
+{{/if}}
+{{/if}}
+{{#if (eq modelProvider "OpenAI")}}
+import os
+
+{{#if (eq modelApiFormat "responses")}}
+from strands.models.openai_responses import OpenAIResponsesModel
+{{else}}
+from strands.models.openai import OpenAIModel
+{{/if}}
+from bedrock_agentcore.identity.auth import requires_api_key
+
+IDENTITY_PROVIDER_NAME = os.environ.get("{{identityProviders.[0].envVarName}}_NAME", "{{identityProviders.[0].name}}")
+IDENTITY_ENV_VAR = "{{identityProviders.[0].envVarName}}"
+
+
+@requires_api_key(provider_name=IDENTITY_PROVIDER_NAME)
+def _agentcore_identity_api_key_provider(api_key: str) -> str:
+    """Fetch API key from AgentCore Identity."""
+    return api_key
+
+
+def _get_api_key() -> str:
+    """
+    Uses AgentCore Identity for API key management in deployed environments.
+    For local development, run via 'agentcore dev' which loads agentcore/.env.
+    """
+    if os.getenv("LOCAL_DEV") == "1":
+        api_key = os.getenv(IDENTITY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
+            )
+        return api_key
+    return _agentcore_identity_api_key_provider()
+
+
+def load_model():
+    """Get authenticated OpenAI model client."""
+    params = {}
+    {{#if modelMaxTokens}}
+    params["{{#if (eq modelApiFormat "responses")}}max_output_tokens{{else}}max_completion_tokens{{/if}}"] = {{modelMaxTokens}}
+    {{/if}}
+    {{#if modelTemperature}}
+    params["temperature"] = {{modelTemperature}}
+    {{/if}}
+    {{#if modelTopP}}
+    params["top_p"] = {{modelTopP}}
+    {{/if}}
+    return {{#if (eq modelApiFormat "responses")}}OpenAIResponsesModel{{else}}OpenAIModel{{/if}}(
+        client_args={"api_key": _get_api_key()},
+        model_id="{{#if modelId}}{{modelId}}{{else}}gpt-4.1{{/if}}",
+        params=params,
+    )
+{{/if}}
+{{#if (eq modelProvider "Gemini")}}
+import os
+
+from strands.models.gemini import GeminiModel
+from bedrock_agentcore.identity.auth import requires_api_key
+
+IDENTITY_PROVIDER_NAME = os.environ.get("{{identityProviders.[0].envVarName}}_NAME", "{{identityProviders.[0].name}}")
+IDENTITY_ENV_VAR = "{{identityProviders.[0].envVarName}}"
+
+
+@requires_api_key(provider_name=IDENTITY_PROVIDER_NAME)
+def _agentcore_identity_api_key_provider(api_key: str) -> str:
+    """Fetch API key from AgentCore Identity."""
+    return api_key
+
+
+def _get_api_key() -> str:
+    """
+    Uses AgentCore Identity for API key management in deployed environments.
+    For local development, run via 'agentcore dev' which loads agentcore/.env.
+    """
+    if os.getenv("LOCAL_DEV") == "1":
+        api_key = os.getenv(IDENTITY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
+            )
+        return api_key
+    return _agentcore_identity_api_key_provider()
+
+
+def load_model() -> GeminiModel:
+    """Get authenticated Gemini model client."""
+    params = {}
+    {{#if modelMaxTokens}}
+    params["max_output_tokens"] = {{modelMaxTokens}}
+    {{/if}}
+    {{#if modelTemperature}}
+    params["temperature"] = {{modelTemperature}}
+    {{/if}}
+    {{#if modelTopP}}
+    params["top_p"] = {{modelTopP}}
+    {{/if}}
+    {{#if modelTopK}}
+    params["top_k"] = {{modelTopK}}
+    {{/if}}
+    return GeminiModel(
+        client_args={"api_key": _get_api_key()},
+        model_id="{{#if modelId}}{{modelId}}{{else}}gemini-2.5-flash{{/if}}",
+        params=params,
+    )
+{{/if}}
+{{#if (eq modelProvider "LiteLLM")}}
+import os
+{{#if litellmAdditionalParams}}
+import json
+{{/if}}
+
+from strands.models.litellm import LiteLLMModel
+{{#if identityProviders.[0].name}}
+from bedrock_agentcore.identity.auth import requires_api_key
+
+IDENTITY_PROVIDER_NAME = os.environ.get("{{identityProviders.[0].envVarName}}_NAME", "{{identityProviders.[0].name}}")
+IDENTITY_ENV_VAR = "{{identityProviders.[0].envVarName}}"
+
+
+@requires_api_key(provider_name=IDENTITY_PROVIDER_NAME)
+def _agentcore_identity_api_key_provider(api_key: str) -> str:
+    """Fetch API key from AgentCore Identity."""
+    return api_key
+
+
+def _get_api_key() -> str:
+    """
+    Uses AgentCore Identity for API key management in deployed environments.
+    For local development, run via 'agentcore dev' which loads agentcore/.env.
+    """
+    if os.getenv("LOCAL_DEV") == "1":
+        api_key = os.getenv(IDENTITY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
+            )
+        return api_key
+    return _agentcore_identity_api_key_provider()
+{{/if}}
+
+
+
+
+def load_model() -> LiteLLMModel:
+    """Get a LiteLLM model client (proxies to the provider encoded in model_id)."""
+    client_args = {}
+    {{#if identityProviders.[0].name}}
+    client_args["api_key"] = _get_api_key()
+    {{/if}}
+    {{#if litellmApiBase}}
+    client_args["api_base"] = {{safeJson litellmApiBase}}
+    {{/if}}
+    params = {{#if litellmAdditionalParams}}json.loads({{pyJsonStr litellmAdditionalParams}}){{else}}{}{{/if}}
+    {{#if modelMaxTokens}}
+    params["max_tokens"] = {{modelMaxTokens}}
+    {{/if}}
+    {{#if modelTemperature}}
+    params["temperature"] = {{modelTemperature}}
+    {{/if}}
+    {{#if modelTopP}}
+    params["top_p"] = {{modelTopP}}
+    {{/if}}
+    return LiteLLMModel(
+        client_args=client_args,
+        model_id="{{#if modelId}}{{modelId}}{{else}}bedrock/us.anthropic.claude-sonnet-4-5-20250514-v1:0{{/if}}",
+        params=params,
+    )
+{{/if}}

package/dist/assets/templates/export-harness-python/model/mantle_compat.py

@@ -0,0 +1,21 @@
+from strands.models.openai_responses import OpenAIResponsesModel
+
+
+class MantleCompatResponsesModel(OpenAIResponsesModel):
+    """Workaround for Bedrock Mantle rejecting output_text in EasyInputMessage content arrays.
+
+    Mantle's Pydantic validation only accepts content as a plain string for assistant messages, while
+    real OpenAI accepts both formats. Flatten assistant content arrays to strings so multi-turn works.
+    Used for open-source OpenAI models (gpt-oss-*) on the /v1 Mantle path; proprietary models use the
+    plain OpenAIResponsesModel on /openai/v1.
+    """
+
+    @classmethod
+    def _format_request_messages(cls, messages):
+        formatted = super()._format_request_messages(messages)
+        for msg in formatted:
+            if msg.get("role") == "assistant" and isinstance(msg.get("content"), list):
+                msg["content"] = "".join(
+                    part.get("text", "") for part in msg["content"] if part.get("type") == "output_text"
+                )
+        return formatted

package/dist/assets/templates/export-harness-python/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling ~= 1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "AgentCore Runtime Application using Strands SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "aws-opentelemetry-distro ~= 0.18.0",
+    "bedrock-agentcore ~= 1.9.1",
+    "botocore[crt] ~= 1.43.0",
+    "mcp >= 1.23.0, < 2.0.0",
+    {{#if bedrockMantle}}"aws-bedrock-token-generator >= 1.1.0, < 2.0.0",
+    {{/if}}"strands-agents{{#if strandsExtras}}[{{strandsExtras}}]{{/if}} ~= 1.54.0",
+    
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

package/dist/assets/templates/export-harness-python/skills/fetcher.py

@@ -0,0 +1,279 @@
+"""Skill fetcher — downloads s3/git skills to local filesystem on first use.
+
+Resolved paths are passed to AgentSkills(skills=...) in main.py.
+Cache directory: <tmpdir>/.agents/skills/ — an absolute path under the system temp
+directory (honors $TMPDIR, defaults to /tmp). The runtime working directory (e.g.
+/var/task in a CodeZip runtime) is read-only, so the cache must live somewhere
+guaranteed-writable.
+"""
+
+import base64
+import hashlib
+import json
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_SKILLS_BASE = Path(tempfile.gettempdir()) / ".agents" / "skills"
+_GIT_TIMEOUT = 60
+_S3_MAX_SIZE_BYTES = 1 * 1024 * 1024 * 1024  # 1 GB
+
+
+def _stable_hash(value: str) -> str:
+    return hashlib.sha256(value.encode()).hexdigest()[:12]
+
+
+def _cleanup(path: Path) -> None:
+    """Remove a partially-created skill directory so retries don't see stale state."""
+    shutil.rmtree(path, ignore_errors=True)
+
+
+def _read_map(type_dir: Path) -> dict:
+    map_file = type_dir / ".map.json"
+    return json.loads(map_file.read_text()) if map_file.exists() else {}
+
+
+def _write_map(type_dir: Path, mapping: dict) -> None:
+    type_dir.mkdir(parents=True, exist_ok=True)
+    (type_dir / ".map.json").write_text(json.dumps(mapping))
+
+
+def _resolve_cached(type_dir: Path, source_hash: str) -> Optional[str]:
+    """Return the cached skill directory for a source hash, or None if not on disk."""
+    mapping = _read_map(type_dir)
+    dir_name = mapping.get(source_hash)
+    if dir_name and (type_dir / dir_name).exists():
+        return str(type_dir / dir_name)
+    return None
+
+
+def _read_skill_name(skill_dir: Path) -> str:
+    """Extract the skill name from SKILL.md YAML frontmatter."""
+    content = (skill_dir / "SKILL.md").read_text()
+    if not content.startswith("---"):
+        raise ValueError(f"SKILL.md in {skill_dir} has no YAML frontmatter (must start with ---)")
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        raise ValueError(f"SKILL.md in {skill_dir} has malformed frontmatter (missing closing ---)")
+    for line in parts[1].strip().splitlines():
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip("\"'")
+            if name:
+                return name
+    raise ValueError(f"SKILL.md in {skill_dir} is missing a 'name' field in frontmatter")
+
+
+def _pick_dir_name(type_dir: Path, name: str, source_hash: str) -> str:
+    """Pick a unique directory name, appending a hash suffix on collision."""
+    if not (type_dir / name).exists():
+        return name
+    return f"{name}-{source_hash[:8]}"
+
+
+def _rename_and_cache_skill(type_dir: Path, temp_dir: Path, source_hash: str, skill_root: Path,
+                            source_label: str = "") -> Path:
+    """Validate SKILL.md, rename the temp dir to the skill's declared name, and update the map.
+
+    Raises ValueError if SKILL.md is missing or has invalid frontmatter.
+    """
+    if not (skill_root / "SKILL.md").exists():
+        _cleanup(temp_dir)
+        hint = f" (source: {source_label})" if source_label else ""
+        raise ValueError(f"No SKILL.md found in fetched skill{hint}")
+
+    name = _read_skill_name(skill_root)
+    dir_name = _pick_dir_name(type_dir, name, source_hash)
+    final_dir = type_dir / dir_name
+    if final_dir != temp_dir:
+        temp_dir.rename(final_dir)
+
+    mapping = _read_map(type_dir)
+    mapping[source_hash] = dir_name
+    _write_map(type_dir, mapping)
+    return final_dir
+
+
+def _fetch_s3_skill(source: str, s3_client=None) -> Path:
+    """Download an s3:// skill prefix and return the local directory."""
+    uri = source if source.endswith("/") else source + "/"
+    source_hash = _stable_hash(uri)
+    type_dir = _SKILLS_BASE / "s3"
+
+    cached = _resolve_cached(type_dir, source_hash)
+    if cached:
+        return Path(cached)
+
+    import boto3
+    client = s3_client or boto3.client("s3")
+    bucket, _, prefix = uri[len("s3://"):].partition("/")
+    if not bucket:
+        raise ValueError(f"Invalid S3 URI (no bucket): {uri}")
+
+    temp_dir = type_dir / source_hash
+    _cleanup(temp_dir)
+    temp_dir.mkdir(parents=True, exist_ok=True)
+    temp_root = temp_dir.resolve()
+
+    paginator = client.get_paginator("list_objects_v2")
+    total = 0
+    for page in paginator.paginate(Bucket=bucket, Prefix=prefix):
+        for obj in page.get("Contents", []):
+            total += obj["Size"]
+            if total > _S3_MAX_SIZE_BYTES:
+                _cleanup(temp_dir)
+                raise ValueError(f"S3 skill {uri} exceeds 1 GB size limit")
+            rel = obj["Key"][len(prefix):].lstrip("/")
+            if not rel:
+                continue
+            dest = (temp_dir / rel).resolve()
+            if dest != temp_root and not str(dest).startswith(str(temp_root) + os.sep):
+                _cleanup(temp_dir)
+                raise ValueError(f"Path traversal detected in S3 key: {obj['Key']}")
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            client.download_file(bucket, obj["Key"], str(dest))
+
+    if total == 0:
+        _cleanup(temp_dir)
+        raise ValueError(f"No files found at S3 URI: {uri}")
+
+    return _rename_and_cache_skill(type_dir, temp_dir, source_hash, temp_dir, source_label=uri)
+
+
+def _resolve_credential_arn(credential_arn: str, identity_client) -> str:
+    """Resolve a Token Vault API-key credential ARN to its secret value via AgentCore Identity.
+
+    ARN format: arn:<p>:bedrock-agentcore:<region>:<account>:token-vault/<vault>/apikeycredentialprovider/<name>
+    """
+    from bedrock_agentcore.runtime.context import BedrockAgentCoreContext  # noqa: PLC0415
+
+    provider_name = credential_arn.rsplit("/", 1)[-1]
+    if not provider_name:
+        raise ValueError(f"Invalid credential ARN: {credential_arn}")
+    workload_token = BedrockAgentCoreContext.get_workload_access_token()
+    if not workload_token:
+        raise ValueError("Credential ARN resolution requires a workload access token")
+    api_key = identity_client.dp_client.get_resource_api_key(
+        resourceCredentialProviderName=provider_name,
+        workloadIdentityToken=workload_token,
+    )["apiKey"]
+    if not api_key:
+        raise ValueError(f"Identity returned empty API key for provider: {provider_name}")
+    return api_key
+
+
+def _build_git_auth_env(credential_arn: Optional[str], username: Optional[str], identity_client=None) -> dict:
+    """Build GIT_CONFIG_* env vars for HTTP Basic auth using a Token Vault credential ARN.
+
+    Uses env vars instead of -c args to avoid leaking credentials in /proc/*/cmdline,
+    and so auth propagates to sub-commands (e.g. sparse-checkout triggering a fetch).
+    """
+    if not credential_arn or not identity_client:
+        return {}
+    password = _resolve_credential_arn(credential_arn, identity_client)
+    user = username or "oauth2"
+    encoded = base64.b64encode(f"{user}:{password}".encode()).decode()
+    return {
+        "GIT_CONFIG_COUNT": "1",
+        "GIT_CONFIG_KEY_0": "http.extraHeader",
+        "GIT_CONFIG_VALUE_0": f"Authorization: Basic {encoded}",
+    }
+
+
+def _fetch_git_skill(url: str, skill_path: str = "", credential_arn: Optional[str] = None,
+                     username: Optional[str] = None, identity_client=None) -> Path:
+    """Shallow-clone a git skill repository and return the local skill directory.
+
+    Returns the directory containing SKILL.md (the subdir itself for sparse checkouts).
+    """
+    if skill_path and (os.path.isabs(skill_path) or ".." in Path(skill_path).parts):
+        raise ValueError(f"Path traversal detected in skill path: {skill_path}")
+
+    source_hash = _stable_hash(f"{url}:{skill_path}")
+    type_dir = _SKILLS_BASE / "git"
+
+    cached = _resolve_cached(type_dir, source_hash)
+    if cached:
+        return Path(cached) / skill_path if skill_path else Path(cached)
+
+    temp_dir = type_dir / source_hash
+    _cleanup(temp_dir)
+    temp_dir.mkdir(parents=True, exist_ok=True)
+
+    extra_env = _build_git_auth_env(credential_arn, username, identity_client)
+    git_env = {**os.environ, **extra_env} if extra_env else None
+
+    try:
+        if skill_path:
+            subprocess.run(
+                ["git", "clone", "--depth", "1", "--filter=blob:none", "--sparse", url, str(temp_dir)],
+                check=True, timeout=_GIT_TIMEOUT, capture_output=True, env=git_env,
+            )
+            subprocess.run(
+                ["git", "sparse-checkout", "set", skill_path],
+                check=True, timeout=_GIT_TIMEOUT, capture_output=True, cwd=str(temp_dir), env=git_env,
+            )
+        else:
+            subprocess.run(
+                ["git", "clone", "--depth", "1", url, str(temp_dir)],
+                check=True, timeout=_GIT_TIMEOUT, capture_output=True, env=git_env,
+            )
+    except Exception:
+        _cleanup(temp_dir)
+        raise
+
+    if skill_path and not (temp_dir / skill_path).exists():
+        _cleanup(temp_dir)
+        raise ValueError(f"Skill path '{skill_path}' not found in repository '{url}'")
+
+    # SKILL.md lives inside the subdir for sparse checkouts.
+    skill_root = temp_dir / skill_path if skill_path else temp_dir
+    label = f"{url}:{skill_path}" if skill_path else url
+    final_dir = _rename_and_cache_skill(type_dir, temp_dir, source_hash, skill_root, source_label=label)
+    return final_dir / skill_path if skill_path else final_dir
+
+
+def resolve_s3_skills(sources: list, s3_client=None) -> list:
+    """Resolve s3:// skill URIs to local filesystem paths.
+
+    Any fetch failure raises and fails the invocation — a partial skill set
+    would silently run the agent without capabilities the harness declared.
+    """
+    paths = []
+    for uri in sources:
+        try:
+            skill_dir = _fetch_s3_skill(uri, s3_client)
+        except Exception as e:
+            raise ValueError(f"Failed to resolve S3 skill '{uri}': {e}") from e
+        paths.append(str(skill_dir.resolve()))
+    return paths
+
+
+def resolve_git_skills(sources: list, identity_client=None) -> list:
+    """Resolve git skill dicts to local filesystem paths.
+
+    Each source is a dict with keys: url (required), path (optional),
+    credentialArn (optional), username (optional).
+
+    Any fetch failure raises and fails the invocation — a partial skill set
+    would silently run the agent without capabilities the harness declared.
+    """
+    paths = []
+    for source in sources:
+        try:
+            skill_dir = _fetch_git_skill(
+                url=source["url"],
+                skill_path=source.get("path") or "",
+                credential_arn=source.get("credentialArn"),
+                username=source.get("username"),
+                identity_client=identity_client,
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to resolve git skill '{source.get('url', source)}': {e}") from e
+        paths.append(str(skill_dir.resolve()))
+    return paths