agentcore-cli 0.31.1__py3-none-any.whl

agentcore/templates/llm_context/aws-targets.ts

@@ -0,0 +1,51 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * READ-ONLY LLM CONTEXT - Do not edit this file.
+ *
+ * JSON File: agentcore/aws-targets.json
+ * Purpose: AWS deployment targets for AgentCore resources
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOT SCHEMA: AwsDeploymentTargets (array)
+// ─────────────────────────────────────────────────────────────────────────────
+
+// The JSON file contains an array of deployment targets.
+// Target names must be unique within the array.
+type AwsDeploymentTargets = AwsDeploymentTarget[];
+
+interface AwsDeploymentTarget {
+  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9-]*$ @min 1 @max 64 - unique identifier
+  description?: string; // @max 256
+  account: string; // @regex ^[0-9]{12}$ - AWS account ID (exactly 12 digits)
+  region: AgentCoreRegion;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SUPPORTED REGIONS
+// https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html
+// ─────────────────────────────────────────────────────────────────────────────
+
+type AgentCoreRegion =
+  | 'ap-northeast-1'
+  | 'ap-northeast-2'
+  | 'ap-south-1'
+  | 'ap-south-2'
+  | 'ap-southeast-1'
+  | 'ap-southeast-2'
+  | 'ap-southeast-5'
+  | 'ap-southeast-7'
+  | 'ca-central-1'
+  | 'eu-central-1'
+  | 'eu-north-1'
+  | 'eu-south-1'
+  | 'eu-south-2'
+  | 'eu-west-1'
+  | 'eu-west-2'
+  | 'eu-west-3'
+  | 'sa-east-1'
+  | 'us-east-1'
+  | 'us-east-2'
+  | 'us-west-1'
+  | 'us-west-2'
+  | 'us-gov-west-1';

agentcore/templates/profiles.py

