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

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 on the Search API screen of your workspace.

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

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

SpecStream for smolagents covers what it does in smolagents 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].