Web search for agents with tool calling
Define a SerpKite search tool, retrieve query-ranked passages, and add page extraction or site discovery. Python and TypeScript code with schemas and budgets.
Function calling (tool use) lets a model decide when it needs fresh information and ask your code to fetch it. This guide defines one tool, web_search, that your code implements with a single POST /v1/search call returning Markdown. The model reads the Markdown, cites the links, and answers.
If your client already supports MCP (Claude Desktop, Claude Code, Cursor, VS Code), you can skip the code and connect the MCP server instead.
The tool implementation
Under the hood every tool call is one search request with format: "markdown", which is far smaller in context than the full JSON (see Output formats):
curl https://api.serpkite.com/v1/search \
-H "Authorization: Bearer $SERPKITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"latest Go release notes","country":"us","format":"markdown"}'Wrapped as a tool with the official SDKs, mapping the model’s arguments onto SerpKite parameters:
import serpkite
from serpkite import SerpKite
sk = SerpKite() # reads SERPKITE_API_KEY
def web_search(query: str, country: str = "us", recency: str | None = None) -> str:
params = {"country": country, "engine": "auto", "format": "markdown"}
if recency:
params["time"] = recency
try:
return sk.search(query, **params) # a Markdown string
except serpkite.SerpKiteError as err:
# Hand errors back to the model as text so it can recover or explain.
return f"Search failed: {err.message}"
import { SerpKite, SerpKiteError } from "serpkite";
const sk = new SerpKite(); // reads SERPKITE_API_KEY
type SearchInput = {
query: string;
country?: string;
recency?: "hour" | "day" | "week" | "month" | "year";
};
export async function webSearch(input: SearchInput): Promise<string> {
try {
return await sk.search({
q: input.query,
country: input.country ?? "us",
time: input.recency,
engine: "auto",
format: "markdown",
});
} catch (err) {
if (err instanceof SerpKiteError) return `Search failed: ${err.message}`;
throw err;
}
}
Both examples opt into automatic fallback for research. Set engine: "google" if the tool must return Google results. The explicit policy overrides the API key’s fallback setting.
Describe the tool to the model
Use this JSON Schema as the input schema in your model or framework’s tool definition. Map query to the API’s q, as the implementations above do:
{
"type": "object",
"properties": {
"query": { "type": "string", "description": "The web search query" },
"country": { "type": "string", "description": "Two-letter country code, default us" },
"recency": { "type": "string", "enum": ["hour", "day", "week", "month", "year"] }
},
"required": ["query"],
"additionalProperties": false
}
Name the tool web_search and describe it as “Search the live web for current information and return source links.” The surrounding tool-definition object depends on your model client; use the framework integrations for that setup.
Your agent loop should:
- Send the conversation and the tool definition to the model.
- Validate a requested tool name and arguments, then call
web_search/webSearch. - Append the model’s tool-call message and return the tool output with its call ID.
- Ask the model to continue, stopping when it produces an answer or after a fixed number of rounds, such as 8.
Keep tool failures as explicit outputs. Tell the model to cite source URLs and to say when retrieval did not provide enough evidence.
Read relevant passages and known URLs
When a snippet is insufficient, add include_content and highlights to the search tool’s implementation:
curl https://api.serpkite.com/v1/search \
-H "Authorization: Bearer $SERPKITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"how do asyncio task groups handle cancellation","engine":"auto","include_content":2,"highlights":true,"format":"markdown"}'This reads two result pages and returns up to three query-ranked passages per page rather than full page bodies. It costs up to 3 credits: 1 for search and 1 per successfully read page; highlights have no extra charge. See RAG pipeline.
Give the agent additional tools only when the workflow needs them:
| Need | API | Inputs to expose |
|---|---|---|
| Read one known HTML page or PDF | /v1/webpage |
url, optional country |
| Read several selected sources | /v1/extract |
urls (1–20), optional query and highlights (1–10) |
| Discover URLs within a site | /v1/map |
url, optional search and a bounded limit |
| Read a site section asynchronously | /v1/crawl |
url, a bounded limit, optional path filters |
Extract and map return JSON objects. Serialize the fields the model needs; for extract, include the source URL and passages plus any failed entries. Search uses boolean highlights, while extract uses an integer passage count.
A crawl returns a task ID, not pages immediately. Poll its status and handle completed, failed and canceled, or expose a separate result tool. The MCP server already provides extract, map, crawl and crawl_result. It does not expose monitor management tools; use the REST API or SDKs for scheduled monitoring.
Using an agent framework
If you build on the Vercel AI SDK, LangChain or CrewAI, you don’t need to write the tool at all.
With the Vercel AI SDK (TypeScript, including Next.js route handlers and the edge runtime), @serpkite/ai-sdk provides the search tool and the page, extract, map and crawl tools above, with input schemas already written:
// npm install @serpkite/ai-sdk ai zod
import { openai } from "@ai-sdk/openai";
import { serpkiteSearch, serpkiteTools } from "@serpkite/ai-sdk";
import { generateText, stepCountIs } from "ai";
const { text } = await generateText({
model: openai("gpt-5-mini"),
tools: {
...serpkiteTools({ only: ["webpage", "extract"] }),
// The same web_search as above: fallback on, an hour of caching at half price.
web_search: serpkiteSearch({ fixed: { engine: "auto", max_age: 3600 } }),
},
stopWhen: stepCountIs(8), // caps the loop
prompt: "How do asyncio task groups handle cancellation? Cite sources.",
});
The SDK runs the agent loop: it validates arguments against each tool’s schema, calls the tool, returns the output with its call ID and stops at stopWhen. See the Next.js integration for a streaming chat route.
For Python frameworks:
# LangChain / LangGraph: pip install langchain-serpkite
from langchain_serpkite import SerpKiteSearch
tool = SerpKiteSearch() # returns Markdown, token-lean, for agents
# CrewAI: pip install "serpkite[crewai]"
from serpkite.crewai import SerpKiteSearchTool
tool = SerpKiteSearchTool() # optional: endpoint="news", country="de", num=10
Pass the tool to your agent like any other. See SDKs for the retriever and webpage loader.
Keep it cheap and fast
- Return Markdown or compact JSON.
format: "markdown"is the best default for a model. If you post-process results in code first,format: "compact"keeps short JSON. See Output formats. - Project fields.
fields: "results.title,results.link,results.snippet"drops everything else from the JSON before it reaches the context. - Keep
numat 10. Most questions are answered from the first page. Offer a second tool (or apageargument) rather than fetching 100 results by default. - Cache repeated queries. Agents often repeat the same search within a session. Add
max_age: 3600to accept a result up to an hour old at half the credits. See Caching. - Fetch pages only when needed. A separate
fetch_pagetool backed by/v1/webpage(sk.webpage(url)in the SDKs) lets the model read one promising result instead of paying forinclude_contenton every search. - Cap the blast radius. Give the agent its own API key with a monthly
credit_limit. When it is hit, calls return403 key_limit_reachedand nothing more is charged. See API keys and Spend controls. - Cap the loop. Limit tool rounds and bound extract URL counts and crawl page limits so recurring tool calls stay within your budget.
Related
Last updated: 2026-10-04