Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Brave Search

Scalekit connector
Open markdown

The Brave Search connector lets your AI agent act in each user's Brave Search account. Each user connects their own Brave Search API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 18 tools.

Tools
18
What they doRead · write · destructive
18 · 0 · 018 read0 write0 destructive
Users sign in with

What you can do

  • Search the web: get real-time web results with titles, URLs, and snippets, filtered by country and language
  • Get AI answers: generate cited answers and summaries grounded in live Brave Search results
  • Search news, images, and videos: find recent news articles, images, and videos with freshness and safe search filters
  • Find local places: search points of interest by location and get addresses, hours, ratings, and reviews
  • Ground LLM responses: retrieve curated snippets and source URLs structured as context for AI-generated answers
  • Suggest and correct queries: get autocomplete suggestions and spelling corrections for search queries

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Brave Search connection

    In AgentKit > Connections, create a Brave Search connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'brave'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Brave Search:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'brave_local_place_search',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Brave Search credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • brave_chat_completionsGet AI-generated answers grounded in real-time Brave Search results using an OpenAI-compatible chat completions interface.Read-only

    Chat Completions

    Get AI-generated answers grounded in real-time Brave Search results using an OpenAI-compatible chat completions interface. Returns summarized, cited answers with source references and token usage statistics.

    Inputs

    messagesarrayrequired
    Array of conversation messages. Each message must have a 'role' (system, user, or assistant) and 'content' (string).
    countrystring
    Target country code for search results used to ground the answer (e.g., us, gb).
    enable_citationsboolean
    Include inline citation markers in the response text.
    enable_entitiesboolean
    Include entity information (people, places, organizations) in the response.
    enable_researchboolean
    Enable multi-search research mode for more comprehensive answers.
    languagestring
    Language code for the response (e.g., en, fr, de).
    modelstring
    The model to use. Must be 'brave' to use Brave's search-grounded AI model.
    streamboolean
    Whether to stream the response as server-sent events.
  • brave_llm_contextRetrieve real-time web search results optimized as grounding context for LLMs.Read-only

    LLM Context

    Retrieve real-time web search results optimized as grounding context for LLMs. Returns curated snippets, source URLs, titles, and metadata specifically structured to maximize contextual relevance for AI-generated answers. Supports fine-grained token and snippet budgets.

    Inputs

    qstringrequired
    The search query to retrieve grounding context for. Max 400 characters, 50 words.
    context_threshold_modestring
    Relevance filter aggressiveness for snippet selection. Defaults to balanced.one of strictbalancedlenientdisabled
    countinteger
    Max number of search results to consider (1–50). Defaults to 20.
    countrystring
    Country code for localised results (e.g., us, gb, de). Defaults to us.
    enable_localboolean
    Enable location-aware recall for locally relevant results.
    freshnessstring
    Filter results by publish date: pd (past day), pw (past week), pm (past month), py (past year), or YYYY-MM-DDtoYYYY-MM-DD.
    gogglesstring
    Custom re-ranking rules via a Goggles URL or inline definition.
    maximum_number_of_snippetsinteger
    Maximum total snippets across all URLs (1–100). Defaults to 50.
    maximum_number_of_snippets_per_urlinteger
    Maximum snippets per URL (1–100). Defaults to 50.
    maximum_number_of_tokensinteger
    Approximate maximum total tokens across all snippets (1024–32768). Defaults to 8192.
    maximum_number_of_tokens_per_urlinteger
    Maximum tokens per URL (512–8192). Defaults to 4096.
    maximum_number_of_urlsinteger
    Maximum number of URLs to include in the grounding response (1–50). Defaults to 20.
    safesearchstring
    Safe search filter level.one of offmoderatestrict
    search_langstring
    Language code for results (e.g., en, fr, de). Defaults to en.
  • brave_local_descriptionsFetch AI-generated descriptions for locations using IDs from a Brave web search response.Read-only

    Get Local Descriptions

    Fetch AI-generated descriptions for locations using IDs from a Brave web search response. Returns natural language summaries describing the place, its atmosphere, and what visitors can expect.

    Inputs

    idsarrayrequired
    Array of location IDs (up to 20) obtained from the locations field in a Brave web search response.
  • brave_local_poisFetch detailed Point of Interest (POI) data for up to 20 location IDs returned by a Brave web search response.Read-only

    Get Local POIs

    Fetch detailed Point of Interest (POI) data for up to 20 location IDs returned by a Brave web search response. Returns rich local business data including address, phone, hours, ratings, and reviews. Note: location IDs are ephemeral and expire after ~8 hours.

    Inputs

    idsarrayrequired
    Array of location IDs (up to 20) obtained from the locations field in a Brave web search response.
  • brave_rich_results_getFetch the enriched real-time 'rich' result (weather, stocks, sports scores, currency conversion, package tracking, etc.) for a callback_key.Read-only

    Get Rich Result

    Fetch the enriched real-time 'rich' result (weather, stocks, sports scores, currency conversion, package tracking, etc.) for a callback_key. The callback_key comes from the 'rich' field of a prior Web Search response — that search must have been made with a query that triggers a rich result hint (e.g. a weather or stock query).

    Inputs

    callback_keystringrequired
    The callback key identifying which rich result to fetch, returned in a Web Search response's rich.hint.callback_key field.

