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 CLI. For more comprehensive guides and examples, see the Amazon Bedrock AgentCore Gateway GitHub repository.

Prerequisites

Before starting, make sure you have the following:

Step 1: Setup and install

Install the AgentCore CLI globally:

npm install -g @aws/agentcore

Create a new AgentCore project with an agent and a gateway:

AgentCore CLI

agentcore create --name MyGatewayAgent --defaults

The --defaults flag creates a project with a default Python Strands agent. Alternatively, omit --defaults and --name to use the interactive wizard to select your preferred framework.

Interactive

You can also run agentcore create without flags to use the interactive wizard. The wizard guides you through selecting a project name, agent framework, model provider, and other options.

Step 2: Create gateway

Add a gateway and a target to your project using the AgentCore CLI:

AgentCore CLI

# Add a gateway with no inbound auth (simplest for getting started)
agentcore add gateway --name TestGateway --authorizer-type NONE --runtimes MyGatewayAgent

# Add a Lambda function target
agentcore add gateway-target --name TestLambdaTarget --type lambda-function-arn \
  --lambda-arn <YOUR_LAMBDA_ARN> \
  --tool-schema-file tools.json \
  --gateway TestGateway

Interactive

Run agentcore to open the TUI, then select add and choose Gateway:

1. Enter the gateway name:

   

2. Select the authorizer type. For this quickstart, choose NONE:

   

3. Configure advanced options or accept the defaults:

   

4. Review the configuration and press Enter to confirm:

   

Next, select add again and choose Gateway Target to add a Lambda function target:

1. Enter the target name.

2. Select Lambda function as the target type:

   

3. Enter the Lambda ARN and tool schema file path, then confirm.

To use JWT-based authorization instead, specify --authorizer-type CUSTOM_JWT with your OAuth discovery URL:

AgentCore CLI

agentcore add gateway --name TestGateway \
  --authorizer-type CUSTOM_JWT \
  --discovery-url https://cognito-idp.us-east-1.amazonaws.com/<POOL_ID>/.well-known/openid-configuration \
  --allowed-audience <CLIENT_ID> \
  --runtimes MyGatewayAgent

Interactive

Run agentcore to open the TUI, then select add and choose Gateway. When prompted for the authorizer type, select Custom JWT:

1. Enter the gateway name:

   

2. Select Custom JWT as the authorizer type:

   

3. Enter the OAuth discovery URL and allowed audience when prompted.

4. Configure advanced options or accept the defaults:

   

5. Review the configuration and press Enter to confirm:

   

Step 3: Run the setup

Deploy your project to AWS:

agentcore deploy

The CLI synthesizes a AWS CDK stack and deploys your gateway, targets, and agent to Amazon Bedrock AgentCore. This takes about 2-3 minutes.

Step 4: Use the gateway with an agent

Retrieve your gateway URL using the AgentCore CLI:

agentcore status

Create a new file called run_agent.py and insert the following code. Install the Python dependencies first:

pip install strands-agents mcp

"""
Agent script to test the Gateway
Run this after setup: python run_agent.py
"""

from strands import Agent
from strands.models import BedrockModel
from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client
import json
import sys

def create_streamable_http_transport(mcp_url: str):
    return streamablehttp_client(mcp_url)

def get_full_tools_list(client):
    """Get all tools with pagination support"""
    more_tools = True
    tools = []
    pagination_token = None
    while more_tools:
        tmp_tools = client.list_tools_sync(pagination_token=pagination_token)
        tools.extend(tmp_tools)
        if tmp_tools.pagination_token is None:
            more_tools = False
        else:
            more_tools = True
            pagination_token = tmp_tools.pagination_token
    return tools

def run_agent():
    # Get the gateway URL from agentcore status
    gateway_url = "<YOUR_GATEWAY_URL>"  # Replace with URL from 'agentcore status'

    # Model configuration - change if needed
    model_id = "anthropic.claude-3-7-sonnet-20250219-v1:0"

    print("Starting AgentCore Gateway Test Agent")
    print(f"Gateway URL: {gateway_url}")
    print(f"Model: {model_id}")
    print("-" * 60)

    # Setup Bedrock model
    bedrockmodel = BedrockModel(
        model_id=model_id,
        streaming=True,
    )

    # Setup MCP client (no auth token needed for NONE authorizer)
    mcp_client = MCPClient(lambda: create_streamable_http_transport(gateway_url))

    with mcp_client:
        # List available tools
        tools = get_full_tools_list(mcp_client)
        print(f"\nAvailable tools: {[tool.tool_name for tool in tools]}")
        print("-" * 60)

        # Create agent
        agent = Agent(model=bedrockmodel, tools=tools)

        # Interactive loop
        print("\nInteractive Agent Ready!")
        print("Try asking: 'What's the weather in Seattle?'")
        print("Type 'exit', 'quit', or 'bye' to end.\n")

        while True:
            user_input = input("You: ")
            if user_input.lower() in ["exit", "quit", "bye"]:
                print("Goodbye!")
                break

            print("\nThinking...\n")
            response = agent(user_input)
            print(f"\nAgent: {response.message.get('content', response)}\n")

if __name__ == "__main__":
    run_agent()

Run your agent

Test your gateway by running the agent and interacting with the tools.

python run_agent.py

That's it! The agent will start and you can ask questions like:

What you've built

Through this getting started tutorial, you've created the following resources:

Troubleshooting

The following table shows some possible issues and their solutions:

Quick validation

Run the following commands in a terminal to check that your gateway is working.

# Check your Gateway is working
curl -X POST YOUR_GATEWAY_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Watch live logs
aws logs tail /aws/bedrock-agentcore/gateways/YOUR_GATEWAY_ID --follow

Cleanup

To remove the gateway and its targets from your project:

agentcore remove gateway --name TestGateway

To remove all resources and redeploy:

agentcore remove all
agentcore deploy

Next steps