feat(tools): add AgentCore Web Search as a Strands Agents tool

[sundargthb]

Description

Adds AgentCoreWebSearch, exposing the AgentCore Web Search tool as a Strands Agents tool. Placement follows memory/integrations/strands, payments/integrations/strands and gateway/integrations/strands: a subpackage behind the existing strands-agents extra, reached only by explicit import. No pyproject.toml change, and a base install is unaffected.

from strands import Agent

from bedrock_agentcore.tools.integrations.strands import AgentCoreWebSearch

with AgentCoreWebSearch(region="us-east-1", gateway_id="my-gateway-abc123") as search:
    agent = Agent(tools=[search.web_search])
    agent("What changed in the most recent boto3 release?")

Notes

region is defaulted only when no region and no gateway ARN were given. WebSearchClient does region = region or arn_region, so filling a default in here unconditionally would silently send a eu-west-1 gateway's traffic to us-east-1.

A failed search raises rather than returning the message as a result. The Strands executor converts the exception to a status: "error" tool result, so the agent keeps running and the model can react. Returning "Web search failed: ..." as a successful result is indistinguishable to the model from a search that found nothing.

Both are pinned down by tests that drive a real Agent, with a scripted model standing in for the model's
choice and WebSearchClient stubbed, so the agent, the tool registry, the spec generation and the tool
executor are the real ones. I checked those tests bite by mutating the source: dropping include_domains
from the forwarded arguments, and returning the failure as text instead of raising, each turned two tests
red and nothing else.

One forward-compatibility note: which transport is used stays inside WebSearchClient. Every gateway argument here is optional and only the ones supplied are forwarded, so the direct web search API will work through the same call without a signature change in this module.

Testing

$ uv run pytest tests/bedrock_agentcore/tools/integrations -q --cov=src/bedrock_agentcore/tools/integrations --cov-report=term-missing
27 passed
src/bedrock_agentcore/tools/integrations/strands/web_search.py   69   0   24   0   100%

$ uv run pytest tests/ -q
3572 passed, 10 skipped, 4 xpassed

$ uv run ruff check src tests tests_integ
All checks passed!

$ uv run ruff format --check src tests tests_integ
341 files already formatted

$ uv run mypy src/bedrock_agentcore/tools/integrations/
Success: no issues found in 3 source files

Also run against a live gateway, on an account entitled to the web search connector, with a web search connector target in us-east-1:

$ WEB_SEARCH_GATEWAY_ID=<gateway-id> BEDROCK_TEST_REGION=us-east-1 \
    uv run pytest tests_integ/tools/integrations/strands/test_web_search_integration.py -v
6 passed, 2 warnings in 14.34s

That covers cited results coming back, max_results being honoured, an include_domains filter, tool-name discovery through tools/list when no target_name is given, one backend and one connection pool being reused across searches, and the end to end path where a real Claude model on Bedrock decides to call the tool and a URL reaches the tool result in the agent's messages.

Two assertions in that file were wrong on their first live run and are fixed in this branch, both the test's fault rather than the tool's. max_results is honoured exactly, but asserting "3. " is absent searches the result extracts too, and web prose contains a digit followed by a period often enough that it was never going to hold, so the numbered blocks are counted instead. And Mcp-Session-Id is optional in MCP and this connector does not send one, so the backend's session id stays None however many searches run through it; the reuse test asserts the backend and its connection pool are the same objects instead.

Related

• The WebSearchClient this wraps, and its tests_integ/tools/test_web_search_client.py
• feat(aws): add AgentCore web search tool langchain-ai/langchain-aws#1275, the equivalent LangChain toolkit

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