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

# Bolna

Give a Bolna voice agent the live web during a call. A custom function sends the caller's question to SpecStream, and in a few seconds the agent has the answer, the page it was read on, and the time it was read.

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

## What you need

-   A Bolna agent you can edit in Agent Studio.
-   A SpecStream account. New accounts get $10 of credit on sign-up, no card. [Create one](https://specstream.ai/signup?utm_source=bolna).

1.  1

    ## 1. Get your SpecStream key

    Copy your key from the [Search API screen](https://specstream.ai/workspace/search?utm_source=bolna&utm_medium=howto) of your SpecStream workspace. Or create one under **Agents & API**, choose **API keys**, then **Create API key**, with a total spending limit above zero. Bolna sends it in the `Authorization` header of each call.

2.  2

    ## 2. Add a custom function

    Open your agent in Agent Studio and go to the **Tools** tab. Under **Add a Custom Tool**, click **Write manually** to open the JSON editor.

3.  3

    ## 3. Paste the SpecStream function

    Replace the default schema with the one below. Put your key after `Bearer` in `api_token`, then click **Submit** and save the agent. The name `q` must be the same in `properties` and in `param`.

    Bolna custom function

    ```json
    {
      "name": "search_live_web",
      "description": "Use this function when the caller asks about something current or specific that you do not know for certain: opening hours, a price, a date, who holds a role at a company, a recent event, or a fact on a named website. Write the caller's question as one short, complete question.",
      "pre_call_message": "One moment, let me check that.",
      "parameters": {
        "type": "object",
        "properties": {
          "q": {
            "type": "string",
            "description": "The question to answer from the live web, in everyday words, with names and places spelled out."
          }
        },
        "required": [
          "q"
        ]
      },
      "key": "custom_task",
      "value": {
        "method": "POST",
        "param": {
          "q": "%(q)s"
        },
        "url": "https://api.specstream.ai/v1/web-search",
        "api_token": "Bearer YOUR_SPECSTREAM_API_KEY",
        "headers": {
          "Content-Type": "application/json"
        }
      }
    }
    ```

4.  4

    ## 4. Tell the agent how to say the answer

    Add these lines to the agent's prompt:

    In the agent prompt

    ```text
    When search_live_web returns, answer from data.answer.value in one or two spoken sentences. If the caller asks where it comes from, name the website in data.answer.page. If data.answer is null, say you could not confirm it and offer to follow up.
    ```

5.  5

    ## 5. Test it

    Call the agent and ask a question whose answer changes, such as today's opening hours of a shop in your city. The agent says the pre-call message, then answers from the page SpecStream read.

## What comes back

Bolna hands the reply to the agent's model. It is JSON with one key, `data`. For a question with one answer, `data.kind` is `fact`, and `data.answer` holds the `value` as the page prints it, the `page` it was read from, and `seen_at`, the time it was read. `data.sources` lists the search results that were read.

When no page prints a value that answers the question, `data.answer` is `null`, and the agent says so in place of guessing.

## When the caller asks for a list

For a request for many results, `data.kind` is `list`, and `data.rows` holds the first rows, each with its `name`, its `page`, and the facts the request asks for, every value with the page it was read from. The agent can read the first few to the caller.

The full list is a Deep Search run. `data.handoff` gives its estimated size and the call that starts it. A Deep Search run is quoted first and starts only after you approve its maximum, so it runs after the call, in your workspace or through the API. Every row arrives with the source URL and read time on each value.

## Why a custom function

Bolna's built-in Web Search tool takes one provider from a fixed list and that provider's key, with no address to change. A custom function calls any endpoint, so SpecStream goes in this way. The search runs on the Search API, the most accurate web search API in the world on [our published benchmarks](https://specstream.ai/benchmarks.md).

## Cost

Each call is one search at $5 per 1,000 searches of up to 10 results, taken from your balance with no quote and no approval. A search that returns no results costs nothing, and the reply's `price_usd` is what the call cost. Deep Search runs are charged per delivered row, never above the maximum you approved. See [how quotes and billing work](https://specstream.ai/docs/billing.md).

## Disconnect

Delete the function's card in the agent's **Tools** tab, then revoke the key in **Agents & API**. Questions: [support@specstream.ai](mailto:support@specstream.ai).

## More

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