aws / aws/agentcore-cli

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

Open
#1,205 0 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
283
Forks
95
Avg merge
1d 2h
Merged PRs (30d)
183

Description

### Description

The `filesystemConfigurations` schema in `@aws/agentcore-cdk` currently only supports `sessionStorage`. However, the AgentCore Runtime API supports BYO (bring-your-own) file systems via `s3FilesAccessPoint` and `efsAccessPoint` configurations, as documented in the [filesystem configurations guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html).

**Current behavior:**
- `agentcore.json` schema validates `filesystemConfigurations` with only `sessionStorage` objects
- `agentcore create` offers `--session-storage-mount-path` but no flags for BYO filesystems
- The CDK L3 construct (`AgentCoreApplication`) only passes `sessionStorage` to the CloudFormation resource

**Expected behavior:**
- `agentcore.json` should accept `s3FilesAccessPoint` and `efsAccessPoint` entries in `filesystemConfigurations`
- `agentcore deploy` should pass these to the `create-agent-runtime` / `update-agent-runtime` API
- The CDK construct should add the required IAM permissions (`s3files:ClientMount`, `s3files:ClientWrite`, `s3files:GetAccessPoint`, `s3files:ListMountTargets`) to the execution role when BYO filesystems are configured

**Current workaround:**
After `agentcore deploy`, manually call `update_agent_runtime` via boto3 to attach the filesystem:

```python
client.update_agent_runtime(
agentRuntimeId='...',
filesystemConfigurations=[{
's3FilesAccessPoint': {
'accessPointArn': 'arn:aws:s3files:...',
'mountPath': '/mnt/skills'
}
}],
# must also re-pass roleArn, networkConfiguration, agentRuntimeArtifact
)
```

This workaround must be re-applied after every `agentcore deploy` since the CDK stack overwrites the runtime configuration without the filesystem settings.

### Acceptance Criteria

- [ ] `agentcore.json` schema accepts `s3FilesAccessPoint: { accessPointArn, mountPath }` and `efsAccessPoint: { accessPointArn, mountPath }` in `filesystemConfigurations` array
- [ ] `agentcore deploy` creates/updates the runtime with BYO filesystem configurations without requiring a manual API call
- [ ] CDK construct automatically adds required IAM permissions to the execution role when BYO filesystems are declared
- [ ] `agentcore create` offers optional flags for BYO filesystem configuration (e.g., `--s3-files-access-point-arn`, `--mount-path`)

### Additional Context

**Use case:** Shared skill libraries mounted via S3 Files into multiple agent runtimes. The skill directory (following the Agent Skills spec) lives on S3, is mounted at `/mnt/skills`, and agents discover skills at runtime via the Strands SDK `AgentSkills` plugin. This pattern requires VPC mode + S3 Files access point, which currently can't be declared in `agentcore.json`.

**API reference:** The `filesystemConfigurations` parameter is documented in the [AgentCore Runtime API](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_S3FilesAccessPointConfiguration.html) and works correctly when called directly via SDK.

**CLI version:** 0.13.1
**CDK package:** @aws/agentcore-cdk ^0.1.0-alpha.19

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.