@@ -0,0 +1,151 @@
+"""Per-framework template profiles (port of ``profiles.ts`` and ``bmaProfile.ts``).
+
+A profile states what a framework template needs from the CLI. The commands, the wizard, and the
+schema mapper read it, so they need no check for a specific framework.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, TypedDict
+
+from agentcore.schema import BuildType, ModelProvider, TargetLanguage
+
+
+class RequiredOptions(TypedDict, total=False):
+    memory: str
+    build: BuildType
+    language: TargetLanguage
+
+
+class DefaultOptions(TypedDict, total=False):
+    modelProvider: ModelProvider
+
+
+@dataclass
+class TemplateRuntimeProfile:
+    # The Dockerfile path under codeLocation.
+    dockerfile: str
+    idle_runtime_session_timeout: int
+    max_lifetime: int
+    # Policy files under codeLocation, or managed policy ARNs, for the execution role.
+    additional_policies: list[str] | None = None
+    tags: dict[str, str] | None = None
+
+
+@dataclass
+class TemplateProfile:
+    # Options the template needs; `create` and `add` fill them in and reject other values.
+    required_options: RequiredOptions = field(default_factory=lambda: RequiredOptions())
+    # Options `create` and `add` fill in when the user does not give them.
+    default_options: DefaultOptions = field(default_factory=lambda: DefaultOptions())
+    # Main file under the agent directory; the default is main.py.
+    entrypoint: str | None = None
+    # `add agent` accepts only `--type create`.
+    create_only: bool = False
+    # False when the runtime runs no model, so the CLI neither asks for nor shows one.
+    uses_model: bool = True
+    # False when the image installs the Python dependencies, so the CLI sets up no local venv.
+    setup_python_venv: bool = True
+    # Runtime settings the template needs; user-supplied values win.
+    runtime: TemplateRuntimeProfile | None = None
+
+
+# Mantle runs Codex and calls into the runtime, so the runtime runs no model or memory. The image
+# installs its Python dependencies at build time. The runtime has no session storage, so the same
+# settings work on microVM and on a capacity provider.
+BMA_TEMPLATE_PROFILE = TemplateProfile(
+    required_options={"memory": "none", "build": "Container", "language": "Python"},
+    default_options={"modelProvider": "Bedrock"},
+    entrypoint="lifecycle/server.py",
+    create_only=True,
+    uses_model=False,
+    setup_python_venv=False,
+    runtime=TemplateRuntimeProfile(
+        dockerfile="Dockerfile",
+        idle_runtime_session_timeout=1800,
+        max_lifetime=28800,
+        additional_policies=["policies/bma-acr-policy.json"],
+        tags={"agentcore:template": "BedrockManagedAgents"},
+    ),
+)
+
+_TEMPLATE_PROFILES: dict[str, TemplateProfile] = {"BedrockManagedAgents": BMA_TEMPLATE_PROFILE}
+
+
+def get_template_profile(framework: str | None) -> TemplateProfile | None:
+    if not framework:
+        return None
+    return _TEMPLATE_PROFILES.get(framework)
+
+
+def template_uses_model(framework: str | None) -> bool:
+    profile = get_template_profile(framework)
+    return profile is None or profile.uses_model
+
+
+def template_needs_python_venv(framework: str | None) -> bool:
+    profile = get_template_profile(framework)
+    return profile is None or profile.setup_python_venv
+
+
+def _get(options: Any, name: str) -> Any:
+    return options.get(name) if isinstance(options, dict) else getattr(options, name, None)
+
+
+def _set(options: Any, name: str, value: Any) -> None:
+    if isinstance(options, dict):
+        options[name] = value
+    else:
+        setattr(options, name, value)
+
+
+def apply_template_option_defaults(framework: str | None, options: Any) -> None:
+    """Fill in options the framework template needs or defaults; user-supplied values win.
+
+    ``options`` is a dict keyed by the upstream option names (``modelProvider``, ``language``, ``memory``,
+    ``build``) or an object with attributes of those names. Like upstream's ``??=``, only missing
+    (None) values are filled, and keys whose default is unset are not added.
+    """
+    profile = get_template_profile(framework)
+    if profile is None:
+        return
+    defaults = {
+        "modelProvider": profile.default_options.get("modelProvider"),
+        "language": profile.required_options.get("language"),
+        "memory": profile.required_options.get("memory"),
+        "build": profile.required_options.get("build"),
+    }
+    for name, value in defaults.items():
+        if _get(options, name) is None and value is not None:
+            _set(options, name, value)
+
+
+def validate_template_options(framework: str | None, options: Any) -> str | None:
+    """Return an error message if an option conflicts with the framework template."""
+    profile = get_template_profile(framework)
+    if profile is None:
+        return None
+    option_type = _get(options, "type")
+    if profile.create_only and option_type and option_type != "create":
+        return f"{framework} supports only --type create"
+    for flag in ("memory", "build", "language"):
+        value = profile.required_options.get(flag)
+        given = _get(options, flag)
+        if value is not None and given is not None and given != value:
+            return f"{framework} supports only --{flag} {value}"
+    return None
+
+
+__all__ = [
+    "BMA_TEMPLATE_PROFILE",
+    "DefaultOptions",
+    "RequiredOptions",
+    "TemplateProfile",
+    "TemplateRuntimeProfile",
+    "apply_template_option_defaults",
+    "get_template_profile",
+    "template_needs_python_venv",
+    "template_uses_model",
+    "validate_template_options",
+]

agentcore/templates/render.py

@@ -0,0 +1,92 @@
+"""Directory copy and Handlebars rendering of template trees (port of ``render.ts``)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Collection, Mapping
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Any
+
+from agentcore.templates._handlebars import HELPERS, SafeString, compile_template, render_template
+
+TemplateSource = Traversable | str | os.PathLike[str]
+
+_TEMPLATE_RENAMES = {
+    "gitignore.template": ".gitignore",
+    "npmignore.template": ".npmignore",
+    "dockerignore.template": ".dockerignore",
+}
+
+
+def resolve_template_name(filename: str) -> str:
+    """Rename template files to their real names, e.g. ``gitignore.template`` -> ``.gitignore``."""
+    return _TEMPLATE_RENAMES.get(filename, filename)
+
+
+def _as_traversable(src: TemplateSource) -> Traversable:
+    if isinstance(src, (str, os.PathLike)):
+        return Path(src)
+    return src
+
+
+# pip byte-compiles package data at install time; those caches are not part of the templates.
+_IGNORED_DIRS = frozenset({"__pycache__"})
+
+
+def _entries(src: Traversable) -> list[Traversable]:
+    entries = (e for e in src.iterdir() if not (e.name in _IGNORED_DIRS and e.is_dir()))
+    return sorted(entries, key=lambda entry: entry.name)
+
+
+def copy_dir(src: TemplateSource, dest: str | os.PathLike[str]) -> None:
+    """Recursively copy ``src`` to ``dest`` byte-for-byte, renaming ``*.template`` dotfiles."""
+    source = _as_traversable(src)
+    target = Path(dest)
+    target.mkdir(parents=True, exist_ok=True)
+    for entry in _entries(source):
+        dest_path = target / resolve_template_name(entry.name)
+        if entry.is_dir():
+            copy_dir(entry, dest_path)
+        else:
+            dest_path.write_bytes(entry.read_bytes())
+
+
+def copy_and_render_dir(
+    src: TemplateSource,
+    dest: str | os.PathLike[str],
+    data: Mapping[str, Any],
+    *,
+    exclude: Collection[str] | None = None,
+) -> None:
+    """Recursively copy ``src`` to ``dest``, rendering every file as a Handlebars template.
+
+    ``exclude`` holds destination names to skip; like upstream, it applies to the top level only.
+    """
+    source = _as_traversable(src)
+    target = Path(dest)
+    target.mkdir(parents=True, exist_ok=True)
+    for entry in _entries(source):
+        dest_name = resolve_template_name(entry.name)
+        if exclude and dest_name in exclude:
+            continue
+        dest_path = target / dest_name
+        if entry.is_dir():
+            copy_and_render_dir(entry, dest_path, data)
+        else:
+            content = entry.read_bytes().decode("utf-8", errors="replace")
+            # newline="" keeps "\n" as-is on Windows, like fs.writeFile.
+            with open(dest_path, "w", encoding="utf-8", newline="") as fh:
+                fh.write(render_template(content, data))
+
+
+__all__ = [
+    "HELPERS",
+    "SafeString",
+    "TemplateSource",
+    "compile_template",
+    "copy_and_render_dir",
+    "copy_dir",
+    "render_template",
+    "resolve_template_name",
+]

