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 AWS SDKs or the AWS Command Line Interface (AWS CLI).

Prerequisites

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

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

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

• A current version of the AWS SDK for Python (Boto3) or the AWS 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 AWS Identity and Access Management (IAM) principal needs the bedrock-agentcore:InvokeWebSearch permission on the AWS 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 AWS 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 AWS managed web search tool is web-search.v1. For an example of the response, see Response.

The following AWS SDK for Python (Boto3) and AWS 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

AWS 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"])

AWS 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.