Support BYO filesystem (S3 Files / EFS access points) in agentcore.json and CDK construct
- 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
Assessment
This issue has not been assessed yet.