agentcore/templates/renderers.py

@@ -0,0 +1,83 @@
+"""Framework renderers and the renderer factory (ports of ``*Renderer.ts`` and ``index.ts``)."""
+
+from __future__ import annotations
+
+from agentcore.templates.base_renderer import BaseRenderer
+from agentcore.templates.template_root import TEMPLATE_ROOT
+from agentcore.templates.types import AgentRenderConfig
+
+
+class StrandsRenderer(BaseRenderer):
+    def __init__(self, config: AgentRenderConfig) -> None:
+        super().__init__(config, "strands", TEMPLATE_ROOT, config.protocol or "http")
+
+
+class GoogleADKRenderer(BaseRenderer):
+    def __init__(self, config: AgentRenderConfig) -> None:
+        super().__init__(config, "googleadk", TEMPLATE_ROOT, config.protocol or "http")
+
+
+class LangGraphRenderer(BaseRenderer):
+    def __init__(self, config: AgentRenderConfig) -> None:
+        super().__init__(config, "langchain_langgraph", TEMPLATE_ROOT, config.protocol or "http")
+
+
+class OpenAIAgentsRenderer(BaseRenderer):
+    def __init__(self, config: AgentRenderConfig) -> None:
+        super().__init__(config, "openaiagents", TEMPLATE_ROOT, config.protocol or "http")
+
+
+class VercelAIRenderer(BaseRenderer):
+    def __init__(self, config: AgentRenderConfig) -> None:
+        super().__init__(config, "vercelai", TEMPLATE_ROOT, config.protocol or "http")
+
+
+class McpRenderer(BaseRenderer):
+    def __init__(self, config: AgentRenderConfig) -> None:
+        super().__init__(config, "standalone", TEMPLATE_ROOT, "mcp")
+
+    def should_render_memory(self) -> bool:
+        return False
+
+
+class BmaRenderer(BaseRenderer):
+    """Bedrock Managed Agents (BMA) customer environment.
+
+    The base template is the Mantle team's control plane with fixes, its Dockerfile, and an
+    OpenTelemetry dependency.
+    """
+
+    def __init__(self, config: AgentRenderConfig) -> None:
+        super().__init__(config, "bma", TEMPLATE_ROOT, "http")
+
+
+_RENDERERS: dict[str, type[BaseRenderer]] = {
+    "Strands": StrandsRenderer,
+    "GoogleADK": GoogleADKRenderer,
+    "LangChain_LangGraph": LangGraphRenderer,
+    "OpenAIAgents": OpenAIAgentsRenderer,
+    "VercelAI": VercelAIRenderer,
+    "BedrockManagedAgents": BmaRenderer,
+}
+
+
+def create_renderer(config: AgentRenderConfig) -> BaseRenderer:
+    """Pick the renderer for ``config``; the MCP protocol uses the standalone renderer for any framework."""
+    if config.protocol == "MCP":
+        return McpRenderer(config)
+    renderer = _RENDERERS.get(config.sdk_framework)
+    if renderer is None:
+        raise ValueError(f"Unsupported SDK framework: {config.sdk_framework}")
+    return renderer(config)
+
+
+__all__ = [
+    "BmaRenderer",
+    "GoogleADKRenderer",
+    "LangGraphRenderer",
+    "McpRenderer",
+    "OpenAIAgentsRenderer",
+    "StrandsRenderer",
+    "VercelAIRenderer",
+    "create_renderer",
+]

