@aws-cdk/aws-bedrock-agentcore-alpha 2.225.0-alpha.0 → 2.227.0-alpha.0

package/agentcore/gateway/gateway.d.ts

@@ -0,0 +1,383 @@
+import * as cognito from 'aws-cdk-lib/aws-cognito';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as kms from 'aws-cdk-lib/aws-kms';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
+import { Construct } from 'constructs';
+import { GatewayBase, GatewayExceptionLevel, IGateway } from './gateway-base';
+import { IGatewayAuthorizerConfig } from './inbound-auth/authorizer';
+import { ICredentialProviderConfig } from './outbound-auth/credential-provider';
+import { IGatewayProtocolConfig } from './protocol';
+import { ApiSchema } from './targets/schema/api-schema';
+import { ToolSchema } from './targets/schema/tool-schema';
+import { GatewayTarget } from './targets/target';
+/******************************************************************************
+ *                                Props
+ *****************************************************************************/
+/**
+ * Options for adding a Lambda target to a gateway
+ */
+export interface AddLambdaTargetOptions {
+    /**
+     * The name of the gateway target
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen)
+     */
+    readonly gatewayTargetName: string;
+    /**
+     * Optional description for the gateway target
+     * @default - No description
+     */
+    readonly description?: string;
+    /**
+     * The Lambda function to associate with this target
+     */
+    readonly lambdaFunction: IFunction;
+    /**
+     * The tool schema defining the available tools
+     */
+    readonly toolSchema: ToolSchema;
+    /**
+     * Credential providers for authentication
+     * @default - [GatewayCredentialProvider.iamRole()]
+     */
+    readonly credentialProviderConfigurations?: ICredentialProviderConfig[];
+}
+/**
+ * Options for adding an OpenAPI target to a gateway
+ */
+export interface AddOpenApiTargetOptions {
+    /**
+     * The name of the gateway target
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen)
+     */
+    readonly gatewayTargetName: string;
+    /**
+     * Optional description for the gateway target
+     * @default - No description
+     */
+    readonly description?: string;
+    /**
+     * The OpenAPI schema defining the API
+     */
+    readonly apiSchema: ApiSchema;
+    /**
+     * Whether to validate the OpenAPI schema or not
+     * Note: Validation is only performed for inline and asset-based schema and  during CDK synthesis.
+     * S3 schemas cannot be validated at synthesis time.
+     * @default true
+     */
+    readonly validateOpenApiSchema?: boolean;
+    /**
+     * Credential providers for authentication
+     * @default - [GatewayCredentialProvider.iamRole()]
+     */
+    readonly credentialProviderConfigurations?: ICredentialProviderConfig[];
+}
+/**
+ * Options for adding a Smithy target to a gateway
+ */
+export interface AddSmithyTargetOptions {
+    /**
+     * The name of the gateway target
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen)
+     */
+    readonly gatewayTargetName: string;
+    /**
+     * Optional description for the gateway target
+     * @default - No description
+     */
+    readonly description?: string;
+    /**
+     * The Smithy model defining the API
+     */
+    readonly smithyModel: ApiSchema;
+    /**
+     * Credential providers for authentication
+     * @default - [GatewayCredentialProvider.iamRole()]
+     */
+    readonly credentialProviderConfigurations?: ICredentialProviderConfig[];
+}
+/**
+ * Options for adding an MCP Server target to a gateway
+ */
+export interface AddMcpServerTargetOptions {
+    /**
+     * The name of the gateway target
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen)
+     */
+    readonly gatewayTargetName: string;
+    /**
+     * Optional description for the gateway target
+     * @default - No description
+     */
+    readonly description?: string;
+    /**
+     * The HTTPS endpoint URL of the MCP server
+     *
+     * The endpoint must:
+     * - Use HTTPS protocol
+     * - Be properly URL-encoded
+     * - Point to an MCP server that implements tool capabilities
+     */
+    readonly endpoint: string;
+    /**
+     * Credential providers for authentication
+     *
+     * MCP servers require explicit authentication configuration.
+     * OAuth2 is strongly recommended over NoAuth.
+     */
+    readonly credentialProviderConfigurations: ICredentialProviderConfig[];
+}
+/**
+ * Properties for defining a Gateway
+ */
+export interface GatewayProps {
+    /**
+     * The name of the gateway
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen)
+     * The name must be unique within your account
+     */
+    readonly gatewayName: string;
+    /**
+     * Optional description for the gateway
+     * Valid characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and spaces
+     * The description can have up to 200 characters
+     * @default - No description
+     */
+    readonly description?: string;
+    /**
+     * The protocol configuration for the gateway
+     * @default - A default protocol configuration will be created using MCP with following params
+     *  supportedVersions: [MCPProtocolVersion.MCP_2025_03_26],
+     *  searchType: McpGatewaySearchType.SEMANTIC,
+     *  instructions: "Default gateway to connect to external MCP tools",
+     */
+    readonly protocolConfiguration?: IGatewayProtocolConfig;
+    /**
+     * The authorizer configuration for the gateway
+     * @default - A default authorizer will be created using Cognito
+     */
+    readonly authorizerConfiguration?: IGatewayAuthorizerConfig;
+    /**
+     * The verbosity of exception messages
+     * Use DEBUG mode to see granular exception messages from a Gateway
+     * @default - Exception messages are sanitized for presentation to end users
+     */
+    readonly exceptionLevel?: GatewayExceptionLevel;
+    /**
+     * The AWS KMS key used to encrypt data associated with the gateway
+     * @default - No encryption
+     */
+    readonly kmsKey?: kms.IKey;
+    /**
+     * The IAM role that provides permissions for the gateway to access AWS services
+     * @default - A new role will be created
+     */
+    readonly role?: iam.IRole;
+    /**
+     * Tags for the gateway
+     * A list of key:value pairs of tags to apply to this Gateway resource
+     * @default - No tags
+     */
+    readonly tags?: {
+        [key: string]: string;
+    };
+}
+/**
+ * Attributes for importing an existing Gateway
+ */
+export interface GatewayAttributes {
+    /**
+     * The ARN of the gateway
+     */
+    readonly gatewayArn: string;
+    /**
+     * The ID of the gateway
+     */
+    readonly gatewayId: string;
+    /**
+     * The name of the gateway
+     */
+    readonly gatewayName: string;
+    /**
+     * The IAM role that provides permissions for the gateway
+     */
+    readonly role: iam.IRole;
+}
+/******************************************************************************
+ *                                Class
+ *****************************************************************************/
+/**
+ * Gateway resource for AWS Bedrock Agent Core.
+ * Serves as an integration point between your agent and external services.
+ *
+ * @resource AWS::BedrockAgentCore::Gateway
+ * @see https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html
+ */
+export declare class Gateway extends GatewayBase {
+    /** Uniquely identifies this class. */
+    static readonly PROPERTY_INJECTION_ID: string;
+    /**
+     * Import an existing Gateway using its attributes
+     *
+     * @param scope The construct scope
+     * @param id The construct id
+     * @param attrs The attributes of the existing Gateway
+     * @returns An IGateway instance representing the imported gateway
+     */
+    static fromGatewayAttributes(scope: Construct, id: string, attrs: GatewayAttributes): IGateway;
+    /**
+     * The ARN of the gateway
+     * @attribute
+     */
+    readonly gatewayArn: string;
+    /**
+     * The unique identifier of the gateway
+     * @attribute
+     */
+    readonly gatewayId: string;
+    /**
+     * The name of the gateway
+     */
+    readonly name: string;
+    /**
+     * The description of the gateway
+     */
+    readonly description?: string;
+    /**
+     * The protocol configuration for the gateway
+     */
+    readonly protocolConfiguration: IGatewayProtocolConfig;
+    /**
+     * The authorizer configuration for the gateway
+     */
+    readonly authorizerConfiguration: IGatewayAuthorizerConfig;
+    /**
+     * The exception level for the gateway
+     */
+    readonly exceptionLevel?: GatewayExceptionLevel;
+    /**
+     * The KMS key used for encryption
+     */
+    readonly kmsKey?: kms.IKey;
+    /**
+     * The IAM role for the gateway
+     */
+    readonly role: iam.IRole;
+    /**
+     * The URL endpoint for the gateway
+     * @attribute
+     */
+    readonly gatewayUrl?: string;
+    /**
+     * The status of the gateway
+     * @attribute
+     */
+    readonly status?: string;
+    /**
+     * The status reasons for the gateway
+     * @attribute
+     */
+    readonly statusReason?: string[];
+    /**
+     * Timestamp when the gateway was created
+     * @attribute
+     */
+    readonly createdAt?: string;
+    /**
+     * Timestamp when the gateway was last updated
+     * @attribute
+     */
+    readonly updatedAt?: string;
+    /**
+     * Tags applied to the gateway
+     */
+    readonly tags?: {
+        [key: string]: string;
+    };
+    /**
+     * The Cognito User Pool created for the gateway (if using default Cognito authorizer)
+     */
+    userPool?: cognito.IUserPool;
+    /**
+     * The Cognito User Pool Client created for the gateway (if using default Cognito authorizer)
+     */
+    userPoolClient?: cognito.IUserPoolClient;
+    constructor(scope: Construct, id: string, props: GatewayProps);
+    /**
+     * Add a Lambda target to this gateway
+     * This is a convenience method that creates a GatewayTarget associated with this gateway
+     *
+     * @param id The construct id for the target
+     * @param props Properties for the Lambda target
+     * @returns The created GatewayTarget
+     */
+    addLambdaTarget(id: string, props: AddLambdaTargetOptions): GatewayTarget;
+    /**
+     * Add an OpenAPI target to this gateway
+     * This is a convenience method that creates a GatewayTarget associated with this gateway
+     *
+     * @param id The construct id for the target
+     * @param props Properties for the OpenAPI target
+     * @returns The created GatewayTarget
+     */
+    addOpenApiTarget(id: string, props: AddOpenApiTargetOptions): GatewayTarget;
+    /**
+     * Add a Smithy target to this gateway
+     * This is a convenience method that creates a GatewayTarget associated with this gateway
+     *
+     * @param id The construct id for the target
+     * @param props Properties for the Smithy target
+     * @returns The created GatewayTarget
+     */
+    addSmithyTarget(id: string, props: AddSmithyTargetOptions): GatewayTarget;
+    /**
+     * Add an MCP server target to this gateway
+     * This is a convenience method that creates a GatewayTarget associated with this gateway
+     *
+     * @param id The construct id for the target
+     * @param props Properties for the MCP server target
+     * @returns The created GatewayTarget
+     * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html
+     */
+    addMcpServerTarget(id: string, props: AddMcpServerTargetOptions): GatewayTarget;
+    /**
+     * Creates the service role for the gateway to assume
+     *
+     * The service role starts with minimal permissions. Additional permissions
+     * are added automatically when targets are configured:
+     * - KMS encryption: Automatically grants encrypt/decrypt permissions
+     *
+     * For other target types, manually grant permissions using standard CDK grant methods:
+     * @internal
+     */
+    private createGatewayRole;
+    /**
+     * Validates the gateway name format
+     * Pattern: ^([0-9a-zA-Z][-]?){1,100}$
+     * Max length: 48 characters
+     * @param name The gateway name to validate
+     * @throws Error if the name is invalid
+     * @internal
+     */
+    private validateGatewayName;
+    /**
+     * Validates the description format
+     * Max length: 200 characters
+     * @param description The description to validate
+     * @throws Error if validation fails
+     * @internal
+     */
+    private validateDescription;
+    /**
+     * Creates a default Cognito authorizer for the gateway
+     * Provisions a Cognito User Pool and configures JWT authentication
+     * @internal
+     */
+    private createDefaultCognitoAuthorizerConfig;
+    /**
+     * Creates a default MCP protocol configuration for the gateway
+     * Provides sensible defaults for MCP protocol settings
+     * @internal
+     */
+    private createDefaultMcpProtocolConfiguration;
+}