@cdklabs/cdk-appmod-catalog-blueprints 1.7.0 → 1.8.0

package/.jsii

@@ -4114,7 +4114,7 @@
     "stability": "experimental"
   },
   "homepage": "https://github.com/cdklabs/cdk-appmod-catalog-blueprints.git",
-  "jsiiVersion": "5.9.22 (build b81c634)",
+  "jsiiVersion": "5.9.25 (build bd30271)",
   "keywords": [
     "cdk"
   ],
@@ -5126,7 +5126,10 @@
       "assembly": "@cdklabs/cdk-appmod-catalog-blueprints",
       "base": "constructs.Construct",
       "docs": {
-        "stability": "experimental"
+        "remarks": "Provides common infrastructure for AI agents including:\n- IAM role and permissions management\n- Encryption key for environment variables\n- Tool integration and S3 asset management\n- Knowledge base integration for RAG (Retrieval-Augmented Generation)\n- Observability configuration (Lambda Powertools + AgentCore)\n\nSubclasses must implement the agent-specific Lambda function creation.\n\n**Observability**: When `enableObservability: true`, BaseAgent configures both\nLambda Powertools (function-level) and AWS Bedrock AgentCore (agent-level)\nobservability. Both systems work together to provide complete visibility:\n- Lambda Powertools captures function execution, logs, and custom metrics\n- AgentCore captures agent reasoning, tool usage, and token consumption\n- Both publish to CloudWatch with correlated service names for unified monitoring\n\nThe observability integration includes:\n- Automatic IAM permission grants for CloudWatch Logs and X-Ray\n- Environment variable configuration for OpenTelemetry\n- ADOT Lambda Layer attachment (handled by concrete implementations)",
+        "see": "https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html",
+        "stability": "experimental",
+        "summary": "Base class for all agent types in the framework."
       },
       "fqn": "@cdklabs/cdk-appmod-catalog-blueprints.BaseAgent",
       "initializer": {
@@ -5135,7 +5138,7 @@
         },
         "locationInModule": {
           "filename": "use-cases/framework/agents/base-agent.ts",
-          "line": 153
+          "line": 218
         },
         "parameters": [
           {
@@ -5161,8 +5164,32 @@
       "kind": "class",
       "locationInModule": {
         "filename": "use-cases/framework/agents/base-agent.ts",
-        "line": 129
+        "line": 186
       },
+      "methods": [
+        {
+          "docs": {
+            "custom": {
+              "throws": "Error if the region is not supported"
+            },
+            "remarks": "The ADOT layer provides automatic instrumentation for observability.\nLayer versions vary by region - some regions have newer versions with\nbetter Python 3.13 support. If you encounter compatibility issues,\nthe layer ARNs can be found at:\nhttps://aws-otel.github.io/docs/getting-started/lambda#adot-lambda-layer-arns",
+            "returns": "The ADOT Lambda Layer for the current region",
+            "stability": "experimental",
+            "summary": "Creates the AWS Distro for OpenTelemetry (ADOT) Lambda Layer."
+          },
+          "locationInModule": {
+            "filename": "use-cases/framework/agents/base-agent.ts",
+            "line": 369
+          },
+          "name": "createADOTLayer",
+          "protected": true,
+          "returns": {
+            "type": {
+              "fqn": "aws-cdk-lib.aws_lambda.ILayerVersion"
+            }
+          }
+        }
+      ],
       "name": "BaseAgent",
       "properties": [
         {
@@ -5173,7 +5200,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 130
+            "line": 187
           },
           "name": "agentFunction",
           "type": {
@@ -5187,7 +5214,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 132
+            "line": 189
           },
           "name": "agentRole",
           "type": {
@@ -5201,7 +5228,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 136
+            "line": 193
           },
           "name": "agentToolsLocationDefinitions",
           "protected": true,
@@ -5221,7 +5248,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 133
+            "line": 190
           },
           "name": "encryptionKey",
           "type": {
@@ -5237,7 +5264,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 144
+            "line": 201
           },
           "name": "knowledgeBaseConfigs",
           "protected": true,
@@ -5250,6 +5277,28 @@
             }
           }
         },
