Getting Started with Amazon Bedrock AgentCore Gateway

10 min readSep 7, 2026

Introduction

AI agents need tools to be useful. A chatbot that can only answer from its training data is limited. The real power comes when an agent can call external APIs, query databases, or trigger workflows. The challenge is connecting agents to these backends securely, with proper authentication, protocol translation, and discovery.

Amazon Bedrock AgentCore Gateway is a fully managed service that provides a single, secure entry point for connecting agents to tools. It transforms existing APIs, Lambda functions, and services into MCP (Model Context Protocol) compatible tools that any agent framework can discover and use. Instead of writing custom integration code for each tool, you configure a Gateway target and the agent interacts with it through a standard protocol.

This article is part of a series I am writing about different aspects of Amazon Bedrock AgentCore. Here, we focus on understanding what Gateway is and how to connect a simple Lambda function as a tool for the Harness. For a broader understanding of AgentCore and its components, check out the other articles in this series:

What is AgentCore Gateway?

AgentCore Gateway acts as a translation and routing layer between your agents and your backend services. Rather than serving only as a tool connector, it routes and secures any agentic traffic through one endpoint.

Key Capabilities

Protocol translation — Converts agent requests using MCP into API calls, Lambda invocations, or HTTP requests. Your backends do not need to understand MCP.
Composition — Combines multiple APIs, functions, and tools into a single MCP endpoint. An agent connects to one Gateway and discovers all available tools.
Security — Manages OAuth authorization and IAM authentication so only valid users and agents can access tools. Supports both ingress and egress authentication.
Semantic tool selection — When you have hundreds of tools, Gateway provides intelligent discovery via a built-in search tool (x_amz_bedrock_agentcore_search) that helps agents find the right tool without being overwhelmed.
Built-in connectors — One-click integration with popular services like Salesforce, Slack, Jira, Asana, Zendesk, and Web Search.

Supported Target Types

A Gateway can have multiple targets, each representing a different tool or set of tools:

Lambda functions — Connect serverless functions as tools with defined schemas
OpenAPI specifications — Transform REST APIs described by OpenAPI (Swagger) into MCP tools
Smithy models — Use Smithy model definitions to expose APIs
Existing MCP servers — Proxy existing MCP servers through the Gateway
Connectors — Pre-built integrations (Web Search, Salesforce, Slack, Jira, etc.)
Passthrough targets — For Agent-to-Agent (A2A) traffic routing

How It Works

The flow is straightforward:

You create a Gateway (MCP protocol endpoint)
You add one or more targets (Lambda, API, connector)
Your agent connects to the Gateway URL via MCP
The agent discovers available tools automatically
When the agent calls a tool, Gateway translates the request and routes it to the correct target

In this article, we will create a simple Lambda function, expose it through Gateway, and connect it to our car dealership Harness so the agent can use it as a tool.

Prerequisites

AWS account with credentials configured
IAM user or role with permissions to create Lambda functions and use Amazon Bedrock AgentCore Gateway
AWS Region where AgentCore is available (us-east-1, us-west-2, ap-southeast-2, or eu-central-1)
A Harness already created (from the first article in this series)

Step 1: Create IAM Roles

Before creating the Lambda function and Gateway, we need two IAM roles: one for the Lambda execution and one for the Gateway to invoke the Lambda.

1.1 Create the Lambda Execution Role

1.1.1. Navigate to IAM > Roles in the AWS Console

1.1.2. Click Create role

1.1.3. Select AWS service as the trusted entity type, then select Lambda as the use case. Click Next.

1.1.4. Search for and select the AWSLambdaBasicExecutionRole managed policy. This grants the Lambda function permission to write logs to CloudWatch. Click Next.

1.1.5. In the Role name field, enter AgentCoreLambdaLuckyNumber

1.1.6. Click Create role

1.2 Create the Gateway Execution Role

1.2.1. Navigate to IAM > Roles in the AWS Console

1.2.2. Click Create role

1.2.3. Select Custom trust policy and enter the following trust policy that allows the AgentCore Gateway service to assume this role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

1.2.4. Click Next

1.2.5. Skip the managed policies (do not select any). Click Next.

1.2.6. In the Role name field, enter AgentCoreGatewayLuckyNumber

1.2.7. Click Create role

1.2.8. After creation, open the role and click Add permissions > Create inline policy

