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

# OWL

Give OWL's Web Agent live web search from SpecStream. CAMEL's SearxNGToolkit takes the address of any SearXNG instance, and SpecStream answers at one, so you add one toolkit to the agent's tools list and run no SearXNG server of your own.

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

## What you need

-   OWL installed from its repository as its README shows, with your model key in `owl/.env`. OWL pins `camel-ai[owl]==0.2.84`, and that release ships `SearxNGToolkit`.
-   A SpecStream key. [Get your key](https://specstream.ai/workspace/search?route=searxng&utm_source=owl&utm_medium=howto) on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

1.  1

    ## 1. Add your key to owl/.env

    `examples/run.py` loads `owl/.env` when it starts, the same file that holds `OPENAI_API_KEY`. Add your SpecStream key there:

    owl/.env

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

2.  2

    ## 2. Give the Web Agent the SearxNG toolkit

    In `examples/run.py`, import `os` and `SearxNGToolkit`. Inside `construct_agent_list()`, next to `search_toolkit = SearchToolkit()`, create the toolkit with SpecStream's SearXNG address and your key. Then put its tools in the `tools` list of `web_agent`, in place of `search_duckduckgo`.

    Give the address without `/search`: the toolkit adds `/search` to every call itself.

    examples/run.py

    ```python
    import os
    
    from camel.toolkits import SearxNGToolkit
    
    # inside construct_agent_list(), next to search_toolkit = SearchToolkit()
        searxng_toolkit = SearxNGToolkit(
            searxng_host="https://api.specstream.ai/searxng/" + os.environ["SPECSTREAM_API_KEY"],
        )
    
    # the tools list of web_agent
            tools=[
                *searxng_toolkit.get_tools(),
                FunctionTool(search_toolkit.search_wiki),
                FunctionTool(document_processing_toolkit.extract_document_content),
                *browser_toolkit.get_tools(),
            ],
    ```

3.  3

    ## 3. Run a task that needs the web

    Run `examples/run.py` with your task as its argument. The Web Agent calls the toolkit's `search` tool, SpecStream answers in SearXNG's JSON shape, and the agent opens the pages it picks with its browser toolkit as before.

    To see the calls, open the request log of your workspace. Each search is listed with its query and price.

    Terminal, in owl

    ```bash
    python examples/run.py "What changed in the latest PostgreSQL release?"
    ```

## What SearxNGToolkit sends and gets back

Each call of the tool is one `GET` to `https://api.specstream.ai/searxng/<key>/search`. SpecStream reads the key from the address and answers in SearXNG's own JSON shape: `results[]` with `title`, `url` and `content`. The toolkit turns each result into the `title`, `link` and `snippet` the agent reads.

| SearxNGToolkit | SpecStream |
| --- | --- |
| `q` | The question, in everyday words, in any language |
| `format=json` | SearXNG's JSON reply |
| `language`, `en` by default | The language the search is run in |
| `categories`, `general` by default | Web results. `images` returns image results |
| `time_range`: `day`, `week`, `month` or `year` | Only results from that period |
| `pageno=1` | The first page of 10 results |
| `num_results`, 10 by default | Cut by the toolkit from the reply. The call is priced as 10 results |

## Why a hosted address in place of your own SearXNG

SearxNGToolkit needs a SearXNG instance that answers `format=json`. Run your own and you keep a server, a `settings.yml` with the JSON format turned on and a limiter, and the public engines it asks can rate limit or block it under an agent's traffic. SpecStream's address needs none of that: each search runs on SpecStream's servers and is read from the live web at the time of the call.

SpecStream's search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions and 64.0 item F1 on all 200 WideSearch tasks. Scores and method are on the [benchmarks page](https://specstream.ai/benchmarks.md). Settings for other SearXNG clients are on [Moving off SearXNG](https://specstream.ai/migrate/searxng.md).

## What each search costs

-   Each search is one Search API call through a drop-in address: $1 per 1,000 searches of up to 10 results, from your balance, with no quote and no approval.
-   SearxNGToolkit asks for the first page and names no count, so every search is 10 results at that price. A search that returns no results costs nothing.
-   New accounts start with $10 of credit, no card. [Balance and billing](https://specstream.ai/docs/billing.md) has the details.

## Limits and errors

-   The `search` tool catches every error, writes `Search failed:` with the error to the log, and gives the agent an empty list. When the agent finds nothing, read the log first.
-   `401` in that line means the key in the address is missing or wrong. Check `SPECSTREAM_API_KEY` in `owl/.env`.
-   When the account has used its calls for the minute, SpecStream answers `429` with `Retry-After`, and nothing is charged. The toolkit does not retry, so the agent gets an empty list for that search.
-   CAMEL logs the address when the toolkit starts, and `examples/run.py` sets the log level to `DEBUG`, so your key shows in the terminal. Keep that output, and `owl/.env`, out of anything you share.

## Use it in any CAMEL agent

SearxNGToolkit is part of CAMEL, so the same three lines work in any `ChatAgent` or `Workforce`, in OWL or outside it: pass `*SearxNGToolkit(searxng_host=...).get_tools()` in the agent's `tools`. More ways to build with SpecStream are in [agent frameworks](https://specstream.ai/docs/frameworks.md).

## Go back

Run `git checkout -- examples/run.py` in the `owl` folder, or put `FunctionTool(search_toolkit.search_duckduckgo)` back in the `tools` list and delete the toolkit lines. To stop the key working everywhere, revoke it in **Agents & API**. Questions: [support@specstream.ai](mailto:support@specstream.ai).

## More

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