> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/agent-web-search. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# Agent Web Search

Set `AGENT_WEB_SEARCH_TAVILY_ENDPOINT` to `https://api.specstream.ai/tavily/search`, put your SpecStream key in `TAVILY_API_KEY` and add `tavily` to `AGENT_WEB_SEARCH_PROVIDERS`. Agent Web Search's own Tavily provider then sends its searches to the SpecStream Search API, at $1 per 1,000 searches of up to 10 results. No code changes, no fork.

[SpecStream for Agent Web SearchCoding agents](https://specstream.ai/integrations/agent-web-search.md)

## What you need

-   Agent Web Search 0.8.1 or later (`pipx install agent-web-search-mcp`), as the MCP server, the CLI or the Hermes plugin.
-   A SpecStream key. [Get your key](https://specstream.ai/workspace/search?route=tavily&utm_source=agent-web-search&utm_medium=howto) on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

1.  1

    ## 1. Set the three variables

    The Tavily provider reads `AGENT_WEB_SEARCH_TAVILY_ENDPOINT` when it starts and posts every search to that exact address, so give the whole search address, `/search` included. It sends `TAVILY_API_KEY` as a Bearer token, which is where SpecStream reads its key.

    Keep `ddgs,exa,parallel` in the list to add SpecStream beside the keyless defaults, or set the list to `tavily` alone so every query is one SpecStream search.

    Shell, for the CLI

    ```bash
    export AGENT_WEB_SEARCH_TAVILY_ENDPOINT=https://api.specstream.ai/tavily/search
    export TAVILY_API_KEY=YOUR_SPECSTREAM_KEY
    export AGENT_WEB_SEARCH_PROVIDERS=ddgs,exa,parallel,tavily
    ```

2.  2

    ## 2. Give them to your MCP client

    The MCP server reads its environment from the client that starts it. In a client that reads an `mcpServers` file, add an `env` block to the `agent-web-search` entry. Keep that file out of git: the project's README asks you not to put keys in checked in MCP configuration.

    The CLI and the Hermes plugin read the same variables from the environment they run in. Restart the client so the server starts again with the new values.

    mcpServers entry

    ```json
    {
      "mcpServers": {
        "agent-web-search": {
          "command": "agent-web-search-mcp",
          "args": [],
          "env": {
            "AGENT_WEB_SEARCH_TAVILY_ENDPOINT": "https://api.specstream.ai/tavily/search",
            "TAVILY_API_KEY": "YOUR_SPECSTREAM_KEY",
            "AGENT_WEB_SEARCH_PROVIDERS": "ddgs,exa,parallel,tavily"
          }
        }
      }
    }
    ```

3.  3

    ## 3. Check it with the Tavily provider alone

    When several providers run, one that fails is left out of the reply and the others still answer, so a wrong address or key can go unnoticed. Run the CLI with only the Tavily provider and the same variables set. A working setup prints `providers.tavily.results`; a problem prints `all_providers_failed` with `tavily HTTP` and the status code. This check is one search.

    Terminal

    ```bash
    agent-web-search --provider tavily --max-results 5 "What changed in the latest Python release?"
    ```

4.  4

    ## 4. Ask your agent

    The MCP server has one tool, `web_search`. Its `providers` argument can narrow a call to `["tavily"]`, but it can't turn on a provider that isn't in `AGENT_WEB_SEARCH_PROVIDERS` when the server starts.

## What the Tavily provider sends

Each search is `POST` on the endpoint with `query`, `max_results` (1 to 20, 5 by default), `search_depth` set to `basic`, `topic` set to `general`, and no answer, page text or images. A `time_range` of `d`, `w`, `m` or `y` goes as `day`, `week`, `month` or `year`, and SpecStream keeps results from that window.

SpecStream answers in Tavily's shape. Agent Web Search reads `title`, `url`, `content` as each result's `description`, and `published_date` as `published_at` when the page states its date.

## When a search fails

| Message | What it means | What to do |
| --- | --- | --- |
| `tavily HTTP 401` | The key is missing, unknown, expired or revoked. | Check `TAVILY_API_KEY`, or make a new key under **Agents & API**. |
| `tavily HTTP 432` | The balance is empty, or the call would go over the account's monthly limit. | Add balance in your SpecStream workspace. |
| `tavily HTTP 403` | The key has no `finds:spend` scope, or the call would go over the key's limit. | Raise the key's limit, or make a key that can spend. |
| `tavily HTTP 429` | The account used its calls for the minute, or search is busy. Nothing is charged. | Send it again after the wait. |

## Cost

Each search the Tavily provider makes is one fast Search API call: $1 per 1,000 searches of up to 10 results. The default `max_results` of 5 stays inside that price. A call that asks for 11 to 20 results adds $0.0012. A search that returns no results costs nothing. Every call comes out of your balance with no quote and no approval, and each one is in your account's request log. New accounts start with $10 of credit, no card. See [pricing](https://specstream.ai/pricing.md).

The other providers in your list keep their own terms. `ddgs` and keyless `exa` and `parallel` send nothing to SpecStream.

## Why this provider

The SpecStream Search API is the most accurate web search API on SimpleQA Verified and WideSearch. Scores and method are on [the benchmarks page](https://specstream.ai/benchmarks.md). The same key works on the other drop-in addresses, listed in [drop-in search](https://specstream.ai/docs/integrations/drop-in-search.md), and on the [Search API](https://specstream.ai/docs/search-api.md) itself.

## Lists of records as well

Agent Web Search returns search results. For Deep Search, which returns every match on the live web as structured rows, add SpecStream to the same agent as an MCP server at `https://api.specstream.ai/mcp`, as in the [MCP guide](https://specstream.ai/docs/mcp.md). Both use one account.

## Turn it off

Remove `tavily` from `AGENT_WEB_SEARCH_PROVIDERS`, or delete `AGENT_WEB_SEARCH_TAVILY_ENDPOINT` to send the provider back to Tavily's own address, and restart the client. To end the key's access, revoke it under **Agents & API** in your SpecStream workspace. Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for Agent Web Search](https://specstream.ai/integrations/agent-web-search.md) covers what it does in Agent Web Search on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).