2.259.0

class Gateway (construct) 🔹

LanguageType name
.NETAmazon.CDK.AWS.Bedrock.Agentcore.Alpha.Gateway
Gogithub.com/aws/aws-cdk-go/awsbedrockagentcorealpha/v2#Gateway
Javasoftware.amazon.awscdk.services.bedrock.agentcore.alpha.Gateway
Pythonaws_cdk.aws_bedrock_agentcore_alpha.Gateway
TypeScript (source)@aws-cdk/aws-bedrock-agentcore-alpha » Gateway

Implements IConstruct, IDependable, IResource, IEnvironmentAware, IGateway, IGatewayRef

Gateway resource for AWS Bedrock Agent Core.

Serves as an integration point between your agent and external services.

See also: https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html

Example


// Create a Policy engine
const policyEngine = new agentcore.PolicyEngine(this, "MyPolicyEngine", {
  policyEngineName: "my_policy_engine",
  description: "Policy engine for access control",
});

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
  policyEngineConfiguration: {
    policyEngine: policyEngine,
    mode: agentcore.PolicyEngineMode.ENFORCE, // Default is LOG_ONLY
  },
});

// Add policy to policy engine
policyEngine.addPolicy("AllowAllActions", {
  definition: `
    permit(
      principal,
      action,
      resource == AgentCore::Gateway::"${gateway.gatewayArn}"
    );
  `,
  description: "Allow all actions on specific gateway (development)",
  validationMode: agentcore.PolicyValidationMode.IGNORE_ALL_FINDINGS, // This will ignore all cedar warnings
});

// you can add multiple policies to the policy engine
policyEngine.addPolicy("SpecificToolPolicy", {
  definition: `
    permit(
      principal is AgentCore::OAuthUser,
      action == AgentCore::Action::"WeatherTool__get_forecast",
      resource == AgentCore::Gateway::"${gateway.gatewayArn}"
    );
  `,
  description: "Allow specific weather tool access",
  validationMode: agentcore.PolicyValidationMode.FAIL_ON_ANY_FINDINGS, // This will fail policy creation for any cedar warning
});

Initializer

new Gateway(scope: Construct, id: string, props?: GatewayProps)

Parameters

Construct Props

NameTypeDescription
authorizerConfiguration?⚠️IGatewayAuthorizerConfigThe authorizer configuration for the gateway.
description?⚠️stringOptional 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.
exceptionLevel?⚠️GatewayExceptionLevelThe verbosity of exception messages Use DEBUG mode to see granular exception messages from a Gateway.
gatewayName?⚠️stringThe name of the gateway Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) The name must be unique within your account.
interceptorConfigurations?⚠️IInterceptor[]Interceptor configurations for the gateway.
kmsKey?⚠️IKeyThe AWS KMS key used to encrypt data associated with the gateway.
policyEngineConfiguration?⚠️GatewayPolicyEngineConfigThe policy engine configuration for this gateway.
protocolConfiguration?⚠️IGatewayProtocolConfigThe protocol configuration for the gateway.
role?⚠️IRoleThe IAM role that provides permissions for the gateway to access AWS services.
tags?⚠️{ [string]: string }Tags for the gateway A list of key:value pairs of tags to apply to this Gateway resource.

authorizerConfiguration?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: IGatewayAuthorizerConfig (optional, default: A default authorizer will be created using Cognito)

The authorizer configuration for the gateway.

description?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: string (optional, default: No description)

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.

exceptionLevel?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: GatewayExceptionLevel (optional, default: Exception messages are sanitized for presentation to end users)

The verbosity of exception messages Use DEBUG mode to see granular exception messages from a Gateway.

gatewayName?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: string (optional, default: auto generate)

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.

interceptorConfigurations?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: IInterceptor[] (optional, default: No interceptors)

Interceptor configurations for the gateway.

Interceptors allow you to run custom code during each gateway invocation:

  • REQUEST interceptors execute before the gateway calls the target
  • RESPONSE interceptors execute after the target responds

A gateway can have at most one REQUEST interceptor and one RESPONSE interceptor.

See also: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-interceptors.html

kmsKey?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: IKey (optional, default: No encryption)

The AWS KMS key used to encrypt data associated with the gateway.

policyEngineConfiguration?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: GatewayPolicyEngineConfig (optional, default: No policy engine (requests are not subject to Cedar policy authorization))

The policy engine configuration for this gateway.

When provided, the specified policy engine will be associated with this gateway. All agent requests through this gateway will be evaluated against the Cedar policies defined in the policy engine.

