agentcore-cli 0.31.1__py3-none-any.whl

agentcore/schema/schemas/mcp_defs.py

@@ -0,0 +1,54 @@
+"""Tool definitions and mcp-defs.json (port of ``schemas/mcp-defs.ts``)."""
+
+from __future__ import annotations
+
+from typing import Final, Literal, get_args
+
+from .._zod import StrictModel, ZodModel, zstr
+
+SchemaPrimitiveType = Literal["string", "number", "object", "array", "boolean", "integer"]
+SCHEMA_PRIMITIVE_TYPES: Final[tuple[SchemaPrimitiveType, ...]] = get_args(SchemaPrimitiveType)
+
+
+class SchemaDefinition(ZodModel):
+    """Opaque (recursive) schema definition for tool input/output, passed through to CloudFormation."""
+
+    type: SchemaPrimitiveType
+    description: str | None = None
+    items: SchemaDefinition | None = None
+    properties: dict[str, SchemaDefinition] | None = None
+    required: list[str] | None = None
+
+
+# Tool name for CLI input: alphanumerics and hyphens (underscores are not permitted for gateway targets).
+ToolName = zstr(
+    min=1,
+    max=128,
+    min_msg="Tool name is required",
+    max_msg="Tool name must be at most 128 characters",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9-]*$",
+    pattern_msg="Tool name must start with a letter and contain only alphanumeric characters or hyphens",
+)
+
+
+class ToolDefinition(StrictModel):
+    name: zstr(min=1, max=128)
+    description: zstr(min=1)
+    input_schema: SchemaDefinition
+    output_schema: SchemaDefinition | None = None
+
+
+class AgentCoreCliMcpDefs(ZodModel):
+    """Top-level mcp-defs.json."""
+
+    tools: dict[str, ToolDefinition]
+
+
+__all__ = [
+    "SCHEMA_PRIMITIVE_TYPES",
+    "AgentCoreCliMcpDefs",
+    "SchemaDefinition",
+    "SchemaPrimitiveType",
+    "ToolDefinition",
+    "ToolName",
+]

agentcore/schema/schemas/primitives/__init__.py

