serverless-bedrock-agentcore-plugin 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Resource-based policy support for AgentCore Runtime
+  - Enable cross-account access to agent runtimes
+  - Standard IAM policy document format
+  - Support for multiple principals and statements
+- New example: `cross-account-access` demonstrating resource policy usage
+- Schema validation for `resourcePolicy` configuration
+- Test coverage for resource policy builder functions
+
 ## [0.2.0] - 2025-12-19
 
 ### Added

package/README.md

@@ -45,15 +45,15 @@ agents:
   myAgent:
     type: runtime
     description: My AI agent
-    handler:
-      type: docker
-      image:
-        dockerfile: ./Dockerfile
-        context: .
-    protocol: AWS_MCP
-    networkMode: PUBLIC
-    authorizationConfig:
-      authorizationType: NONE
+    artifact:
+      docker:
+        path: .
+        file: Dockerfile
+        repository: my-agent
+    protocol: HTTP
+    network:
+      networkMode: PUBLIC
+    # Omit 'authorizer' for no authentication
 ```
 
 ## Resource Types
@@ -67,35 +67,75 @@ 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
+    artifact:
+      docker:
+        path: .
+        file: Dockerfile
+        repository: my-agent
+    protocol: HTTP # HTTP, MCP, or A2A
+    network:
+      networkMode: PUBLIC # PUBLIC or VPC
+    # Optional: JWT authorization (omit for no auth)
+    authorizer:
+      customJwtAuthorizer:
+        discoveryUrl: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx/.well-known/openid-configuration
+        allowedAudience:
+          - my-client-id
     # Optional: Pass specific headers to the runtime
     requestHeaders:
       allowlist:
         - X-User-Id
         - X-Session-Id
         - Authorization
+    # Optional: Resource-based policy for cross-account access
+    resourcePolicy:
+      Version: '2012-10-17'
+      Statement:
+        - Sid: AllowCrossAccountInvoke
+          Effect: Allow
+          Principal:
+            AWS: arn:aws:iam::123456789012:role/MyRole
+          Action:
+            - bedrock-agentcore:InvokeAgentRuntime
+          Resource: '*'
 ```
 
-| 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                 |
+| Property                                         | Required  | Description                              |
+| ------------------------------------------------ | --------- | ---------------------------------------- |
+| `type`                                           | Yes       | `runtime`                                |
+| `artifact.docker.path`                           | Yes\*     | Docker build context path                |
+| `artifact.docker.file`                           | No        | Dockerfile name (default: Dockerfile)    |
+| `artifact.docker.repository`                     | No        | ECR repository name                      |
+| `artifact.containerImage`                        | Yes\*     | Pre-built container image URI            |
+| `protocol`                                       | No        | `HTTP`, `MCP`, or `A2A`                  |
+| `network.networkMode`                            | No        | `PUBLIC` or `VPC`                        |
+| `authorizer.customJwtAuthorizer`                 | No        | JWT authorizer config (omit for no auth) |
+| `authorizer.customJwtAuthorizer.discoveryUrl`    | Yes\*\*   | OIDC discovery URL                       |
+| `authorizer.customJwtAuthorizer.allowedAudience` | No        | Array of allowed audience values         |
+| `authorizer.customJwtAuthorizer.allowedClients`  | No        | Array of allowed client IDs              |
+| `requestHeaders.allowlist`                       | No        | Headers to pass to runtime (max 20)      |
+| `resourcePolicy`                                 | No        | Resource-based policy (IAM policy doc)   |
+| `resourcePolicy.Statement`                       | Yes\*\*\* | Array of policy statements               |
+| `description`                                    | No        | Runtime description                      |
+| `roleArn`                                        | No        | Custom IAM role ARN                      |
+
+\*Either `artifact.docker` or `artifact.containerImage` is required
+
+\*\*Required when using `customJwtAuthorizer`
+
+\*\*\*Required when using `resourcePolicy`
+
+#### Resource-Based Policies
+
+Resource-based policies allow you to grant cross-account or cross-principal access to invoke your AgentCore runtime. This is useful when you need to allow another AWS account or service to invoke your agent.
+
+Example use cases:
+
+- **Cross-account access**: Allow an ECS task in another account to invoke your agent
+- **Service-to-service**: Grant specific IAM roles permission to invoke the runtime
+- **Multi-tenant architectures**: Control access across different AWS accounts
+
+The `resourcePolicy` follows standard IAM policy document format with `Version` (defaults to `2012-10-17`) and `Statement` array.
 
 ### Memory
 
