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:

Creating the Connector

A Web Search connector is one resource in a declarative configuration directory. To create the connector, perform these steps:

  1. Write the connector file under the connectors/ directory, as described in Connector YAML.

  2. Reference the API key through an environment variable, as described in Referencing Secrets.

  3. 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_name field replaces the tool name. The name must start with web_search_, contain only lowercase letters, digits, and underscores, be at most 64 characters, and not be the name of a built-in tool such as web_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_description field 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_key references is set in the shell that runs sam config apply, or in a .env file 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: