Web Search Connectors via the CLI (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 define the connector as a declarative configuration resource and apply it with the Solace Agent Mesh CLI, instead of using the Agent Mesh UI. To configure the same connector in the UI, and to read about choosing a provider, the API key check, and the tool the connector provides, see Web Search Connectors (Early Access).
The following sections describe the YAML shape and the sam config command workflow. For the sam config plan, apply, and pull workflow that applies to every kind, see Managing Configuration as Code.
Prerequisites
Before you author a Web Search connector, ensure you have the following:
-
Outbound HTTPS access to the provider from the Secure Tool Runtime, as described in Network Access and Billing
-
The
samCLI and a declarative configuration directory with amanifest.yaml, as described in Managing Configuration as Code
Creating the Connector
A Web Search connector is one resource in a declarative configuration directory. To create the connector, perform these steps:
-
Write the connector file under the
connectors/directory, as described in Connector YAML. -
Reference the API key through an environment variable, as described in Referencing Secrets.
-
Add the connector to the manifest and apply it, as described in Applying the Connector.
Connector YAML
A connector is a single YAML file under the connectors/ directory. The file declares the resource envelope (kind, name, and description) and a spec block that sets type: web_search, the provider as the subtype (tavily or exa), and the settings under values.
The following example shows a Tavily connector:
# connectors/tavily-search.yaml
kind: connector
name: tavily-search
description: "Tavily web search for the research agents."
spec:
type: web_search
subtype: tavily
values:
api_key: ${TAVILY_API_KEY}
api_base: https://api.tavily.com
max_results: 5
safe_search: "no"
The following example shows an Exa connector that filters unsafe content out of the results:
# connectors/exa-search.yaml
kind: connector
name: exa-search
description: "Exa web search for the support agents."
spec:
type: web_search
subtype: exa
values:
api_key: ${EXA_API_KEY}
api_base: https://api.exa.ai
safe_search: "yes"
The name must be 3 to 255 characters and unique across all connectors in your deployment. The description must be 10 to 1,000 characters.
The following table maps each field in values to its label in the Agent Mesh UI.
| Field | UI label | Required | Default | Description |
|---|---|---|---|---|
api_key
|
API Key | Yes | None | The API key from your Tavily or Exa account, referenced as ${VAR}. |
api_base
|
API Base URL | No | https://api.tavily.com (Tavily) or https://api.exa.ai (Exa) |
The provider API endpoint. If you omit it, the connector uses the provider's default URL. Set it only to use a private mirror or proxy. |
max_results
|
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
|
Safe Search | No | "no"
|
Whether to filter adult or unsafe content out of the results. To filter, set "yes". |
The api_base value must be an absolute http:// or https:// URL with a hostname, and must not contain a username or password. If you change api_base in an update, you must also set api_key: Agent Mesh does not send the stored key to a new address. The safe_search value is the string "yes" or "no", so quote it as the examples do.
Optional Tool Overrides
The agent's web search tool is named web_search_ followed by the last eight characters of the connector's ID. Two optional fields in values change what the agent's language model sees:
-
The
tool_namefield replaces the tool name. The name must start withweb_search_, contain only lowercase letters, digits, and underscores, be at most 64 characters, and not be the name of a built-in tool such asweb_search_google. Agent Mesh rejects any other name when you apply the connector. The agent numbers citations only for tools whose names start with that prefix. -
The
tool_descriptionfield replaces the description of what the tool does. Agent Mesh keeps the instructions that tell the model how to cite the results.
If you set tool_name and assign several Web Search connectors to one agent, give each connector a different name.
Referencing Secrets
Never write the API key into the YAML file. The api_key field takes a ${VAR} placeholder that the Agent Mesh CLI substitutes from the environment at apply time. Before you run sam config apply, set the variable that the placeholder names, for example TAVILY_API_KEY, in your shell. The Agent Mesh CLI also loads a .env file from the nearest ancestor directory, so you can keep the value there instead.
When you run sam config pull to export an existing connector, the Agent Mesh CLI rewrites the key back to a ${VAR} placeholder, so a pulled repository never contains a live credential. For more information, see Secrets and Variables.
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 it to source control. If a key leaks, revoke it in your provider account, create a replacement, and apply the connector again with the new key.
Applying the Connector
List the connector under resources.connectors in the manifest, alongside any agents that use it:
# manifest.yaml
kind: manifest
name: my-deployment
description: Connectors and the agents that use them.
target:
url: https://platform.example.com
resources:
connectors:
- tavily-search
agents:
- research-assistant
To give an agent the web search tool, list the connector's name under spec.connectors in the agent's file. The following example shows an agent that searches through the tavily-search connector:
# agents/research-assistant.yaml
kind: agent
name: research-assistant
description: Researches questions on the internet and cites its sources.
spec:
systemPrompt: |
You research questions for the analyst team. Run a web search for current
information before you answer, and cite your sources.
modelProvider:
- general
connectors:
- tavily-search
inputModes:
- text
outputModes:
- text
Create the connector before the agent that references it. An agent that names a connector missing from the Platform service fails to deploy. For more information about the other agent fields, see Creating Agents with the CLI.
Validate your changes without affecting the Platform service, then apply them when you are ready:
sam config plan sam config apply
The sam config plan command shows the connectors and agents that would be created, updated, or deleted. The sam config apply command reconciles the Platform service to match the manifest. It creates and updates resources but does not delete anything unless you pass --prune.
When sam config apply creates or updates the connector, Agent Mesh checks the API key with one test search, as described in API Key Check:
-
If the provider rejects the key, the apply fails for this connector with an error that starts with "Tavily rejected the API key" or "Exa rejected the API key".
-
In any other case where the key could not be confirmed, the apply saves the connector and prints the reason as a warning that names the connector.
Using the Connector in Workflows
Workflow tool nodes do not offer the web search tool. To run a web search from a workflow, use an agent node whose agent lists the connector under spec.connectors. For more information about node types, see Creating Workflows with the CLI (Early Access).
Security Considerations
Web Search connectors use a shared credential model. For more information, see Shared Credential Model.
Be aware of the following considerations when you assign a Web Search connector to agents:
-
Every agent assigned to the connector searches with the same API key and shares that key's rate limits, plan limits, and credits. 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, so review the provider's data handling terms before you assign the connector to agents that handle sensitive data.
For more information about protecting the API key, see Security Considerations in Web Search Connectors (Early Access).
Troubleshooting
Use the following tips to resolve issues with a Web Search connector that you apply from the Agent Mesh CLI.
Apply Fails Because the Provider Rejected the API Key
The apply output shows "Tavily rejected the API key" or "Exa rejected the API key".
Check the following:
-
The environment variable that
api_keyreferences is set in the shell that runssam config apply, or in a.envfile that the Agent Mesh CLI loads. -
The key is active in your provider account and belongs to the provider named in
subtype.
Apply Rejects the Tool Name
The apply output shows an error that starts with tool_name must start with "web_search_".
Change tool_name so that it starts with web_search_, contains only lowercase letters, digits, and underscores, is at most 64 characters, and is not the name of a built-in tool such as web_search_google. To keep the generated name, remove tool_name.
Apply Rejects the API Base URL
The apply output shows an error that starts with API Base URL must be.
Change api_base so that it starts with http:// or https://, includes a hostname, and contains no username or password. To use the provider's own API endpoint, set api_base to https://api.tavily.com for Tavily or https://api.exa.ai for Exa.
Next Steps
From here, you can:
-
Give an agent the web search tool by listing the connector under
spec.connectorsin the agent's file. For more information, see Creating Agents with the CLI. -
Choose a provider and review the tool the connector gives an agent. For more information, see Web Search Connectors (Early Access).
-
Manage every resource kind through the same workflow. For more information, see Managing Configuration as Code.