Workflows

Proxy API call
const result = await actions.request({
  connectionName: 'brave-search',
  identifier: 'user_123',
  path: '/res/v1/web/search',
  method: 'GET',
  queryParams: { q: 'best open source LLM frameworks 2025', count: '5' },
});
console.log(result.data.web.results);
Web search

Search the web and retrieve real-time results. Works on all plans including Free.

examples/brave_web_search.py
# Search for recent articles — freshness "pw" limits results to the past 7 days
result = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_web_search",
    tool_input={
        "q": "open source LLM frameworks 2025",
        "count": 5,
        "freshness": "pw",
    },
)


for item in result["web"]["results"]:
    print(item["title"], item["url"])
News search

Retrieve recent news articles by topic or keyword. Useful for monitoring a brand, topic, or competitor.

examples/brave_news_search.py
# Fetch the latest news on a topic from the past 24 hours
result = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_news_search",
    tool_input={
        "q": "AI regulation Europe",
        "count": 10,
        "freshness": "pd",   # pd = past 24 hours
    },
)


for article in result["results"]:
    print(article["title"], article["age"], article["url"])
LLM grounding context

Retrieve search results structured specifically for grounding LLM responses. Requires Pro plan. Use token_budget to stay within your model’s context window.

examples/brave_llm_context.py
# Get search context sized to fit a 4 000-token budget
result = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_llm_context",
    tool_input={
        "q": "vector database comparison 2025",
        "count": 5,
        "token_budget": 4000,
    },
)


# Pass the structured context directly to your LLM
grounding_context = result["context"]
print(grounding_context)
AI chat completions grounded in search

Get an AI-generated answer backed by real-time Brave Search results, using an OpenAI-compatible interface. Requires AI plan.

examples/brave_chat_completions.py
# Drop-in replacement for OpenAI /v1/chat/completions — results are grounded in live search
result = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_chat_completions",
    tool_input={
        "messages": [
            {"role": "user", "content": "What are the latest developments in quantum computing?"}
        ],
        "model": "brave/serp-claude-3-5-haiku",
    },
)


print(result["choices"][0]["message"]["content"])
# Each answer includes citations back to source URLs
for source in result.get("search_results", []):
    print(source["title"], source["url"])
Local place search and POI details

Find nearby businesses or points of interest, then retrieve full details. Requires Data for AI plan.

examples/brave_local_search.py
# Step 1: Find coffee shops near San Francisco city centre
places = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_local_place_search",
    tool_input={
        "q": "specialty coffee",
        "location": "San Francisco, CA",
        "count": 5,
    },
)


location_ids = [p["id"] for p in places["results"]]


# Step 2: Fetch rich details (hours, ratings, address) for those locations
# Location IDs expire after ~8 hours — always fetch details in the same session
pois = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_local_pois",
    tool_input={"ids": location_ids},
)


for poi in pois["results"]:
    print(poi["name"], poi["address"], poi["rating"])
AI summary with follow-up queries

Get an AI-generated summary for a search query, then surface follow-up questions. Requires Pro plan.

examples/brave_summarizer.py
# Step 1: Web search with summary: true to obtain a summarizer key
search_result = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_web_search",
    tool_input={
        "q": "benefits of RAG vs fine-tuning for enterprise LLMs",
        "summary": True,
        "count": 5,
    },
)


summarizer_key = search_result["summarizer"]["key"]


# Step 2: Retrieve the full AI summary using the key
summary = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_summarizer_search",
    tool_input={"key": summarizer_key, "entity_info": True},
)


print(summary["title"])
print(summary["summary"])


# Step 3: Get follow-up questions for a conversational search experience
followups = actions.execute_tool(
    connection_name="brave-search",
    identifier="user_123",
    tool_name="brave_summarizer_followups",
    tool_input={"key": summarizer_key},
)


for q in followups["queries"]:
    print("-", q)
LangChain integration

Use Scalekit’s LangChain helper to load all Brave Search tools into a LangChain agent. The agent selects and calls the right tool automatically based on the user’s query.

examples/brave_langchain_agent.py
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import ChatPromptTemplate


# Load all Brave Search tools — Scalekit handles auth for each call
tools = actions.langchain.get_tools(
    providers=["BRAVE_SEARCH"],
    identifier="user_123",
    page_size=100,  # avoid missing tools when a connector has more than the default page
)


llm = ChatAnthropic(
    model="claude-sonnet-4-6",
    api_key=os.environ["ANTHROPIC_API_KEY"],
)


prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful research assistant with access to Brave Search tools."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])


agent = create_tool_calling_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)


response = agent_executor.invoke({
    "input": (
        "Find the top 5 news articles about AI regulation in Europe from the past week "
        "and give me a one-sentence summary of each."
    )
})
print(response["output"])
All 121 in Analytics