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

package/agentcore/gateway/targets/target.d.ts

@@ -0,0 +1,345 @@
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
+import { Construct } from 'constructs';
+import { IGateway } from '../gateway-base';
+import { ApiSchema } from './schema/api-schema';
+import { ToolSchema } from './schema/tool-schema';
+import { GatewayTargetBase, GatewayTargetProtocolType, IGatewayTarget, IMcpGatewayTarget, McpTargetType } from './target-base';
+import { ITargetConfiguration } from './target-configuration';
+import { ICredentialProviderConfig } from '../outbound-auth/credential-provider';
+/******************************************************************************
+ *                                Props
+ *****************************************************************************/
+/**
+ * Common properties for all Gateway Target types
+ */
+export interface GatewayTargetCommonProps {
+    /**
+     * The name of the gateway target
+     * The name must be unique within the gateway
+     * Pattern: ^([0-9a-zA-Z][-]?){1,100}$
+     */
+    readonly gatewayTargetName: string;
+    /**
+     * Optional description for the gateway target
+     * The description can have up to 200 characters
+     * @default - No description
+     */
+    readonly description?: string;
+}
+/**
+ * Properties for creating a Gateway Target resource
+ */
+export interface GatewayTargetProps extends GatewayTargetCommonProps {
+    /**
+     * The gateway this target belongs to
+     */
+    readonly gateway: IGateway;
+    /**
+     * The target configuration (Lambda, OpenAPI, or Smithy)
+     * Use one of the configuration helper classes:
+     * - LambdaTargetConfiguration.create()
+     * - OpenApiTargetConfiguration.create()
+     * - SmithyTargetConfiguration.create()
+     */
+    readonly targetConfiguration: ITargetConfiguration;
+    /**
+     * Credential providers for authentication
+     * @default - [GatewayCredentialProvider.fromIamRole()]
+     */
+    readonly credentialProviderConfigurations?: ICredentialProviderConfig[];
+}
+/**
+ * Properties for creating a Lambda-based Gateway Target
+ * Convenience interface for the most common use case
+ */
+export interface GatewayTargetLambdaProps extends GatewayTargetCommonProps {
+    /**
+     * The gateway this target belongs to
+     */
+    readonly gateway: IGateway;
+    /**
+     * 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
+     * Lambda targets only support IAM role authentication
+     * @default - [GatewayCredentialProvider.fromIamRole()]
+     */
+    readonly credentialProviderConfigurations?: ICredentialProviderConfig[];
+}
+/**
+ * Properties for creating an OpenAPI-based Gateway Target
+ */
+export interface GatewayTargetOpenApiProps extends GatewayTargetCommonProps {
+    /**
+     * The gateway this target belongs to
+     */
+    readonly gateway: IGateway;
+    /**
+     * The OpenAPI schema defining the API
+     */
+    readonly apiSchema: ApiSchema;
+    /**
+     * Whether to validate the OpenAPI schema (only applies to inline schemas)
+     * Note: Validation is only performed for inline schemas during CDK synthesis.
+     * S3 and asset-based schemas cannot be validated at synthesis time.
+     * @default true
+     */
+    readonly validateOpenApiSchema?: boolean;
+    /**
+     * Credential providers for authentication
+     * OpenAPI targets support API key and OAuth authentication (not IAM)
+     * @default: If not provided, defaults to IAM role which will fail at runtime
+     */
+    readonly credentialProviderConfigurations?: ICredentialProviderConfig[];
+}
+/**
+ * Properties for creating a Smithy-based Gateway Target
+ */
+export interface GatewayTargetSmithyProps extends GatewayTargetCommonProps {
+    /**
+     * The gateway this target belongs to
+     */
+    readonly gateway: IGateway;
+    /**
+     * The Smithy model defining the API
+     */
+    readonly smithyModel: ApiSchema;
+    /**
+     * Credential providers for authentication
+     * Smithy targets only support IAM role authentication
+     * @default - [GatewayCredentialProvider.fromIamRole()]
+     */
+    readonly credentialProviderConfigurations?: ICredentialProviderConfig[];
+}
+/**
+ * Properties for creating an MCP Server-based Gateway Target
+ */
+export interface GatewayTargetMcpServerProps extends GatewayTargetCommonProps {
+    /**
+     * The gateway this target belongs to
+     */
+    readonly gateway: IGateway;
+    /**
+     * 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
+     */
+    readonly credentialProviderConfigurations: ICredentialProviderConfig[];
+}
+/**
+ * Attributes for importing an existing Gateway Target
+ */
+export interface GatewayTargetAttributes {
+    /**
+     * The ARN of the gateway target
+     */
+    readonly targetArn: string;
+    /**
+     * The ID of the gateway target
+     */
+    readonly targetId: string;
+    /**
+     * The name of the gateway target
+     */
+    readonly gatewayTargetName: string;
+    /**
+     * The gateway this target belongs to
+     */
+    readonly gateway: IGateway;
+    /**
+     * Optional status of the target
+     * @default - No status
+     */
+    readonly status?: string;
+    /**
+     * Optional creation timestamp
+     * @default - No creation timestamp
+     */
+    readonly createdAt?: string;
+    /**
+     * Optional last update timestamp
+     * @default - No update timestamp
+     */
+    readonly updatedAt?: string;
+}
+/******************************************************************************
+ *                                Class
+ *****************************************************************************/
+/**
+ *
+ * Defines tools that your gateway will host. Supports multiple target types:
+ * - Lambda: Wraps a Lambda function as MCP tools
+ * - OpenAPI: Exposes an OpenAPI/REST API as MCP tools
+ * - Smithy: Exposes a Smithy-modeled API as MCP tools
+ *
+ * @resource AWS::BedrockAgentCore::GatewayTarget
+ * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html
+ */
+export declare class GatewayTarget extends GatewayTargetBase implements IMcpGatewayTarget {
+    /** Uniquely identifies this class. */
+    static readonly PROPERTY_INJECTION_ID: string;
+    /**
+     * Import an existing Gateway Target using its attributes
+     * This allows you to reference a Gateway Target that was created outside of CDK
+     *
+     * @param scope The construct scope
+     * @param id The construct id
+     * @param attrs The attributes of the existing Gateway Target
+     * @returns An IGatewayTarget instance representing the imported target
+     */
+    static fromGatewayTargetAttributes(scope: Construct, id: string, attrs: GatewayTargetAttributes): IGatewayTarget;
+    /**
+     * Create a Lambda-based MCP target
+     * Convenience method for creating a target that wraps a Lambda function
+     *
+     * @param scope The construct scope
+     * @param id The construct id
+     * @param props The properties for the Lambda target
+     * @returns A new GatewayTarget instance
+     */
+    static forLambda(scope: Construct, id: string, props: GatewayTargetLambdaProps): GatewayTarget;
+    /**
+     * Create an OpenAPI-based MCP target
+     * Convenience method for creating a target that exposes an OpenAPI/REST API
+     *
+     * @param scope The construct scope
+     * @param id The construct id
+     * @param props The properties for the OpenAPI target
+     * @returns A new GatewayTarget instance
+     *
+     */
+    static forOpenApi(scope: Construct, id: string, props: GatewayTargetOpenApiProps): GatewayTarget;
+    /**
+     * Create a Smithy-based MCP target
+     * Convenience method for creating a target that exposes a Smithy-modeled API
+     *
+     * @param scope The construct scope
+     * @param id The construct id
+     * @param props The properties for the Smithy target
+     * @returns A new GatewayTarget instance
+     */
+    static forSmithy(scope: Construct, id: string, props: GatewayTargetSmithyProps): GatewayTarget;
+    /**
+     * Create an MCP Server-based target
+     * Convenience method for creating a target that connects to an external MCP server
+     *
+     * @param scope The construct scope
+     * @param id The construct id
+     * @param props The properties for the MCP server target
+     * @returns A new GatewayTarget instance
+     * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html
+     */
+    static forMcpServer(scope: Construct, id: string, props: GatewayTargetMcpServerProps): GatewayTarget;
+    /**
+     * The ARN of the gateway target
+     * @attribute
+     */
+    readonly targetArn: string;
+    /**
+     * The unique identifier of the gateway target
+     * @attribute
+     */
+    readonly targetId: string;
+    /**
+     * The name of the gateway target
+     */
+    readonly name: string;
+    /**
+     * Optional description for the gateway target
+     */
+    readonly description: string | undefined;
+    /**
+     * The gateway this target belongs to
+     */
+    readonly gateway: IGateway;
+    /**
+     * The credential providers for this target
+     */
+    readonly credentialProviderConfigurations: ICredentialProviderConfig[] | undefined;
+    /**
+     * The protocol type (always MCP for now)
+     */
+    readonly targetProtocolType = GatewayTargetProtocolType.MCP;
+    /**
+     * The specific MCP target type (Lambda, OpenAPI, Smithy, or MCP Server)
+     */
+    readonly targetType: McpTargetType;
+    /**
+     * The status of the gateway target
+     * @attribute
+     */
+    readonly status?: string | undefined;
+    /**
+     * The status reasons for the gateway target
+     * @attribute
+     */
+    readonly statusReasons?: string[];
+    /**
+     * Timestamp when the gateway target was created
+     * @attribute
+     */
+    readonly createdAt?: string | undefined;
+    /**
+     * Timestamp when the gateway target was last updated
+     * @attribute
+     */
+    readonly updatedAt?: string | undefined;
+    private readonly targetResource;
+    private readonly targetConfiguration;
+    constructor(scope: Construct, id: string, props: GatewayTargetProps);
+    /**
+     * Grants permission to synchronize this gateway's targets
+     *
+     * This method grants the `SynchronizeGatewayTargets` permission, which is primarily
+     * needed for MCP Server targets when you need to refresh the tool catalog after the
+     * MCP server's tools have changed.
+     */
+    grantSync(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Determines the credential provider configurations based on target type
+     *
+     * - Lambda & Smithy: Default to IAM role if not provided
+     * - MCP Server: Return undefined if not provided (service handles NoAuth)
+     * - OpenAPI: Return as-is (must be explicitly provided)
+     *
+     * @param providedCredentials The credentials from props
+     * @returns The credential configurations to use, or undefined
+     * @internal
+     */
+    private _getTargetSpecificCredentials;
+    /**
+     * Renders credential provider configurations for CloudFormation
+     * @internal
+     */
+    private _renderCredentialProviderConfigurations;
+    /**
+     * Validates the gateway target name format
+     * Pattern: ^([0-9a-zA-Z][-]?){1,100}$
+     * Max length: 100 characters
+     * @param gatewayTargetName The gateway target name to validate
+     * @throws Error if the name is invalid
+     * @internal
+     */
+    private validateGatewayTargetName;
+    /**
+     * Validates the description format
+     * Must be between 1 and 200 characters
+     * @throws Error if validation fails
+     * @internal
+     */
+    private validateDescription;
+}