Using the Parallel Search and Research APIs with Ollama Tools
Local language models running on Ollama have a fixed training cutoff date. When you ask a local model about recent events, new software releases, or live market data, the model cannot answer from its weights alone. By combining Ollama native tool calling with the Parallel Search and Task (Research) APIs, a small local model can fetch current web facts or run multi-step research jobs and cite its sources.
This chapter shows how to wrap the official Parallel Python SDK (parallel-web) as Ollama tools. All code for this chapter is in the source-code/parallel_apis directory.
Why Use Parallel APIs with Local Models?
Standard web search engines return ranked links and short snippets written for human readers. To use a standard search engine with an LLM, your program must run a query, download full HTML pages, strip navigation and script tags, convert the markup to text, and trim the text so it fits inside a small local model context window.
Parallel (https://parallel.ai) provides APIs built for language models and agents:
- Parallel Search API (
client.search): Accepts both a natural-languageobjectiveand a list of shortsearch_queries. It returns pre-compressed textexcerptsextracted from relevant pages along with titles and URLs. This keeps token counts small for local models such asqwen3.5:2borqwen3.5:0.8b. - Parallel Task / Research API (
client.task_run.createandclient.task_run.result): Runs an asynchronous, multi-step web research job on Parallel servers. You supply an input topic, anoutput_schemadescription, and a processor tier (lite,base,core,pro, orultra). The API returns a synthesized answer along with abasisarray that lists confidence ratings (high,medium, orlow), reasoning, and source citations for the output.
By exposing both APIs as Python tool functions, an Ollama model can pick fast search for quick factual questions and deep research for complex reports.
How Ollama Native Tool Calling Works
When you pass Python functions in the tools=[...] argument of client.chat(), the Ollama Python SDK inspects each function signature, type annotations, and docstring at runtime. It converts that metadata into a JSON Schema tool specification and sends it to the model.
The conversation loop follows four steps:
- Your script sends the system prompt, the user prompt, and the tool definitions to Ollama.
- If the model needs external data, it returns an assistant message containing one or more
tool_callswith the chosen function name and JSON arguments. - Your script runs the matching Python function with those arguments and appends a message with
role="tool"containing the serialized tool output. - Your script calls
client.chat()again with the updated message list so the model can read the tool output and write a sourced response.
Data Formats Returned by Parallel
Before looking at the Python code, examine the data structures that our tool functions pass back into the Ollama context window.
A call to search_web returns a compact dictionary of search results where each entry contains a URL, a page title, and up to three relevant text excerpts:
1 {
2 "results": [
3 {
4 "url": "https://docs.parallel.ai/integrations/ollama-tool-calling",
5 "title": "Ollama Tool Calling - Parallel Documentation",
6 "excerpts": [
7 "Give local models (Qwen 3.5, Gemma 4, Llama 3.1+, etc.) running under Ollama real-time web search by registering Parallel Search as a tool.",
8 "Modern Ollama models support native tool calling. You pass tools=[...] on a chat call, the model emits structured tool_calls, your code executes them against Parallel, and you feed the results back in a follow-up turn."
9 ]
10 }
11 ]
12 }
A call to research_topic uses the Parallel Task API and returns the task run_id, the synthesized output, and the verification basis containing confidence scores, reasoning, and citations:
1 {
2 "run_id": "trun_01j8x9k2m4p7q",
3 "output": "Recent open-weight small language models supporting native tool calling include Qwen 3.5 (0.8B, 2B, 4B), Llama 3.2 (1B, 3B), and Granite 3.",
4 "basis": [
5 {
6 "field": "output",
7 "confidence": "high",
8 "reasoning": "Verified across official model documentation and Ollama library listings.",
9 "citations": [
10 {
11 "url": "https://ollama.com/library/qwen3.5",
12 "title": "qwen3.5 - Ollama Library"
13 }
14 ]
15 }
16 ]
17 }
Defining the Parallel Tool Functions
The file source-code/parallel_apis/parallel_tools.py defines two tool functions: search_web and research_topic.
Pay close attention to the docstrings in search_web and research_topic. Ollama reads the Args: section of each docstring to tell the language model how to format each parameter. In search_web, the docstring instructs the model to pass a self-contained objective and three diverse keyword queries of three to six words each.
Here is the complete listing of source-code/parallel_apis/parallel_tools.py:
1 import os
2 from typing import Any
3 from parallel import Parallel
4
5
6 def _get_parallel_client() -> Parallel:
7 api_key = os.environ.get("PARALLEL_API_KEY")
8 if not api_key:
9 raise ValueError("Set the PARALLEL_API_KEY environment variable.")
10 return Parallel(api_key=api_key)
11
12
13 def search_web(objective: str, search_queries: list[str]) -> dict[str, Any]:
14 """Searches the web for current and factual information using Parallel.
15
16 Args:
17 objective: A concise, self-contained search query. Must include the key entity or topic being searched for.
18 search_queries: Exactly 3 keyword queries, each 3-6 words. Must be diverse: vary entity names, synonyms, and angles. Each query must include the key entity. Never write sentences or use site: operators.
19
20 Returns:
21 A dict with a results list, each containing url, title, and excerpts.
22 """
23 client = _get_parallel_client()
24 response = client.search(
25 objective=objective,
26 search_queries=search_queries,
27 )
28 # Limit to 3 excerpts per result to keep tool output within small local model context limits.
29 return {
30 "results": [
31 {
32 "url": r.url,
33 "title": r.title,
34 "excerpts": r.excerpts[:3] if r.excerpts else [],
35 }
36 for r in response.results
37 ]
38 }
39
40
41 def research_topic(
42 topic: str,
43 output_schema: str = "A structured research report with key facts, findings, and dates.",
44 processor: str = "base",
45 ) -> dict[str, Any]:
46 """Executes a multi-step deep web research task with citations and confidence scores using the Parallel Task API.
47
48 Args:
49 topic: The research question or subject to investigate in depth.
50 output_schema: Description of the expected research output structure.
51 processor: Parallel processor tier to use (lite, base, core, pro, or ultra).
52
53 Returns:
54 A dict with the synthesized output and a basis list containing citations, confidence, and reasoning.
55 """
56 client = _get_parallel_client()
57 task_run = client.task_run.create(
58 input=topic,
59 task_spec={"output_schema": output_schema},
60 processor=processor,
61 )
62 # task_run.result blocks and polls the background job until synthesis completes or api_timeout expires.
63 run_result = client.task_run.result(task_run.run_id, api_timeout=600)
64
65 raw_basis = (
66 getattr(run_result.output, "basis", None)
67 or getattr(run_result, "basis", None)
68 or []
69 )
70 basis_summary = []
71 for item in raw_basis:
72 citations = [
73 {"url": c.url, "title": getattr(c, "title", "")}
74 for c in getattr(item, "citations", []) or []
75 ]
76 basis_summary.append(
77 {
78 "field": getattr(item, "field", "output"),
79 "confidence": getattr(item, "confidence", ""),
80 "reasoning": getattr(item, "reasoning", ""),
81 "citations": citations,
82 }
83 )
84
85 output_content = getattr(run_result.output, "content", run_result.output)
86 return {
87 "run_id": task_run.run_id,
88 "output": output_content,
89 "basis": basis_summary,
90 }
91
92
93 __all__ = ["search_web", "research_topic"]
In search_web, slicing r.excerpts[:3] bounds the returned payload size so that even if a search returns many results, the tool response will not overflow a local model’s context window. In research_topic, client.task_run.create() starts the research job on Parallel servers and returns a task_run handle with a run_id. Calling client.task_run.result(task_run.run_id, api_timeout=600) waits for the task to finish and returns the synthesized content together with its citation basis.
Building a Web Search Agent with Ollama
The file source-code/parallel_apis/search_agent.py connects search_web to an Ollama chat loop. It uses get_client() and get_model() from our shared ollama_config.py module so you can run the agent against either a local Ollama server or Ollama Cloud.
Here is source-code/parallel_apis/search_agent.py:
1 import json
2 import sys
3 from pathlib import Path
4
5 ROOT = Path(__file__).resolve().parents[1]
6 if str(ROOT) not in sys.path:
7 sys.path.insert(0, str(ROOT))
8
9 from ollama_config import get_client, get_model
10 from parallel_tools import search_web
11
12
13 def chat_with_search(user_message: str, model: str | None = None) -> str:
14 client = get_client()
15 active_model = model or get_model()
16 messages = [
17 {
18 "role": "system",
19 "content": (
20 "You are a helpful research assistant. Use search_web "
21 "for current information. Cite sources with URLs."
22 ),
23 },
24 {"role": "user", "content": user_message},
25 ]
26 available = {"search_web": search_web}
27
28 # Loop until the model produces a final answer without requesting more tool calls.
29 while True:
30 response = client.chat(
31 model=active_model,
32 messages=messages,
33 tools=[search_web],
34 )
35 messages.append(response.message)
36
37 if not response.message.tool_calls:
38 return response.message.content
39
40 for call in response.message.tool_calls:
41 fn = available.get(call.function.name)
42 if fn is None:
43 result = {"error": f"Unknown tool: {call.function.name}"}
44 else:
45 print(
46 f"[Tool Call] {call.function.name}("
47 f"{json.dumps(call.function.arguments)})"
48 )
49 result = fn(**call.function.arguments)
50 messages.append(
51 {
52 "role": "tool",
53 "tool_name": call.function.name,
54 "content": json.dumps(result),
55 }
56 )
57
58
59 if __name__ == "__main__":
60 prompt = "What is new with Parallel Web Systems and its Search API?"
61 print(f"Prompt: {prompt}\n")
62 answer = chat_with_search(prompt)
63 print("\nResponse:\n")
64 print(answer)
The while True loop in chat_with_search supports multi-step tool calling. If the first search does not answer every part of the user question, the model can emit a second search_web tool call before returning a final text response. The loop serializes each tool result to JSON and appends it with role="tool" and tool_name=call.function.name.
Combining Fast Search and Deep Research in One Agent
Some questions only need a single web lookup, while others need a structured report built from multiple sources. The file source-code/parallel_apis/research_agent.py passes both [search_web, research_topic] in the tools list so the Ollama model can choose the right tool for the prompt.
Here is source-code/parallel_apis/research_agent.py:
1 import json
2 import sys
3 from pathlib import Path
4
5 ROOT = Path(__file__).resolve().parents[1]
6 if str(ROOT) not in sys.path:
7 sys.path.insert(0, str(ROOT))
8
9 from ollama_config import get_client, get_model
10 from parallel_tools import research_topic, search_web
11
12
13 def run_research_assistant(user_message: str, model: str | None = None) -> str:
14 client = get_client()
15 active_model = model or get_model()
16 messages = [
17 {
18 "role": "system",
19 "content": (
20 "You are a research assistant with two tools: "
21 "use search_web for fast factual lookups, and use research_topic "
22 "when the user asks for an in-depth report with confidence scores "
23 "and verified citations. Always include source URLs in your answer."
24 ),
25 },
26 {"role": "user", "content": user_message},
27 ]
28 available = {
29 "search_web": search_web,
30 "research_topic": research_topic,
31 }
32
33 while True:
34 response = client.chat(
35 model=active_model,
36 messages=messages,
37 tools=[search_web, research_topic],
38 )
39 messages.append(response.message)
40
41 if not response.message.tool_calls:
42 return response.message.content
43
44 for call in response.message.tool_calls:
45 fn = available.get(call.function.name)
46 if fn is None:
47 result = {"error": f"Unknown tool: {call.function.name}"}
48 else:
49 print(
50 f"[Tool Call] {call.function.name}("
51 f"{json.dumps(call.function.arguments)})"
52 )
53 result = fn(**call.function.arguments)
54 messages.append(
55 {
56 "role": "tool",
57 "tool_name": call.function.name,
58 "content": json.dumps(result),
59 }
60 )
61
62
63 if __name__ == "__main__":
64 prompt = (
65 "Run a deep research report on recent open-weight small language models "
66 "that support native tool calling, and summarize the findings with citations."
67 )
68 print(f"Prompt: {prompt}\n")
69 answer = run_research_assistant(prompt)
70 print("\nResponse:\n")
71 print(answer)
The system message tells the model when to pick each tool: search_web for fast factual lookups and research_topic when the user asks for an in-depth report with confidence scores and verified citations.
Running the Examples and Interpreting the Output
To run the examples, set your PARALLEL_API_KEY environment variable and run the scripts with uv run from source-code/parallel_apis:
1 $ cd source-code/parallel_apis
2 $ export PARALLEL_API_KEY="your-parallel-api-key"
3 $ uv run search_agent.py
4 Prompt: What is new with Parallel Web Systems and its Search API?
5
6 [Tool Call] search_web({"objective": "Find recent product releases and updates for Parallel Web Systems and its Search API", "search_queries": ["Parallel Web Systems Search API", "Parallel Web Systems product releases", "Parallel AI search documentation"]})
7
8 Response:
9
10 Parallel Web Systems provides AI-native web search and research APIs designed for language models and agents:
11
12 1. **Search API**: Accepts a natural-language objective alongside keyword queries and returns compressed, citation-ready text excerpts rather than raw HTML.
13 2. **Extract API**: Converts target URLs, including JavaScript-heavy pages and PDFs, into clean Markdown or focused excerpts.
14 3. **Task API**: Runs multi-step deep research jobs with processor tiers (`lite`, `base`, `core`, `pro`, `ultra`) and returns a Research Basis with citations and confidence scores.
15
16 Sources:
17 - https://docs.parallel.ai/search/search-quickstart
18 - https://docs.parallel.ai/integrations/ollama-tool-calling
Next, run the multi-tool research assistant:
1 $ uv run research_agent.py
2 Prompt: Run a deep research report on recent open-weight small language models that support native tool calling, and summarize the findings with citations.
3
4 [Tool Call] research_topic({"output_schema": "A structured research report listing open-weight small language models with native tool calling, parameter sizes, and key capabilities.", "processor": "base", "topic": "Recent open-weight small language models that support native tool calling"})
5
6 Response:
7
8 ### Open-Weight Small Language Models with Native Tool Calling
9
10 1. **Qwen 3.5 (0.8B, 2B, 4B, 9B)**: Supports native function calling in Ollama, structured JSON tool arguments, and multi-turn tool execution loops.
11 2. **Llama 3.2 (1B, 3B)**: Supports native tool definitions for edge and laptop deployments.
12 3. **Granite 3 Dense (2B, 8B)**: Tuned for enterprise function calling and RAG workflows.
13
14 **Verification Basis:**
15 - Confidence: `high`
16 - Sources:
17 - https://ollama.com/library/qwen3.5
18 - https://ollama.com/library/llama3.2
19 - https://docs.parallel.ai/integrations/ollama-tool-calling
Look at what happened in these two runs:
- In
search_agent.py, the local Ollama model read the docstring rules onsearch_weband generated both a clearobjectivestring and three 3-6 word keyword queries. Parallel executed those searches in one round-trip and returned pre-compressed excerpts that the local model synthesized with source URLs. - In
research_agent.py, the prompt asked for a deep research report with citations. The local model selectedresearch_topicinstead ofsearch_web, delegated the multi-step web research to the Parallel Task API (processor="base"), and formatted the returned output, confidence level, and citations into the final answer.
Wrap Up
Combining local Ollama models with the Parallel Search and Task APIs gives small models access to current web knowledge without complex scraping code. The search_web tool handles low-latency lookups by returning compact excerpts tuned for LLM context windows, while research_topic offloads deep multi-step research and source verification to the Parallel Task API. Because both tools use standard Python type hints and docstrings, you can plug them directly into any Ollama tool-calling workflow.
Optional Practice Problems
- Add the Parallel Extract API as a Third Tool. The Parallel SDK provides
client.extract(urls=[...], objective=...)to extract clean Markdown from specific URLs. Write a new tool functionextract_urls(urls: list[str], objective: str) -> dictinparallel_tools.pyand register it alongsidesearch_webandresearch_topicinresearch_agent.py. Test it by asking the agent to search for a topic and then extract full details from the top URL. - Filter Research Results by Confidence Score. Modify
research_topicinparallel_tools.pyto accept amin_confidence: str = "medium"parameter. Filter thebasisentries so the function flags any field whose confidence is"low"and warns the local Ollama model not to state low-confidence claims as certain facts. - Expose Structured JSON Schemas in
research_topic. The Parallel Task API accepts a JSON Schema dictionary intask_spec={"output_schema": ...}in addition to plain-text schema descriptions. Create a specialized tool functionresearch_company(company_name: str)that requests a strict JSON schema with fields forfounding_year,headquarters,key_products, andcitations, and test it with an Ollama model.