agentcore/templates/schema_assets.py

@@ -0,0 +1,23 @@
+"""LLM-compacted schema files (port of ``schema-assets.ts``).
+
+Written to ``agentcore/.llm-context/`` during project creation to give AI coding assistants compact,
+readable type definitions. Upstream embeds ``src/schema/llm-compacted/*`` at build time; here the same
+files ship as package data under ``templates/llm_context/``.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+_FILENAMES = ("README.md", "agentcore.ts", "aws-targets.ts")
+
+
+def _load() -> dict[str, str]:
+    root = files(__package__) / "llm_context"
+    return {name: (root / name).read_text(encoding="utf-8") for name in _FILENAMES}
+
+
+# Each file is self-contained and maps to a JSON config file.
+LLM_CONTEXT_FILES: dict[str, str] = _load()
+
+__all__ = ["LLM_CONTEXT_FILES"]

agentcore/templates/template_root.py

@@ -0,0 +1,28 @@
+"""Location of the bundled template assets (port of ``templateRoot.ts``).
+
+Assets ship inside the package (``<package>/assets``) and are located with ``importlib.resources``, so
+they work from a source checkout and from an installed wheel alike. The returned objects are
+``Traversable``s; for a regular (unzipped) install they are ``pathlib.Path`` instances.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+# Top-level package name, resolved at runtime so the package can be renamed without edits here.
+_PACKAGE = __name__.split(".")[0]
+
+TEMPLATE_ROOT: Traversable = files(_PACKAGE) / "assets"
+
+
+def get_template_path(*segments: str) -> Traversable:
+    """Join ``segments`` onto the assets root (``get_template_path("cdk")`` -> ``assets/cdk``)."""
+    path = TEMPLATE_ROOT
+    for segment in segments:
+        if segment:
+            path = path / segment
+    return path
+
+
+__all__ = ["TEMPLATE_ROOT", "get_template_path"]

