serverless-bedrock-agentcore-plugin 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-12-19
+
+### Added
+
+- Initial release of serverless-bedrock-agentcore plugin
+- Support for AWS::BedrockAgentCore::Runtime resource
+  - Container image and S3 artifact support
+  - Network configuration (PUBLIC and VPC modes)
+  - Protocol configuration (HTTP, MCP, A2A)
+  - Environment variables
+  - Authorizer configuration (AWS_IAM, CUSTOM_JWT)
+  - Lifecycle configuration
+- Support for AWS::BedrockAgentCore::RuntimeEndpoint resource
+  - Multiple endpoints per runtime
+  - Version targeting
+- Support for AWS::BedrockAgentCore::Memory resource
+  - Event expiry duration configuration
+  - Memory strategies (semantic, userPreference, summary, custom)
+  - Encryption key support
+- Support for AWS::BedrockAgentCore::Gateway resource
+  - AWS_IAM and CUSTOM_JWT authorization
+  - MCP protocol support
+  - KMS encryption support
+- Support for AWS::BedrockAgentCore::GatewayTarget resource
+  - Lambda function targets
+  - OpenAPI specification targets
+  - Smithy model targets
+  - OAuth and API Key credential providers
+- Automatic IAM role generation with least-privilege permissions
+- Schema validation for serverless.yml configuration
+- Custom command: `sls agentcore info`
+- CloudFormation outputs for all resources
+- Automatic tagging with service, stage, and resource metadata
+- Example projects:
+  - basic-runtime: Simple runtime deployment
+  - with-memory: Runtime with conversation memory
+  - full-stack: Complete setup with runtime, memory, gateway, and Lambda functions
+
+### Security
+
+- IAM roles follow least-privilege principle
+- Support for KMS encryption for Memory and Gateway resources
+- Support for VPC deployment for Runtime resources

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The serverless-bedrock-agentcore-plugin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,476 @@
+# serverless-bedrock-agentcore
+
+Deploy AWS Bedrock AgentCore resources with Serverless Framework.
+
+## Features
+
+- Define AgentCore resources in `serverless.yml`
+- Supports all AgentCore resource types:
+  - **Runtime** - Deploy containerized AI agents
+  - **Memory** - Conversation history with semantic search
+  - **Gateway** - External API integrations
+  - **Browser** - Web browsing capabilities
+  - **CodeInterpreter** - Sandboxed code execution
+  - **WorkloadIdentity** - OAuth2 authentication
+- Auto-generates IAM roles with least-privilege permissions
+- Automatic tagging and naming conventions
+- CloudFormation outputs for cross-stack references
+
+## Installation
+
+```bash
+npm install serverless-bedrock-agentcore --save-dev
+```
+
+Add to `serverless.yml`:
+
+```yaml
+plugins:
+  - serverless-bedrock-agentcore
+```
+
+## Quick Start
+
+```yaml
+service: my-agent
+
+provider:
+  name: aws
+  region: us-east-1
+
+plugins:
+  - serverless-bedrock-agentcore
+
+agents:
+  myAgent:
+    type: runtime
+    description: My AI agent
+    handler:
+      type: docker
+      image:
+        dockerfile: ./Dockerfile
+        context: .
+    protocol: AWS_MCP
+    networkMode: PUBLIC
+    authorizationConfig:
+      authorizationType: NONE
+```
+
+## Resource Types
+
+### Runtime
+
+Deploy containerized AI agents with the AgentCore Runtime.
+
+```yaml
+agents:
+  myAgent:
+    type: runtime
+    description: My AI agent
+    handler:
+      type: docker
+      image:
+        dockerfile: ./Dockerfile
+        context: .
+    protocol: AWS_MCP # AWS_MCP, HTTP, or A2A
+    networkMode: PUBLIC # PUBLIC or VPC
+    authorizationConfig:
+      authorizationType: NONE # NONE or AWS_IAM
+    # Optional: Pass specific headers to the runtime
+    requestHeaders:
+      allowlist:
+        - X-User-Id
+        - X-Session-Id
+        - Authorization
+```
+
+| Property                                | Required | Description                         |
+| --------------------------------------- | -------- | ----------------------------------- |
+| `type`                                  | Yes      | `runtime`                           |
+| `handler.type`                          | Yes      | `docker`                            |
+| `handler.image.dockerfile`              | Yes      | Path to Dockerfile                  |
+| `handler.image.context`                 | Yes      | Docker build context                |
+| `protocol`                              | No       | `AWS_MCP`, `HTTP`, or `A2A`         |
+| `networkMode`                           | No       | `PUBLIC` or `VPC`                   |
+| `authorizationConfig.authorizationType` | No       | `NONE` or `AWS_IAM`                 |
+| `requestHeaders.allowlist`              | No       | Headers to pass to runtime (max 20) |
+| `description`                           | No       | Runtime description                 |
+| `roleArn`                               | No       | Custom IAM role ARN                 |
+
+### Memory
+
+Store conversation history with semantic search and summarization.
+
+```yaml
+agents:
+  conversationMemory:
+    type: memory
+    description: Conversation memory with semantic search
+    eventExpiryDuration: 90
+    strategies:
+      # Semantic search strategy
+      - SemanticMemoryStrategy:
+          Name: ConversationSearch
+          Type: SEMANTIC
+          Namespaces:
+            - /conversations/{sessionId}
+          SemanticMemoryConfiguration:
+            ModelId: amazon.titan-embed-text-v2:0
+            SimilarityThreshold: 0.75
+
+      # Summarization strategy
+      - SummaryMemoryStrategy:
+          Name: SessionSummary
+          Type: SUMMARIZATION
+          SummaryConfiguration:
+            SummaryModelId: anthropic.claude-3-haiku-20240307-v1:0
+            MaxMessages: 100
+
+      # User preference strategy
+      - UserPreferenceMemoryStrategy:
+          Name: UserPrefs
+          Type: USER_PREFERENCE
+          Namespaces:
+            - /users/{userId}/preferences
+```
+
+| Property              | Required | Description                         |
+| --------------------- | -------- | ----------------------------------- |
+| `type`                | Yes      | `memory`                            |
+| `eventExpiryDuration` | No       | Days to retain (7-365, default: 30) |
+| `strategies`          | No       | Memory strategies array             |
+| `description`         | No       | Memory description                  |
+| `encryptionKeyArn`    | No       | KMS key for encryption              |
+| `roleArn`             | No       | Custom IAM role ARN                 |
+
+#### Memory Strategy Types
+
+**SemanticMemoryStrategy** - Semantic search over conversations:
+
+```yaml
+- SemanticMemoryStrategy:
+    Name: Search
+    Type: SEMANTIC
+    Namespaces:
+      - /sessions/{sessionId}
+    SemanticMemoryConfiguration:
+      ModelId: amazon.titan-embed-text-v2:0
+      SimilarityThreshold: 0.75
+```
+
+**SummaryMemoryStrategy** - Summarize long conversations:
+
+```yaml
+- SummaryMemoryStrategy:
+    Name: Summary
+    Type: SUMMARIZATION
+    SummaryConfiguration:
+      SummaryModelId: anthropic.claude-3-haiku-20240307-v1:0
+      MaxMessages: 100
+```
+
+**UserPreferenceMemoryStrategy** - Track user preferences:
+
+```yaml
+- UserPreferenceMemoryStrategy:
+    Name: Preferences
+    Type: USER_PREFERENCE
+    Namespaces:
+      - /users/{userId}
+```
+
+**CustomMemoryStrategy** - Custom memory handling:
+
+```yaml
+- CustomMemoryStrategy:
+    Name: Custom
+    Type: CUSTOM
+    CustomConfiguration:
+      key: value
+```
+
+### Browser
+
+Enable web browsing capabilities for agents.
+
+```yaml
+agents:
+  webBrowser:
+    type: browser
+    description: Web browser for agent
+    network:
+      networkMode: PUBLIC # PUBLIC or VPC
+    signing:
+      enabled: true
+    recording:
+      enabled: true
+      s3Location:
+        bucket: my-recordings-bucket
+        prefix: browser-sessions/
+```
+
+| Property               | Required | Description                               |
+| ---------------------- | -------- | ----------------------------------------- |
+| `type`                 | Yes      | `browser`                                 |
+| `network.networkMode`  | No       | `PUBLIC` or `VPC` (default: `PUBLIC`)     |
+| `network.vpcConfig`    | No       | VPC configuration (required for VPC mode) |
+| `signing.enabled`      | No       | Enable request signing                    |
+| `recording.enabled`    | No       | Enable session recording                  |
+| `recording.s3Location` | No       | S3 bucket/prefix for recordings           |
+| `description`          | No       | Browser description                       |
+| `roleArn`              | No       | Custom IAM role ARN                       |
+
+### CodeInterpreter
+
+Enable sandboxed code execution.
+
+```yaml
+agents:
+  codeExecutor:
+    type: codeInterpreter
+    description: Python code execution
+    network:
+      networkMode: SANDBOX # SANDBOX, PUBLIC, or VPC
+```
+
+| Property              | Required | Description                                        |
+| --------------------- | -------- | -------------------------------------------------- |
+| `type`                | Yes      | `codeInterpreter`                                  |
+| `network.networkMode` | No       | `SANDBOX`, `PUBLIC`, or `VPC` (default: `SANDBOX`) |
+| `network.vpcConfig`   | No       | VPC configuration (required for VPC mode)          |
+| `description`         | No       | CodeInterpreter description                        |
+| `roleArn`             | No       | Custom IAM role ARN                                |
+
+### WorkloadIdentity
+
+Enable OAuth2 authentication for agents.
+
+```yaml
+agents:
+  agentIdentity:
+    type: workloadIdentity
+    oauth2ReturnUrls:
+      - https://example.com/callback
+      - http://localhost:3000/auth/callback
+```
+
+| Property           | Required | Description                  |
+| ------------------ | -------- | ---------------------------- |
+| `type`             | Yes      | `workloadIdentity`           |
+| `oauth2ReturnUrls` | No       | Allowed OAuth2 redirect URLs |
+
+### Gateway
+
+Integrate external APIs as agent tools.
+
+```yaml
+agents:
+  apiGateway:
+    type: gateway
+    description: External API gateway
+    authorizationType: NONE
+    targets:
+      weatherApi:
+        type: lambdaArn
+        lambdaArn:
+          Fn::GetAtt:
+            - WeatherFunction
+            - Arn
+        name: WeatherAPI
+        description: Get weather data
+```
+
+| Property            | Required | Description                        |
+| ------------------- | -------- | ---------------------------------- |
+| `type`              | Yes      | `gateway`                          |
+| `authorizationType` | No       | `NONE` or `AWS_IAM`                |
+| `targets`           | No       | Gateway targets (Lambda functions) |
+| `description`       | No       | Gateway description                |
+| `roleArn`           | No       | Custom IAM role ARN                |
+
+## Commands
+
+```bash
+sls agentcore info        # Show defined resources
+sls package               # Generate CloudFormation
+sls deploy                # Deploy to AWS
+sls remove                # Remove deployed resources
+```
+
+## Examples
+
+The `examples/` directory contains complete working examples:
+
+### Full-Stack Agent (`examples/full-stack-agent/`)
+
+A comprehensive example showing all resource types working together:
+
+- Runtime with Docker handler
+- Memory with multiple strategies
+- Browser for web interactions
+- CodeInterpreter for code execution
+- WorkloadIdentity for OAuth2
+- Gateway for external APIs
+
+### Memory Strategies (`examples/memory-strategies/`)
+
+Detailed examples of all memory strategy types:
+
+- Semantic search configuration
+- Summarization settings
+- User preference tracking
+- Custom strategies
+- Multi-strategy memory
+
+### Browser & CodeInterpreter (`examples/browser-code-interpreter/`)
+
+Examples of browser and code interpreter configurations:
+
+- Public, VPC, and sandbox network modes
+- Session recording
+- Request signing
+- Custom IAM roles
+
+### Google ADK (`examples/google-adk/`)
+
+Deploy a Google ADK agent to AWS Bedrock AgentCore.
+
+### Strands Framework Examples
+
+The [Strands Agents SDK](https://github.com/strands-agents/sdk-python) is a lightweight, model-driven framework for building AI agents. These examples show how to deploy Strands agents to AgentCore:
+
+#### Strands Basic (`examples/strands-basic/`)
+
+Simple Strands agent with custom tools:
+
+- Custom `@tool` decorated functions
+- Basic prompt/response flow
+- Minimal setup example
+
+```python
+from strands import Agent, tool
+
+@tool
+def get_weather(location: str) -> str:
+    """Get weather for a location."""
+    return f"Weather in {location}: Sunny, 72°F"
+
+agent = Agent(
+    model="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
+    tools=[get_weather],
+)
+```
+
+#### Strands Streaming (`examples/strands-streaming/`)
+
+Async agent with streaming responses:
+
+- `stream_async()` for real-time streaming
+- Async event iteration
+- Suitable for long-form responses
+
+#### Strands Memory (`examples/strands-memory/`)
+
+Agent with AgentCore Memory integration:
+
+- MemoryHook provider for automatic memory ops
+- Short-term memory (within session)
+- Long-term memory with semantic search
+- User preference tracking
+
+#### Strands MCP Tools (`examples/strands-mcp-tools/`)
+
+Agent with Gateway/MCP tool integration:
+
+- MCP protocol for tool discovery
+- Gateway targets with Lambda functions
+- Dynamic tool registration
+
+#### Strands OAuth Identity (`examples/strands-oauth-identity/`)
+
+Agent with WorkloadIdentity for external API credentials:
+
+- `@requires_api_key` decorator for secure credential retrieval
+- OAuth2 flows for external services (OpenAI, GitHub)
+- Secure credential storage without hardcoding
+
+#### Strands Cognito JWT (`examples/strands-cognito-jwt/`)
+
+Agent protected by Cognito JWT authentication:
+
+- CustomJWTAuthorizer configuration
+- Cognito User Pool and Client setup
+- JWT token validation at AgentCore level
+- Secure endpoints requiring authentication
+
+## Configuration Options
+
+### Default Tags
+
+Apply tags to all resources:
+
+```yaml
+custom:
+  agentCore:
+    defaultTags:
+      Project: MyProject
+      Environment: ${self:provider.stage}
+```
+
+### VPC Configuration
+
+For resources that support VPC mode:
+
+```yaml
+network:
+  networkMode: VPC
+  vpcConfig:
+    subnetIds:
+      - subnet-12345678
+      - subnet-87654321
+    securityGroupIds:
+      - sg-12345678
+```
+
+### Custom IAM Roles
+
+Bring your own IAM roles:
+
+```yaml
+agents:
+  myAgent:
+    type: runtime
+    roleArn: arn:aws:iam::123456789012:role/MyCustomRole
+    # ... other config
+```
+
+## Migration Guide
+
+### Memory Strategy Format (v0.2.0+)
+
+The memory strategy format has changed to a typed union structure. The legacy format is deprecated but still supported with a warning.
+
+**Legacy format (deprecated):**
+
+```yaml
+strategies:
+  - type: semantic
+    name: Search
+    configuration:
+      modelId: amazon.titan-embed-text-v2:0
+```
+
+**New format:**
+
+```yaml
+strategies:
+  - SemanticMemoryStrategy:
+      Name: Search
+      Type: SEMANTIC
+      SemanticMemoryConfiguration:
+        ModelId: amazon.titan-embed-text-v2:0
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "serverless-bedrock-agentcore-plugin",
+  "version": "0.1.0",
+  "description": "Serverless Framework plugin for AWS Bedrock AgentCore - deploy Runtime, Memory, and Gateway resources",
+  "main": "src/index.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "serverless",
+    "serverless-plugin",
+    "aws",
+    "bedrock",
+    "agentcore",
+    "ai-agents",
+    "mcp",
+    "cloudformation",
+    "lambda"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/LawProAI/serverless-bedrock-agentcore-plugin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LawProAI/serverless-bedrock-agentcore-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/LawProAI/serverless-bedrock-agentcore-plugin/issues"
+  },
+  "peerDependencies": {
+    "serverless": ">=3.0.0 || >=4.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^9.0.0",
+    "jest": "^29.7.0",
+    "js-yaml": "^4.1.0",
+    "lint-staged": "^15.2.0",
+    "prettier": "^3.2.0",
+    "sinon": "^17.0.0"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:unit": "jest test/unit",
+    "test:integration": "jest test/integration",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "prepublishOnly": "npm test && npm run lint",
+    "examples:list": "./scripts/deploy-examples.sh --list",
+    "examples:info": "./scripts/deploy-examples.sh --info",
+    "examples:deploy": "./scripts/deploy-examples.sh --deploy",
+    "examples:deploy:parallel": "./scripts/deploy-examples.sh --deploy --parallel",
+    "examples:remove": "./scripts/deploy-examples.sh --remove"
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testTimeout": 30000,
+    "testMatch": [
+      "**/test/**/*.test.js"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.js"
+    ],
+    "coveragePathIgnorePatterns": [
+      "/node_modules/",
+      "/test/"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 70,
+        "functions": 70,
+        "lines": 70,
+        "statements": 70
+      }
+    }
+  },
+  "files": [
+    "src/**/*.js",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}