View a markdown version of this page

Get started with AgentCore Web Search - Amazon Bedrock AgentCore
PrerequisitesGrant permission to call the APISearch the web
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Get started with AgentCore Web Search

To search the web with AgentCore Web Search, grant a principal permission to call the InvokeWebSearch API, and then call it with the Amazon SDKs or the Amazon Command Line Interface (Amazon CLI).

Prerequisites

Before you call the API, make sure that you have the following:

  • An Amazon account and credentials that the Amazon SDKs or the Amazon CLI can use.

  • An Amazon Region where the API is available. For the list, see Regions.

  • A current version of the Amazon SDK for Python (Boto3) or the Amazon CLI. Earlier versions don’t include the InvokeWebSearch operation.

  • Permission to call the API, as described in the following section.

Grant permission to call the API

To call the API, an Amazon Identity and Access Management (IAM) principal needs the bedrock-agentcore:InvokeWebSearch permission on the Amazon managed web search tool. The tool’s Amazon Resource Name (ARN) has the following form:

arn:aws:bedrock-agentcore:<Region>:aws:tool/web-search.v1

The account field of the ARN is the literal value aws, because Amazon owns the tool. It is not your account ID.

The following identity-based policy allows a principal to call the API in one Region. Replace <Region> with the code of a Region from Regions. To allow calls in every Region, use * in place of the Region code.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowInvokeWebSearch",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeWebSearch",
            "Resource": "arn:aws:bedrock-agentcore:<Region>:aws:tool/web-search.v1"
        }
    ]
}

Search the web

Only webSearchId and searchQuery are required. The identifier of the Amazon managed web search tool is web-search.v1. For an example of the response, see Response.

The following Amazon SDK for Python (Boto3) and Amazon CLI examples search for recent pages about a topic. They return up to five results, limit the results to two domains, and keep only pages published in January 2026:

Example
Amazon SDK (Boto3)
import boto3
from botocore.exceptions import ClientError

client = boto3.client("bedrock-agentcore", region_name="us-east-1")

try:
    response = client.invoke_web_search(
        webSearchId="web-search.v1",
        searchQuery="Amazon Bedrock AgentCore release announcements",
        maxResults=5,
        filters={
            "domainFilter": {
                "include": ["example.net", "example.org"]
            },
            "publishedDateFilter": {
                "publishedAfter": "2026-01-01T00:00:00Z",
                "publishedBefore": "2026-01-31T23:59:59Z"
            }
        }
    )
except ClientError as error:
    print(error.response["Error"]["Code"], error.response["Error"]["Message"])
    raise

for result in response["results"]:
    print(result.get("title"), result.get("url"))
    print(result["text"])
Amazon CLI
aws bedrock-agentcore invoke-web-search \
  --region us-east-1 \
  --web-search-id web-search.v1 \
  --search-query "Amazon Bedrock AgentCore release announcements" \
  --max-results 5 \
  --filters '{
    "domainFilter": {"include": ["example.net", "example.org"]},
    "publishedDateFilter": {
      "publishedAfter": "2026-01-01T00:00:00Z",
      "publishedBefore": "2026-01-31T23:59:59Z"
    }
  }'

For the request fields and their limits, see Request and response. For the full request and response syntax, see InvokeWebSearch in the Amazon Bedrock AgentCore API Reference.