konokenj.cdk-api-mcp-server 0.54.0__py3-none-any.whl → 0.56.0__py3-none-any.whl

cdk_api_mcp_server/resources/aws-cdk/constructs/@aws-cdk/aws-bedrock-agentcore-alpha/README.md

@@ -24,6 +24,8 @@
 
 This construct library facilitates the deployment of Bedrock AgentCore primitives, enabling you to create sophisticated AI applications that can interact with your systems and data sources.
 
+> **Note:** Users need to ensure their CDK deployment role has the `iam:CreateServiceLinkedRole` permission for AgentCore service-linked roles.
+
 ## Table of contents
 
 - [AgentCore Runtime](#agentcore-runtime)
@@ -45,12 +47,87 @@ This construct library facilitates the deployment of Bedrock AgentCore primitive
   - [Code Interpreter Network Modes](#code-interpreter-network-modes)
   - [Basic Code Interpreter Creation](#basic-code-interpreter-creation)
   - [Code Interpreter IAM permissions](#code-interpreter-iam-permissions)
+- [Gateway](#gateway)
+  - [Gateway Properties](#gateway-properties)
+  - [Basic Gateway Creation](#basic-gateway-creation)
+  - [Protocol configuration](#protocol-configuration)
+  - [Inbound authorization](#inbound-authorization)
+  - [Gateway with KMS Encryption](#gateway-with-kms-encryption)
+  - [Gateway with Custom Execution Role](#gateway-with-custom-execution-role)
+  - [Gateway IAM Permissions](#gateway-iam-permissions)
+- [Gateway Target](#gateway-target)
+  - [Gateway Target Properties](#gateway-target-properties)
+  - [Targets types](#targets-types)
+  - [Outbound auth](#outbound-auth)
+  - [Api schema](#api-schema-for-openapi-and-smithy-target)
+  - [Basic Gateway Target Creation](#basic-gateway-target-creation)
+    - [Using addTarget methods (Recommended)](#using-addtarget-methods-recommended)
+    - [Using static factory methods](#using-static-factory-methods)
+  - [Lambda Target with Tool Schema](#tools-schema-for-lambda-target)
+  - [Smithy Model Target with OAuth](#api-schema-for-openapi-and-smithy-target)
+  - [Gateway Target IAM Permissions](#gateway-target-iam-permissions)
 - [Memory](#memory)
   - [Memory properties](#memory-properties)
   - [Basic Memory Creation](#basic-memory-creation)
   - [LTM Memory Extraction Stategies](#ltm-memory-extraction-stategies)
   - [Memory Strategy Methods](#memory-strategy-methods)
-
+- [Amazon Bedrock AgentCore Construct Library](#amazon-bedrock-agentcore-construct-library)
+  - [Table of contents](#table-of-contents)
+  - [AgentCore Runtime](#agentcore-runtime)
+    - [Runtime Endpoints](#runtime-endpoints)
+    - [AgentCore Runtime Properties](#agentcore-runtime-properties)
+    - [Runtime Endpoint Properties](#runtime-endpoint-properties)
+    - [Creating a Runtime](#creating-a-runtime)
+      - [Option 1: Use an existing image in ECR](#option-1-use-an-existing-image-in-ecr)
+      - [Option 2: Use a local asset](#option-2-use-a-local-asset)
+    - [Granting Permissions to Invoke Bedrock Models or Inference Profiles](#granting-permissions-to-invoke-bedrock-models-or-inference-profiles)
+    - [Runtime Versioning](#runtime-versioning)
+      - [Managing Endpoints and Versions](#managing-endpoints-and-versions)
+        - [Step 1: Initial Deployment](#step-1-initial-deployment)
+        - [Step 2: Creating Custom Endpoints](#step-2-creating-custom-endpoints)
+        - [Step 3: Runtime Update Deployment](#step-3-runtime-update-deployment)
+        - [Step 4: Testing with Staging Endpoints](#step-4-testing-with-staging-endpoints)
+        - [Step 5: Promoting to Production](#step-5-promoting-to-production)
+    - [Creating Standalone Runtime Endpoints](#creating-standalone-runtime-endpoints)
+      - [Example: Creating an endpoint for an existing runtime](#example-creating-an-endpoint-for-an-existing-runtime)
+    - [Runtime Authentication Configuration](#runtime-authentication-configuration)
+      - [IAM Authentication (Default)](#iam-authentication-default)
+      - [Cognito Authentication](#cognito-authentication)
+      - [JWT Authentication](#jwt-authentication)
+      - [OAuth Authentication](#oauth-authentication)
+      - [Using a Custom IAM Role](#using-a-custom-iam-role)
+    - [Runtime Network Configuration](#runtime-network-configuration)
+      - [Public Network Mode (Default)](#public-network-mode-default)
+      - [VPC Network Mode](#vpc-network-mode)
+      - [Managing Security Groups with VPC Configuration](#managing-security-groups-with-vpc-configuration)
+  - [Browser](#browser)
+    - [Browser Network modes](#browser-network-modes)
+    - [Browser Properties](#browser-properties)
+    - [Basic Browser Creation](#basic-browser-creation)
+    - [Browser with Tags](#browser-with-tags)
+    - [Browser with VPC](#browser-with-vpc)
+    - [Browser with Recording Configuration](#browser-with-recording-configuration)
+    - [Browser with Custom Execution Role](#browser-with-custom-execution-role)
+    - [Browser with S3 Recording and Permissions](#browser-with-s3-recording-and-permissions)
+    - [Browser IAM Permissions](#browser-iam-permissions)
+  - [Code Interpreter](#code-interpreter)
+    - [Code Interpreter Network Modes](#code-interpreter-network-modes)
+    - [Code Interpreter Properties](#code-interpreter-properties)
+    - [Basic Code Interpreter Creation](#basic-code-interpreter-creation)
+    - [Code Interpreter with VPC](#code-interpreter-with-vpc)
+    - [Code Interpreter with Sandbox Network Mode](#code-interpreter-with-sandbox-network-mode)
+    - [Code Interpreter with Custom Execution Role](#code-interpreter-with-custom-execution-role)
+    - [Code Interpreter IAM Permissions](#code-interpreter-iam-permissions)
+    - [Code interpreter with tags](#code-interpreter-with-tags)
+  - [Memory](#memory)
+    - [Memory Properties](#memory-properties)
+    - [Basic Memory Creation](#basic-memory-creation)
+    - [LTM Memory Extraction Stategies](#ltm-memory-extraction-stategies)
+    - [Memory with Built-in Strategies](#memory-with-built-in-strategies)
+    - [Memory with custom Strategies](#memory-with-custom-strategies)
+      - [Memory with Custom Execution Role](#memory-with-custom-execution-role)
+    - [Memory with self-managed Strategies](#memory-with-self-managed-strategies)
+    - [Memory Strategy Methods](#memory-strategy-methods)
 
 ## AgentCore Runtime
 
@@ -118,27 +195,11 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
 });
 ```
 
-To grant the runtime permission to invoke a Bedrock model or inference profile:
-
-```typescript fixture=default
-// Note: This example uses @aws-cdk/aws-bedrock-alpha which must be installed separately
-declare const runtime: agentcore.Runtime;
-
-// Create a cross-region inference profile for Claude 3.7 Sonnet
-const inferenceProfile = bedrock.CrossRegionInferenceProfile.fromConfig({
-  geoRegion: bedrock.CrossRegionInferenceProfileRegion.US,
-  model: bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0
-});
-
-// Grant the runtime permission to invoke the inference profile
-inferenceProfile.grantInvoke(runtime);
-```
-
 #### Option 2: Use a local asset
 
 Reference a local directory containing a Dockerfile.
 Images are built from a local Docker context directory (with a Dockerfile), uploaded to Amazon Elastic Container Registry (ECR)
-by the CDK toolkit,and can be naturally referenced in your CDK app .
+by the CDK toolkit,and can be naturally referenced in your CDK app.
 
 ```typescript
 const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromAsset(
@@ -151,6 +212,30 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
 });
 ```
 
+### Granting Permissions to Invoke Bedrock Models or Inference Profiles
+
+To grant the runtime permissions to invoke Bedrock models or inference profiles:
+
+```typescript fixture=default
+// Note: This example uses @aws-cdk/aws-bedrock-alpha which must be installed separately
+declare const runtime: agentcore.Runtime;
+
+// Define the Bedrock Foundation Model
+const model = bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0;
+
+// Grant the runtime permissions to invoke the model
+model.grantInvoke(runtime);
+
+// Create a cross-region inference profile for Claude 3.7 Sonnet
+const inferenceProfile = bedrock.CrossRegionInferenceProfile.fromConfig({
+  geoRegion: bedrock.CrossRegionInferenceProfileRegion.US,
+  model: bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0
+});
+
+// Grant the runtime permissions to invoke the inference profile
+inferenceProfile.grantInvoke(runtime);
+```
+
 ### Runtime Versioning
 
 Amazon Bedrock AgentCore automatically manages runtime versioning to ensure safe deployments and rollback capabilities.
@@ -418,6 +503,7 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
     // securityGroups: [mySecurityGroup],
   }),
 });
+
 ```
 
 #### Managing Security Groups with VPC Configuration
@@ -803,6 +889,781 @@ const codeInterpreter = new agentcore.CodeInterpreterCustom(this, "MyCodeInterpr
 });
 ```
 
+## Gateway
+
+The Gateway construct provides a way to create Amazon Bedrock Agent Core Gateways, which serve as integration points between agents and external services.
+
+### Gateway Properties
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `gatewayName` | `string` | Yes | The name of the gateway. Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen). Maximum 100 characters |
+| `description` | `string` | No | Optional description for the gateway. Maximum 200 characters |
+| `protocolConfiguration` | `IGatewayProtocolConfig` | No | The protocol configuration for the gateway. Defaults to MCP protocol |
+| `authorizerConfiguration` | `IGatewayAuthorizerConfig` | No | The authorizer configuration for the gateway. Defaults to Cognito |
+| `exceptionLevel` | `GatewayExceptionLevel` | No | The verbosity of exception messages. Use DEBUG mode to see granular exception messages |
+| `kmsKey` | `kms.IKey` | No | The AWS KMS key used to encrypt data associated with the gateway |
+| `role` | `iam.IRole` | No | The IAM role that provides permissions for the gateway to access AWS services. A new role will be created if not provided |
+| `tags` | `{ [key: string]: string }` | No | Tags for the gateway. A list of key:value pairs of tags to apply to this Gateway resource |
+
+### Basic Gateway Creation
+
+The protocol configuration defaults to MCP and the inbound auth configuration uses Cognito (it is automatically created on your behalf).
+
+```typescript fixture=default
+// Create a basic gateway with default MCP protocol and Cognito authorizer
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+```
+
+### Protocol configuration
+
+Currently MCP is the only protocol available. To configure it, use the `protocol` property with `McpProtocolConfiguration`:
+
+- Instructions: Guidance for how to use the gateway with your tools
+- Semantic search: Smart tool discovery that finds the right tools without typical limits. It improves accuracy by finding relevant tools based on context
+- Supported versions: Which MCP protocol versions the gateway can use
+
+```typescript fixture=default
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+  protocolConfiguration: new agentcore.McpProtocolConfiguration({
+    instructions: "Use this gateway to connect to external MCP tools",
+    searchType: agentcore.McpGatewaySearchType.SEMANTIC,
+    supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
+  }),
+});
+```
+
+### Inbound authorization
+
+Before you create your gateway, you must set up inbound authorization. Inbound authorization validates users who attempt to access targets through
+your AgentCore gateway. By default, if not provided, the construct will create and configure Cognito as the default identity provider
+(inbound Auth setup). AgentCore supports the following types of inbound authorization:
+
+**JSON Web Token (JWT)** – A secure and compact token used for authorization. After creating the JWT, you specify it as the authorization
+configuration when you create the gateway. You can create a JWT with any of the identity providers at Provider setup and configuration.
+
+You can configure a custom authorization provider using the `inboundAuthorizer` property with `GatewayAuthorizer.usingCustomJwt()`.
+You need to specify an OAuth discovery server and client IDs/audiences when you create the gateway. You can specify the following:
+
+- Discovery Url — String that must match the pattern ^.+/\.well-known/openid-configuration$ for OpenID Connect discovery URLs
+- At least one of the below options depending on the chosen identity provider.
+- Allowed audiences — List of allowed audiences for JWT tokens
+- Allowed clients — List of allowed client identifiers
+
+```typescript fixture=default
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+  authorizerConfiguration: agentcore.GatewayAuthorizer.usingCustomJwt({
+    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
+    allowedAudience: ["my-app"],
+    allowedClients: ["my-client-id"],
+  }),
+});
+```
+
+**IAM** – Authorizes through the credentials of the AWS IAM identity trying to access the gateway.
+
+```typescript fixture=default
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+  authorizerConfiguration: agentcore.GatewayAuthorizer.usingAwsIam(),
+});
+
+// Grant access to a Lambda function's role
+const lambdaRole = new iam.Role(this, "LambdaRole", {
+  assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+});
+
+// The Lambda needs permission to invoke the gateway
+gateway.grantInvoke(lambdaRole);
+```
+
+### Gateway with KMS Encryption
+
+You can provide a KMS key, and configure the authorizer as well as the protocol configuration.
+
+```typescript fixture=default
+// Create a KMS key for encryption
+const encryptionKey = new kms.Key(this, "GatewayEncryptionKey", {
+  enableKeyRotation: true,
+  description: "KMS key for gateway encryption",
+});
+
+// Create gateway with KMS encryption
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-encrypted-gateway",
+  description: "Gateway with KMS encryption",
+  protocolConfiguration: new agentcore.McpProtocolConfiguration({
+    instructions: "Use this gateway to connect to external MCP tools",
+    searchType: agentcore.McpGatewaySearchType.SEMANTIC,
+    supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
+  }),
+  authorizerConfiguration: agentcore.GatewayAuthorizer.usingCustomJwt({
+    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
+    allowedAudience: ["my-app"],
+    allowedClients: ["my-client-id"],
+  }),
+  kmsKey: encryptionKey,
+  exceptionLevel: agentcore.GatewayExceptionLevel.DEBUG,
+});
+```
+
+### Gateway with Custom Execution Role
+
+```typescript fixture=default
+// Create a custom execution role
+const executionRole = new iam.Role(this, "GatewayExecutionRole", {
+  assumedBy: new iam.ServicePrincipal("bedrock-agentcore.amazonaws.com"),
+  managedPolicies: [
+    iam.ManagedPolicy.fromAwsManagedPolicyName("AmazonBedrockAgentCoreGatewayExecutionRolePolicy"),
+  ],
+});
+
+// Create gateway with custom execution role
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+  description: "Gateway with custom execution role",
+  protocolConfiguration: new agentcore.McpProtocolConfiguration({
+    instructions: "Use this gateway to connect to external MCP tools",
+    searchType: agentcore.McpGatewaySearchType.SEMANTIC,
+    supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
+  }),
+  authorizerConfiguration: agentcore.GatewayAuthorizer.usingCustomJwt({
+    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
+    allowedAudience: ["my-app"],
+    allowedClients: ["my-client-id"],
+  }),
+  role: executionRole,
+});
+```
+
+### Gateway IAM Permissions
+
+The Gateway construct provides convenient methods for granting IAM permissions:
+
+```typescript fixture=default
+// Create a gateway
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+  description: "Gateway for external service integration",
+  protocolConfiguration: new agentcore.McpProtocolConfiguration({
+    instructions: "Use this gateway to connect to external MCP tools",
+    searchType: agentcore.McpGatewaySearchType.SEMANTIC,
+    supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
+  }),
+  authorizerConfiguration: agentcore.GatewayAuthorizer.usingCustomJwt({
+    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
+    allowedAudience: ["my-app"],
+    allowedClients: ["my-client-id"],
+  }),
+});
+
+// Create a role that needs access to the gateway
+const userRole = new iam.Role(this, "UserRole", {
+  assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+});
+
+// Grant read permissions (Get and List actions)
+gateway.grantRead(userRole);
+
+// Grant manage permissions (Create, Update, Delete actions)
+gateway.grantManage(userRole);
+
+// Grant specific custom permissions
+gateway.grant(userRole, "bedrock-agentcore:GetGateway");
+```
+
+## Gateway Target
+
+After Creating gateways, you can add targets which define the tools that your gateway will host. Gateway supports multiple target
+types including Lambda functions and API specifications (either OpenAPI schemas or Smithy models). Gateway allows you to attach multiple
+targets to a Gateway and you can change the targets / tools attached to a gateway at any point. Each target can have its own
+credential provider attached enabling you to securely access targets whether they need IAM, API Key, or OAuth credentials.
+
+### Gateway Target Properties
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `gatewayTargetName` | `string` | Yes | The name of the gateway target. Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen) |
+| `description` | `string` | No | Optional description for the gateway target. Maximum 200 characters |
+| `gateway` | `IGateway` | Yes | The gateway this target belongs to |
+| `targetConfiguration` | `ITargetConfiguration` | Yes | The target configuration (Lambda, OpenAPI, or Smithy). **Note:** Users typically don't create this directly. When using convenience methods like `GatewayTarget.forLambda()`, `GatewayTarget.forOpenApi()`, `GatewayTarget.forSmithy()` or the gateway's `addLambdaTarget()`, `addOpenApiTarget()`, `addSmithyTarget()` methods, this configuration is created internally for you. Only needed when using the GatewayTarget constructor directly for [advanced scenarios](#advanced-usage-direct-configuration-for-gateway-target). |
+| `credentialProviderConfigurations` | `IGatewayCredentialProvider[]` | No | Credential providers for authentication. Defaults to `[GatewayCredentialProvider.fromIamRole()]`. Use `GatewayCredentialProvider.fromApiKeyIdentityArn()`, `GatewayCredentialProvider.fromOauthIdentityArn()`, or `GatewayCredentialProvider.fromIamRole()` |
+| `validateOpenApiSchema` | `boolean` | No | (OpenAPI targets only) Whether to validate the OpenAPI schema at synthesis time. Defaults to `true`. Only applies to inline and local asset schemas. For more information refer here <https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-schema-openapi.html> |
+
+This approach gives you full control over the configuration but is typically not necessary for most use cases.
+
+### Targets types
+
+You can create the following targets types:
+
+**Lambda Target**: Lambda targets allow you to connect your gateway to AWS Lambda functions that implement your tools. This is useful
+when you want to execute custom code in response to tool invocations.
+
+- Supports GATEWAY_IAM_ROLE credential provider only
+- Ideal for custom serverless function integration
+- Need tool schema (tool schema is a blueprint that describes the functions your Lambda provides to AI agents).
+  The construct provide [3 ways to upload a tool schema to Lambda target](#tools-schema-for-lambda-target)
+- When using the default IAM authentication (no `credentialProviderConfigurations` specified),
+  the construct automatocally grants the gateway role permission to invoke your Lambda function (`lambda:InvokeFunction`).
+
+**OpenAPI Schema Target** : OpenAPI widely used standard for describing RESTful APIs. Gateway supports OpenAPI 3.0
+specifications for defining API targets. It connects to REST APIs using OpenAPI specifications
+
+- Supports OAUTH and API_KEY credential providers (Do not support IAM, you must provide `credentialProviderConfigurations`)
+- Ideal for integrating with external REST services
+- Need API schema. The construct provide [3 ways to upload a API schema to OpenAPI target](#api-schema-for-openapi-and-smithy-target)
+
+**Smithy Model Target** : Smithy is a language for defining services and software development kits (SDKs). Smithy models provide
+a more structured approach to defining APIs compared to OpenAPI, and are particularly useful for connecting to AWS services.
+AgentCore Gateway supports built-in AWS service models only. It connects to services using Smithy model definitions
+
+- Supports OAUTH and API_KEY credential providers
+- Ideal for AWS service integrations
+- Need API schema. The construct provide 3 ways to upload a API schema to Smity target
+- When using the default IAM authentication (no `credentialProviderConfigurations` specified), The construct only
+  grants permission to read the Smithy schema file from S3. You MUST manually grant permissions for the gateway
+  role to invoke the actual Smithy API endpoints
+
+> Note: For Smithy model targets that access AWS services, your Gateway's execution role needs permissions to access those services.
+For example, for a DynamoDB target, your execution role needs permissions to perform DynamoDB operations.
+This is not managed by the construct due to the large number of options. Please refer to
+[Smithy Model Permission](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-prerequisites-permissions.html) for example.
+
+**MCP Server Target**: Model Context Protocol (MCP) servers provide external tools, data access, and custom functions for AI agents.
+MCP servers enable agents to interact with external systems and services through a standardized protocol. Gateway automatically
+discovers and indexes available tools from MCP servers through synchronization.
+
+**Key Features:**
+
+- Requires explicit authentication configuration (OAuth2 recommended, empty array for NoAuth)
+- Ideal for connecting to external MCP-compliant servers
+- The endpoint must use HTTPS protocol
+- Supported MCP protocol versions: 2025-06-18, 2025-03-26
+- Automatic tool discovery through synchronization
+
+**Synchronization Behavior:**
+
+MCP Server targets require synchronization to discover and index available tools:
+
+- **Implicit Synchronization (Automatic)**: Tool discovery happens automatically during:
+  - Target creation (`CreateGatewayTarget`)
+  - Target updates (`UpdateGatewayTarget`)
+  - The Gateway calls the MCP server's `tools/list` endpoint and indexes tools without user intervention
+
+- **Explicit Synchronization (Manual)**: When the MCP server's tools change independently (new tools added, schemas modified, tools removed):
+  - The Gateway's tool catalog becomes stale
+  - Call the `SynchronizeGatewayTargets` API to refresh the catalog
+  - Use the `grantSync()` method to grant permissions to Lambda functions, CI/CD pipelines, or scheduled tasks that will trigger synchronization
+
+**Authentication & Permissions:**
+
+When using OAuth2, the Gateway service role automatically receives:
+
+- `bedrock-agentcore:GetWorkloadAccessToken`
+- `bedrock-agentcore:GetResourceOauth2Token`
+- `secretsmanager:GetSecretValue`
+- KMS decrypt (if secrets are encrypted)
+
+For explicit synchronization, use `grantSync()` to grant `bedrock-agentcore:SynchronizeGatewayTargets` permission to your operator roles.
+
+> For more information, refer to the [MCP Server Target documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html).
+
+### Understanding Tool Naming
+
+When tools are exposed through gateway targets, AgentCore Gateway prefixes each tool name with the target name to ensure uniqueness across multiple targets. This is important to understand when building your application logic.
+
+**Naming Pattern:**
+
+**Example:**
+
+If your target is named `my-lambda-target` and provides a tool called `calculate_price`, agents will discover and invoke it as `my-lambda-target__calculate_price`.
+
+**Important Considerations:**
+
+- **For Lambda Targets**: Your Lambda handler must strip the target name prefix before processing the tool request. The full tool name (with prefix) is sent in the event.
+- **For MCP Server Targets**: The MCP server receives tool calls with the prefixed name from the gateway.
+- **For OpenAPI/Smithy Targets**: The gateway handles the prefix automatically when mapping to API operations based on the `operationId`.
+
+This naming convention ensures that:
+
+- Tools from different targets don't collide even if they have the same name
+- Agents can access tools from multiple targets through a single gateway
+- Tool names remain unique in the unified tool catalog
+
+For more details, see the [Gateway Tool Naming Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-tool-naming.html).
+
+### Tools schema For Lambda target
+
+The lambda target need tools schema to understand the fuunction lambda provides. You can upload the tool schema by following 3 ways:
+
+- From a local asset file
+
+```typescript
+const toolSchema = agentcore.ToolSchema.fromLocalAsset(
+    path.join(__dirname, "schemas", "my-tool-schema.json")
+  );
+```
+
+- From an existing S3 file:
+
+```typescript
+
+const toolSchema = agentcore.ToolSchema.fromS3File(
+    s3.Bucket.fromBucketName(this, "SchemasBucket", "my-schemas-bucket"),
+    "tools/complex-tool-schema.json",
+    "123456789012"
+  );
+```
+
+- From Inline:
+
+```typescript
+const toolSchema = agentcore.ToolSchema.fromInline([{
+      name: "hello_world",
+      description: "A simple hello world tool",
+      inputSchema: {
+        type: agentcore.SchemaDefinitionType.OBJECT,
+        properties: {
+          name: {
+            type: agentcore.SchemaDefinitionType.STRING,
+            description: "The name to greet",
+          },
+        },
+        required: ["name"],
+      },
+    }]);
+
+```
+
+### Api schema For OpenAPI and Smithy target
+
+The OpenAPI and Smithy target need API Schema. The Gateway construct provide three ways to upload API schema for your target:
+
+- From a local asset file (requires binding to scope):
+
+```typescript fixture=default
+// When using ApiSchema.fromLocalAsset, you must bind the schema to a scope
+const schema = agentcore.ApiSchema.fromLocalAsset(path.join(__dirname, "mySchema.yml"));
+
+schema.bind(this);
+```
+
+- From an inline schema:
+
+```typescript fixture=default
+const inlineSchema = agentcore.ApiSchema.fromInline(`
+openapi: 3.0.3
+info:
+  title: Library API
+  version: 1.0.0
+paths:
+  /search:
+    get:
+      summary: Search for books
+      operationId: searchBooks
+      parameters:
+        - name: query
+          in: query
+          required: true
+          schema:
+            type: string
+`);
+```
+
+- From an existing S3 file:
+
+```typescript fixture=default
+const bucket = s3.Bucket.fromBucketName(this, "ExistingBucket", "my-schema-bucket");
+const s3Schema = agentcore.ApiSchema.fromS3File(bucket, "schemas/action-group.yaml");
+```
+
+### Outbound auth
+
+Outbound authorization lets Amazon Bedrock AgentCore gateways securely access gateway targets on behalf of users authenticated
+and authorized during Inbound Auth.
+
+AgentCore Gateway supports the following types of outbound authorization:
+
+**IAM-based outbound authorization** – The gateway uses its execution role to authenticate with AWS services. This is the default
+ and most common approach for Lambda targets and AWS service integrations.
+
+**2-legged OAuth (OAuth 2LO)** – Use OAuth 2.0 two-legged flow (2LO) for targets that require OAuth authentication.
+The gateway authenticates on its own behalf, not on behalf of a user.
+
+**API key** – Use the AgentCore service/AWS console to generate an API key to authenticate access to the gateway target.
+
+**Note > You need to set up the outbound identity before you can create a gateway target.
+
+### Basic Gateway Target Creation
+
+You can create targets in two ways: using the static factory methods on `GatewayTarget` or using the convenient `addTarget` methods on the gateway instance.
+
+#### Using addTarget methods (Recommended)
+
+Below are the examples on how you can create Lambda , Smity and OpenAPI target using `addTarget` method.
+
+```typescript fixture=default
+// Create a gateway first
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+const lambdaFunction = new lambda.Function(this, "MyFunction", {
+  runtime: lambda.Runtime.NODEJS_22_X,
+  handler: "index.handler",
+  code: lambda.Code.fromInline(`
+    exports.handler = async (event) => {
+      return {
+        statusCode: 200,
+        body: JSON.stringify({ message: 'Hello from Lambda!' })
+      };
+    };
+  `),
+});
+
+const lambdaTarget = gateway.addLambdaTarget("MyLambdaTarget", {
+  gatewayTargetName: "my-lambda-target",
+  description: "Lambda function target",
+  lambdaFunction: lambdaFunction,
+  toolSchema: agentcore.ToolSchema.fromInline([
+    {
+      name: "hello_world",
+      description: "A simple hello world tool",
+      inputSchema: {
+        type: agentcore.SchemaDefinitionType.OBJECT,
+        properties: {
+          name: {
+            type: agentcore.SchemaDefinitionType.STRING,
+            description: "The name to greet",
+          },
+        },
+        required: ["name"],
+      },
+    },
+  ]),
+});
+```
+
+- OpenAPI Target
+
+``` typescript
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+// These ARNs are returned when creating the API key credential provider via Console or API
+const apiKeyProviderArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/apikeycredentialprovider/my-apikey"
+const apiKeySecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-apikey-secret-abc123"
+
+const bucket = s3.Bucket.fromBucketName(this, "ExistingBucket", "my-schema-bucket");
+const s3mySchema = agentcore.ApiSchema.fromS3File(bucket, "schemas/myschema.yaml");
+
+// Add an OpenAPI target directly to the gateway
+const target = gateway.addOpenApiTarget("MyTarget", {
+  gatewayTargetName: "my-api-target",
+  description: "Target for external API integration",
+  apiSchema: s3mySchema,
+  credentialProviderConfigurations: [
+    agentcore.GatewayCredentialProvider.fromApiKeyIdentityArn({
+      providerArn: apiKeyProviderArn,
+      secretArn: apiKeySecretArn, 
+      credentialLocation: agentcore.ApiKeyCredentialLocation.header({
+        credentialParameterName: "X-API-Key",
+      }),
+    }),
+  ],
+});
+
+// This make sure your s3 bucket is available before target 
+target.node.addDependency(bucket);
+```
+
+- Smithy Target
+
+```typescript fixture=default
+
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+const smithySchema = agentcore.ApiSchema.fromLocalAsset(
+  path.join(__dirname, "models", "smithy-model.json")
+);
+smithySchema.bind(this);
+
+const smithyTarget = gateway.addSmithyTarget("MySmithyTarget", {
+  gatewayTargetName: "my-smithy-target",
+  description: "Smithy model target",
+  smithyModel: smithySchema,
+
+});
+```
+
+- MCP Server Target
+
+```typescript fixture=default
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+// OAuth2 authentication (recommended)
+// Note: Create the OAuth provider using AWS console or Identity L2 construct when available
+const oauthProviderArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/oauth2credentialprovider/my-oauth";
+const oauthSecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-oauth-secret-abc123";
+
+// Add an MCP server target directly to the gateway
+const mcpTarget = gateway.addMcpServerTarget("MyMcpServer", {
+  gatewayTargetName: "my-mcp-server",
+  description: "External MCP server integration",
+  endpoint: "https://my-mcp-server.example.com",
+  credentialProviderConfigurations: [
+    agentcore.GatewayCredentialProvider.fromOauthIdentityArn({
+      providerArn: oauthProviderArn,
+      secretArn: oauthSecretArn,
+      scopes:['mcp-runtime-server/invoke']
+    }),
+  ],
+});
+
+// Grant sync permission to a Lambda function that will trigger synchronization
+const syncFunction = new lambda.Function(this, "SyncFunction", {
+  runtime: lambda.Runtime.PYTHON_3_12,
+  handler: "index.handler",
+  code: lambda.Code.fromInline(`
+import boto3
+
+def handler(event, context):
+    client = boto3.client('bedrock-agentcore')
+    response = client.synchronize_gateway_targets(
+        gatewayIdentifier=event['gatewayId'],
+        targetIds=[event['targetId']]
+    )
+    return response
+  `),
+});
+
+mcpTarget.grantSync(syncFunction);
+```
+
+#### Using static factory methods
+
+Create Gateway target using static convienence method.
+
+- Lambda Target
+
+```typescript fixture=default
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+const lambdaFunction = new lambda.Function(this, "MyFunction", {
+  runtime: lambda.Runtime.NODEJS_22_X,
+  handler: "index.handler",
+  code: lambda.Code.fromInline(`
+        exports.handler = async (event) => {
+            return {
+                statusCode: 200,
+                body: JSON.stringify({ message: 'Hello from Lambda!' })
+            };
+        };
+    `),
+});
+
+// Create a gateway target with Lambda and tool schema 
+const target = agentcore.GatewayTarget.forLambda(this, "MyLambdaTarget", {
+  gatewayTargetName: "my-lambda-target",
+  description: "Target for Lambda function integration",
+  gateway: gateway,
+  lambdaFunction: lambdaFunction,
+  toolSchema: agentcore.ToolSchema.fromLocalAsset(
+    path.join(__dirname, "schemas", "my-tool-schema.json")
+  ),
+});
+```
+
+- OpenAPI Target
+
+```typescript fixture=default
+
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+// outbound auth (Use AWS console to create it, Once Identity L2 construct is available you can use it to create identity)
+const apiKeyIdentityArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/apikeycredentialprovider/my-apikey"
+const apiKeySecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-apikey-secret-abc123"
+
+const opneapiSchema = agentcore.ApiSchema.fromLocalAsset(path.join(__dirname, "mySchema.yml"));
+opneapiSchema.bind(this);
+
+// Create a gateway target with OpenAPI Schema 
+const target = agentcore.GatewayTarget.forOpenApi(this, "MyTarget", {
+  gatewayTargetName: "my-api-target",
+  description: "Target for external API integration",
+  gateway: gateway,  // Note: you need to pass the gateway reference
+  apiSchema: opneapiSchema,
+  credentialProviderConfigurations: [
+    agentcore.GatewayCredentialProvider.fromApiKeyIdentityArn({
+     providerArn: apiKeyIdentityArn,
+     secretArn: apiKeySecretArn
+    }),
+  ],
+});
+
+```
+
+- Smithy Target
+
+```typescript fixture=default
+
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+const smithySchema = agentcore.ApiSchema.fromLocalAsset(
+  path.join(__dirname, "models", "smithy-model.json")
+);
+smithySchema.bind(this);
+
+// Create a gateway target with Smithy Model and OAuth 
+const target = agentcore.GatewayTarget.forSmithy(this, "MySmithyTarget", {
+  gatewayTargetName: "my-smithy-target",
+  description: "Target for Smithy model integration",
+  gateway: gateway,
+  smithyModel: smithySchema,
+});
+
+```
+
+- MCP Server Target
+
+```typescript fixture=default
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+// OAuth2 authentication (recommended)
+// Note: Create the OAuth provider using AWS console or Identity L2 construct when available
+const oauthProviderArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/oauth2credentialprovider/my-oauth";
+const oauthSecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-oauth-secret-abc123";
+
+// Create a gateway target with MCP Server
+const mcpTarget = agentcore.GatewayTarget.forMcpServer(this, "MyMcpServer", {
+  gatewayTargetName: "my-mcp-server",
+  description: "External MCP server integration",
+  gateway: gateway,
+  endpoint: "https://my-mcp-server.example.com",
+  credentialProviderConfigurations: [
+    agentcore.GatewayCredentialProvider.fromOauthIdentityArn({
+      providerArn: oauthProviderArn,
+      secretArn: oauthSecretArn,
+      scopes:['mcp-runtime-server/invoke']
+    }),
+  ],
+});
+```
+
+### Advanced Usage: Direct Configuration for gateway target
+
+For advanced use cases where you need full control over the target configuration, you can create configurations manually using the static factory methods and use the GatewayTarget constructor directly.
+
+#### Configuration Factory Methods
+
+Each target type has a corresponding configuration class with a static `create()` method:
+
+- **Lambda**: `LambdaTargetConfiguration.create(lambdaFunction, toolSchema)`
+- **OpenAPI**: `OpenApiTargetConfiguration.create(apiSchema, validateSchema?)`
+- **Smithy**: `SmithyTargetConfiguration.create(smithyModel)`
+
+#### Example: Lambda Target with Custom Configuration
+
+```typescript
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+const myLambdaFunction = new lambda.Function(this, "MyFunction", {
+  runtime: lambda.Runtime.NODEJS_22_X,
+  handler: "index.handler",
+  code: lambda.Code.fromInline(`
+    exports.handler = async (event) => ({ statusCode: 200 });
+  `),
+});
+
+const myToolSchema = agentcore.ToolSchema.fromInline([{
+  name: "my_tool",
+  description: "My custom tool",
+  inputSchema: {
+    type: agentcore.SchemaDefinitionType.OBJECT,
+    properties: {},
+  },
+}]);
+
+// Create a custom Lambda configuration
+const customConfig = agentcore.LambdaTargetConfiguration.create(
+  myLambdaFunction,
+  myToolSchema
+);
+
+// Use the GatewayTarget constructor directly
+const target = new agentcore.GatewayTarget(this, "AdvancedTarget", {
+  gateway: gateway,
+  gatewayTargetName: "advanced-target",
+  targetConfiguration: customConfig,  // Manually created configuration
+  credentialProviderConfigurations: [
+    agentcore.GatewayCredentialProvider.fromIamRole()
+  ]
+});
+```
+
+This approach gives you full control over the configuration but is typically not necessary for most use cases. The convenience methods (`GatewayTarget.forLambda()`, `GatewayTarget.forOpenApi()`, `GatewayTarget.forSmithy()`) handle all of this internally.
+
+### Gateway Target IAM Permissions
+
+The Gateway Target construct provides convenient methods for granting IAM permissions:
+
+```typescript fixture=default
+// Create a gateway and target
+const gateway = new agentcore.Gateway(this, "MyGateway", {
+  gatewayName: "my-gateway",
+});
+
+const smithySchema = agentcore.ApiSchema.fromLocalAsset(
+  path.join(__dirname, "models", "smithy-model.json")
+);
+smithySchema.bind(this);
+
+// Create a gateway target with Smithy Model and OAuth 
+const target = agentcore.GatewayTarget.forSmithy(this, "MySmithyTarget", {
+  gatewayTargetName: "my-smithy-target",
+  description: "Target for Smithy model integration",
+  gateway: gateway,
+  smithyModel: smithySchema,
+});
+
+// Create a role that needs access to the gateway target
+const userRole = new iam.Role(this, "UserRole", {
+  assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+});
+
+// Grant read permissions (Get and List actions)
+target.grantRead(userRole);
+
+// Grant manage permissions (Create, Update, Delete actions)
+target.grantManage(userRole);
+
+// Grant specific custom permissions
+target.grant(userRole, "bedrock-agentcore:GetGatewayTarget");
+
+
+// Grants permission to invoke this Gateway
+gateway.grantInvoke(userRole);
+```
+
 ## Memory
 
 Memory is a critical component of intelligence. While Large Language Models (LLMs) have impressive capabilities, they lack persistent memory across conversations. Amazon Bedrock AgentCore Memory addresses this limitation by providing a managed service that enables AI agents to maintain context over time, remember important facts, and deliver consistent, personalized experiences.
@@ -1050,7 +1911,7 @@ const memory = new agentcore.Memory(this, "MyMemory", {
 
 ### Memory with self-managed Strategies
 
-A self-managed strategy in Amazon Bedrock AgentCore Memory gives you complete control over your memory extraction and consolidation pipelines. 
+A self-managed strategy in Amazon Bedrock AgentCore Memory gives you complete control over your memory extraction and consolidation pipelines.
 With a self-managed strategy, you can build custom memory processing workflows while leveraging Amazon Bedrock AgentCore for storage and retrieval.
 
 For additional information, you can refer to the [developer guide for self managed strategies](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory-self-managed-strategies.html).