+        {
+          "docs": {
+            "remarks": "This array contains Lambda layers from all configured knowledge bases.\nSubclasses should add these layers to the agent Lambda function to\nensure retrieval tools have access to required dependencies.",
+            "stability": "experimental",
+            "summary": "Lambda layers required by knowledge base retrieval tools."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "use-cases/framework/agents/base-agent.ts",
+            "line": 216
+          },
+          "name": "knowledgeBaseLayers",
+          "protected": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "fqn": "aws-cdk-lib.aws_lambda.LayerVersion"
+              },
+              "kind": "array"
+            }
+          }
+        },
         {
           "docs": {
             "stability": "experimental",
@@ -5258,7 +5307,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 135
+            "line": 192
           },
           "name": "logGroupDataProtection",
           "protected": true,
@@ -5273,7 +5322,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 131
+            "line": 188
           },
           "name": "bedrockModel",
           "optional": true,
@@ -5290,7 +5339,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 151
+            "line": 208
           },
           "name": "knowledgeBaseToolAsset",
           "optional": true,
@@ -5351,17 +5400,37 @@
             "primitive": "string"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "Architecture.ARM_64",
+            "stability": "experimental",
+            "summary": "The architecture used by the Lambda function where the agent is hosted."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "use-cases/framework/agents/base-agent.ts",
+            "line": 157
+          },
+          "name": "agentArchitecture",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_lambda.Architecture"
+          }
+        },
         {
           "abstract": true,
           "docs": {
             "default": "false",
+            "remarks": "When enabled, configures both Lambda Powertools and AWS Bedrock AgentCore observability:\n- **Lambda Powertools**: Provides function-level observability including structured logging,\n  distributed tracing with X-Ray, and custom metrics\n- **AgentCore Observability**: Provides agent-specific observability including agent invocations,\n  reasoning steps, tool usage, token consumption, and agent latency\n\nBoth systems publish to Amazon CloudWatch and use the same service name and namespace\nfor correlation. This provides complete visibility at both function and agent levels.\n\n**Environment Variables Set** (AgentCore):\n- `AGENT_OBSERVABILITY_ENABLED`: Enables AgentCore observability\n- `OTEL_RESOURCE_ATTRIBUTES`: Service identification for OpenTelemetry\n- `OTEL_EXPORTER_OTLP_LOGS_HEADERS`: Agent identification headers\n- `AWS_LAMBDA_EXEC_WRAPPER`: ADOT wrapper for automatic instrumentation\n\n**IAM Permissions Granted** (AgentCore):\n- CloudWatch Logs: `logs:CreateLogGroup`, `logs:CreateLogStream`, `logs:PutLogEvents`\n- X-Ray: `xray:PutTraceSegments`, `xray:PutTelemetryRecords`\n\n**Additional Requirements**:\n- BatchAgent automatically adds ADOT (AWS Distro for OpenTelemetry) Lambda Layer",
+            "see": "https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html",
             "stability": "experimental",
-            "summary": "Enable observability."
+            "summary": "Enable observability for the agent."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 104
+            "line": 127
           },
           "name": "enableObservability",
           "optional": true,
@@ -5379,7 +5448,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 118
+            "line": 141
           },
           "name": "encryptionKey",
           "optional": true,
@@ -5397,7 +5466,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 111
+            "line": 134
           },
           "name": "network",
           "optional": true,
@@ -5415,7 +5484,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/base-agent.ts",
-            "line": 126
+            "line": 149
           },
           "name": "removalPolicy",
           "optional": true,
@@ -6055,7 +6124,7 @@
         },
         "locationInModule": {
           "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-          "line": 74
+          "line": 75
         },
         "parameters": [
           {
@@ -6093,7 +6162,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-        "line": 32
+        "line": 33
       },
       "methods": [
         {
@@ -6105,7 +6174,7 @@
           },
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 125
+            "line": 126
           },
           "name": "exportConfiguration",
           "overrides": "@cdklabs/cdk-appmod-catalog-blueprints.IKnowledgeBase",
@@ -6125,7 +6194,7 @@
           },
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 113
+            "line": 114
           },
           "name": "generateIamPermissions",
           "overrides": "@cdklabs/cdk-appmod-catalog-blueprints.IKnowledgeBase",
@@ -6149,7 +6218,7 @@
           },
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 143
+            "line": 144
           },
           "name": "retrievalToolAsset",
           "overrides": "@cdklabs/cdk-appmod-catalog-blueprints.IKnowledgeBase",
@@ -6160,6 +6229,31 @@
             }
           }
         },
