[sundargthb]

Summary

WebSearchClient can now call the new Web Search API (InvokeWebSearch on the bedrock-agentcore data plane) directly. With no gateway argument, the client uses the API; with gateway_id, gateway_arn, or gateway_endpoint, it behaves exactly as before.

from bedrock_agentcore.tools import WebSearchClient

client = WebSearchClient(region="us-east-1")
response = client.search("aws news this week", max_results=5)
for result in response:
    print(result.published_at, result.title, result.url)

Changes

• WebSearchApiBackend (new, exported): calls invoke_web_search through boto3. It builds the data plane client the same way BrowserClient and CodeInterpreter do (BEDROCK_AGENTCORE_DP_ENDPOINT override, validate_region, SDK User-Agent). It holds no lock, since boto3 clients are thread-safe, so one client can serve concurrent searches.
• Default backend: WebSearchClient(region=...) with no gateway argument now uses the API. Previously this raised ValueError, so no existing call changes behavior. A new web_search_id argument defaults to web-search.v1.
• Fixed filters on the client: include_domains, exclude_domains, published_after, and published_before set on the constructor apply to every search. A call to search() can narrow them but not widen them: excludes are combined (the 100-domain limit counts both), a call's include is kept only if it equals or is a subdomain of a client include, compared case-insensitively (no match returns an empty response without a call, after the call's arguments are validated), and a date bound applies only when it is stricter. Client-level date bounds are validated in the constructor. This lets applications keep rules out of a model's control.
• Parsed dates: WebSearchResult gains published_at and acquired_at, timezone-aware UTC datetimes parsed from either the API's ISO 8601 timestamps or the gateway connector's "05:00PM, Wednesday, October 28 2026, PDT" form. published_date keeps the raw value.
• Errors and timeouts: on the API path, ClientError (for example ThrottlingException, AccessDeniedException) is raised as is, matching BrowserClient and CodeInterpreter. timeout sets the boto3 client's connect and read timeouts.
• Dates: a date-only published_before covers that whole day on the API, as on the gateway; fractional seconds are kept; the gateway's date form is parsed without the process locale.
• UTC dates: the API accepts only UTC date-times, so the backend converts a bound given with an offset.
• KNOWN_API_REGIONS (warning only, like KNOWN_REGIONS).

Testing

• Unit: tests/bedrock_agentcore/tools passes (378 passed). New tests cover the backend's request translation, UTC conversion, ClientError pass-through, timeouts, date-only and fractional bounds, fixed-filter narrowing (subdomains, case, combined limit, validation order), and locale-independent date parsing for both transports.
• Integration: new tests_integ/tools/test_web_search_api_client.py, which skips when botocore has no invoke_web_search.
• Live: tests_integ/tools/test_web_search_api_client.py passes (6 passed) against the API in us-east-1 with public botocore 1.43.127. Also verified earlier with a preview botocore build, including the LangChain toolkit on top of this client and a Deep Agents subagent.

Dependencies

• boto3 / botocore floor raised to 1.43.127, the first public release with InvokeWebSearch (uv.lock updated; only boto3, botocore, and awscrt moved).

This change was developed with the help of an AI coding assistant (Claude Code). All code was reviewed and tested by the author.

[github-actions]

✅ No Breaking Changes Detected

No public API breaking changes found in this PR.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)