@@ -111,25 +151,18 @@ agents:
       # 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
+          Namespaces:
+            - /sessions/{sessionId}
 
       # User preference strategy
       - UserPreferenceMemoryStrategy:
           Name: UserPrefs
-          Type: USER_PREFERENCE
           Namespaces:
             - /users/{userId}/preferences
 ```
@@ -150,12 +183,8 @@ agents:
 ```yaml
 - SemanticMemoryStrategy:
     Name: Search
-    Type: SEMANTIC
     Namespaces:
       - /sessions/{sessionId}
-    SemanticMemoryConfiguration:
-      ModelId: amazon.titan-embed-text-v2:0
-      SimilarityThreshold: 0.75
 ```
 
 **SummaryMemoryStrategy** - Summarize long conversations:
@@ -163,10 +192,8 @@ agents:
 ```yaml
 - SummaryMemoryStrategy:
     Name: Summary
-    Type: SUMMARIZATION
-    SummaryConfiguration:
-      SummaryModelId: anthropic.claude-3-haiku-20240307-v1:0
-      MaxMessages: 100
+    Namespaces:
+      - /sessions/{sessionId}
 ```
 
 **UserPreferenceMemoryStrategy** - Track user preferences:
@@ -174,7 +201,6 @@ agents:
 ```yaml
 - UserPreferenceMemoryStrategy:
     Name: Preferences
-    Type: USER_PREFERENCE
     Namespaces:
       - /users/{userId}
 ```
@@ -184,8 +210,7 @@ agents:
 ```yaml
 - CustomMemoryStrategy:
     Name: Custom
-    Type: CUSTOM
-    CustomConfiguration:
+    Configuration:
       key: value
 ```
 
@@ -265,33 +290,65 @@ Integrate external APIs as agent tools.
 
 ```yaml
 agents:
-  apiGateway:
+  # Gateway without authentication
+  publicGateway:
     type: gateway
-    description: External API gateway
-    authorizationType: NONE
+    description: Public API gateway
+    authorizerType: NONE
     targets:
-      weatherApi:
-        type: lambdaArn
-        lambdaArn:
+      - name: WeatherAPI
+        type: lambda
+        description: Get weather data
+        functionArn:
           Fn::GetAtt:
             - WeatherFunction
             - Arn
-        name: WeatherAPI
-        description: Get weather data
+
+  # Gateway with JWT authentication
+  secureGateway:
+    type: gateway
+    description: Secure API gateway with JWT auth
+    authorizerType: CUSTOM_JWT
+    authorizerConfiguration:
+      customJwtAuthorizer:
+        discoveryUrl: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx/.well-known/openid-configuration
+        allowedAudience:
+          - my-client-id
+        allowedClients:
+          - my-app-client
+    targets:
+      - name: SecureAPI
+        type: lambda
+        functionArn:
+          Fn::GetAtt:
+            - SecureFunction
+            - Arn
 ```
 
-| 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                |
+| Property                                                      | Required | Description                                                        |
+| ------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
+| `type`                                                        | Yes      | `gateway`                                                          |
+| `authorizerType`                                              | No       | `NONE`, `AWS_IAM`, or `CUSTOM_JWT` (default: `AWS_IAM`)            |
+| `authorizerConfiguration.customJwtAuthorizer`                 | No\*     | JWT authorizer config (required when `authorizerType: CUSTOM_JWT`) |
+| `authorizerConfiguration.customJwtAuthorizer.discoveryUrl`    | Yes\*\*  | OIDC discovery URL                                                 |
+| `authorizerConfiguration.customJwtAuthorizer.allowedAudience` | No       | Array of allowed audience values                                   |
+| `authorizerConfiguration.customJwtAuthorizer.allowedClients`  | No       | Array of allowed client IDs                                        |
+| `protocolType`                                                | No       | `MCP` (default: `MCP`)                                             |
+| `targets`                                                     | No       | Gateway targets (Lambda functions)                                 |
+| `description`                                                 | No       | Gateway description                                                |
+| `roleArn`                                                     | No       | Custom IAM role ARN                                                |
+
+\*Required when `authorizerType` is `CUSTOM_JWT`
+
+\*\*Required when using `customJwtAuthorizer`
 
 ## Commands
 
 ```bash
 sls agentcore info        # Show defined resources
+sls agentcore build       # Build Docker images
+sls agentcore invoke      # Invoke a deployed agent
+sls agentcore logs        # Fetch logs for a runtime
 sls package               # Generate CloudFormation
 sls deploy                # Deploy to AWS
 sls remove                # Remove deployed resources
