Skip to main content

AgentCore Web Search API: call it directly or through Gateway?

AWS made web search on Amazon Bedrock AgentCore a plain API call. What InvokeWebSearch returns, how it differs from the Gateway tool and the Bedrock server-side tool, and the controls to set before an agent reads the web.

Share -
Dark navy CodeDTX banner with a glowing cyan network and the words AgentCore Web Search API: call it directly or through Gateway?

The AgentCore Web Search API is a generally available AWS call, InvokeWebSearch, that returns ranked web results without setting up AgentCore Gateway. Use it when your own code decides when to search, such as pipelines and custom agent loops. Keep the Gateway tool when the agent itself chooses to search and an administrator manages access centrally.

What AWS released

The Web Search API was announced by AWS on 10 November 2026 as generally available on Amazon Bedrock AgentCore. Web search on AgentCore already existed, but only as an MCP tool behind AgentCore Gateway. The new InvokeWebSearch API gives applications, custom agent loops and data pipelines the same search with no resources to create.

Access goes through what an AWS team already uses: the AWS SDKs or the AWS CLI, with calls authorised by IAM. At launch it is available in US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Sydney), Asia Pacific (Tokyo) and Europe (Ireland).

What actually changed

From the announcement, the Web Search product page and the AgentCore pricing page:

  • One call, no setup. You no longer need a Gateway and a Web Search target before the first query. Your code calls InvokeWebSearch and gets results back.
  • What comes back. Ranked results from an Amazon-operated web index. Each result has a text extract and, when available, the page title, URL and publication time. It returns material, not an answer: your model or code decides what to use and cite.
  • Filters per request. You can restrict each query by domain and by publication time, for example to recent announcements or a list of trusted sites.
  • Network and audit. Calls can come from your VPC through AWS PrivateLink, and each search can be logged as an AWS CloudTrail data event.
  • Price. Billing is per query, at the same rate as Web Search through Gateway, with no Gateway charges on top. The AgentCore pricing page lists the current rate.
  • Data handling. The product page says AgentCore queries are served inside AWS and never sent to a third-party search engine, and that Web Search does not write prompts or generated queries to durable storage.

Which of the four web paths fits

AWS now offers web grounding four ways, and they suit different designs. This mapping is CodeDTX's advice, built on the official descriptions:

  • InvokeWebSearch (the new API): your code decides when to search. Good for retrieval steps that run before the model, scheduled research jobs, enrichment pipelines and fact checks against named domains. You control the query text, the filters and how many queries run.
  • Web Search as a Gateway target: the agent decides when to search, through MCP. An administrator adds it once and every attached agent can call it, from clients such as Strands Agents, LangChain, LangGraph and CrewAI. Pick this when several agents share tools and you want one place to grant or remove access.
  • Web Search on Amazon Bedrock: a server-side tool in a Responses API call, where Bedrock runs the whole search loop and returns a grounded response with citations. The product page limits it to OpenAI GPT-5.4 and later models.
  • Web Answer on AgentCore: a finished answer with citations in a single call, billed per tool call at a higher rate than a search query. Use it when you want the answer, not raw results to feed your own model.

If your agent already uses the Gateway tool and works, there is no reason to rewrite it. The direct API matters most for teams that avoided Gateway because they only needed search, and for pipelines where a model choosing its own queries was never the right design.

Controls to set before an agent reads the web

Web results are text written by strangers, and they land in your model's context. Treat them as untrusted input, as you would any tool output covered in how AI agents connect securely:

  • Use the domain filter as an allow-list for anything that drives a decision, such as compliance checks or supplier data. Open web search is fine for exploration, not for actions.
  • Use the publication-time filter when freshness matters, and pass the returned publication time to the model so it can say how current a source is.
  • Turn CloudTrail data events on. The product page says data events are not logged by default, and that CloudTrail records who searched and when but not the query text or returned URLs. If your audit trail needs the query, log it in your own code with the same redaction rules you apply to prompts.
  • Cap query volume in code. Billing is per query, so a loop that searches on every turn adds up. With the direct API you decide the count; set a per-task limit and track it alongside your other agent running costs.
  • Check the acceptable use terms. AWS links an acceptable use policy for Web Search from the product page. Read it before you store, display or redistribute results.

When not to switch

  • Your data must stay in an EU Region other than Ireland. Europe (Ireland) is the only European Region at launch.
  • You need an answer, not results. Web Answer or the Bedrock server-side tool will save you building the synthesis and citation step.
  • Your search is about your own documents. Web search does not replace retrieval over internal content; test that retrieval separately.

Frequently asked questions

What is the difference between InvokeWebSearch and the Gateway Web Search tool?

Both use the same Amazon-operated web index and the same per-query price. InvokeWebSearch is a direct API call from your code, with no Gateway or target to create. The Gateway version is an MCP tool that agents discover and call themselves, managed centrally by an administrator. Choose the direct API when your code controls searching, and Gateway when the agent decides and several agents share tools.

Which models can use results from the AgentCore Web Search API?

Any. The API returns ranked results with text extracts, titles, URLs and publication times, and your code passes them to whichever model you run, on Bedrock or elsewhere. That differs from Web Search on Amazon Bedrock, the server-side tool, which AWS limits to OpenAI GPT-5.4 and later models through the Responses API. If you need model freedom, the AgentCore paths give it.

Do search queries leave AWS?

According to the AWS product page, queries on AgentCore are served inside AWS infrastructure and are not sent to a third-party search engine. AWS also says Web Search does not write your prompts or generated queries to durable storage. Your own application logs are a separate matter, so decide what query text you keep and apply your usual redaction rules to it.

Enable CloudTrail data event logging for Web Search, which AWS says is off by default. Each search is then recorded with the calling identity, time, action and Region context. CloudTrail deliberately leaves out the query text and returned URLs, so if investigations need to know what an agent searched for, record that in your own audit store with appropriate access controls.

Share this post

Contact us to build the right product

Talk to our engineers about your application, the systems it connects to, and what you want to build next.

Get in touch
Two people discussing work with a laptop