@@ -0,0 +1,52 @@
+"""Primitive resource schemas (port of ``src/schema/schemas/primitives``).
+
+``harness`` depends on ``agent_env`` (which itself imports ``primitives.tags``), so its names are
+resolved lazily here to avoid an import cycle; ``agentcore.schema.schemas`` re-exports them eagerly.
+"""
+
+from typing import Any
+
+from .ab_test import *
+from .ab_test import __all__ as _ab_test
+from .capacity_provider import *
+from .capacity_provider import __all__ as _capacity_provider
+from .config_bundle import *
+from .config_bundle import __all__ as _config_bundle
+from .dataset import *
+from .dataset import __all__ as _dataset
+from .evaluator import *
+from .evaluator import __all__ as _evaluator
+from .knowledge_base import *
+from .knowledge_base import __all__ as _knowledge_base
+from .memory import *
+from .memory import __all__ as _memory
+from .online_eval_config import *
+from .online_eval_config import __all__ as _online_eval_config
+from .payment import *
+from .payment import __all__ as _payment
+from .policy import *
+from .policy import __all__ as _policy
+from .tags import *
+from .tags import __all__ as _tags
+
+__all__ = [
+    *_ab_test,
+    *_capacity_provider,
+    *_config_bundle,
+    *_dataset,
+    *_evaluator,
+    *_knowledge_base,
+    *_memory,
+    *_online_eval_config,
+    *_payment,
+    *_policy,
+    *_tags,
+]
+
+
+def __getattr__(name: str) -> Any:
+    from . import harness
+
+    if name in harness.__all__:
+        return getattr(harness, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

agentcore/schema/schemas/primitives/ab_test.py

@@ -0,0 +1,162 @@
+"""A/B tests (port of ``primitives/ab-test.ts``)."""
+
+from __future__ import annotations
+
+from typing import Annotated, Final, Literal, get_args
+
+from pydantic import Field, model_validator
+
+from ..._zod import Issue, ZBool, ZodModel, array_checks, raise_issues, zint, zstr
+
+ABTestName = zstr(
+    min=1,
+    max=48,
+    min_msg="Name is required",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$",
+    pattern_msg="Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
+)
+
+ABTestDescription = zstr(min=1, max=200)
+
+ABTestMode = Literal["config-bundle", "target-based"]
+AB_TEST_MODES: Final[tuple[ABTestMode, ...]] = get_args(ABTestMode)
+
+VariantName = Literal["C", "T1"]
+
+VariantWeight = zint(ge=1, le=100)
+
+# ── Config Bundle variant configuration ────────────────────────────────────
+
+
+class ConfigurationBundleRef(ZodModel):
+    bundle_arn: zstr(min=1)
+    bundle_version: zstr(min=1)
+
+
+# ── Target-based variant configuration ─────────────────────────────────────
+
+
+class TargetRef(ZodModel):
+    target_name: zstr(min=1, max=100)
+
+
+# ── Variant configuration union: exactly one of configurationBundle or target ──
+
+
+class ConfigBundleVariantConfig(ZodModel):
+    configuration_bundle: ConfigurationBundleRef
+    target: None = None
+
+
+class TargetVariantConfig(ZodModel):
+    configuration_bundle: None = None
+    target: TargetRef
+
+
+VariantConfiguration = Annotated[ConfigBundleVariantConfig | TargetVariantConfig, Field(union_mode="left_to_right")]
+
+
+class ABTestVariant(ZodModel):
+    name: VariantName
+    weight: VariantWeight
+    variant_configuration: VariantConfiguration
+
+
+# ── Evaluation config union ────────────────────────────────────────────────
+
+
+class PerVariantOnlineEvaluationConfig(ZodModel):
+    treatment_name: VariantName
+    online_evaluation_config_arn: zstr(min=1)
+
+
+class SingleOnlineEvaluationConfig(ZodModel):
+    online_evaluation_config_arn: zstr(min=1)
+
+
+class PerVariantEvaluationConfig(ZodModel):
+    per_variant_online_evaluation_config: Annotated[list[PerVariantOnlineEvaluationConfig], array_checks(length=2)]
+
+
+ABTestEvaluationConfig = Annotated[
+    SingleOnlineEvaluationConfig | PerVariantEvaluationConfig, Field(union_mode="left_to_right")
+]
+
+# ── Gateway filter ─────────────────────────────────────────────────────────
+
+
+class GatewayFilter(ZodModel):
+    target_paths: Annotated[list[zstr(min=1, max=500)], array_checks(max=1)]
+
+
+# ── Traffic allocation ─────────────────────────────────────────────────────
+
+
+class TrafficRouteOnHeader(ZodModel):
+    header_name: zstr(min=1)
+
+
+class TrafficAllocationConfig(ZodModel):
+    route_on_header: TrafficRouteOnHeader
+
+
+# ── AB Test ────────────────────────────────────────────────────────────────
+
+
+class ABTest(ZodModel):
+    name: ABTestName
+    description: ABTestDescription | None = None
+    mode: ABTestMode = "config-bundle"
+    gateway_ref: zstr(min=1)
+    role_arn: zstr(min=1) | None = None
+    variants: Annotated[list[ABTestVariant], array_checks(length=2)]
+    evaluation_config: ABTestEvaluationConfig
+    gateway_filter: GatewayFilter | None = None
+    enable_on_create: ZBool | None = None
+    promoted: ZBool | None = None
+
+    @model_validator(mode="after")
+    def _refine(self) -> ABTest:
+        issues: list[Issue] = []
+        names = [v.name for v in self.variants]
+        if not ("C" in names and "T1" in names):
+            issues.append((("variants",), "Variants must include exactly one control (C) and one treatment (T1)"))
+        if sum(v.weight for v in self.variants) != 100:
+            issues.append((("variants",), "Variant weights must sum to 100"))
+        if self.mode == "target-based":
+            ok = all(v.variant_configuration.target is not None for v in self.variants)
+        else:
+            ok = all(v.variant_configuration.configuration_bundle is not None for v in self.variants)
+        if not ok:
+            issues.append(
+                (
+                    ("variants",),
+                    "Target-based mode requires target on each variant; config-bundle mode requires configurationBundle",
+                )
+            )
+        raise_issues(issues, self)
+        return self
+
+
+__all__ = [
+    "AB_TEST_MODES",
+    "ABTest",
+    "ABTestDescription",
+    "ABTestEvaluationConfig",
+    "ABTestMode",
+    "ABTestName",
+    "ABTestVariant",
+    "ConfigBundleVariantConfig",
+    "ConfigurationBundleRef",
+    "GatewayFilter",
+    "PerVariantEvaluationConfig",
+    "PerVariantOnlineEvaluationConfig",
+    "SingleOnlineEvaluationConfig",
+    "TargetRef",
+    "TargetVariantConfig",
+    "TrafficAllocationConfig",
+    "TrafficRouteOnHeader",
+    "VariantConfiguration",
+    "VariantName",
+    "VariantWeight",
+]

agentcore/schema/schemas/primitives/capacity_provider.py

@@ -0,0 +1,214 @@
+"""Capacity providers: AWS::BedrockAgentCore::CapacityProvider (port of ``primitives/capacity-provider.ts``).
+
+Known fields are typed and validated; the long tail of launch parameters is accepted via
+passthrough models and validated by CloudFormation on deploy.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Final, Literal, get_args
+
+from pydantic import Field, model_validator
+
+from ..._zod import PassthroughModel, StrictModel, ZBool, ZodModel, array_checks, js_regex, raise_issues, zint, zstr
+from .tags import Tags
+
+CapacityProviderName = zstr(
+    min=1,
+    max=48,
+    min_msg="Capacity provider name is required",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$",
+    pattern_msg="Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
+)
+
+# ============================================================================
+# Operator Role ARN Validation
+# ============================================================================
+
+# The account segment is OPTIONAL — the service accepts role ARNs without an account id.
+CAPACITY_PROVIDER_OPERATOR_ROLE_ARN_PATTERN: Final = js_regex(r"^arn:[^:]+:iam::([0-9]{12})?:role\/.+$")
+
+OperatorRoleArn = zstr(
+    min=1,
+    max=2048,
+    min_msg="Operator role ARN is required",
+    pattern=CAPACITY_PROVIDER_OPERATOR_ROLE_ARN_PATTERN,
+    pattern_msg="Must be a valid IAM role ARN (e.g. arn:<partition>:iam::123456789012:role/MyOperatorRole)",
+)
+
+
+def is_valid_operator_role_arn(value: str) -> bool:
+    return CAPACITY_PROVIDER_OPERATOR_ROLE_ARN_PATTERN.search(value) is not None
+
+
+# ============================================================================
+# Capacity Provider Attach (runtime -> capacity provider reference)
+# ============================================================================
+
+# Partition-agnostic; the resource segment is the service capacityProviderId `{name}-{10 alnum}`.
+CAPACITY_PROVIDER_ARN_PATTERN: Final = js_regex(
+    r"^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:\d{12}:capacity-provider\/[a-zA-Z][a-zA-Z0-9_]{0,47}-[a-zA-Z0-9]{10}$"
+)
+
+CapacityProviderArn = zstr(
+    pattern=CAPACITY_PROVIDER_ARN_PATTERN,
+    pattern_msg="Must be a valid bedrock-agentcore capacity provider ARN (…:capacity-provider/{name}-{10 alphanumerics})",
+)
+
+
+def is_capacity_provider_arn(value: str) -> bool:
+    """An ``arn:`` prefix means an external CP by ARN; otherwise an in-project sibling name."""
+    return value.startswith("arn:")
+
+
+_VOLUME_NAME_PATTERN = r"^[a-zA-Z][a-zA-Z0-9_-]{0,47}$"
+_VOLUME_NAME_MSG = (
+    "Volume name must begin with a letter and contain only alphanumerics, underscores, and hyphens (max 48 chars)"
+)
+
+# Logical name of a capacity-provider volume, referenced by a runtime's capacityProviderVolume mount.
+CapacityProviderVolumeName = zstr(
+    min=1,
+    max=48,
+    min_msg="Capacity provider volume name is required",
+    pattern=_VOLUME_NAME_PATTERN,
+    pattern_msg=_VOLUME_NAME_MSG,
+)
+
+
+class CapacityProviderConfiguration(StrictModel):
+    """Runtime -> capacity-provider reference: exactly one of ARN (external) or name (sibling)."""
+
+    capacity_provider_arn: CapacityProviderArn | None = None
+    capacity_provider_name: CapacityProviderName | None = None
+
+    @model_validator(mode="after")
+    def _exactly_one(self) -> CapacityProviderConfiguration:
+        if (self.capacity_provider_arn is not None) == (self.capacity_provider_name is not None):
+            raise_issues(
+                [
+                    (
+                        (),
+                        "capacityProviderConfiguration must set exactly one of capacityProviderArn or capacityProviderName",
+                    )
+                ],
+                self,
+            )
+        return self
+
+
+# ============================================================================
+# Operating System (the CLI follows the service API, which supports only Linux)
+# ============================================================================
+
+OperatingSystem = Literal["LINUX_X86_64", "LINUX_ARM64"]
+OPERATING_SYSTEMS: Final[tuple[OperatingSystem, ...]] = get_args(OperatingSystem)
+
+
+class VpcConfiguration(ZodModel):
+    subnets: Annotated[
+        list[zstr(pattern=r"^subnet-[0-9a-zA-Z]{8,17}$", pattern_msg="Must be a valid subnet ID")],
+        array_checks(min=1, max=16, min_msg="At least one subnet is required"),
+    ]
+    security_groups: Annotated[
+        list[zstr(pattern=r"^sg-[0-9a-zA-Z]{8,17}$", pattern_msg="Must be a valid security group ID")],
+        array_checks(min=1, max=16, min_msg="At least one security group is required"),
+    ]
+
+
+class InstanceRequirements(ZodModel):
+    allowed_instance_types: Annotated[
+        list[zstr(min=1, max=255)], array_checks(min=1, max=30, min_msg="At least one instance type is required")
+    ]
+
+
+class LaunchParameters(PassthroughModel):
+    operating_system: OperatingSystem
+    instance_requirements: InstanceRequirements
+    instance_profile_arn: (
+        zstr(
+            pattern=r"^arn:[^:]+:iam::[0-9]{12}:instance-profile\/.+$",
+            pattern_msg="Must be a valid IAM instance profile ARN",
+        )
+        | None
+    ) = None
+
+
+VolumeType = Literal["standard", "io1", "io2", "gp2", "sc1", "st1", "gp3"]
+
+
+class EbsVolumeConfiguration(PassthroughModel):
+    name: zstr(min=1, max=48, pattern=_VOLUME_NAME_PATTERN, pattern_msg=_VOLUME_NAME_MSG)
+    size_gib: Annotated[zint(ge=1, le=65536), Field(alias="sizeGiB")]
+    volume_type: VolumeType | None = None
+    encrypted: ZBool | None = None
+    kms_key_id: (
+        zstr(
+            pattern=r"^arn:[^:]+:kms:[a-z0-9-]+:[0-9]{12}:key\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
+            pattern_msg="Must be a valid KMS key ARN",
+        )
+        | None
+    ) = None
+
+
+class VolumeConfiguration(ZodModel):
+    ebs_configuration: EbsVolumeConfiguration
+
+
+_LIFECYCLE_SECONDS_MIN = 60
+_LIFECYCLE_SECONDS_MAX = 1209600
+
+
+class InstanceLifecycleConfiguration(ZodModel):
+    idle_instance_timeout: zint(ge=_LIFECYCLE_SECONDS_MIN, le=_LIFECYCLE_SECONDS_MAX) | None = None
+    max_lifetime: zint(ge=_LIFECYCLE_SECONDS_MIN, le=_LIFECYCLE_SECONDS_MAX) | None = None
+
+
+class LaunchTemplateSource(ZodModel):
+    launch_parameters: LaunchParameters
+
+
+class Ec2Configuration(PassthroughModel):
+    launch_template_source: LaunchTemplateSource
+    vpc_configuration: VpcConfiguration
+    volumes: Annotated[list[VolumeConfiguration], array_checks(max=5)] | None = None
+    lifecycle_configuration: InstanceLifecycleConfiguration | None = None
+
+
+class ComputeConfiguration(ZodModel):
+    ec2_configuration: Ec2Configuration
+
+
+class CapacityProvider(ZodModel):
+    name: CapacityProviderName
+    description: zstr(min=1, max=4096) | None = None
+    # Optional: when omitted, an operator role is created automatically at deploy time.
+    operator_role_arn: OperatorRoleArn | None = None
+    compute_configuration: ComputeConfiguration
+    tags: Tags | None = None
+
+
+__all__ = [
+    "CAPACITY_PROVIDER_ARN_PATTERN",
+    "CAPACITY_PROVIDER_OPERATOR_ROLE_ARN_PATTERN",
+    "OPERATING_SYSTEMS",
+    "CapacityProvider",
+    "CapacityProviderArn",
+    "CapacityProviderConfiguration",
+    "CapacityProviderName",
+    "CapacityProviderVolumeName",
+    "ComputeConfiguration",
+    "EbsVolumeConfiguration",
+    "Ec2Configuration",
+    "InstanceLifecycleConfiguration",
+    "InstanceRequirements",
+    "LaunchParameters",
+    "LaunchTemplateSource",
+    "OperatingSystem",
+    "OperatorRoleArn",
+    "VolumeConfiguration",
+    "VolumeType",
+    "VpcConfiguration",
+    "is_capacity_provider_arn",
+    "is_valid_operator_role_arn",
+]

agentcore/schema/schemas/primitives/config_bundle.py

@@ -0,0 +1,48 @@
+"""Configuration bundles (port of ``primitives/config-bundle.ts``)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from ..._zod import ZodModel, zstr
+from .evaluator import KmsKeyArn
+
+ConfigBundleName = zstr(
+    min=1,
+    max=100,
+    min_msg="Name is required",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9_]{0,99}$",
+    pattern_msg="Must begin with a letter and contain only alphanumeric characters and underscores (max 100 chars)",
+)
+
+ConfigBundleDescription = zstr(min=1, max=500)
+
+
+class ComponentConfiguration(ZodModel):
+    """Freeform configuration for a single component within a bundle."""
+
+    configuration: dict[str, Any]
+
+
+# Map of component identifier (ARN or `{{runtime:<name>}}` placeholder) to its configuration.
+ComponentConfigurationMap = dict[str, ComponentConfiguration]
+
+
+class ConfigBundle(ZodModel):
+    name: ConfigBundleName
+    # Discriminator required by the CDK package's schema validation.
+    type: Literal["ConfigurationBundle"] = "ConfigurationBundle"
+    description: ConfigBundleDescription | None = None
+    components: ComponentConfigurationMap
+    branch_name: zstr(max=128) | None = None
+    commit_message: zstr(max=500) | None = None
+    kms_key_arn: KmsKeyArn | None = None
+
+
+__all__ = [
+    "ComponentConfiguration",
+    "ComponentConfigurationMap",
+    "ConfigBundle",
+    "ConfigBundleDescription",
+    "ConfigBundleName",
+]

