Getting Started with Amazon Bedrock AgentCore Web Search Tool

9 min readSep 21, 2026

Introduction

AI agents become significantly more useful when they can search the internet for current information. Instead of relying solely on a model’s training data (which is always outdated), you can give your agent the ability to search the web, retrieve recent results, and synthesize answers grounded in live data.

The Amazon Bedrock AgentCore Web Search Tool is a managed web search connector available through AgentCore Gateway. It enables agents to search the web without requiring third-party API keys (such as Google Custom Search or Bing API). The tool is exposed as an MCP (Model Context Protocol) endpoint, which means any MCP-compatible framework can discover and invoke it automatically.

This article is part of a series I am writing about different aspects of Amazon Bedrock AgentCore. Here, we focus on how to use the Web Search Tool to give agents real-time web search capabilities. For a broader understanding of AgentCore and its components, check out the other articles in this series:

In this article, we explore the Web Search Tool from two perspectives:

First, we invoke the tool locally using the Strands Agents SDK, demonstrating how developers can use it in isolation outside of a Harness.
Then, we connect the tool to the car dealership Harness introduced in the first article and let the AI agent use it autonomously to answer customer questions.

What is the Web Search Tool?

The Web Search Tool is a managed connector available through AgentCore Gateway. If you followed the Gateway article, you already know that Gateway transforms backends into MCP-compatible tools. The Web Search Tool is one of the built-in connectors that Gateway provides out of the box.

Key characteristics:

No API keys or subscriptions required
Exposed via AgentCore Gateway (MCP protocol)
Returns search results with titles, snippets, and URLs
Agents decide when and what to search based on the conversation

Use the Web Search Tool when the agent needs to find information but does not know the exact URL. The agent formulates a search query, retrieves results, and synthesizes an answer.

Prerequisites

AWS account with credentials configured
Python 3.12 installed (Python 3.14 has known compatibility issues with Playwright)
IAM user or role with permissions to use Amazon Bedrock AgentCore Gateway and invoke Bedrock models
Model access enabled for Amazon Nova Pro in the Amazon Bedrock console
AWS Region where AgentCore is available (us-east-1, us-west-2, ap-southeast-2, or eu-central-1)

Step 1: Clone the Repository and Install Dependencies

Clone the companion repository and set up the Python environment:

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

On Windows, replace the activation command with .venv\Scripts\activate.

Step 2: Create the Web Search Tool Gateway

The Web Search Tool is exposed through AgentCore Gateway as an MCP connector. To use it, you need to create a Gateway and add a Web Search target.

2.1 Create the Gateway Execution Role

Before creating the Gateway, you need an IAM role that allows the AgentCore service to perform web search operations. Create a role named AgentCoreGatewayWebSearch with a trust policy for bedrock-agentcore.amazonaws.com and attach the following inline 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": "InvokeWebSearch",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeWebSearch",
      "Resource": "arn:aws:bedrock-agentcore:<your-region>:aws:tool/web-search.v1"
    }
  ]
}

For the detailed role creation process (trust policy, inline policy), follow the same steps described in the Gateway article. The only difference is the inline policy content above. For reference, see the Web Search Tool service role documentation.

2.2 Create the Gateway

2.2.1. Navigate to Amazon Bedrock AgentCore > Gateways in the AWS Console

2.2.2. Click Create Gateway

AgentCore Gateway console showing the navigation path and Create Gateway button

The creation wizard has four steps:

Step 1 — Define gateway details:

2.2.3. In the Gateway name field, enter WebSearchGateway

2.2.4. Under Permissions, select Use another role and choose the role you created in Step 2.1 (e.g., AgentCoreGatewayWebSearch)

2.2.5. Leave all optional sections at their defaults. Click Next.

Step 1 showing gateway name and permissions

Step 2 — Configure Inbound Identity:

2.2.6. Under Inbound Auth type, select No authorization (for this tutorial). Click Next.

Step 2 showing inbound identity with No authorization selected

Step 3 — Add targets:

2.2.7. Under Select a target protocol, select MCP target

2.2.8. In the Target name field, enter WebSearchTool

2.2.9. In the Target description field, enter Web search connector for finding current information

2.2.10. Under Passthrough, keep the default Do not use passthrough — default aggregated