@@ -305,7 +362,7 @@ The `examples/` directory contains complete working examples:
 
 A comprehensive example showing all resource types working together:
 
-- Runtime with Docker handler
+- Runtime with Docker artifact
 - Memory with multiple strategies
 - Browser for web interactions
 - CodeInterpreter for code execution
@@ -456,8 +513,8 @@ The memory strategy format has changed to a typed union structure. The legacy fo
 strategies:
   - type: semantic
     name: Search
-    configuration:
-      modelId: amazon.titan-embed-text-v2:0
+    namespaces:
+      - /sessions/{sessionId}
 ```
 
 **New format:**
@@ -466,9 +523,8 @@ strategies:
 strategies:
   - SemanticMemoryStrategy:
       Name: Search
-      Type: SEMANTIC
-      SemanticMemoryConfiguration:
-        ModelId: amazon.titan-embed-text-v2:0
+      Namespaces:
+        - /sessions/{sessionId}
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-bedrock-agentcore-plugin",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Serverless Framework plugin for AWS Bedrock AgentCore - deploy Runtime, Memory, and Gateway resources",
   "main": "src/index.js",
   "engines": {

package/src/compilers/gateway.js

@@ -4,19 +4,28 @@ const { getLogicalId } = require('../utils/naming');
 
 /**
  * Build authorizer configuration for the gateway
+ * Only used when authorizerType is CUSTOM_JWT
  *
  * @param {Object} authConfig - The authorizer configuration from serverless.yml
  * @returns {Object|null} CloudFormation authorizer configuration or null
  */
 function buildGatewayAuthorizerConfiguration(authConfig) {
-  if (!authConfig) {
+  if (!authConfig || !authConfig.customJwtAuthorizer) {
     return null;
   }
 
+  const jwtConfig = authConfig.customJwtAuthorizer;
+
+  if (!jwtConfig.discoveryUrl) {
+    throw new Error('Gateway CustomJWTAuthorizer requires discoveryUrl');
+  }
+
   return {
-    ...(authConfig.allowedAudiences && { AllowedAudiences: authConfig.allowedAudiences }),
-    ...(authConfig.allowedClients && { AllowedClients: authConfig.allowedClients }),
-    ...(authConfig.allowedIssuers && { AllowedIssuers: authConfig.allowedIssuers }),
+    CustomJWTAuthorizer: {
+      DiscoveryUrl: jwtConfig.discoveryUrl,
+      ...(jwtConfig.allowedAudience && { AllowedAudience: jwtConfig.allowedAudience }),
+      ...(jwtConfig.allowedClients && { AllowedClients: jwtConfig.allowedClients }),
+    },
   };
 }
 

package/src/compilers/memory.js

@@ -109,6 +109,7 @@ function buildMemoryStrategies(strategies) {
     if (isLegacyFormat(strategy)) {
       // Emit deprecation warning once per deployment
       if (!deprecationWarningShown) {
+        // eslint-disable-next-line no-console -- Intentional user-facing deprecation warning
         console.warn(
           '\x1b[33m%s\x1b[0m', // Yellow color
           'DEPRECATION WARNING: Memory strategy format has changed to typed union structure. ' +

package/src/compilers/runtime.js

@@ -182,6 +182,26 @@ function buildRequestHeaderConfiguration(requestHeaders) {
   };
 }
 
+/**
+ * Build resource-based policy for the runtime
+ * Allows cross-account or cross-principal access to invoke the agent
+ *
+ * @param {Object} resourcePolicy - The resource policy configuration from serverless.yml
+ * @returns {Object|null} CloudFormation ResourcePolicy or null
+ */
+function buildResourcePolicy(resourcePolicy) {
+  if (!resourcePolicy || !resourcePolicy.Statement || resourcePolicy.Statement.length === 0) {
+    return null;
+  }
+
+  // CloudFormation expects the policy as a JSON object
+  // The policy should be in standard IAM policy document format
+  return {
+    Version: resourcePolicy.Version || '2012-10-17',
+    Statement: resourcePolicy.Statement,
+  };
+}
+
 /**
  * Compile a Runtime resource to CloudFormation
  *
@@ -203,6 +223,7 @@ function compileRuntime(name, config, context, tags) {
   const protocolConfig = buildProtocolConfiguration(config.protocol);
   const envVars = buildEnvironmentVariables(config.environment);
   const requestHeaderConfig = buildRequestHeaderConfiguration(config.requestHeaders);
+  const resourcePolicy = buildResourcePolicy(config.resourcePolicy);
 
   return {
     Type: 'AWS::BedrockAgentCore::Runtime',
@@ -217,6 +238,7 @@ function compileRuntime(name, config, context, tags) {
       ...(protocolConfig && { ProtocolConfiguration: protocolConfig }),
       ...(envVars && { EnvironmentVariables: envVars }),
       ...(requestHeaderConfig && { RequestHeaderConfiguration: requestHeaderConfig }),
+      ...(resourcePolicy && { ResourcePolicy: resourcePolicy }),
       ...(Object.keys(tags).length > 0 && { Tags: tags }),
     },
   };
@@ -231,4 +253,5 @@ module.exports = {
   buildProtocolConfiguration,
   buildEnvironmentVariables,
   buildRequestHeaderConfiguration,
+  buildResourcePolicy,
 };

package/src/index.js

@@ -309,7 +309,7 @@ class ServerlessBedrockAgentCore {
    * Validate gateway configuration
    */
   validateGateway(name, config) {
-    const validAuthTypes = ['AWS_IAM', 'CUSTOM_JWT'];
+    const validAuthTypes = ['NONE', 'AWS_IAM', 'CUSTOM_JWT'];
     if (config.authorizerType && !validAuthTypes.includes(config.authorizerType)) {
       throw new this.serverless.classes.Error(
         `Gateway '${name}' has invalid authorizerType '${config.authorizerType}'. Valid types: ${validAuthTypes.join(', ')}`

package/src/validators/schema.js

@@ -101,6 +101,57 @@ function defineAgentsSchema(serverless) {
             maxConcurrency: { type: 'number' },
           },
         },
+        resourcePolicy: {
+          type: 'object',
+          properties: {
+            Version: { type: 'string' },
+            Statement: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  Sid: { type: 'string' },
+                  Effect: {
+                    type: 'string',
+                    enum: ['Allow', 'Deny'],
+                  },
+                  Principal: { type: 'object' },
+                  Action: {
+                    oneOf: [
+                      { type: 'string' },
+                      {
+                        type: 'array',
+                        items: { type: 'string' },
+                      },
+                    ],
+                  },
+                  Resource: {
+                    oneOf: [
+                      { type: 'string' },
+                      {
+                        type: 'array',
+                        items: { type: 'string' },
+                      },
+                    ],
+                  },
+                  Condition: { type: 'object' },
+                },
+                required: ['Effect', 'Principal', 'Action'],
+              },
+            },
+          },
+          required: ['Statement'],
+        },
+        requestHeaders: {
+          type: 'object',
+          properties: {
+            allowlist: {
+              type: 'array',
+              items: { type: 'string' },
+              maxItems: 20,
+            },
+          },
+        },
         endpoints: {
           type: 'array',
           items: {
@@ -126,28 +177,17 @@ function defineAgentsSchema(serverless) {
           type: 'array',
           items: {
             type: 'object',
-            properties: {
-              type: {
-                type: 'string',
-                enum: ['semantic', 'userPreference', 'summary', 'custom'],
-              },
-              name: { type: 'string' },
-              namespaces: {
-                type: 'array',
-                items: { type: 'string' },
-              },
-              configuration: {
-                type: 'object',
-              },
-            },
-            required: ['type', 'name'],
+            // Supports both legacy format and new typed union format
+            // Legacy: { type: 'semantic', name: 'Search', ... }
+            // New: { SemanticMemoryStrategy: { Name: 'Search', ... } }
+            additionalProperties: true,
           },
         },
 
         // Gateway-specific properties
         authorizerType: {
           type: 'string',
-          enum: ['AWS_IAM', 'CUSTOM_JWT'],
+          enum: ['NONE', 'AWS_IAM', 'CUSTOM_JWT'],
         },
         protocolType: {
           type: 'string',
@@ -156,17 +196,20 @@ function defineAgentsSchema(serverless) {
         authorizerConfiguration: {
           type: 'object',
           properties: {
-            allowedAudiences: {
-              type: 'array',
-              items: { type: 'string' },
-            },
-            allowedClients: {
-              type: 'array',
-              items: { type: 'string' },
-            },
-            allowedIssuers: {
-              type: 'array',
-              items: { type: 'string' },
+            customJwtAuthorizer: {
+              type: 'object',
+              properties: {
+                discoveryUrl: { type: 'string' },
+                allowedAudience: {
+                  type: 'array',
+                  items: { type: 'string' },
+                },
+                allowedClients: {
+                  type: 'array',
+                  items: { type: 'string' },
+                },
+              },
+              required: ['discoveryUrl'],
             },
           },
         },