+        {
+          "docs": {
+            "remarks": "By default, returns undefined indicating no additional layers are needed.\nSubclasses can override this method to provide Lambda layers containing\ndependencies required by their retrieval tool.",
+            "returns": "undefined indicating no additional layers needed",
+            "stability": "experimental",
+            "summary": "Provide Lambda layers required by the retrieval tool."
+          },
+          "locationInModule": {
+            "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
+            "line": 157
+          },
+          "name": "retrievalToolLayers",
+          "overrides": "@cdklabs/cdk-appmod-catalog-blueprints.IKnowledgeBase",
+          "returns": {
+            "optional": true,
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "fqn": "aws-cdk-lib.aws_lambda.LayerVersion"
+                },
+                "kind": "array"
+              }
+            }
+          }
+        },
         {
           "docs": {
             "custom": {
@@ -6171,7 +6265,7 @@
           },
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 96
+            "line": 97
           },
           "name": "validateProps",
           "parameters": [
@@ -6199,7 +6293,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 47
+            "line": 48
           },
           "name": "description",
           "overrides": "@cdklabs/cdk-appmod-catalog-blueprints.IKnowledgeBase",
@@ -6216,7 +6310,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 39
+            "line": 40
           },
           "name": "name",
           "overrides": "@cdklabs/cdk-appmod-catalog-blueprints.IKnowledgeBase",
@@ -6233,7 +6327,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 55
+            "line": 56
           },
           "name": "retrievalConfig",
           "protected": true,
@@ -6250,7 +6344,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/base-knowledge-base.ts",
-            "line": 63
+            "line": 64
           },
           "name": "aclConfig",
           "optional": true,
@@ -6368,7 +6462,7 @@
         },
         "locationInModule": {
           "filename": "use-cases/framework/agents/batch-agent.ts",
-          "line": 76
+          "line": 77
         },
         "parameters": [
           {
@@ -6394,7 +6488,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "use-cases/framework/agents/batch-agent.ts",
-        "line": 73
+        "line": 74
       },
       "name": "BatchAgent",
       "properties": [
@@ -6405,7 +6499,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/batch-agent.ts",
-            "line": 74
+            "line": 75
           },
           "name": "agentFunction",
           "overrides": "@cdklabs/cdk-appmod-catalog-blueprints.BaseAgent",
@@ -6429,7 +6523,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "use-cases/framework/agents/batch-agent.ts",
-        "line": 17
+        "line": 18
       },
       "name": "BatchAgentProps",
       "properties": [
@@ -6441,7 +6535,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/batch-agent.ts",
-            "line": 18
+            "line": 19
           },
           "name": "prompt",
           "type": {
@@ -6456,7 +6550,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/batch-agent.ts",
-            "line": 19
+            "line": 20
           },
           "name": "expectJson",
           "optional": true,
@@ -6475,7 +6569,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/batch-agent.ts",
-            "line": 28
+            "line": 29
           },
           "name": "invokeType",
           "optional": true,
@@ -8741,6 +8835,108 @@
       ],
       "symbolId": "use-cases/document-processing/chunking-config:CleanupResponse"
     },
