Skip to content

feat: support BYO filesystem (S3 Files / EFS) in schema and CLI#1220

Open
johanneslanger wants to merge 1 commit into
aws:mainfrom
johanneslanger:feat/byo-filesystem-support
Open

feat: support BYO filesystem (S3 Files / EFS) in schema and CLI#1220
johanneslanger wants to merge 1 commit into
aws:mainfrom
johanneslanger:feat/byo-filesystem-support

Conversation

@johanneslanger
Copy link
Copy Markdown

Summary

Adds support for BYO (bring-your-own) filesystem configurations in agentcore.json and the CLI, enabling S3 Files access points and EFS access points alongside the existing session storage.

Closes #1205

Changes

Schema (src/schema/schemas/agent-env.ts)

  • Added S3FilesAccessPointSchema with ARN pattern validation for arn:*:s3files:* access points
  • Added EfsAccessPointSchema with ARN pattern validation for arn:*:elasticfilesystem:* access points
  • Extended FilesystemConfigurationSchema to accept sessionStorage, s3FilesAccessPoint, or efsAccessPoint (at least one required per entry)
  • Regenerated schemas/agentcore.schema.v1.json

CLI (src/cli/primitives/AgentPrimitive.tsx)

  • Added flags: --s3-files-access-point-arn, --s3-files-mount-path, --efs-access-point-arn, --efs-mount-path
  • Added buildFilesystemConfigurations() helper that assembles the array from flat CLI options

Validation (src/cli/commands/add/validate.ts)

  • ARN + mount path are required as a pair (error if one is missing)
  • ARN format validated via existing isValidArn() utility
  • Mount path validated against the same /mnt/<name> pattern as session storage

What's NOT in this PR

  • CDK IAM permissions (s3files:ClientMount, etc.) — these belong in @aws/agentcore-cdk and will be a follow-up PR against that package
  • agentcore create TUI wizard — BYO filesystems are a non-interactive advanced feature; the TUI wizard continues to offer only session storage

Testing

  • 8 new schema tests (valid/invalid ARNs, mixed configs, empty configs)
  • 9 new validation tests (pair requirements, ARN format, mount path format)
  • All existing tests pass (no regressions)
  • TypeScript compiles clean

Example usage

agentcore add agent --name my_agent --type byo --build CodeZip \
  --language Python --framework Strands --model-provider Bedrock \
  --code-location ./app/my_agent/ \
  --s3-files-access-point-arn arn:aws:s3files:eu-central-1:123456789012:access-point/skills-ap \
  --s3-files-mount-path /mnt/skills

Resulting agentcore.json:

{
  "filesystemConfigurations": [
    {
      "s3FilesAccessPoint": {
        "accessPointArn": "arn:aws:s3files:eu-central-1:123456789012:access-point/skills-ap",
        "mountPath": "/mnt/skills"
      }
    }
  ]
}

… and CLI

Extends filesystemConfigurations to accept s3FilesAccessPoint and
efsAccessPoint entries alongside the existing sessionStorage type.

Changes:
- Extended FilesystemConfigurationSchema with S3FilesAccessPointSchema
  and EfsAccessPointSchema (Zod validators with ARN pattern matching)
- Added CLI flags: --s3-files-access-point-arn, --s3-files-mount-path,
  --efs-access-point-arn, --efs-mount-path
- Added validation requiring ARN + mount path pairs
- Regenerated agentcore.schema.v1.json from Zod
- Added 17 unit tests covering schema validation and CLI option validation

Closes aws#1205
@johanneslanger johanneslanger requested a review from a team May 13, 2026 07:49
@github-actions github-actions Bot added the size/xl PR size: XL label May 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/xl PR size: XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support BYO filesystem (S3 Files / EFS access points) in agentcore.json and CDK construct

1 participant