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

# smolagents

smolagents' ApiWebSearchTool calls the Brave Search API by default. Set its endpoint to SpecStream's Brave address and your agents search through SpecStream's Search API, with no other code change.

[SpecStream for smolagentsAgent frameworks & builders](https://specstream.ai/integrations/smolagents.md)

## What you need

-   Python with smolagents installed. ApiWebSearchTool is in the current release, 1.26.0.
-   A SpecStream API key. New accounts get $10 of credit on sign up, no card. [Get your key](https://specstream.ai/workspace/search?route=brave&utm_source=smolagents&utm_medium=howto) on the Search API screen of your workspace.

1.  1

    ## 1. Put your key in the environment

    ApiWebSearchTool reads its key from an environment variable, `BRAVE_API_KEY` unless you name another one. Give the SpecStream key its own name, so it is never mixed up with a Brave key:

    Shell

    ```bash
    export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_KEY"
    ```

2.  2

    ## 2. Set the endpoint

    Pass SpecStream's address as `endpoint` and the variable's name as `api_key_name`. The tool sends the key in the `X-Subscription-Token` header and the question as `q`, the way Brave takes them, and SpecStream answers in Brave's shape: `web.results[]` with `title`, `url` and `description`, which is what the tool reads.

    `rate_limit=None` turns off the tool's own wait of one query per second. Leave it out to keep that wait.

    agent.py

    ```python
    from smolagents import ApiWebSearchTool, CodeAgent, InferenceClientModel
    
    search = ApiWebSearchTool(
        endpoint="https://api.specstream.ai/res/v1/web/search",
        api_key_name="SPECSTREAM_API_KEY",
        rate_limit=None,
    )
    
    agent = CodeAgent(tools=[search], model=InferenceClientModel())
    agent.run("What did Hugging Face release this week?")
    ```

3.  3

    ## 3. Check it

    Call the tool once on its own. It prints `## Search Results` and a numbered list of titles, links and descriptions. The tool's name stays `web_search`, so prompts written for the default tool keep working.

    Python

    ```python
    print(search("smolagents ApiWebSearchTool"))
    ```

## What the tool sends, and what comes back

| ApiWebSearchTool sends | SpecStream |
| --- | --- |
| `GET` to the `endpoint` you set | `https://api.specstream.ai/res/v1/web/search`, Brave's path on SpecStream's host |
| `q`, the agent's query | Searched as written |
| `count=10`, the tool's default `params` | 10 results, at the price of one search |
| `X-Subscription-Token` | Your SpecStream key |
| Reads `web.results[]` | `title`, `url` and `description` on each result |

## More results per search

`params` replaces the tool's default `{"count": 10}`, so name the count when you pass it. `params={"count": 20}` brings 20 results, and the call is priced as a search of 20 results, as [Search API](https://specstream.ai/docs/search-api.md) lists.

## Read pages with the Extract API

smolagents' VisitWebpageTool fetches a page itself with `requests`, so a page that refuses a plain read comes back as an error. This tool, with the same name, reads pages through SpecStream's [Extract API](https://specstream.ai/docs/extract-api.md) instead. A page that refuses a plain read is tried again as a browser, then from the site's feed, then from its newest public archive capture, and the reply is the page's main text as Markdown, without menus and ads:

## If a search fails

The tool raises the HTTP error it gets. `401` means SpecStream got no valid key: check that `SPECSTREAM_API_KEY` is set in the environment the agent runs in, and that the key was made on the Search API screen. A key made with no scopes can read and cannot search.

## Cost

Each search is one Search API call on the fast tier, which costs a fifth of the default search's $5 per 1,000 searches of up to 10 results. Each page read through the Extract API is $0.80 per 1,000 pages, and a page with no text is not charged. Both come out of your balance, with no quote and no approval. New accounts start with $10 of credit, no card. Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for smolagents](https://specstream.ai/integrations/smolagents.md) covers what it does in smolagents 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).