agentcore/schema/schemas/primitives/dataset.py

@@ -0,0 +1,55 @@
+"""Evaluation datasets (port of ``primitives/dataset.ts``)."""
+
+from __future__ import annotations
+
+from typing import Final, Literal, get_args
+
+from ..._zod import ZodModel, zstr
+
+DatasetName = zstr(
+    min=1,
+    max=48,
+    min_msg="Dataset name is required",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$",
+    pattern_msg="Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
+)
+
+# Versioned schema type governing the structure of dataset examples (immutable after creation).
+DatasetSchemaType = Literal["AGENTCORE_EVALUATION_PREDEFINED_V1", "AGENTCORE_EVALUATION_SIMULATED_V1"]
+DATASET_SCHEMA_TYPES: Final[tuple[DatasetSchemaType, ...]] = get_args(DatasetSchemaType)
+
+
+class DatasetManagedConfig(ZodModel):
+    """Managed dataset config — CLI manages the local file and syncs to service."""
+
+    location: zstr(min=1)
+
+
+class DatasetConfig(ZodModel):
+    managed: DatasetManagedConfig
+
+
+class Dataset(ZodModel):
+    """Dataset specification in agentcore.json."""
+
+    name: DatasetName
+    schema_type: DatasetSchemaType
+    description: zstr(max=200) | None = None
+    config: DatasetConfig
+    kms_key_arn: (
+        zstr(
+            pattern=r"^arn:aws(-[a-z]+)*:kms:[a-zA-Z0-9-]*:[0-9]{12}:key\/[a-zA-Z0-9-]{36}$",
+            pattern_msg="Must be a valid KMS key ARN",
+        )
+        | None
+    ) = None
+
+
+__all__ = [
+    "DATASET_SCHEMA_TYPES",
+    "Dataset",
+    "DatasetConfig",
+    "DatasetManagedConfig",
+    "DatasetName",
+    "DatasetSchemaType",
+]