The latest release of the Cloudflare Agents SDK (v0.27.0 or newer) ships a web_search tool that lets an agent issue a query to the Cloudflare Web Search API and receive a short, numbered list of titles, URLs, and trimmed descriptions. When paired with the existing web_fetch tool, the agent can automatically retrieve the full content of the returned pages, enabling end‑to‑end web‑driven reasoning without leaving the durable object environment.
How the Web Search Tool Works
When an agent is given the web_search tool, the model supplies two inputs: the search query string and a maximum number of results to return. The API responds with a concise list where each entry includes a title, a URL, and a brief description. The response format is deliberately short to keep token usage low and to make it easy for the model to decide which results to explore further.
Adding the Tool to a Pi Harness
Integration requires three steps:
- Confirm the runtime is using Agents SDK v0.27.0 or later.
- Import the tool from the
agents/websearch/pipackage. - Register the tool in the Pi harness extension registry before the harness is opened.
import { webSearchTool } from "agents/websearch/pi";
export class MyAgent extends DurableObject {
harness = new PiHarness({
harness: async ({ storage, context }) => {
this.registry.install({
name: "web-tools",
tools: [
webSearchTool({
binding: this.env.AI,
provider: "exa"
})
]
});
return Harness.open(storage, { models, registry: this.registry }, context);
}
});
}
The snippet shows a typical registration where the provider argument selects one of the supported back‑ends (ceramic.ai, Exa, or Linkup). After installation, the agent can invoke web_search just like any other tool.
Operational and Security Considerations
From an operational standpoint, the new tool adds a dependency on the Cloudflare Web Search service, so monitoring usage and cost becomes part of the agent’s lifecycle. Because the tool returns URLs that the agent may subsequently fetch, practitioners should be aware of the latency and potential rate‑limiting of downstream web_fetch calls.
Security‑wise, the content retrieved from arbitrary web pages is untrusted. Agents should treat fetched data as potentially hostile and apply any necessary sanitisation or validation before further processing. The choice of provider also introduces a trust boundary; each provider’s data handling policies may differ, so teams may want to review provider documentation when selecting one.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Integrating web_search expands the functional surface of Agents without requiring external services or custom scraping logic. Engineers can now prototype agents that augment their reasoning with live web results, while keeping the entire flow inside the Cloudflare platform. The primary actions are to upgrade to SDK v0.27.0+, register the tool in the Pi harness, and adopt a disciplined approach to handling fetched web content. Ongoing evaluation should focus on provider performance, cost impact, and the security posture of any downstream processing of web data.
