> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Web search tools for open models on Ollama and vLLM

> Give a local open-weights model web search and page fetch as tools: a tool loop with Ollama's SDK, and the vLLM server flags for the OpenAI-compatible loop.

A model running on your own hardware decides when to search the web or read a page, and your code runs each call with the Keenable SDK. Ollama and vLLM both take tools in the format the SDK exports, so you pass `TOOLS` as is.

| Server | How your code talks to it | Loop |
| - | - | - |
| Ollama | Ollama's SDK (`ollama`), or its OpenAI-compatible endpoint at `http://localhost:11434/v1/` | [Run the loop with Ollama](#run-the-loop-with-ollama) |
| vLLM | The OpenAI SDK, at the server's OpenAI-compatible endpoint, by default `http://localhost:8000/v1` | [Run the loop with vLLM](#run-the-loop-with-vllm) |

## How the loop works

1. Your code sends the conversation and `TOOLS` to the local server.
2. If the model wants the web, the assistant message holds `tool_calls`, each with a `function` that has a `name` and `arguments`.
3. Your code appends the assistant message, runs each call with `run_tool_call`, and appends one `role: "tool"` message per call.
4. When the assistant message has no tool calls, its `content` is the answer.

The model must support tool calling. A model without it answers from its own knowledge and never calls the tools.

## Prerequisites