agentcore/templates/types.py

@@ -0,0 +1,192 @@
+"""Render configuration consumed by the agent template renderers (port of ``types.ts``).
+
+Fields are snake_case; ``to_template_data()`` produces the camelCase mapping the Handlebars templates
+reference. Unset (``None``) fields are omitted, mirroring absent optional properties upstream.
+Free-form dict values (tool input schemas, custom parameters, ...) are passed through untouched.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from pydantic.alias_generators import to_camel
+
+from agentcore.schema import BuildType, MemoryStrategyType, ModelProvider, ProtocolMode, SDKFramework, TargetLanguage
+
+TruncationStrategy = Literal["sliding_window", "summarization", "none"]
+MantleApiFormat = Literal["responses", "chat_completions"]
+
+
+def _template_value(value: Any) -> Any:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {
+            to_camel(f.name): _template_value(getattr(value, f.name))
+            for f in dataclasses.fields(value)
+            if getattr(value, f.name) is not None
+        }
+    if isinstance(value, (list, tuple)):
+        return [_template_value(item) for item in value]
+    return value
+
+
+class _TemplateData:
+    def to_template_data(self) -> dict[str, Any]:
+        """camelCase mapping of the set fields, as the templates expect."""
+        data = _template_value(self)
+        assert isinstance(data, dict)
+        return data
+
+
+@dataclass(kw_only=True)
+class IdentityProviderRenderConfig(_TemplateData):
+    name: str
+    env_var_name: str
+
+
+@dataclass(kw_only=True)
+class MemoryProviderRenderConfig(_TemplateData):
+    name: str
+    env_var_name: str
+    # Strategy types configured for this memory.
+    strategies: list[MemoryStrategyType] = field(default_factory=list)
+
+
+@dataclass(kw_only=True)
+class GatewayProviderRenderConfig(_TemplateData):
+    name: str
+    env_var_name: str
+    auth_type: str  # AWS_IAM, CUSTOM_JWT, NONE
+    # CUSTOM_JWT only: provider name for @requires_access_token, OIDC discovery URL, space-separated scopes.
+    credential_provider_name: str | None = None
+    discovery_url: str | None = None
+    scopes: str | None = None
+    # CUSTOM_JWT only: CLIENT_CREDENTIALS -> M2M, AUTHORIZATION_CODE -> USER_FEDERATION (default M2M).
+    auth_flow: str | None = None
+    # CUSTOM_JWT only: rendered through safeJson so the JSON is not HTML-escaped.
+    custom_parameters: dict[str, str] | None = None
+    # URL of an external gateway that is not in deployed-state.json.
+    hardcoded_url: str | None = None
+
+
+@dataclass(kw_only=True)
+class MountRenderConfig(_TemplateData):
+    mount_path: str
+
+
+@dataclass(kw_only=True)
+class InlineFunctionToolRenderConfig(_TemplateData):
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+
+
+@dataclass(kw_only=True)
+class HeaderCredentialRenderConfig(_TemplateData):
+    header_key: str
+    credential_name: str
+    env_var_name: str
+
+
+@dataclass(kw_only=True)
+class RemoteMcpToolRenderConfig(_TemplateData):
+    name: str
+    url: str
+    header_credentials: list[HeaderCredentialRenderConfig] | None = None
+
+
+@dataclass(kw_only=True)
+class GitSkillRenderConfig(_TemplateData):
+    url: str
+    path: str | None = None
+    credential_arn: str | None = None
+    username: str | None = None
+
+
+@dataclass(kw_only=True)
+class AgentRenderConfig(_TemplateData):
+    """Configuration needed by template renderers (separate from the stored agent schema)."""
+
+    name: str
+    sdk_framework: SDKFramework = "Strands"
+    target_language: TargetLanguage = "Python"
+    model_provider: ModelProvider = "Bedrock"
+    has_memory: bool = False
+    has_identity: bool = False
+    has_gateway: bool = False
+    has_payment: bool = False
+    # Whether the agent is deployed in VPC mode (affects example MCP endpoints).
+    is_vpc: bool = False
+    build_type: BuildType | None = None
+    memory_providers: list[MemoryProviderRenderConfig] = field(default_factory=list)
+    # Maps to credentials in the schema.
+    identity_providers: list[IdentityProviderRenderConfig] = field(default_factory=list)
+    gateway_providers: list[GatewayProviderRenderConfig] = field(default_factory=list)
+    # Unique auth types across all gateways (for conditional imports).
+    gateway_auth_types: list[str] = field(default_factory=list)
+    protocol: ProtocolMode | None = None
+    # Custom Dockerfile name: when set, the template Dockerfile is not scaffolded.
+    dockerfile: str | None = None
+    session_storage_mount_path: str | None = None
+    efs_mounts: list[MountRenderConfig] | None = None
+    s3_mounts: list[MountRenderConfig] | None = None
+    # True when any filesystem mount is configured (drives `import os` in templates).
+    needs_os: bool | None = None
+    # Wrap the entrypoint with opentelemetry-instrument. Defaults to true.
+    enable_otel: bool | None = None
+    has_config_bundle: bool | None = None
+
+    # -- Export-only fields (set by the harness mapper, consumed by export templates) --
+    max_iterations: int | None = None
+    max_tokens: int | None = None
+    timeout_seconds: int | float | None = None
+    # 'none' renders no truncation block.
+    truncation_strategy: TruncationStrategy | None = None
+    truncation_config: dict[str, Any] | None = None
+    inline_function_tools: list[InlineFunctionToolRenderConfig] | None = None
+    remote_mcp_tools: list[RemoteMcpToolRenderConfig] | None = None
+    path_skills: list[str] | None = None
+    s3_skills: list[str] | None = None
+    git_skills: list[GitSkillRenderConfig] | None = None
+    has_skills_fetcher: bool | None = None
+    has_fetched_skills: bool | None = None
+    has_browser: bool | None = None
+    # Env var holding a custom browser identifier; None when the AWS-managed default is used.
+    browser_identifier_env_var: str | None = None
+    has_code_interpreter: bool | None = None
+    code_interpreter_identifier_env_var: str | None = None
+    has_shell: bool | None = None
+    has_file_operations: bool | None = None
+    has_execution_limits: bool | None = None
+    model_id: str | None = None
+    litellm_api_base: str | None = None
+    # Rendered through pyJsonStr + json.loads so JSON booleans/null parse at runtime.
+    litellm_additional_params: dict[str, Any] | None = None
+    # Bedrock model served through the Mantle OpenAI-compatible endpoint rather than Converse.
+    bedrock_mantle: bool | None = None
+    mantle_api_format: MantleApiFormat | None = None
+    # Proprietary OpenAI models use the /openai/v1 Mantle path + OpenAIResponsesModel.
+    mantle_proprietary: bool | None = None
+    model_temperature: float | None = None
+    model_top_p: float | None = None
+    model_max_tokens: int | None = None
+    # Generating from a harness export (suppresses placeholder tools).
+    is_export_harness: bool | None = None
+    system_prompt_text: str | None = None
+    actor_id: str | None = None
+
+
+__all__ = [
+    "AgentRenderConfig",
+    "GatewayProviderRenderConfig",
+    "GitSkillRenderConfig",
+    "HeaderCredentialRenderConfig",
+    "IdentityProviderRenderConfig",
+    "InlineFunctionToolRenderConfig",
+    "MantleApiFormat",
+    "MemoryProviderRenderConfig",
+    "MountRenderConfig",
+    "RemoteMcpToolRenderConfig",
+    "TruncationStrategy",
+]