Integrate · Agent Tool Integrations

Amazon Bedrock AgentCore Web Search

Give BotDojo agents web search through an Amazon Bedrock AgentCore Gateway in your own AWS account, with cited results and queries that stay inside AWS.

5 min read

Connect the Amazon Bedrock AgentCore Web Search Tool to BotDojo so any agent can search the web. BotDojo calls an AgentCore Gateway in your AWS account, so queries stay inside AWS and AWS bills the searches to your account.

It works with any model. The agent decides when to search, BotDojo runs the search, and the results come back to the agent with citations that appear in chat.

Built-In Web Search Or Your Own Gateway

You don't need this integration for agents to search the web. The built-in Search Web tool and agent web research use the web search service your deployment is configured for, and those searches are billed as web search usage.

Connect this integration when you want searches to run through a gateway in your AWS account instead: for example, to keep queries in your account, set your own domain filters on the gateway, or have AWS bill the searches to you.

For Administrators

BOTDOJO_WEB_SEARCH_PROVIDER picks the service behind built-in web search for the whole deployment. Users never choose it.

`BOTDOJO_WEB_SEARCH_PROVIDER`	Built-in web search	Serp API integration and node
Unset or `serpapi`	SerpApi, using `BOTDOJO_SERPA_API_KEY`.	Available.
`agentcore`	Every built-in search runs on the AgentCore gateway below: Search Web (both modes), the legacy Search Web node, agent web research and the skills `web_search` tool. SerpApi is never called, even if `BOTDOJO_SERPA_API_KEY` is set. If the gateway settings are missing, searches fail with an error instead of falling back.	Hidden from the integration list, and existing Serp API nodes fail with an error.

Any other value is treated as agentcore, so a typo can't turn SerpApi back on.

With agentcore, set these server environment variables. Store the keys in your secrets manager, not in source control.

Variable	Value
`BOTDOJO_AGENTCORE_WEB_SEARCH_GATEWAY_ID`	The gateway ID.
`BOTDOJO_AGENTCORE_WEB_SEARCH_REGION`	The gateway's Region. Defaults to `us-east-1`.
`BOTDOJO_AGENTCORE_WEB_SEARCH_ACCESS_KEY_ID`	Access key for an IAM user that only has `bedrock-agentcore:InvokeGateway` on the gateway.
`BOTDOJO_AGENTCORE_WEB_SEARCH_SECRET_ACCESS_KEY`	That user's secret access key.

Set up the gateway and IAM user the same way as in Before You Start. AgentCore has no direct-answer box, so Quick Answer mode returns the top 5 results instead.

Before You Start

You need an AWS account in a Region that offers the Web Search Tool: us-east-1, us-east-2, us-west-2, eu-west-1, ap-southeast-2, ap-northeast-1 or us-gov-west-1.

Create a gateway with IAM inbound authorization. In Amazon Bedrock AgentCore, create a gateway with the MCP protocol and the AWS IAM authorizer.
Add a Web Search Tool target. Add a connector target with connectorId: "web-search". You can set a target-level domain include or exclude list here; agents can't override it. See Web Search Tool.
Grant the gateway service role access to the tool. The role needs bedrock-agentcore:InvokeWebSearch on arn:aws:bedrock-agentcore:<region>:aws:tool/web-search.v1.
Create an IAM identity for BotDojo. Give it only permission to invoke this gateway, then create an access key for it:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:InvokeGateway",
      "Resource": "arn:aws:bedrock-agentcore:<region>:<account-id>:gateway/<gateway-id>"
    }
  ]
}

Don't reuse the access keys from your Amazon Bedrock model integration. A separate identity limited to this gateway keeps the keys' reach small.

Connect In BotDojo

In BotDojo, open Integrations.
In Agent Tools, find Amazon Bedrock AgentCore Web Search and click Connect.
Choose the gateway's AWS Region and enter its Gateway ID. BotDojo builds the gateway's MCP URL from these, so requests only go to AgentCore.
Enter the AWS Access Key ID and AWS Secret Access Key for the identity you created.
Click Test Connection. BotDojo signs a tools/list request and checks that the gateway exposes the WebSearch tool.
Click Connect.

To give an agent web search, add the Web Search tool from this integration to the agent.

What This Integration Supports

webSearch accepts:

query (required): a natural-language query of 200 characters or fewer.
max_results: 1 to 25 results. The default is 10.
include_domains and exclude_domains: lists of up to 100 domains each, such as aws.amazon.com. A root domain also matches its subdomains.
published_after and published_before: ISO-8601 UTC dates that bound the results' publication dates.

AWS validates domain and date values and returns an error the agent can see if one is wrong.

Each result has a title, url, publishedDate (when known), text (the passages from the page that match the query) and a citationId. The agent cites results inline, for example [^1], and BotDojo shows the sources in chat.

Request filters are applied on top of the gateway target's own lists. They can narrow results but can't bring back domains the target excludes.

Usage Requirements And Billing

AWS requires you to keep and display the source citations and links for any Web Search result you show users. Keep citations enabled in chat experiences that use this tool. You also may not use the tool to extract content in bulk or to build a competing index. See the Acceptable use section of the Web Search Tool documentation.

Searches are billed by AWS to the account that owns the gateway, along with Gateway usage. BotDojo does not add a per-search charge for this integration.

Troubleshooting

Status 401 or 403: Check the access keys, that the identity has bedrock-agentcore:InvokeGateway on this gateway, and that the gateway uses IAM inbound authorization rather than JWT.
"Could not find a WebSearch tool": Add a Web Search Tool target to the gateway, or check the Region and Gateway ID.
The tool returns an error: The message from the Web Search Tool is shown as-is. A common cause is a query over 200 characters.