2.2.11. Under Target type, select Connectors. This option provides pre-configured targets from integration providers.

2.2.12. Under Pre-configured targets, select Web Search tool

2.2.13. Under Outbound Auth configurations, select IAM Role (this is the only option available for the Web Search connector)

2.2.14. Under Additional configurations, you can optionally add domains to the Exclude domains field to filter out results from specific websites. Leave empty for this tutorial.

Get Carlos Biagolini’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

2.2.15. Click Next.

Step 3 showing the complete Add targets configuration with Connectors and Web Search tool selected

Step 4 — Review and create:

2.2.12. Review your configuration and click Create

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

2.3 Copy the Gateway ID

After creation, open the Gateway details page and copy the Gateway ID. You will need it in the next step to configure the local script. The ID follows the pattern websearchgateway-xxxxxxxxxx.

Gateway details page showing the Gateway ID location

Step 3: Test the Web Search Tool Locally

The script web_search_agent.py demonstrates how to use the Web Search Tool via Gateway. It connects to the Gateway MCP endpoint, discovers the search tool, and lets the agent search the web.

3.1 Understanding the Script

import os
import sys
import logging
import warnings
from datetime import date
from dotenv import load_dotenv

logging.getLogger("asyncio").setLevel(logging.CRITICAL)
warnings.filterwarnings("ignore", category=DeprecationWarning)

load_dotenv()

REGION = os.getenv("AWS_REGION", "us-east-1")
GATEWAY_ID = os.getenv("WEB_SEARCH_GATEWAY_ID")

if not GATEWAY_ID:
    print("Error: WEB_SEARCH_GATEWAY_ID not set in .env file")
    sys.exit(1)

gateway_url = f"https://{GATEWAY_ID}.gateway.bedrock-agentcore.{REGION}.amazonaws.com/mcp"

from strands import Agent
from strands.models.bedrock import BedrockModel
from strands.tools.mcp import MCPClient
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client = MCPClient(lambda: aws_iam_streamablehttp_client(
    endpoint=gateway_url,
    aws_region=REGION,
    aws_service="bedrock-agentcore",
))

model = BedrockModel(
    model_id="us.amazon.nova-pro-v1:0",
    region_name=REGION,
)

system_prompt = (
    f"You are a helpful research assistant for a used car dealership. "
    f"Today's date is {date.today().isoformat()}. "
    "Use the available web search tool to find current information and provide "
    "accurate answers based on search results."
)

prompt = "What is the best 2-4 year old used car for value in the US market?"

print(f"Prompt: {prompt}\n")

try:
    with mcp_client:
        tools = mcp_client.list_tools_sync()
        print(f"Discovered tools: {[t.tool_name for t in tools]}\n")
        agent = Agent(model=model, tools=tools, system_prompt=system_prompt)
        response = agent(prompt)
        print("\n--- Agent Response ---")
        print(response.message["content"][0]["text"])
except Exception as e:
    print(f"\nError: {e}")
finally:
    print("\nDone.")
    os._exit(0)

The key concepts:

The Web Search Tool is exposed as an MCP endpoint through the Gateway
We use MCPClient from Strands with aws_iam_streamablehttp_client from mcp-proxy-for-aws to handle IAM authentication
The Gateway URL is constructed from the Gateway ID: https://{GATEWAY_ID}.gateway.bedrock-agentcore.{REGION}.amazonaws.com/mcp
Tools are discovered dynamically via mcp_client.list_tools_sync() — the agent sees WebSearchTool and uses it when needed

The system prompt includes today’s date so the agent can scope search results to the current time period.

3.2 Run the Script

python web_search_agent.py

Expected behavior:

Prompt: What is the best 2-4 year old used car for value in the US market?

Discovered tools: ['WebSearchTool___WebSearch']

<thinking> To determine the best 2-4 year old used car for value in the US market, I need to search for recent reviews, expert opinions, and market analysis that focus on used cars within this age range. I will use the WebSearchTool to find the most relevant and up-to-date information. </thinking>

Tool #1: WebSearchTool___WebSearch
Based on the search results, the best 2-4 year old used cars for value in the US market are:

