Agentcore Websearch

AgentCore Web Search

Search the web using the AgentCore Web Search tool through a private MCP gateway in the user's AWS account, via the agentcore-websearch CLI. Authentication is local AWS credentials (SigV4/IAM) — no API keys or tokens. Results are grounded, cited, and current.

> [!NOTE] > This skill only searches. It assumes the agentcore-websearch CLI is installed > and the AgentCore Gateway already exists, with AGENTCORE_GATEWAY_URL set (env or a > .env). Provisioning the gateway and installing the CLI is a one-time step — see > the project's README.md / AGENTS.md. This skill never creates or deletes > AWS resources.

Prerequisites — run this preflight check first

Before searching, actually run the commands below in the shell and read their printed output. Do not infer readiness from a .env file, from this conversation, or from earlier turns — environment variables that matter are the ones live in the shell that will run agentcore-websearch, so verify them with a real echo.

# 1. Is the CLI installed and on PATH?
command -v agentcore-websearch || echo "MISSING: run 'uv tool install .' in the project repo"

# 2. Is the gateway URL actually set in THIS shell's environment?
echo "AGENTCORE_GATEWAY_URL=${AGENTCORE_GATEWAY_URL:-}"

# 3. Which AWS identity/profile will sign requests?
echo "AWS_PROFILE=${AWS_PROFILE:-}"
aws sts get-caller-identity --query Arn --output text 2>&1

Interpret the real output:

• Line 2 prints `` → the URL is not exported in this shell. If you're

running the CLI from a directory containing a .env, the CLI will load it — but confirm by running agentcore-websearch --list-tools (below), not by reading the file. Otherwise export it: export AGENTCORE_GATEWAY_URL=https://…/mcp (see the project's README/AGENTS.md to provision the gateway if it doesn't exist yet).

• Line 3 shows an unexpected profile/account → the caller will sign as the wrong

identity (a common cause of 403). Override per-call with --profile , or export AWS_PROFILE=.

• get-caller-identity errors → credentials are missing/expired; refresh your

AWS_PROFILE / SSO login.

The caller's IAM principal needs bedrock-agentcore:InvokeGateway on the gateway. Confirm the whole chain end-to-end with a live, non-destructive call:

agentcore-websearch --list-tools    # prints the WebSearch tool on success

Search

agentcore-websearch ""

Options:

• --max-results N — number of results, 1–25 (default 10)
• --json — raw tool result JSON (results[] with text, url, title, publishedDate)
• --list-tools — show the gateway's tools (diagnostic)
• --gateway-url / --profile / --region — override the environment/.env

Workflow

1. On first use in a session, run the [preflight check](#prerequisites--run-this-preflight-check-first)

and read its real output — don't assume the env is set.

1. Formulate a focused query (must be ≤ 200 characters).
2. Run agentcore-websearch with an appropriate --max-results.
3. Read the printed results (title, URL, publication date, snippet).
4. Always cite sources (title + URL) in the answer — an AWS acceptable-use

requirement for AgentCore Web Search.

Examples

agentcore-websearch "latest TypeScript release"
agentcore-websearch "AWS re:Invent 2026 keynotes" --max-results 15 --json

Notes & limits

• Region: the gateway lives in us-east-1; the CLI signs for the host region

automatically, so a different AWS_REGION in the shell is fine.

• Cost: ~$7 per 1,000 queries (each search = one query).
• Common errors:
• AGENTCORE_GATEWAY_URL is not set → export it, or cd to a dir with a .env,

or provision per the project's README/AGENTS.md.

• credentials missing/expired → refresh your AWS_PROFILE / SSO login.
• Insufficient permissions → caller lacks bedrock-agentcore:InvokeGateway.
• agentcore-websearch: command not found → uv tool install . in the project repo.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aws-samples
• Source: aws-samples/sample-agentcore-websearch-agent-skill
• License: MIT-0

Install and usage instructions live in the source repository linked above.