protocolConfiguration?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: IGatewayProtocolConfig (optional, 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",)

The protocol configuration for the gateway.

role?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: IRole (optional, default: A new role will be created)

The IAM role that provides permissions for the gateway to access AWS services.

tags?⚠️

⚠️ Deprecated: Use the equivalent construct from aws-cdk-lib/aws-bedrockagentcore instead.

Type: { [string]: string } (optional, default: No tags)

Tags for the gateway A list of key:value pairs of tags to apply to this Gateway resource.

Properties

NameTypeDescription
authorizerConfiguration🔹IGatewayAuthorizerConfigThe authorizer configuration for the gateway.
env🔹ResourceEnvironmentThe environment this resource belongs to.
gatewayArn🔹stringThe ARN of the gateway.
gatewayId🔹stringThe unique identifier of the gateway.
gatewayRef⚠️GatewayReferenceA reference to a Gateway resource.
name🔹stringThe name of the gateway.
node🔹NodeThe tree node.
protocolConfiguration🔹IGatewayProtocolConfigThe protocol configuration for the gateway.
role🔹IRoleThe IAM role for the gateway.
stack🔹StackThe stack in which this resource is defined.
createdAt?🔹stringTimestamp when the gateway was created.
description?🔹stringThe description of the gateway.
exceptionLevel?🔹GatewayExceptionLevelThe exception level for the gateway.
gatewayUrl?🔹stringThe URL endpoint for the gateway.
kmsKey?🔹IKeyThe KMS key used for encryption.
oauthScopes?🔹string[]The OAuth2 scope strings for client credentials flow.
policyEngineConfiguration?🔹GatewayPolicyEngineConfigThe policy engine configuration associated with this gateway.
resourceServer?🔹IUserPoolResourceServerThe Cognito Resource Server created for the gateway (if using default Cognito authorizer).
status?🔹stringThe status of the gateway.
statusReason?🔹string[]The status reasons for the gateway.
tags?🔹{ [string]: string }Tags applied to the gateway.
tokenEndpointUrl?🔹stringThe OAuth2 token endpoint URL for client credentials flow.
updatedAt?🔹stringTimestamp when the gateway was last updated.
userPool?🔹IUserPoolThe Cognito User Pool created for the gateway (if using default Cognito authorizer).
userPoolClient?🔹IUserPoolClientThe Cognito User Pool Client created for the gateway (if using default Cognito authorizer).
userPoolDomain?🔹IUserPoolDomainThe Cognito User Pool Domain created for the gateway (if using default Cognito authorizer).
static PROPERTY_INJECTION_ID🔹stringUniquely identifies this class.

authorizerConfiguration🔹

Type: IGatewayAuthorizerConfig

The authorizer configuration for the gateway.

env🔹

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed in a Stack (those created by creating new class instances like new Role(), new Bucket(), etc.), this is always the same as the environment of the stack they belong to.

For referenced resources (those obtained from referencing methods like Role.fromRoleArn(), Bucket.fromBucketName(), etc.), they might be different than the stack they were imported into.

gatewayArn🔹

Type: string

The ARN of the gateway.

gatewayId🔹

Type: string

The unique identifier of the gateway.

gatewayRef⚠️

⚠️ Deprecated: undefined

Type: GatewayReference

A reference to a Gateway resource.

name🔹

Type: string

The name of the gateway.

node🔹

Type: Node

The tree node.

protocolConfiguration🔹

Type: IGatewayProtocolConfig

The protocol configuration for the gateway.

role🔹

Type: IRole

The IAM role for the gateway.

stack🔹

Type: Stack

The stack in which this resource is defined.

createdAt?🔹

Type: string (optional)

Timestamp when the gateway was created.

description?🔹

Type: string (optional)

The description of the gateway.

exceptionLevel?🔹

Type: GatewayExceptionLevel (optional)

The exception level for the gateway.

gatewayUrl?🔹

Type: string (optional)

The URL endpoint for the gateway.

kmsKey?🔹

Type: IKey (optional)

The KMS key used for encryption.

oauthScopes?🔹

Type: string[] (optional)

The OAuth2 scope strings for client credentials flow.

Only available when using the default Cognito authorizer.

policyEngineConfiguration?🔹

Type: GatewayPolicyEngineConfig (optional)

The policy engine configuration associated with this gateway.

resourceServer?🔹

Type: IUserPoolResourceServer (optional)

The Cognito Resource Server created for the gateway (if using default Cognito authorizer).

status?🔹

Type: string (optional)

The status of the gateway.

statusReason?🔹

Type: string[] (optional)

The status reasons for the gateway.

tags?🔹

Type: { [string]: string } (optional)

Tags applied to the gateway.

tokenEndpointUrl?🔹

Type: string (optional)

The OAuth2 token endpoint URL for client credentials flow.

Only available when using the default Cognito authorizer.

updatedAt?🔹

Type: string (optional)

Timestamp when the gateway was last updated.

userPool?🔹

Type: IUserPool (optional)

The Cognito User Pool created for the gateway (if using default Cognito authorizer).

userPoolClient?🔹

Type: IUserPoolClient (optional)

The Cognito User Pool Client created for the gateway (if using default Cognito authorizer).

userPoolDomain?🔹

Type: IUserPoolDomain (optional)

The Cognito User Pool Domain created for the gateway (if using default Cognito authorizer).

static PROPERTY_INJECTION_ID🔹

Type: string

Uniquely identifies this class.

Methods

NameDescription
addApiGatewayTarget(id, props)🔹Add an API Gateway target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.
addInterceptor(interceptor)🔹Add an interceptor to this gateway.
addLambdaTarget(id, props)🔹Add a Lambda target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.
addMcpServerTarget(id, props)🔹Add an MCP server target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.
addOpenApiTarget(id, props)🔹Add an OpenAPI target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.
addSmithyTarget(id, props)🔹Add a Smithy target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.
applyCrossStackReferenceStrength(strength)🔹Override the cross-stack reference strength for this resource.
applyRemovalPolicy(policy)🔹Apply the given removal policy to this resource.
grant(grantee, ...actions)⚠️Grants IAM actions to the IAM Principal.
grantInvoke(grantee)⚠️Grants permission to invoke this Gateway.
grantManage(grantee)⚠️Grants Create, Update, and Delete actions on the Gateway.
grantRead(grantee)⚠️Grants Get and List actions on the Gateway.
metric(metricName, dimensions, props?)⚠️Return the given named metric for this gateway.
metricDuration(props?)⚠️Return a metric measuring the duration of requests for this gateway.
metricInvocations(props?)⚠️Return a metric containing the total number of invocations for this gateway.
metricLatency(props?)⚠️Return a metric measuring the latency of requests for this gateway.
metricSystemErrors(props?)⚠️Return a metric containing the number of system errors (5xx status code) for this gateway.
metricTargetExecutionTime(props?)⚠️Return a metric measuring the target execution time for this gateway.
metricTargetType(targetType, props?)⚠️Return a metric containing the number of requests served by each target type for this gateway.
metricThrottles(props?)⚠️Return a metric containing the number of throttled requests (429 status code) for this gateway.
metricUserErrors(props?)⚠️Return a metric containing the number of user errors (4xx status code, excluding 429) for this gateway.
toString()🔹Returns a string representation of this construct.
with(...mixins)🔹Applies one or more mixins to this construct.
static fromGatewayAttributes(scope, id, attrs)🔹Import an existing Gateway using its attributes.

addApiGatewayTarget(id, props)🔹

public addApiGatewayTarget(id: string, props: AddApiGatewayTargetOptions): GatewayTarget

Parameters

Returns

Add an API Gateway target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.

See also: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html

addInterceptor(interceptor)🔹

public addInterceptor(interceptor: IInterceptor): void

Parameters

  • interceptor IInterceptor — The interceptor to add (use LambdaInterceptor factory methods).

Add an interceptor to this gateway.

Interceptors allow you to run custom code at specific points in the gateway request/response flow:

  • REQUEST interceptors execute before the gateway calls the target
  • RESPONSE interceptors execute after the target responds

A gateway can have at most one REQUEST interceptor and one RESPONSE interceptor.

addLambdaTarget(id, props)🔹

public addLambdaTarget(id: string, props: AddLambdaTargetOptions): GatewayTarget

Parameters

  • id string — The construct id for the target.
  • props AddLambdaTargetOptions — Properties for the Lambda target.

Returns

Add a Lambda target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.

addMcpServerTarget(id, props)🔹

public addMcpServerTarget(id: string, props: AddMcpServerTargetOptions): GatewayTarget

Parameters

Returns

Add an MCP server target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.

See also: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html

addOpenApiTarget(id, props)🔹

public addOpenApiTarget(id: string, props: AddOpenApiTargetOptions): GatewayTarget

Parameters

  • id string — The construct id for the target.
  • props AddOpenApiTargetOptions — Properties for the OpenAPI target.

Returns

Add an OpenAPI target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.

addSmithyTarget(id, props)🔹

public addSmithyTarget(id: string, props: AddSmithyTargetOptions): GatewayTarget

Parameters

  • id string — The construct id for the target.
  • props AddSmithyTargetOptions — Properties for the Smithy target.

Returns

Add a Smithy target to this gateway This is a convenience method that creates a GatewayTarget associated with this gateway.

applyCrossStackReferenceStrength(strength)🔹

public applyCrossStackReferenceStrength(strength: ReferenceStrength): void

Parameters

Override the cross-stack reference strength for this resource.

When set, any cross-stack reference to this resource will use the specified mechanism instead of the global default determined by the @aws-cdk/core:defaultCrossStackReferences context key. This is useful for selectively weakening specific references to avoid the "deadly embrace" problem without changing the app-wide default.

applyRemovalPolicy(policy)🔹

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

grant(grantee, ...actions)⚠️

public grant(grantee: IGrantable, ...actions: string[]): Grant

⚠️ Deprecated: undefined

Parameters

  • grantee IGrantable — The principal to grant permissions to.
  • actions string — The actions to grant.

Returns

Grants IAM actions to the IAM Principal.

[disable-awslint:no-grants]

grantInvoke(grantee)⚠️

public grantInvoke(grantee: IGrantable): Grant

⚠️ Deprecated: undefined

Parameters

  • grantee IGrantable — The principal to grant invoke permissions to.

Returns

Grants permission to invoke this Gateway.

[disable-awslint:no-grants]

grantManage(grantee)⚠️

public grantManage(grantee: IGrantable): Grant

⚠️ Deprecated: undefined

Parameters

  • grantee IGrantable — The principal to grant manage permissions to.

Returns

Grants Create, Update, and Delete actions on the Gateway.

[disable-awslint:no-grants]

grantRead(grantee)⚠️

public grantRead(grantee: IGrantable): Grant

⚠️ Deprecated: undefined

Parameters

  • grantee IGrantable — The principal to grant read permissions to.

Returns

Grants Get and List actions on the Gateway.

[disable-awslint:no-grants]

metric(metricName, dimensions, props?)⚠️

public metric(metricName: string, dimensions: { [string]: string }, props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

  • metricName string — The name of the metric.
  • dimensions { [string]: string } — Additional dimensions for the metric.
  • props MetricOptions — Optional metric configuration.

Returns

Return the given named metric for this gateway.

By default, the metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

metricDuration(props?)⚠️

public metricDuration(props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric measuring the duration of requests for this gateway.

The duration metric represents the total time elapsed between receiving the request and sending the final response token, representing complete end-to-end processing time.

metricInvocations(props?)⚠️

public metricInvocations(props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric containing the total number of invocations for this gateway.

metricLatency(props?)⚠️

public metricLatency(props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric measuring the latency of requests for this gateway.

The latency metric represents the time elapsed between when the service receives the request and when it begins sending the first response token.

metricSystemErrors(props?)⚠️

public metricSystemErrors(props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric containing the number of system errors (5xx status code) for this gateway.

metricTargetExecutionTime(props?)⚠️

public metricTargetExecutionTime(props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric measuring the target execution time for this gateway.

This metric helps determine the contribution of the target (Lambda, OpenAPI, etc.) to the total latency.

metricTargetType(targetType, props?)⚠️

public metricTargetType(targetType: string, props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric containing the number of requests served by each target type for this gateway.

metricThrottles(props?)⚠️

public metricThrottles(props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric containing the number of throttled requests (429 status code) for this gateway.

metricUserErrors(props?)⚠️

public metricUserErrors(props?: MetricOptions): Metric

⚠️ Deprecated: undefined

Parameters

Returns

Return a metric containing the number of user errors (4xx status code, excluding 429) for this gateway.

toString()🔹

public toString(): string

Returns

  • string

Returns a string representation of this construct.

with(...mixins)🔹

public with(...mixins: IMixin[]): IConstruct

Parameters

Returns

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

static fromGatewayAttributes(scope, id, attrs)🔹

public static fromGatewayAttributes(scope: Construct, id: string, attrs: GatewayAttributes): IGateway

Parameters

  • scope Construct — The construct scope.
  • id string — The construct id.
  • attrs GatewayAttributes — The attributes of the existing Gateway.

Returns

Import an existing Gateway using its attributes.

← PreviousNext →