The Managed Web Search Tool

Grounding agent responses in current web knowledge with no data egress.

A model's training data has a cutoff, and even a well-designed prompt cannot tell an agent about something that happened yesterday. The usual fix is a search tool: let the agent issue a query, read back results, and ground its answer in them. AgentCore's value proposition here is offering this as a built-in, managed tool - something you enable rather than build - alongside the custom tools you register yourself through Gateway.

Be aware up front: of everything in this section, the specifics of a managed web-search tool are among the least confirmed publicly at the time of writing. AWS's broader AgentCore materials describe built-in tools generally (with a documented code-execution/interpreter-style tool being the most concretely shown example), and web grounding fits the same pattern, but the exact tool name, its parameters, and how strictly "no data egress" is enforced should all be verified against current AWS documentation before you depend on the specifics below.

Recipe

Quick-reference recipe card - copy-paste ready. Tool name/parameters are illustrative; verify at build time.

# --- Python (boto3) --- illustrative shape, verify exact tool name/params at build time
import boto3, json
 
client = boto3.client("bedrock-agentcore", region_name="us-east-1")
resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/research-agent",
    payload=json.dumps({
        "prompt": "What were the top AWS re:Invent announcements this year?",
        "enabledTools": ["web_search"],  # representative name only
    }).encode(),
)
print(json.loads(resp["response"].read()))

// --- TypeScript (AWS SDK v3) --- illustrative shape, verify exact tool name/params at build time
import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore";
 
const client = new BedrockAgentCoreClient({ region: "us-east-1" });
const resp = await client.send(new InvokeAgentRuntimeCommand({
  agentRuntimeArn: "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/research-agent",
  payload: new TextEncoder().encode(JSON.stringify({
    prompt: "What were the top AWS re:Invent announcements this year?",
    enabledTools: ["web_search"], // representative name only
  })),
}));
console.log(new TextDecoder().decode(resp.response as Uint8Array));

• The caller-side shape is unchanged from any other invocation - a prompt in, an answer out - the tool is an internal detail of how that answer got grounded.
• Enabling a built-in tool is expected to be a much lighter step than registering a Gateway target, since there is no external service to describe.
• enabledTools (or whatever the real field turns out to be called) is a placeholder for "how you opt an agent into a specific built-in capability" - do not copy the field name as authoritative.
• As with all built-in tools, the harness (see that page) is the thing deciding when, during the reasoning loop, to actually call search.

Working Example

A harness-managed agent that is instructed to prefer search for time-sensitive questions and to say so when it used it.

# --- Python (boto3) --- illustrative shape, verify exact fields at build time
import boto3, json
 
control = boto3.client("bedrock-agentcore-control", region_name="us-east-1")
control.update_agent_runtime(  # representative operation name only
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/research-agent",
    modelId="amazon.nova-lite-v1:0",
    systemPrompt=(
        "You answer questions about current events. If a question depends on "
        "information newer than your training data, use the web search tool "
        "and mention that you searched."
    ),
    builtInTools=["web_search"],  # representative name only
)

// --- TypeScript (AWS SDK v3) --- illustrative shape, verify exact fields at build time
import { BedrockAgentCoreControlClient, UpdateAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore-control";
 
const control = new BedrockAgentCoreControlClient({ region: "us-east-1" });
await control.send(new UpdateAgentRuntimeCommand({ // representative operation name only
  agentRuntimeArn: "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/research-agent",
  modelId: "amazon.nova-lite-v1:0",
  systemPrompt:
    "You answer questions about current events. If a question depends on " +
    "information newer than your training data, use the web search tool " +
    "and mention that you searched.",
  builtInTools: ["web_search"], // representative name only
}));

What this demonstrates:

• Instructing the model to disclose when it searched is good practice regardless of the exact tool contract - it makes grounded vs. ungrounded answers distinguishable to a user.
• A built-in tool is still subject to the model's own judgment about when to call it - a vague prompt produces inconsistent search behavior just like with any tool.
• Nothing here differs structurally from registering a Gateway tool from the agent's perspective; the difference is that AWS operates the tool's backend, not you.
• Treat builtInTools as a stand-in for whatever field actually toggles this - the pattern (a named list of enabled built-ins) is the reasonable part, not the field name.

Deep Dive

Why a Built-In Tool Instead of Gateway

Gateway (covered on its own page) is for tools whose implementation is yours - an internal API, a Lambda function, something specific to your business. Web search is different: it is a generic capability nearly every agent could use, and AWS is positioned to operate it directly rather than have every customer wire up their own search API key and vendor contract. A built-in tool removes that integration work entirely - you are not managing credentials or a billing relationship with a search provider yourself.

The "No Data Egress" Framing

Part of AWS's positioning for managed built-in tools, web search included, is that the tool executes inside AWS-managed infrastructure rather than shipping your query (and by extension, conversation context) out to an arbitrary third-party endpoint you would otherwise have to configure and trust separately. This is a meaningful data-governance argument if it holds as described, but it is exactly the kind of claim worth confirming against AWS's current documentation and your own compliance requirements rather than taking at face value from any secondary source, including this page.

Interaction With the Reasoning Loop

Whether via the managed harness or a hand-written loop, a search-capable turn looks like any other tool-use turn: the model requests a call (implicitly, "search for X"), the tool executes, and results feed back as context for the next turn. The main practical difference from a custom tool is that you do not control the result format - you take what the built-in tool returns and can only shape behavior around it through the system prompt, not through your own result-formatting code.

Gotchas

• Assuming this tool is definitely named "web search" in the real API. It may be named or grouped differently. Fix: check current AgentCore built-in tool documentation for the actual name before writing code against it.
• Expecting deterministic search behavior from prompt wording alone. Models vary in how eagerly they invoke a search tool. Fix: test with your actual prompts and time-sensitive questions rather than assuming the instruction alone guarantees search use.
• Not disclosing search use to end users. An answer that silently used or didn't use live search can mislead users about its freshness. Fix: instruct the agent to state when it searched, and treat this as a UX requirement, not an optional nicety.
• Assuming zero data egress means zero data governance work. Even if the tool runs inside AWS, your own compliance posture may still require review of what queries are sent and logged. Fix: treat AWS's framing as a starting point, not a substitute for your own review.
• Relying on this tool for domain-specific or internal data. Web search only reaches public web content. Fix: use Gateway-registered tools for internal/private data sources instead.

Alternatives

FAQs

Related

• The AgentCore Managed Harness: Model + Prompt + Tools - how the harness decides when to call any tool, built-in or custom.
• AgentCore Gateway & Tool Registration - registering your own tools when the built-ins aren't enough.
• Observability & Guardrails for Production Agents - confirming whether a given answer actually used search.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Amazon Bedrock AgentCore is a fast-moving 2026 preview capability - verify exact API/CLI surface against current AWS docs before relying on specific method names.