feat(tools): add WebSearchClient for invoking Amazon Web Search

[sundargthb]

Description

The SDK can already create a web search connector target on a gateway (GatewayClient.create_web_search_target, #656), but there is no way to call the resulting tool from Python. Today anything that is not already an MCP client has to hand-roll the SigV4 signed MCP handshake against the gateway endpoint to use web search.

This adds WebSearchClient:

from bedrock_agentcore.tools import WebSearchClient

client = WebSearchClient(region="us-east-1", gateway_id="my-gateway-abc123")
for result in client.search("what is amazon bedrock agentcore", max_results=5):
    print(result.title, result.url)

Design notes

No new dependency. The transport sits behind a WebSearchBackend seam. GatewayMcpBackend speaks only the slice of MCP streamable HTTP that one tool call needs (initialize, the notifications/initialized ack, optionally tools/list, then tools/call) using urllib3 and botocore.auth.SigV4Auth, both already core dependencies. mcp-proxy-for-aws would do the signing for us, but it is currently dev/test only here and it is async, so it would change the SDK's dependency surface and the calling style for one capability. If reviewers would rather take that dependency as a published extra, the backend is one file to swap and the public search() signature does not move.

Two response framings. A gateway may answer a POST with application/json or with text/event-stream. Both are parsed, since which one comes back for a single tools/call is not something the client can assume.

Tool name resolution. Gateway prefixes every tool with the name of the target it came from, delimited by three underscores, so the tool the agent sees is <targetName>___WebSearch, not WebSearch. Passing target_name derives the name directly and skips a round trip. Otherwise tools/list is walked (following nextCursor) and the WebSearch tool is picked, with a clear error when more than one target exposes one.

Validation before the call. query is required and capped at 200 characters, max_results at 1 to 25, per the documented tool schema. The domain and published-date filters require connector version 1.2.0 or later on the target, which the docstring says.

Citations are preserved. WebSearchResult keeps url, title and published_date alongside text, because the acceptable use terms require source citations and links to be retained and displayed in anything surfaced to an end user. Dropping them in the response type would make compliant use harder than it needs to be.

Endpoint safety. get_gateway_mcp_endpoint validates the gateway identifier as a DNS label before interpolating it into the hostname, matching the region validation already in _utils/endpoints.py, so a crafted identifier cannot redirect the request off AWS. The connection header is excluded from signing, which otherwise produces a signature mismatch server-side.

Region handling. The connector is offered in us-east-1, eu-west-1 and ap-northeast-1. Calling from another region logs a warning rather than raising, so a stale constant in the SDK never blocks a call to a region that was added after the release.

Testing

uv run pytest tests -q passes: 3501 passed, 10 skipped, 4 xpassed. 97 new unit tests (81 for the client, 16 for the gateway identifier validation) cover the SigV4 header set, the request sequence, session reuse, both response framings, tool-name resolution including pagination and ambiguity, the isError and JSON-RPC error paths, ARN parsing, and the gateway identifier validation. ruff check and ruff format --check are clean. Statement coverage of the new module is 100%.

Not verified against a live service. The web search connector is enabled per account and this repo's integration test account is not entitled to it, so the invoke path has been exercised only against mocked HTTP responses. The request shapes come from the public tool schema and response format documentation, and the MCP sequence from the streamable HTTP transport spec, but nothing here has completed a real search. tests_integ/tools/test_web_search_client.py is included and will exercise the real path once run against an entitled account with WEB_SEARCH_GATEWAY_ID set; it skips rather than fails without one. Reviewers with an entitled account running that file would be the useful confirmation.

Confirmed with the service team

The API surface this is built on has since been confirmed by the Web Search Tool team, and matches what is implemented here: SigV4 (AWS_IAM) with no search-specific API key or credential; availability in us-east-1, eu-west-1 and ap-northeast-1; access scoped through IAM policies on the gateway ARN rather than any key; and both domainFilter (include and exclude, 100 domains per list) and publishedDateFilter (from/to, ISO-8601 UTC, inclusive) at target and request level from connector version 1.2.0.

Two clarifications from that exchange are now in the docstrings: the caller's credentials need bedrock-agentcore:InvokeGateway on the gateway ARN while the gateway service role needs bedrock-agentcore:InvokeWebSearch on the connector, and request-level include lists intersect with the target-level include list rather than replacing it, so disjoint lists return no results with no error raised.

Checklist

• Unit tests added
• Integration tests added (skip without an entitled account and a gateway)
• Lint and format pass
• No new dependencies

[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)

[tejaskash]

Reviewed the transport layer against the MCP streamable HTTP spec. Tests pass locally. Inline comments below, ordered roughly by severity. The first three matter once this runs against a real gateway.

[agentcore-devx-automation]

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

[tejaskash]

Requesting changes for the first three items in my inline review above (#658 (review)):

1. SSE decoder returns the first JSON-RPC message rather than the response matching the request id (line 459).
2. urllib3 transport exceptions escape _post despite the WebSearchError contract in the docstring (line 314).
3. An expired session (HTTP 404) leaves the backend permanently failing until close() (line 327).

The remaining comments are non-blocking.

[tejaskash]

All 12 items addressed at 0ed088e. Verified locally: 171 tests pass, and I exercised _decode_jsonrpc directly with a notification ahead of the reply, a reply to another id, and a message split across two data: lines. The reordered _initialized handling with rollback is the right call given the protocol version header dependency. Approving.