A search-API wrapper adds a separate vendor credential, endpoint, response contract, and bill. Amazon Bedrock AgentCore WebSearch packages search as a managed MCP connector attached to a Gateway, and the agent discovers it with a standard tools/list call.
The evidence set contains 331 searches across 10 active days of normal agent traffic and a separate fixed suite of 47 cases that checks the connector’s contract and boundaries.
What the managed connector actually is
AgentCore WebSearch is available in us-east-1, eu-west-1, and ap-northeast-1, with the regional list documented by AWS. It is a built-in connector target on an AgentCore Gateway, spoken over MCP. You attach it with connectorId: "web-search" and the Gateway handles schema management, endpoint resolution, and service authentication.
Two things make it more than a search proxy. First, it is backed by a web index Amazon operates directly, spanning tens of billions of documents, rather than reselling a third-party engine. Second, it returns semantic snippets tuned for a model’s context window — ranked excerpts with source URLs, titles, and publication dates — not raw HTML you then have to strip. The design goal is intelligence per token, and it combines the web index with knowledge-graph facts so entities resolve to verified data rather than inferred page text.
The public documentation says the query is served within AWS infrastructure and is not sent to a third-party search engine. That is a documented service property, not something a client-side test can independently prove. The integration consequence is narrower and directly observable: the agent calls an AWS Gateway with its AWS identity and does not carry a separate search-vendor credential.
Why choose it over a search-API wrapper
The reason an agent needs web search at all is grounding. A model’s training data does not supply dependable current facts about a recent release, a changed price, or a new filing. WebSearch provides current web evidence with source citations. Whether a model uses that evidence correctly remains a separate answer-quality test.
The rest of the case is what you don’t build. Rolling your own web search for an agent is several projects stacked together: procure a third-party search API, manage keys and quotas and rate limits, parse inconsistent result formats, write snippet-extraction logic so the model gets passages instead of raw HTML, reason about where queries travel and how they’re retained, and keep coverage fresh over time. The managed connector collapses all of it into one connectorId.
Concretely, the benefits that matter:
- Evidence for grounding — current web results with citations that an answer model can use and that an evaluator can inspect.
- Zero infrastructure — no search API to provision, no quotas to tune, no result parser to maintain. The Gateway exposes it as a standard MCP tool.
- Framework-agnostic — any MCP-compatible client works: Strands, LangChain, LangGraph, CrewAI, or a hand-rolled shim. Nothing is tied to one agent framework.
- A purpose-built index, not a reseller — backed by an index Amazon operates directly (tens of billions of documents, refreshed within minutes), the same search infrastructure behind Alexa+, Amazon Q Business, and Kiro.
- An AWS-operated data path — AWS documents that queries are served within AWS infrastructure rather than sent to a third-party search engine. Treat that as a documented service property and evaluate it against your own security requirements.
- Usage-based pricing — $7 per 1,000 queries with no upfront commitment, plus Free Tier credits for new accounts. You pay per search, not for standing infrastructure.
The shape of the wiring
The connector lives in AWS. The caller can be a local agent speaking MCP over stdio or an agent deployed on AgentCore Runtime or other compute. Both discover the tool with tools/list and invoke it with tools/call. A deployed agent signs with its execution role; a local agent uses a small shim:
Caller
· deployed agent on AgentCore Runtime / Lambda / ECS → execution role signs (SigV4)
· local agent on your laptop (Codex / Cursor / Zed / Claude Code / Kiro / GitHub Copilot) → MCP shim signs (SigV4)
→ POST https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp
→ target (connectorId: web-search)
→ Amazon web index + knowledge graph
→ ranked snippets + source URLs + titles + datesYou create the Gateway once with authorizerType: AWS_IAM and protocolType: MCP, then add a connector target pointing at web-search. The Gateway assumes an execution role to reach the backend; that role needs no special search permissions because AWS operates the search stack.
If you want to bound what the tool can reach, connector version 1.2.0 supports request-level domain include/exclude lists and inclusive publication-date bounds, with up to 100 domains per list. Gateway-level domain policy can add an administrator-controlled boundary underneath those request filters.
One thing worth calling out, because it trips people up: configuring the connector needs current AWS tooling (or the console), but calling it does not. The invocation path is a SigV4-signed JSON-RPC POST to the gateway URL, so an agent or shim runs on whatever SDK version it already has.
Wiring in the auth
The Gateway is IAM-authorized, so the caller presents a SigV4-signed request from an AWS principal that has bedrock-agentcore:InvokeGateway permission on the Gateway. AWS documents that requirement in its inbound authorization guide. There is no separate search-vendor token endpoint, client secret, or refresh loop.
The signing is identical whether the caller is a deployed agent or a local one — it resolves credentials from the standard AWS chain (environment variables, then a named profile, then an instance or container role) and signs each MCP request before sending it. A deployed agent on Runtime or Lambda gets its execution role from that chain; a local shim can use a configured profile. Same code, different credential source:
import botocore.session, botocore.auth, botocore.awsrequest
def sign(url, body, region):
creds = botocore.session.Session().get_credentials().get_frozen_credentials()
req = botocore.awsrequest.AWSRequest(method="POST", url=url, data=body, headers={
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"MCP-Protocol-Version": "2025-06-18",
})
botocore.auth.SigV4Auth(creds, "bedrock-agentcore", region).add_auth(req)
return dict(req.headers.items())Notice what get_credentials() does not take: no search-vendor API key, secret, or token. A deployed agent presents its execution role automatically; a local tool config can select a profile and Region. In both cases the resolved principal still needs permission to invoke the Gateway.
What 331 real searches look like
This operational sample covers 10 active days of normal agent traffic. It is not a benchmark.
| Metric | Value |
|---|---|
| WebSearch invocations | 331 across 10 active days |
| Busiest day | 91 calls |
| Total request latency p50 | 635 ms |
| Total request latency p90 | 784 ms |
| Total request latency p99 | 1,013 ms |
| Connector backend time (p50) | 547 ms |
| SystemErrors | 0 |
| Throttles | 0 |
| UserErrors | 1 |
Total request p50 stayed under one second, with zero system errors and zero throttles across the sample. Connector backend time had a 547 ms p50, while total request latency had a 635 ms p50. Those independent percentiles describe the same traffic at different measurement points, but they cannot be subtracted to calculate Gateway overhead; paired traces are required for that conclusion.
Where these numbers come from
Every figure above is emitted automatically — there is nothing to instrument. The Gateway publishes to the CloudWatch namespace AWS/Bedrock-AgentCore, dimensioned per tool, so latency and error rate can be inspected for the WebSearch target specifically. TargetExecutionTime is the connector’s backend-time metric.
What it costs, from the actual bill
The pricing claim is easy to verify because it shows up as its own line. In Cost Explorer and the Cost and Usage Report, WebSearch appears under the service Amazon Bedrock AgentCore with the usage type USE1-WebSearchTool:Consumption-based:Queries. Across two billing periods, 144 queries cost $1.008 and 152 cost $1.064 — exactly $0.007 per query, or the advertised $7 per 1,000, with no rounding surprises. The Gateway itself bills separately and trivially, as USE1-Gateway:Consumption-based:API-Invocations (fractions of a cent for the same traffic) plus an even smaller Gateway:Consumption-based:Tool-Indexing line — a fraction of a tenth of a cent, and it scales with the number of tools registered on the gateway rather than with search volume, which fits a per-schema indexing cost for the Gateway’s semantic tool discovery. So the cost model is legible: one metered line for searches, one negligible line for gateway invocations, and nothing for standing infrastructure.
Runtime domain and date filtering
Connector version 1.2.0 supports runtime domain and published-date filtering. A call can pass filters.domainFilter.include / exclude and filters.publishedDateFilter.from / to, enforced server-side and layered under the Gateway’s administrator-level domain policy.
The current setup has two requirements: the target declares source.version: "1.2.0" so discovery advertises the filter schema, and the client populates those fields when it calls the tool. The target version alone does not apply a filter; the request arguments carry the domain and date constraints.
Controlled validation: 47 fixed cases
The operational sample answers how the connector behaves under normal agent traffic. The September 13 controlled suite answers whether fixed counts, filters, schema fields, protocol checks, and repeated queries behave as expected. All 47 retrieval calls completed successfully.
| Check | Result |
|---|---|
| Requested result counts | Requests for 1, 5, and 25 returned exactly 1, 5, and 25 |
| Domain-filter compliance | 20 of 20 returned results matched the requested domain constraint |
| Publication-date compliance | 20 of 20 returned results had parseable dates inside the inclusive requested bounds |
| Boundary behavior | An exact UTC date boundary passed; 100 excluded domains succeeded |
| Result schema | 426 of 426 results had valid URLs, nonempty excerpts, and publication dates; 424 had nonempty titles |
| Exact duplicate URLs | 7 within-request duplicates across the 47 cases |
| Repeat stability | URL-set Jaccard similarity across five repeated news queries was 1.000, 0.667, 1.000, 0.818, and 1.000 |
| Observed latency | 525 ms minimum, 867 ms median, 1,028 ms maximum |
These latency values come from one sequential controlled run, so they are boundaries of that run, not a load benchmark or service-level promise. The filter checks establish compliance among returned results; they do not measure whether filtering reduced recall or excluded relevant pages. The duplicate count uses exact URL equality without normalizing tracking parameters, redirects, or equivalent page variants.
The run produced 426 result objects and exercised the filter-capable schema through the Gateway. It also confirmed that an unsigned request was rejected with HTTP 401 while signed discovery and calls succeeded. At public list prices, the 47 searches, one separate discovered-tool search, and one signed discovery request were approximately $0.336245. That figure is arithmetic from the published rates, not billed-spend evidence, and stays separate from the two Cost Explorer amounts above.
What’s missing
Two honest constraints remain. The query is capped at 200 characters, which is fine for natural-language questions but forces you to decompose anything long. And the connector is semantic web search for grounding, not a data feed: the acceptable-use terms require you to retain and display source citations on any result you surface, and prohibit bulk-extracting results or using them to build a competing index.
Per-user authorization remains unverified for this connector. The current WebSearch path uses an IAM-authorized Gateway. A separate JWT-authorized Gateway used for other tools proves only the external Gateway authentication path; it does not establish the same behavior for WebSearch.
The documented path to finer control is a JWT-authorized Gateway with Cedar policy evaluation. The authorization request can use the token’s sub claim, tool name, Gateway resource, claims such as scope or role, and tool arguments. Per-user scoping remains a policy experiment for WebSearch until it passes through a disposable JWT-authorized Gateway.
So what
If you are giving an agent web search, the question is not which search API to wrap. It is whether the search results ground the agent and whether the documented data path meets your requirements. WebSearch combines an Amazon-operated index spanning tens of billions of documents with semantic snippets and knowledge-graph facts. AWS also documents that queries are served inside AWS infrastructure rather than sent to a third-party search engine. The 47-case run validates the exposed retrieval behavior; the service documentation remains the source for index architecture and data-path properties.
The auth model reuses AWS identity and an explicit bedrock-agentcore:InvokeGateway permission, so the integration adds no separate search-vendor secret or account. The remaining question is whether per-user Cedar policy stays understandable once multiple users, claims, and request-level filters interact. That is the next boundary to test before calling the multi-user integration complete.