feat(bedrock-alpha): add guardrails l2 construct

packages/@aws-cdk/aws-bedrock-alpha/bedrock/agents/agent.ts

@@ -16,6 +16,7 @@ import { AgentCollaborator } from './agent-collaborator';
 import { AgentCollaboration } from './agent-collaboration';
 import { PromptOverrideConfiguration } from './prompt-override';
 import { AssetApiSchema, S3ApiSchema } from './api-schema';
+import { IGuardrail } from '../guardrails/guardrails';
 import * as validation from './validation-helpers';
 import { IBedrockInvokable } from '.././models';
 import { Memory } from './memory';
@@ -178,7 +179,6 @@ export abstract class AgentBase extends Resource implements IAgent {
 /**
  * Properties for creating a CDK managed Bedrock Agent.
  * TODO: Knowledge bases configuration will be added in a future update
- * TODO: Guardrails configuration will be added in a future update
  * TODO: Inference profile configuration will be added in a future update
  *
  */
@@ -241,7 +241,11 @@ export interface AgentProps {
    * @default - Only default action groups (UserInput and CodeInterpreter) are added
    */
   readonly actionGroups?: AgentActionGroup[];
-
+  /**
+   * The guardrail that will be associated with the agent.
+   * @default - No guardrail is provided.
+   */
+  readonly guardrail?: IGuardrail;
   /**
    * Overrides some prompt templates in different parts of an agent sequence configuration.
    *
@@ -408,7 +412,10 @@ export class Agent extends AgentBase implements IAgent {
    * action groups associated with the ageny
    */
   public readonly actionGroups: AgentActionGroup[] = [];
-
+  /**
+   * The guardrail that will be associated with the agent.
+   */
+  public guardrail?: IGuardrail;
   // ------------------------------------------------------
   // CDK-only attributes
   // ------------------------------------------------------
@@ -519,6 +526,10 @@ export class Agent extends AgentBase implements IAgent {
       });
     }
 
+    if (props.guardrail) {
+      this.addGuardrail(props.guardrail);
+    }
+
     // Grant permissions for custom orchestration if provided
     if (this.customOrchestrationExecutor?.lambdaFunction) {
       this.customOrchestrationExecutor.lambdaFunction.grantInvoke(this.role);
@@ -540,6 +551,7 @@ export class Agent extends AgentBase implements IAgent {
       customerEncryptionKeyArn: props.kmsKey?.keyArn,
       description: props.description,
       foundationModel: this.foundationModel.invokableArn,
+      guardrailConfiguration: Lazy.any({ produce: () => this.renderGuardrail() }),
       idleSessionTtlInSeconds: this.idleSessionTTL.toSeconds(),
       instruction: props.instruction,
       memoryConfiguration: props.memory?._render(),
@@ -581,6 +593,19 @@ export class Agent extends AgentBase implements IAgent {
   // HELPER METHODS - addX()
   // ------------------------------------------------------
 
+  /**
+   * Add guardrail to the agent.
+   */
+  @MethodMetadata()
+  public addGuardrail(guardrail: IGuardrail) {
+    // Do some checks
+    validation.throwIfInvalid(this.validateGuardrail, guardrail);
+    // Add it to the construct
+    this.guardrail = guardrail;
+    // Handle permissions
+    guardrail.grantApply(this.role);
+  }
+
   /**
    * Adds an action group to the agent and configures necessary permissions.
    *
@@ -662,6 +687,20 @@ export class Agent extends AgentBase implements IAgent {
   // Lazy Renderers
   // ------------------------------------------------------
 
+  /**
+   * Render the guardrail configuration.
+   *
+   * @internal This is an internal core function and should not be called directly.
+   */
+  private renderGuardrail(): bedrock.CfnAgent.GuardrailConfigurationProperty | undefined {
+    return this.guardrail
+      ? {
+        guardrailIdentifier: this.guardrail.guardrailId,
+        guardrailVersion: this.guardrail.guardrailVersion,
+      }
+      : undefined;
+  }
+
   /**
    * Render the action groups
    *
@@ -715,6 +754,24 @@ export class Agent extends AgentBase implements IAgent {
   // ------------------------------------------------------
   // Validators
   // ------------------------------------------------------
+  /**
+   * Checks if the Guardrail is valid
+   *
+   * @param guardrail - The guardrail to validate
+   * @returns Array of validation error messages, empty if valid
+   */
+  private validateGuardrail = (guardrail: IGuardrail) => {
+    let errors: string[] = [];
+    if (this.guardrail) {
+      errors.push(
+        `Cannot add Guardrail ${guardrail.guardrailId}. ` +
+          `Guardrail ${this.guardrail.guardrailId} has already been specified for this agent.`,
+      );
+    }
+    errors.push(...validation.validateFieldPattern(guardrail.guardrailVersion, 'version', /^(([0-9]{1,8})|(DRAFT))$/));
+    return errors;
+  };
+
   /**
    * Check if the action group is valid
    *