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

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 on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

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
SPECSTREAM_API_KEY="YOUR_SPECSTREAM_KEY"

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
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. 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
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. Settings for other SearXNG clients are on Moving off SearXNG.

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 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.

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: [email protected].

SpecStream for OWL covers what it does in OWL on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].

OWL