+    "@cdklabs/cdk-appmod-catalog-blueprints.CloudWatchTransactionSearch": {
+      "assembly": "@cdklabs/cdk-appmod-catalog-blueprints",
+      "base": "constructs.Construct",
+      "docs": {
+        "remarks": "This construct configures account-level settings to enable cost-effective\ncollection of all X-Ray spans through CloudWatch Logs. It performs three steps:\n\n1. Creates a CloudWatch Logs resource-based policy allowing X-Ray to send traces\n2. Configures X-Ray to send trace segments to CloudWatch Logs\n3. Sets the sampling percentage for span indexing (default 1%)\n\nThe construct checks if Transaction Search is already enabled and only applies\nconfiguration if needed. It's idempotent and safe to deploy multiple times.\n\n## Benefits\n- Cost-effective: Uses CloudWatch Logs pricing instead of X-Ray pricing\n- Full visibility: All spans are collected and searchable\n- Automatic indexing: 1% of spans indexed by default for trace summaries\n\n## Usage\n```typescript\nnew CloudWatchTransactionSearch(this, 'TransactionSearch', {\n  samplingPercentage: 1  // Optional: 1% is default\n});\n```",
+        "see": "https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Enable-TransactionSearch.html",
+        "stability": "experimental",
+        "summary": "Enables CloudWatch Transaction Search for X-Ray traces."
+      },
+      "fqn": "@cdklabs/cdk-appmod-catalog-blueprints.CloudWatchTransactionSearch",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        },
+        "locationInModule": {
+          "filename": "use-cases/utilities/observability/cloudwatch-transaction-search.ts",
+          "line": 58
+        },
+        "parameters": [
+          {
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "props",
+            "optional": true,
+            "type": {
+              "fqn": "@cdklabs/cdk-appmod-catalog-blueprints.CloudWatchTransactionSearchProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "use-cases/utilities/observability/cloudwatch-transaction-search.ts",
+        "line": 57
+      },
+      "name": "CloudWatchTransactionSearch",
+      "symbolId": "use-cases/utilities/observability/cloudwatch-transaction-search:CloudWatchTransactionSearch"
+    },
+    "@cdklabs/cdk-appmod-catalog-blueprints.CloudWatchTransactionSearchProps": {
+      "assembly": "@cdklabs/cdk-appmod-catalog-blueprints",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental",
+        "summary": "Configuration properties for CloudWatch Transaction Search."
+      },
+      "fqn": "@cdklabs/cdk-appmod-catalog-blueprints.CloudWatchTransactionSearchProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "use-cases/utilities/observability/cloudwatch-transaction-search.ts",
+        "line": 14
+      },
+      "name": "CloudWatchTransactionSearchProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "default": "'TransactionSearchXRayAccess'",
+            "stability": "experimental",
+            "summary": "Name of the CloudWatch Logs resource policy."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "use-cases/utilities/observability/cloudwatch-transaction-search.ts",
+            "line": 27
+          },
+          "name": "policyName",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "1 (1% of spans indexed)",
+            "stability": "experimental",
+            "summary": "Sampling percentage for span indexing."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "use-cases/utilities/observability/cloudwatch-transaction-search.ts",
+            "line": 20
+          },
+          "name": "samplingPercentage",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ],
+      "symbolId": "use-cases/utilities/observability/cloudwatch-transaction-search:CloudWatchTransactionSearchProps"
+    },
     "@cdklabs/cdk-appmod-catalog-blueprints.CloudfrontDistributionObservabilityPropertyInjector": {
       "assembly": "@cdklabs/cdk-appmod-catalog-blueprints",
       "docs": {
@@ -10972,7 +11168,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "use-cases/framework/agents/knowledge-base/i-knowledge-base.ts",
-        "line": 21
+        "line": 22
       },
       "methods": [
         {
@@ -10985,7 +11181,7 @@
           },
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/i-knowledge-base.ts",
-            "line": 65
+            "line": 66
           },
           "name": "exportConfiguration",
           "returns": {
@@ -11004,7 +11200,7 @@
           },
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/i-knowledge-base.ts",
-            "line": 54
+            "line": 55
           },
           "name": "generateIamPermissions",
           "returns": {
@@ -11028,7 +11224,7 @@
           },
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/i-knowledge-base.ts",
-            "line": 76
+            "line": 77
           },
           "name": "retrievalToolAsset",
           "returns": {
@@ -11037,6 +11233,31 @@
               "fqn": "aws-cdk-lib.aws_s3_assets.Asset"
             }
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "This optional method allows knowledge base implementations to provide\nLambda layers containing dependencies needed by their retrieval tool.\nFor example, a knowledge base might need specific boto3 versions,\ncustom libraries, or SDK extensions.\n\nThe layers will be added to the agent's Lambda function, making the\ndependencies available to the retrieval tool at runtime.",
+            "returns": "Array of Lambda LayerVersion objects, or undefined if no layers needed",
+            "stability": "experimental",
+            "summary": "Provide Lambda layers required by the retrieval tool."
+          },
+          "locationInModule": {
+            "filename": "use-cases/framework/agents/knowledge-base/i-knowledge-base.ts",
+            "line": 92
+          },
+          "name": "retrievalToolLayers",
+          "returns": {
+            "optional": true,
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "fqn": "aws-cdk-lib.aws_lambda.LayerVersion"
+                },
+                "kind": "array"
+              }
+            }
+          }
         }
       ],
       "name": "IKnowledgeBase",
@@ -11052,7 +11273,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/i-knowledge-base.ts",
-            "line": 43
+            "line": 44
           },
           "name": "description",
           "type": {
@@ -11070,7 +11291,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "use-cases/framework/agents/knowledge-base/i-knowledge-base.ts",
-            "line": 31
+            "line": 32
           },
           "name": "name",
           "type": {
@@ -13666,6 +13887,6 @@
   "usedFeatures": [
     "class-covariant-overrides"
   ],
-  "version": "1.7.0",
-  "fingerprint": "LgCZEzgklok8vyM/7Y8S0XMXBDqyg7hr8qyVLe4P9xM="
+  "version": "1.8.0",
+  "fingerprint": "CW/GLUUsXU7ov54HZOTjbxdZu1sPRbz3xC9vS0OSABY="
 }