Web Search Connectors (Early Access)
This feature is in the Early Access stage and under active development. Configuration schemas and behavior are subject to change. We recommend that you do not use this feature in production environments.
A Web Search connector lets agents search the internet through Tavily or Exa and cite the pages they find. You create the connector once with the provider's API key, then assign it to any agent. Each assigned agent gets one web search tool, and every result the agent cites appears as a numbered citation in the Agent Mesh UI chat.
The Agent Mesh UI marks the Web Search connector type with an EARLY ACCESS badge.
Web Search connectors are not the same as Search Connectors (Experimental), which query your own Elasticsearch clusters and Amazon OpenSearch domains.
If you use the web_search_google built-in tool, see Replacing Google Custom Search.
Network Access and Billing
The web search tool runs in the Secure Tool Runtime. For more information, see Where Each Tool Runs. Every search goes from the Secure Tool Runtime to the provider's API, so the Secure Tool Runtime must have outbound HTTPS access to api.tavily.com for Tavily or api.exa.ai for Exa, or to the address that you set in API Base URL. The agent receives the results.
The provider bills each search to the connector's API key. Every agent assigned to the connector shares that key, so every agent also shares the key's rate limits, plan limits, and credits.
Choosing a Provider
The following table shows the search options that each provider supports.
| Search option | Tavily | Exa |
|---|---|---|
| Image search | Yes | No |
| Recency filter (past day, week, month, or year) | Yes | Yes |
| Include or exclude specific domains | Yes | Yes |
The agent sets these options for each search. The agent sees only the options that the connector's provider supports.
Prerequisites
Before you create this connector, ensure you have the following:
-
Outbound HTTPS access from the Secure Tool Runtime to the provider, as described in Network Access and Billing
Creating the Connector
To create a Web Search connector, perform these steps:
-
In the Agent Mesh UI, navigate to the Connectors page and click Create Connector.
-
Select Web Search as the connector type, then select the provider: Tavily or Exa.
-
Enter a Connector Name that is unique across all connectors in your deployment. You can rename it later.
-
Enter a Description of 10 to 1,000 characters that tells other users what the connector is for.
-
Enter the provider's API Key. The form masks the value.
-
If your organization routes searches through a private mirror or proxy, enter its address in API Base URL. Otherwise, keep the default. For more information, see Connector Fields.
-
(Optional) Change Results per Search and Safe Search.
-
Click Create to save the connector. Agent Mesh checks the API key before it saves the connector. For more information, see API Key Check.
When you later edit a saved connector, keep the placeholder value in the API Key field to preserve the existing key. If you change the API Base URL, enter the key again, because Agent Mesh does not send the stored key to a new address.
Connector Fields
The following table describes the fields that a Web Search connector takes.
| Field | Required | Default | Description |
|---|---|---|---|
| API Key | Yes | None | The API key from your Tavily or Exa account. |
| API Base URL | Yes | https://api.tavily.com (Tavily) or https://api.exa.ai (Exa) |
The provider API endpoint that searches go to. Change it only to use a private mirror or proxy. |
| Results per Search | No | 5
|
The number of results a search returns when the agent does not ask for a specific number, from 1 to 20. |
| Safe Search | No | No | Whether to filter adult or unsafe content out of the results. To filter, select Yes. |
The API Base URL must be an absolute http:// or https:// URL with a hostname. Agent Mesh rejects a URL that contains a username or password.
API Key Check
When you create the connector, or edit it and enter a new API key, Agent Mesh runs one test search with that key. The test search asks the provider for a single result. If you edit the connector and keep the existing key, Agent Mesh does not run a test search. The result of the test search determines whether Agent Mesh saves the connector:
-
If the provider rejects the key, Agent Mesh does not save the connector and shows an error that starts with "Tavily rejected the API key" or "Exa rejected the API key". Check that the key is correct and active, then save again.
-
If the key has reached its rate limit, plan limit, or credit limit, Agent Mesh saves the connector and shows a warning. Agents' searches fail until the limit resets.
-
If the provider returns any other error, or the Platform service cannot reach the provider, Agent Mesh saves the connector and shows a warning that the key could not be checked.
The Platform service runs the test search from its own network location, which can differ from the network location of the Secure Tool Runtime that runs the searches. Be aware of the following limitations of the test search:
-
The Platform service does not send the test search through an outbound proxy.
-
By default, the Platform service does not contact private network addresses. For more information about the private-address setting, see Connectivity.
-
A test search against a private mirror usually ends in a warning.
A connector that saves with a warning can still work for the agents. If the agents' searches fail, see Searches Fail After the Connector Saves with a Warning.
Tools the Connector Provides
When you assign this connector to an agent, the agent gets one web search tool named web_search_ followed by the last eight characters of the connector's ID, for example web_search_3f9c2a71. If you assign several Web Search connectors to one agent, each connector gives the agent its own tool with its own name.
The agent's language model can set the following parameters when it calls the tool.
| Parameter | Required | Description |
|---|---|---|
query
|
Yes | The search query. |
max_results
|
No | The number of results, from 1 to 20. Defaults to the connector's Results per Search value. |
recency
|
No | Only results published within the last day, week, month, or year. |
include_domains
|
No | Only results from these domains, for example example.com. |
exclude_domains
|
No | No results from these domains. |
search_type
|
No | Set to image for an image search. Tavily only. |
The agent cites the results it uses in its response, and the Agent Mesh UI chat shows each citation as a numbered link to its source page.
The tool is built for agents, and workflow tool nodes do not offer it. To run a web search from a workflow, use an agent node whose agent has the connector assigned.
For more information about assigning, editing, and deleting connectors, see Configuring Connectors.
Replacing Google Custom Search
The web_search_google built-in tool searches through the Google Custom Search JSON API. Google shuts down the Custom Search JSON API on January 1, 2027. After that date, web_search_google cannot return results. For more information about the built-in tool, see Built-In Tools.
An agent gets web_search_google through the Research Tools (builtin_research_tools) toolset, the Web Request Tools (builtin_web_request_tools) toolset, or both. To keep web search working, perform these steps:
-
Create a Web Search connector, as described in Creating the Connector.
-
Assign the connector to each agent that uses
web_search_google, as described in Assigning Connectors to Agents. -
Exclude
web_search_googlefrom each toolset that contains it, and keep the toolsets' other tools. Use either of these methods:In the Agent Mesh UI, click Edit in the agent's Toolsets section, expand each toolset that contains
web_search_google, clear theweb_search_googlecheckbox, and click Apply.In the agent's YAML file, list
web_search_googleunderspec.toolsetExcludedTools, keyed by each toolset that contains it.
-
Replace any mention of
web_search_googlein the agents' instructions with a general instruction, for example "Run a web search for current information before you answer questions about recent events". If the instructions mention thedate_restrictparameter, replace it with therecencyparameter of the connector's tool. For more information, see Tools the Connector Provides. -
Redeploy the agents: in the Agent Mesh UI, click Save and Deploy; with the Agent Mesh CLI, run
sam config apply.
Security Considerations
Web Search connectors use a shared credential model. For more information, see Shared Credential Model.
To track usage and cost per team or use case, create a separate connector with its own API key for each one.
The agent sends its search queries to the provider. Queries can contain text from the user's conversation, so review the provider's data handling terms before you assign the connector to agents that handle sensitive data.
The API key lets anyone who holds it run searches that the provider bills to your account. Treat it as a production secret. Never commit downloaded configuration files that contain a real key. If a key leaks, revoke it in your provider account, create a replacement, and update the connector.
Troubleshooting
Use the following tips to resolve issues with this connector.
Save Fails Because the Provider Rejected the API Key
Agent Mesh shows "Tavily rejected the API key" or "Exa rejected the API key" and does not save the connector.
Check the following:
-
The key is copied in full, without extra spaces.
-
The key is active in your Tavily or Exa account.
-
The key belongs to the provider that you selected.
Searches Fail After the Connector Saves with a Warning
The connector saved with a warning that the key could not be checked, and the agent's searches fail.
Check the following:
-
The API Base URL is the provider's default, or the address of a mirror or proxy that the Secure Tool Runtime can reach.
-
The network that the Secure Tool Runtime runs in permits outbound HTTPS traffic to the provider or to the mirror or proxy.
-
The key has not reached its rate limit, plan limit, or credit limit, as shown in your provider account.
Agent Does Not Use the Web Search Tool
The agent answers without running a web search.
Check the following:
-
The connector is assigned to the agent, and you redeployed the agent after you assigned it. For more information, see Assigning Connectors to Agents.
-
The agent's instructions say when to run a web search, for example "Run a web search for current information before you answer questions about recent events".
Search Tool Is Not Found or Citations Are Missing After an Upgrade
The agent's web search fails because the tool is not found, or the search returns results but the chat shows no numbered citations.
To use Web Search connectors, run the current release of the Secure Tool Runtime, the Agent-Workflow Executor, and the Platform service. Check the following:
-
The Secure Tool Runtime runs the current release. An older Secure Tool Runtime does not have the web search tool.
-
The Agent-Workflow Executor runs the current release. Agents on an older Agent-Workflow Executor return search results without citations.
Upgrade any component that does not run the current release. If you upgrade the components separately, upgrade the Secure Tool Runtime first, then the Agent-Workflow Executor, and then the Platform service. Assign a Web Search connector to agents only after all three run the current release.
Next Steps
From here, you can:
-
Assign the connector to an agent. For more information, see Assigning Connectors to Agents.
-
Define the connector as version-controllable YAML instead. For more information, see Web Search Connectors via the CLI (Early Access).