1. **2021-2023 Toyota 4Runner** - Known for its reliability and strong resale value, the Toyota 4Runner is a great option for a used SUV. It has consistently high J.D. Power reliability ratings and many satisfied owners report few problems.

2. **2021-2022 Hyundai Elantra** - The pre-facelift, seventh-generation Hyundai Elantra is beginning to depreciate below $20,000. It's important to check the condition of the drivetrain and ensure the transmissions have been well-maintained.

3. **2022-2023 Toyota Camry** - These sedans have high J.D. Power reliability ratings and many satisfied owners. Be sure to inspect the condition of the drivetrain and check for any recalls, such as the 'Do Not Drive' recall for early 2023 models.

...
Done.

The agent discovers the WebSearchTool___WebSearch tool from the Gateway, formulates a search query, and synthesizes the results into a coherent answer. This connects directly to our car dealership scenario — a sales assistant that can research current market information.

Step 4: Integrating with the Harness

Now we connect the Web Search Tool to the Harness so the agent can use it autonomously.

4.1 Edit the Harness to Add the Gateway

4.1.1. Navigate to Amazon Bedrock AgentCore > Harness

4.1.2. Click on your Harness name (car_agent) to open its details page

4.1.3. Click Edit in the top-right area

4.1.4. In the Tools section, click Add Gateway and select the WebSearchGateway

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

After saving, the console may display a message suggesting that the Harness execution role needs to be updated with permissions to invoke the Gateway. If this message appears, follow the instructions provided by the console to update the role. This ensures the Harness has the necessary permissions to call the Gateway on your behalf.

Harness configuration panel showing the added Gateway tool

4.2 Test the Web Search Tool via Harness

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

4.2.2. Enter a prompt that requires web search:

Search the web for: What are the most reliable used SUVs under $25,000?

4.2.3. The agent will invoke the Web Search Tool, search for the requested information, and present a summary of findings. The test interface will show an indicator like “WebSearchTool WebSearch” confirming the tool was used.

Harness test showing Web Search Tool invocation and response

Conclusion

In this article, you learned how to use the Amazon Bedrock AgentCore Web Search Tool to give agents real-time web search capabilities:

The Web Search Tool is a managed connector available through AgentCore Gateway that requires no third-party API keys. You created a Gateway with the Web Search connector, connected to it via MCP protocol, and demonstrated how the agent searches the web and synthesizes results.
Local invocation lets developers test the tool in isolation using the Strands Agents SDK with the MCPClient and aws_iam_streamablehttp_client for IAM authentication.
Harness integration allows the agent to use the Web Search Tool autonomously, deciding when to search based on the conversation context.

The Web Search Tool is ideal for scenarios where the agent needs current information but does not know the exact URL. Once your Gateway is running in production, consider enabling observability (log delivery and tracing) as described in Getting Started with Observability for Amazon Bedrock AgentCore to monitor tool invocations, latency, and errors.

In the next article, we will explore the Browser Tool, which complements Web Search by allowing the agent to navigate to specific URLs and extract detailed content from web pages.

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 Web Search Tool

Introduction

What is the Web Search Tool?

Prerequisites

Step 1: Clone the Repository and Install Dependencies

Step 2: Create the Web Search Tool Gateway

2.1 Create the Gateway Execution Role

2.2 Create the Gateway

Get Carlos Biagolini’s stories in your inbox

2.3 Copy the Gateway ID

Step 3: Test the Web Search Tool Locally

3.1 Understanding the Script

3.2 Run the Script

Step 4: Integrating with the Harness

4.1 Edit the Harness to Add the Gateway

4.2 Test the Web Search Tool via Harness

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.

Building an Agentic Knowledge Graph for Billions of Events

Rebuilding Netflix-inspired observability with AI

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…

How to Master API Load Testing with Grafana k6 and Visualize Real-Time Performance Metrics Like an…

Load testing ensures your applications survive traffic surges, but understanding performance metrics often feels overwhelming for…

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.

Building an Agentic Knowledge Graph for Billions of Events

Rebuilding Netflix-inspired observability with AI

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…

How to Master API Load Testing with Grafana k6 and Visualize Real-Time Performance Metrics Like an…

Load testing ensures your applications survive traffic surges, but understanding performance metrics often feels overwhelming for…

Getting Started with Amazon Bedrock AgentCore Identity

Introduction