* Ollama or vLLM installed, with a model that supports tool calling.
* Python 3 or Node.js with `tsx` to run the program.
* No Keenable key. The SDK searches without one. To raise the rate limit, set `KEENABLE_API_KEY` to an [API key](https://docs.keenable.ai/api-keys.md).

## Tool definition (copy verbatim)

Ollama and vLLM take each tool as `type: "function"` with a nested `function` object holding `name`, `description` and `parameters`. That is the format of the Keenable SDK's `TOOLS`:

```json Chat Completions format theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
[
  {
    "type": "function",
    "function": {
      "name": "keenable_search",
      "description": "Search the web for current information. Returns ranked pages with their title, URL and extracted page text. Use this whenever the answer depends on recent events or facts you are unsure about.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "What to look for, described in natural language rather than keywords."
          },
          "site": {
            "type": "string",
            "description": "Optional. Restrict results to one domain, e.g. 'arxiv.org'."
          },
          "exclude_domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional. Never return results from these hosts or their subdomains, e.g. 'pinterest.com'. Hosts only, no paths or wildcards. Up to 1,000."
          },
          "published_after": {
            "type": "string",
            "description": "Optional. Only pages published on or after this date (YYYY-MM-DD)."
          },
          "objective": {
            "type": "string",
            "description": "Optional. Two or three natural sentences, with no field labels and no line breaks, that cover: the exact facts, entities, numbers, dates or names a useful page must contain; task context the query does not state (who, where, when, eligibility, date window); which kinds of sources count or must be excluded; what is already established from earlier steps; and what is still unknown. Every sentence must be self-contained: name the entities, places, dates and figures explicitly, and never refer to 'the task', 'the clue', 'the question', 'above' or earlier results. Do not paste the conversation, and do not include personal, confidential or sensitive information. At most 1,000 characters."
          },
          "disable_cards": {
            "type": "boolean",
            "description": "Optional. true returns ordinary web pages in place of Keenable's cards (results Keenable writes for prices, exchange rates or company facts, whose URLs expire after one day). Default false."
          }
        },
        "required": [
          "query"
        ]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "keenable_fetch",
      "description": "Fetch one web page and return its main content as markdown. Use after keenable_search when a search snippet is not enough.",
      "parameters": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL of the page to read."
          }
        },
        "required": [
          "url"
        ]
      }
    }
  }
]
```

The loops below pass the SDK's `TOOLS` directly, so the definitions always match the SDK version you installed. If you paste the JSON instead, check the SDK column of the [arguments table](https://docs.keenable.ai/tool-calling.md#tool-arguments): an older `run_tool_call` drops any argument its version doesn't offer.

## Run the loop with Ollama

Pull a model that supports tool calling. This page uses `qwen3`:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
ollama pull qwen3
```

Install the Keenable SDK and Ollama's SDK:

```bash TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
npm install keenable ollama
```

```bash Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
pip install keenable ollama
```

Save this program as `ollama-tools.mts` or `ollama_tools.py`. It asks a question, runs every tool call the model makes, and prints the answer:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable, KeenableError, TOOLS, runToolCall } from "keenable";
import ollama, { type Message, type Tool } from "ollama";

const keenable = new Keenable();

const messages: Message[] = [
  { role: "user", content: "What changed in the latest Node.js LTS release? Cite your sources." },
];

while (true) {
  const response = await ollama.chat({ model: "qwen3", messages, tools: TOOLS as Tool[] });
  messages.push(response.message);
  const calls = response.message.tool_calls ?? [];
  if (calls.length === 0) {
    console.log(response.message.content);
    break;
  }

  for (const call of calls) {
    let content: string;
    try {
      content = await runToolCall(keenable, call.function.name, call.function.arguments);
    } catch (error) {
      content = `Tool call failed: ${error instanceof KeenableError ? error.message : error}`;
    }
    messages.push({ role: "tool", tool_name: call.function.name, content });
  }
}
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
from keenable import TOOLS, Keenable, KeenableError, run_tool_call
from ollama import chat

keenable = Keenable()

messages = [
    {"role": "user", "content": "What changed in the latest Node.js LTS release? Cite your sources."}
]

while True:
    response = chat(model="qwen3", messages=messages, tools=TOOLS)
    messages.append(response.message)
    if not response.message.tool_calls:
        print(response.message.content)
        break

    for call in response.message.tool_calls:
        try:
            content = run_tool_call(keenable, call.function.name, call.function.arguments)
        except KeenableError as exc:
            content = f"Tool call failed: {exc}"
        messages.append({"role": "tool", "tool_name": call.function.name, "content": content})
```

Run it with `npx tsx ollama-tools.mts` or `python ollama_tools.py` while Ollama is running. The program prints the model's final answer.

Ollama returns `arguments` as an object, which `run_tool_call` takes as is, and the tool message names the tool with `tool_name`. If a tool call fails, the loop sends the error message as the tool result so the model can retry. [Errors inside a tool call](https://docs.keenable.ai/tool-calling.md#errors-inside-a-tool-call) lists what `run_tool_call` raises.

## Run the loop with vLLM

vLLM returns tool calls only when the server starts with `--enable-auto-tool-choice` and a `--tool-call-parser` that matches the model. For Qwen2.5 models the parser is `hermes`:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
vllm serve Qwen/Qwen2.5-7B-Instruct --enable-auto-tool-choice --tool-call-parser hermes
```

vLLM's [tool calling docs](https://docs.vllm.ai/en/latest/features/tool_calling/) list the parser for each model family, such as `llama3_json` for Llama 3.1 and `mistral` for Mistral models.

The server speaks the OpenAI Chat Completions API, so the loop on [Tool calling](https://docs.keenable.ai/tool-calling.md#run-the-tool-calling-loop) runs against it unchanged. Point it at vLLM with these variables. vLLM ignores the key unless you started it with [`--api-key`](https://docs.vllm.ai/en/latest/serving/online_serving/openai_compatible_server):

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
export OPENAI_BASE_URL=http://localhost:8000/v1
export OPENAI_API_KEY=unused
export OPENAI_MODEL=Qwen/Qwen2.5-7B-Instruct
```

To run the same loop against Ollama instead, set `OPENAI_BASE_URL=http://localhost:11434/v1/` and `OPENAI_MODEL=qwen3`. Ollama requires a key value but ignores it.

## Differences from other providers

| Compared with | What changes with Ollama and vLLM |
| - | - |
| [Anthropic](https://docs.keenable.ai/tool-calling/anthropic.md) | No mapping: `TOOLS` goes in unchanged, and each result is its own `tool` message. No Anthropic key and no `max_tokens`. |
| [OpenAI](https://docs.keenable.ai/tool-calling/openai.md) | The servers speak Chat Completions, so use the loop on [Tool calling](https://docs.keenable.ai/tool-calling.md#run-the-tool-calling-loop) rather than the Responses API page. Tool calls depend on the model and, on vLLM, on the parser you start it with. |
| [Gemini](https://docs.keenable.ai/tool-calling/gemini.md) | No server-side conversation: you append every message and resend the list. |
| [Mistral](https://docs.keenable.ai/tool-calling/mistral.md) | Same tool format and message shape. Ollama's tool message names the tool with `tool_name` where Mistral's uses `name` and `tool_call_id`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.