1.2.9. Select the JSON tab and enter the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetGateway",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetGateway"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:<your-region>:<your-account-id>:gateway/*"
      ]
    },
    {
      "Sid": "LambdaInvoke",
      "Effect": "Allow",
      "Action": "lambda:InvokeFunction",
      "Resource": "arn:aws:lambda:<your-region>:<your-account-id>:function:agentcore-lucky-number*"
    }
  ]
}

For example, in account 123456789012 in us-east-1:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetGateway",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetGateway"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    },
    {
      "Sid": "LambdaInvoke",
      "Effect": "Allow",
      "Action": "lambda:InvokeFunction",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:agentcore-lucky-number*"
    }
  ]
}

1.2.10. Click Next, name the policy GatewayLambdaAccess, and click Create policy

Step 2: Create a Simple Lambda Function

We will create a minimal Lambda function that generates a random “lucky number” for a customer. This is intentionally simple so we can focus on the Gateway mechanics rather than the Lambda logic itself.

2.1 Create the Function

2.1.1. Navigate to AWS Lambda > Functions in the AWS Console

2.1.2. Click Create function

2.1.3. Select Author from scratch

2.1.4. Configure the function:

Function name: agentcore-lucky-number
Runtime: Select the latest available Python version. At the time of writing, this was Python 3.14. The specific version may differ depending on when you are following this tutorial.
Architecture: arm64
Execution role: Select Use an existing role and choose AgentCoreLambdaLuckyNumber (created in Step 1.1)

2.1.5. Click Create function

2.2 Add the Function Code

2.2.1. In the function’s Code tab, replace the default code with the following:

import json
import random


def lambda_handler(event, context):
    """Generate a lucky number for a customer."""
    body = event.get("body", {})
    if isinstance(body, str):
        body = json.loads(body) if body else {}

    customer_name = body.get("customer_name", "valued customer")
    lucky_number = random.randint(1, 100)

    return {
        "statusCode": 200,
        "body": json.dumps({
            "message": f"Hello {customer_name}! Your lucky number today is {lucky_number}.",
            "lucky_number": lucky_number,
            "customer_name": customer_name
        })
    }import json
import random

2.2.2. Click Deploy

2.3 Test the Function

2.3.1. Click the Test tab

2.3.2. Create a test event with the following payload:

{
  "body": {
    "customer_name": "Carlos"
  }
}

2.3.3. Click Test and verify the output:

{
  "statusCode": 200,
  "body": "{\"message\": \"Hello Carlos! Your lucky number today is 42.\", \"lucky_number\": 42, \"customer_name\": \"Carlos\"}"
}

Step 3: Create a Gateway with a Lambda Target

The Gateway creation wizard has four steps that guide you through configuring the gateway and adding targets in a single flow.

3.1 Navigate to the Gateway Console

3.1.1. Open the Amazon Bedrock AgentCore console

3.1.2. In the left navigation pane, under Build, click Gateways

3.1.3. Click the Create Gateway button

Agent Core Gateway console showing the navigation path and Create Gateway button

3.2 Step 1 — Define Gateway Details

3.2.1. In the Gateway name field, enter LuckyNumberGateway

Get Carlos Biagolini’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

3.2.2. Under Permissions, select Use another role and choose the AgentCoreGatewayLuckyNumber role created in Step 1.2.

3.2.3. Leave all optional sections collapsed (Additional configurations, Policy, KMS key, WAF). Click Next.

Step 1 of the Gateway creation wizard showing name and permissions

3.3 Step 2 — Configure Inbound Identity

3.3.1. Under Inbound Auth type, select No authorization. This simplifies the tutorial by removing authentication requirements. For production environments, use IAM permissions or JWT to control access.

3.3.2. Click Next

Step 2 showing inbound identity options with No authorization selected

3.4 Step 3 — Add Targets

This is where you connect your Lambda function as a tool. A target represents a backend service exposed through the Gateway.

3.4.1. Click Add target

3.4.2. Select Lambda as the target type

3.4.3. In the Target name field, enter LuckyNumber

3.4.4. In the Target description field, enter Generates a lucky number for a customer

3.4.5. In the Lambda ARN field, enter:

arn:aws:lambda:<your-region>:<your-account-id>:function:agentcore-lucky-number:$LATEST

3.4.6. For the Tool schema, select Inline and enter the following JSON definition that describes what the tool does and its input parameters:

[
  {
    "name": "get_lucky_number",
    "description": "Generates a lucky number for a customer. Use this when a customer asks for their lucky number or wants a fun random number.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "customer_name": {
          "type": "string",
          "description": "The name of the customer requesting the lucky number"
        }
      },
      "required": []
    }
  }
]

The description field is critical. It tells the model when and why to use this tool. A well-written description leads to more accurate tool selection by the agent.

3.4.7. Click Next

Step 3 of the Gateway creation wizard showing the Lambda target configured with name, description, ARN, and inline tool schema

3.5 Step 4 — Review and Create

3.5.1. Review your configuration (gateway name, inbound identity, target)

3.5.2. Click Create

3.5.3. Wait for both the Gateway and the target status to reach Ready

3.6 Note the Gateway ARN

After creation, open the Gateway details page and note the Gateway ARN. You will need it when connecting to the Harness.

Step 4: Access the Gateway Programmatically

You can access the Gateway programmatically using the Strands Agents SDK. This is useful for testing, automation, or integrating Gateway tools into your own applications.

Clone the companion repository:

git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreGateway.git
cd PythonAwsBedrockAgentCoreGateway
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure the environment with your Gateway ID:

cp .env.example .env

Edit .env:

AWS_REGION=us-east-1
GATEWAY_ID=<your-gateway-id>

Run the script:

python gateway_agent.py

The script connects to the Gateway via MCP protocol, discovers available tools (including the LuckyNumber target you created in Step 3), and lets the agent interact with them. This demonstrates that any MCP-compatible client can consume the same Gateway endpoint.

Step 5: Connect the Gateway to the Harness

Now we attach the Gateway to our car dealership Harness so the agent can discover and use the lucky number tool.

5.1 Edit the Harness

5.1.1. Navigate to Amazon Bedrock AgentCore > Harness

5.1.2. Select the car_agent Harness from the list

5.1.3. Select the car_agent Harness from the list and click the Edit button

Agent Core Harness console showing the Harness details page with the Edit button

5.1.4. In the Tools section, click Add Gateway

5.1.5. Select the LuckyNumberGateway from the dropdown

5.1.6. Click Save Harness and wait for the status to return to Ready

Edit Harness page showing the full updated configuration with the Save Harness buttondit Harness page showing the Tools section with Gateway added — Edit Harness page showing the full updated configuration with the Save Harness button

5.2 Test with the Harness

5.2.1. Once the Harness is Ready, click the Test Harness button

Harness details page showing the updated status and the Test Harness button

5.2.2. Enter a prompt that should trigger the tool:

Hi! My name is Maria. Can you give me a lucky number for today?

5.2.3. The agent will recognize that it has a tool for generating lucky numbers, invoke it with the customer’s name, and present the result in a friendly way. The test interface will show an indicator like “LuckyNumber Get Lucky Number” confirming the tool was used.

Harness test showing the lucky number tool invocation and response

5.2.4. Try a prompt that should NOT trigger the tool to verify the agent uses it selectively:

Do you have any SUVs under $25,000?

The agent should respond from its general knowledge and system prompt without invoking the lucky number tool. This confirms that the agent makes intelligent decisions about when to use each tool.

Step 6: Clean Up

If you do not plan to continue using the resources created in this tutorial, it is a good practice to remove them from your account. For pricing details, check the AgentCore pricing page.

To remove the resources:

Remove the Gateway from the Harness (edit the Harness and remove the Gateway tool)
Delete the Gateway itself
Delete the Lambda function
Delete the IAM roles created in Step 1

Conclusion

In this article, you learned how Amazon Bedrock AgentCore Gateway connects agents to external tools through a managed, secure interface:

Gateway is a managed MCP endpoint that transforms your existing backends (APIs, Lambda functions, services) into tools that any agent can discover and use.
Targets represent individual backends connected to a Gateway. You can have multiple targets (Lambda, REST API, connectors) on a single Gateway.
The agent decides when to use tools based on the conversation. It does not need to be explicitly told which tool to call. The tool schema description helps the model understand when each tool is appropriate.
No custom integration code is needed. You define a schema, connect your Lambda, and the Gateway handles protocol translation, routing, and authentication.

The key takeaways are:

Gateway provides a standard interface (MCP) between agents and any backend. The backend does not need to know about MCP.
Tool schemas are critical. The description field tells the model when and why to use the tool. A well-written description leads to better tool selection.
Gateway supports much more than Lambda. In future articles, we will explore OpenAPI targets, built-in connectors (Web Search, Salesforce), and Agent-to-Agent communication through the same Gateway infrastructure.

References

Stay Connected

If you found this article helpful and want to learn more about AWS, cloud architecture, AI, infrastructure as code, and cloud security, follow the author for future content and tutorials:

LinkedIn: https://www.linkedin.com/in/biagolini
Medium: https://medium.com/@biagolini
GitHub: https://github.com/biagolini
YouTube (PT-BR): https://www.youtube.com/@BiagoliniTech
AWS Builder Center (PT-BR): https://builder.aws.com/community/@cbiagolini

Stay tuned for more practical walkthroughs and solutions for cloud infrastructure and DevOps challenges.

Happy building on AWS! 🚀☁️

AWS Tip

Getting Started with Amazon Bedrock AgentCore Gateway

Introduction

What is AgentCore Gateway?

Key Capabilities

Supported Target Types

How It Works

Prerequisites

Step 1: Create IAM Roles

1.1 Create the Lambda Execution Role

1.2 Create the Gateway Execution Role

Step 2: Create a Simple Lambda Function

2.1 Create the Function

2.2 Add the Function Code

2.3 Test the Function

Step 3: Create a Gateway with a Lambda Target

3.1 Navigate to the Gateway Console

3.2 Step 1 — Define Gateway Details

Get Carlos Biagolini’s stories in your inbox

3.3 Step 2 — Configure Inbound Identity

3.4 Step 3 — Add Targets

3.5 Step 4 — Review and Create

3.6 Note the Gateway ARN

Step 4: Access the Gateway Programmatically

Step 5: Connect the Gateway to the Harness

5.1 Edit the Harness

5.2 Test with the Harness

Step 6: Clean Up

Conclusion

References

Stay Connected

Written by Carlos Biagolini

Published in AWS Tip

No responses yet

More from Carlos Biagolini and AWS Tip

Getting Started with Amazon Bedrock AgentCore Knowledge Bases

Introduction

Google Gave Me 45 Minutes to Design a URL Shortener. I Used 40 Minutes on the Wrong Thing.

Every engineer overthinks this question in exactly the similar way.

20 Terraform Best Practices I Wish I Had Learned Earlier

Hard-earned lessons to keep your infrastructure predictable, secure, and drama-free

Getting Started with Amazon CloudWatch for Bedrock AgentCore Observability

Introduction

Recommended from Medium

How To Run Claude Like a Tech Lead, Not a Senior Engineer

You already know how to brief one session. The leverage now is running four of them and still shipping code you’d put your own name on.

8 New AI Terms You Should Know to Be Ahead of 90% of People

A few more AI terms to know beyond tokens, prompts, and hallucinations.

I Built 15 SLOs for an AI Agent. Here’s What OpenTelemetry Could Measure

A hands-on look at what OpenTelemetry captures out of the box and the reliability signals you still need to instrument yourself.

Infrastructure Documentation Best Practices: ADRs, Runbooks and Diagrams as Code

Infrastructure documentation has a reputation problem. It is written during calm periods, never updated during incidents, and discovered by…

Top 30 AWS Amazon Bedrock Interview Questions and Answers — 2026

1. What is Amazon Bedrock?

Getting Started with Amazon Bedrock AgentCore Identity

Introduction

No responses yet

More from Carlos Biagolini and AWS Tip

Getting Started with Amazon Bedrock AgentCore Knowledge Bases

Introduction

Google Gave Me 45 Minutes to Design a URL Shortener. I Used 40 Minutes on the Wrong Thing.

Every engineer overthinks this question in exactly the similar way.

20 Terraform Best Practices I Wish I Had Learned Earlier

Hard-earned lessons to keep your infrastructure predictable, secure, and drama-free

Getting Started with Amazon CloudWatch for Bedrock AgentCore Observability

Introduction

Recommended from Medium

How To Run Claude Like a Tech Lead, Not a Senior Engineer

You already know how to brief one session. The leverage now is running four of them and still shipping code you’d put your own name on.

8 New AI Terms You Should Know to Be Ahead of 90% of People

A few more AI terms to know beyond tokens, prompts, and hallucinations.

I Built 15 SLOs for an AI Agent. Here’s What OpenTelemetry Could Measure

A hands-on look at what OpenTelemetry captures out of the box and the reliability signals you still need to instrument yourself.

Infrastructure Documentation Best Practices: ADRs, Runbooks and Diagrams as Code

Infrastructure documentation has a reputation problem. It is written during calm periods, never updated during incidents, and discovered by…

Top 30 AWS Amazon Bedrock Interview Questions and Answers — 2026

1. What is Amazon Bedrock?

Getting Started with Amazon Bedrock AgentCore Identity

Introduction