Skip to the page
Get started free

Bland

Give a Bland phone agent live web search. A webhook tool sends the caller's question to SpecStream, and a few seconds later the agent has the answer, the page it was read on, and the time it was read.

SpecStream for BlandAgent frameworks & builders

What you need

  • A Bland agent you can edit in the agent builder, and the owner, admin or operator role to add a secret.
  • A SpecStream account. New accounts start with $10 of credit, no card. Create one.

  1. 1. Store your SpecStream key as a secret

    Copy your key from the Search API screen of your SpecStream workspace, or create one under Agents & API, API keys, Create API key, with a spending limit above zero.

    In Bland, set the sidebar selector to All agents, open Tools, and on the Secrets tab click Add Secret. Name it specstream_api_key and paste the key as a Static secret.

  2. 2. Create a webhook tool

    Open your agent, go to Tools, click Create tool, and choose Webhook.

    Name: Search live web. Description: Answer a question 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. Agent speech: One moment, let me check that.

  3. 3. Point it at the Search API

    Set the method to POST and the URL to https://api.specstream.ai/v1/web-search. On the Authorization tab, choose Bearer Token and pick specstream_api_key. On the Headers tab, add Content-Type with the value application/json. On the Body tab, enter:

    Body
    {
      "q": "{{q}}"
    }

  4. 4. Let the agent fill in the question

    Under Detected variables, click Add input variable next to q. Set its type to string, mark it required, and give it this instruction: The caller's question as one short, complete question, with names and places spelled out.

  5. 5. Declare the answer fields

    Keep ok and message checked under Output fields, then save the tool and open it again: on a POST tool the response rows are named rest_api_post_* only after the first save. Add these rows, each with a name and a JSONPath:

    answer: $.data.rest_api_post_data.data.answer.value. answer_page: $.data.rest_api_post_data.data.answer.page. top_result: $.data.rest_api_post_data.data.sources[0].snippet.

    Set Timeout to 15000. Checking at least one output field is what makes the tool wait for the answer.

  6. 6. Test it

    Run the tool with a sample question, such as today's opening hours of a shop in your city. The response shows ok as true and the answer in answer. A 401 means the secret holds the wrong key; a 403 names the spending limit to raise.

  7. 7. Tag the tool into the prompt

    Building the tool does not give it to the agent. In the agent's Prompt, type @, pick Search live web, and add how to use the answer. Check that the tool now shows under Tool references:

    Agent prompt
    When the caller asks about something that can change, use @Search live web. If {{ok}} is true and {{answer}} is filled, say it in one or two sentences, and if the caller asks where it comes from, name the website in {{answer_page}}. If {{answer}} is empty, say you could not confirm it and offer to follow up. Do not read out web addresses.

What comes back

Bland puts SpecStream's reply in data.rest_api_post_data. The reply 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 read, each with its url, title, site and snippet.

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

Inside a pathway

Tools attach per prompt, and they do not follow the agent into a pathway. If the step that needs live answers lives in a pathway, tag Search live web in that pathway's prompt too.

Tagging gives the agent its own copy of the tool. To change the tool later, open it from the agent's Tool references row, so the agent's copy changes too.

On the legacy Custom Tools API

Bland now calls Custom Tools legacy and builds new tools in the agent builder. If your calls still send a tools array with the call request, the same search fits that form. The {{input}} variable comes from input_schema, and response maps the reply into variables you use in the prompt as {{answer}} and {{answer_page}}:

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. 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, with the source URL and read time on every value.

Cost

Each tool 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. The key's spending limit caps what the agent can spend, and Bland bills its own minutes separately. Search runs on the Search API, the most accurate web search API in the world on our published benchmarks. See balance, quotes, and billing.

Disconnect

Remove Search live web from the agent's prompt and delete it under Tools, then revoke the key in Agents & API and delete the specstream_api_key secret in Bland. Questions go to [email protected].

More

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