AWS bedrock-agentcore documentation change
Summary
Comprehensive restructuring of quick start guide with detailed step-by-step instructions, added code samples for gateway setup, OAuth integration with Cognito, IAM permission handling, and agent implementation
Security assessment
Added documentation for OAuth authorization with Cognito and IAM permission configuration, which are security features. However, there's no evidence this addresses a specific disclosed vulnerability or security incident.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-quick-start.md b/bedrock-agentcore/latest/devguide/gateway-quick-start.md index 5157509b5..7faec460c 100644 --- a//bedrock-agentcore/latest/devguide/gateway-quick-start.md +++ b//bedrock-agentcore/latest/devguide/gateway-quick-start.md @@ -5 +5,31 @@ -PrerequisitesCreating a Gateway and attaching a TargetOpenAPI and Smithy TargetsUsing the Gateway in an Agent +PrerequisitesStep 1: Setup and installStep 2: Create gateway setup scriptStep 3: Run the setupStep 4: Use the gateway with an agentWhat you've builtTroubleshootingQuick validationCleanupNext steps + +# Get started with AgentCore Gateway + +In this quick start guide you'll learn how to set up a gateway and integrate it into your agents using the AgentCore starter toolkit. For more comprehensive guides and examples, see the [Amazon Bedrock AgentCore Gateway GitHub repository](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials/02-AgentCore-gateway). + +###### Note + +The AgentCore starter toolkit abstracts the Boto3 Python SDK into simplified methods and is intended to help developers get started quickly. For a more comprehensive set of operations, you should use an AWS SDK such as Boto3. For more information on Boto3 operations for AgentCore, see [AgentCore Control Plane operations](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html). + +###### Topics + + * Prerequisites + + * Step 1: Setup and install + + * Step 2: Create gateway setup script + + * Step 3: Run the setup + + * Step 4: Use the gateway with an agent + + * What you've built + + * Troubleshooting + + * Quick validation + + * Cleanup + + * Next steps @@ -7 +36,0 @@ PrerequisitesCreating a Gateway and attaching a TargetOpenAPI and Smithy Targets -Amazon Bedrock AgentCore is in preview release and is subject to change. @@ -9 +37,0 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -# Quick Start with creating and using a Gateway @@ -11 +38,0 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -This section provides quick start examples for creating a gateway and using it with different frameworks. @@ -15 +42,3 @@ This section provides quick start examples for creating a gateway and using it w -Before creating a gateway, ensure you have the following prerequisites: +Before starting, make sure you have the followinsg: + + * **AWS Account** with credentials configured. To configure credentials, you can install and use the AWS Command Line Interface by following the steps at [Getting started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html). @@ -17 +46 @@ Before creating a gateway, ensure you have the following prerequisites: - * AWS account with permissions to create IAM roles, Lambda functions, and Cognito resources. You will also need permission to use Bedrock AgentCore APIs. + * **Python 3.10+** installed. @@ -19 +48 @@ Before creating a gateway, ensure you have the following prerequisites: - * AWS credentials configured on your development environment + * **IAM permissions** for creating roles, Lambda functions, and using Amazon Bedrock AgentCore. @@ -21 +50 @@ Before creating a gateway, ensure you have the following prerequisites: - * Python 3.6+ with boto3 installed + * **Model Access** – Enable Anthropic's Claude Sonnet 3.7 in the Amazon Bedrock console (or another model for the demo agent) @@ -26 +55 @@ Before creating a gateway, ensure you have the following prerequisites: -If you would rather create your roles, Lambda, and/or Cognito authorization server yourself, refer to the detailed setup instructions in [Set up an Amazon Bedrock AgentCore gateway](./gateway-building.html). +## Step 1: Setup and install @@ -28 +57,10 @@ If you would rather create your roles, Lambda, and/or Cognito authorization serv -Install the key dependencies: +Run the following in a terminal to set up the virtual environment in which to install the dependencies. + + + mkdir agentcore-gateway-quickstart + cd agentcore-gateway-quickstart + python3 -m venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + + +Then, run the following to install the dependencies @@ -33 +70,0 @@ Install the key dependencies: - pip install bedrock-agentcore @@ -35,0 +73 @@ Install the key dependencies: +## Step 2: Create gateway setup script @@ -37 +75 @@ Install the key dependencies: -For detailed setup instructions, see [Set up an Amazon Bedrock AgentCore gateway](./gateway-building.html). +Create a new file called `setup_gateway.py` and insert the following complete code into it: @@ -39,3 +76,0 @@ For detailed setup instructions, see [Set up an Amazon Bedrock AgentCore gateway -## Creating a Gateway and attaching a Target - -Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: @@ -42,0 +78,4 @@ Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: + """ + Setup script to create Gateway with Lambda target and save configuration + Run this first: python setup_gateway.py + """ @@ -44,0 +84 @@ Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: + import json @@ -45,0 +86 @@ Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: + import time @@ -47,9 +88,3 @@ Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: - # setup the client - client = GatewayClient(region_name="us-east-1") - client.logger.setLevel(logging.DEBUG) - - # create cognito authorizer - cognito_response = client.create_oauth_authorizer_with_cognito("TestGateway") - - # create the gateway - gateway = client.create_mcp_gateway(authorizer_config=cognito_response["authorizer_config"]) + def setup_gateway(): + # Configuration + region = "us-east-1" # Change to your preferred region @@ -57,2 +92,2 @@ Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: - # create a lambda target - lambda_target = client.create_mcp_gateway_target(gateway=gateway, target_type="lambda") + print("🚀 Setting up AgentCore Gateway...") + print(f"Region: {region}\n") @@ -59,0 +95,3 @@ Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: + # Initialize client + client = GatewayClient(region_name=region) + client.logger.setLevel(logging.INFO) @@ -61,2 +99,4 @@ Now, let's dive in! Let's first create a Gateway and attach a Lambda Target: -You can customize your Gateway and Targets using your own role, Lambda functions, etc.: - + # Step 2.1: Create OAuth authorizer + print("Step 2.1: Creating OAuth authorization server...") + cognito_response = client.create_oauth_authorizer_with_cognito("TestGateway") + print("✓ Authorization server created\n") @@ -64 +104,2 @@ You can customize your Gateway and Targets using your own role, Lambda functions - # create the gateway. + # Step 2.2: Create Gateway + print("Step 2.2: Creating Gateway...") @@ -66,4 +107,10 @@ You can customize your Gateway and Targets using your own role, Lambda functions - name=None, # the name of the Gateway - if you don't set one, one will be generated. - role_arn=None, # the role arn that the Gateway will use - if you don't set one, one will be created. - authorizer_config=cognito_response["authorizer_config"], # the OAuth authorizer details for authorizing callers to your Gateway (MCP only supports OAuth). - enable_semantic_search=True, # enable semantic search. + # the name of the Gateway - if you don't set one, one will be generated. + name=None, + # the role arn that the Gateway will use - if you don't set one, one will be created. + # NOTE: if you are using your own role make sure it has a trust policy that trusts bedrock-agentcore.amazonaws.com + role_arn=None, + # the OAuth authorization server details. If you are providing your own authorization server, + # then pass an input of the following form: {"customJWTAuthorizer": {"allowedClients": ["<INSERT CLIENT ID>"], "discoveryUrl": "<INSERT DISCOVERY URL>"}} + authorizer_config=cognito_response["authorizer_config"], + # enable semantic search + enable_semantic_search=True, @@ -70,0 +118 @@ You can customize your Gateway and Targets using your own role, Lambda functions + print(f"✓ Gateway created: {gateway['gatewayUrl']}\n") @@ -71,0 +120,6 @@ You can customize your Gateway and Targets using your own role, Lambda functions + # If role_arn was not provided, fix IAM permissions + # NOTE: This is handled internally by the toolkit when no role is provided + client.fix_iam_permissions(gateway) + print("⏳ Waiting 30s for IAM propagation...") + time.sleep(30) + print("✓ IAM permissions configured\n") @@ -73,2 +127,2 @@ You can customize your Gateway and Targets using your own role, Lambda functions - - # create a lambda target. + # Step 2.3: Add Lambda target + print("Step 2.3: Adding Lambda target...") @@ -75,0 +130 @@ You can customize your Gateway and Targets using your own role, Lambda functions + # the gateway created in the previous step @@ -77,4 +132,9 @@ You can customize your Gateway and Targets using your own role, Lambda functions - name=None, # the name of the Target - if you don't set one, one will be generated. - target_type="lambda", # the type of the Target - you will see other target types later in the tutorial. - target_payload=None, # the target details - set this to define your own lambda if you pre-created one. Otherwise leave this None and one will be created for you. - credentials=None, # you will see later in the tutorial how to use this to connect to APIs using API keys and OAuth credentials. + # the name of the Target - if you don't set one, one will be generated. + name=None, + # the type of the Target + target_type="lambda", + # the target details - set this to define your own lambda if you pre-created one. + # Otherwise leave this None and one will be created for you. + target_payload=None, + # you will see later in the tutorial how to use this to connect to APIs using API keys and OAuth credentials. + credentials=None, @@ -81,0 +142,9 @@ You can customize your Gateway and Targets using your own role, Lambda functions + print("✓ Lambda target added\n") + + # Step 2.4: Save configuration for agent + config = { + "gateway_url": gateway["gatewayUrl"], + "gateway_id": gateway["gatewayId"], + "region": region, + "client_info": cognito_response["client_info"] + } @@ -82,0 +152,2 @@ You can customize your Gateway and Targets using your own role, Lambda functions + with open("gateway_config.json", "w") as f: + json.dump(config, f, indent=2) @@ -84 +155,7 @@ You can customize your Gateway and Targets using your own role, Lambda functions -Example of target_payload for Lambda. Note this Lambda will be created for you if you don't provide a target_payload: + print("=" * 60) + print("✅ Gateway setup complete!") + print(f"Gateway URL: {gateway['gatewayUrl']}") + print(f"Gateway ID: {gateway['gatewayId']}") + print("\nConfiguration saved to: gateway_config.json") + print("\nNext step: Run 'python run_agent.py' to test your Gateway") + print("=" * 60) @@ -85,0 +163 @@ Example of target_payload for Lambda. Note this Lambda will be created for you i + return config @@ -87,38 +165,2 @@ Example of target_payload for Lambda. Note this Lambda will be created for you i - { - "lambdaArn": "<insert your lambda arn>", - "toolSchema": { - "inlinePayload": [ - {