INTEGRITY Cloudflare Docs

← Agents / agents / tools

AI Search

Agents can use AI Search to retrieve relevant information from indexed content and use it to augment calls to AI models. AI Search manages the retrieval pipeline for you, including indexing, search, and optional chat completions over your content.

Use AI Search when you want an agent to:

Basic pattern

Bind AI Search to your Worker, then query an instance from an agent method.

import { Agent, callable } from "agents";

export class SearchAgent extends Agent {
	@callable()
	async searchKnowledge(query) {
		const instance = this.env.AI_SEARCH.get("my-instance");

		const results = await instance.search({
			messages: [{ role: "user", content: query }],
		});

		return results;
	}
}
import { Agent, callable } from "agents";

type Env = {
	AI_SEARCH: AiSearchNamespace;
};

export class SearchAgent extends Agent<Env> {
	@callable()
	async searchKnowledge(query: string) {
		const instance = this.env.AI_SEARCH.get("my-instance");

		const results = await instance.search({
			messages: [{ role: "user", content: query }],
		});

		return results;
	}
}

For answer generation, use chatCompletions() to retrieve relevant content and generate a response in one call.

const instance = this.env.AI_SEARCH.get("my-instance");

const response = await instance.chatCompletions({
	messages: [{ role: "user", content: "How do I deploy an Agent?" }],
	model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	ai_search_options: {
		retrieval: {
			max_num_results: 5,
		},
	},
});
const instance = this.env.AI_SEARCH.get("my-instance");

const response = await instance.chatCompletions({
	messages: [{ role: "user", content: "How do I deploy an Agent?" }],
	model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	ai_search_options: {
		retrieval: {
			max_num_results: 5,
		},
	},
});

Configuration

Use an ai_search_namespaces binding when the agent needs to access AI Search instances by name.

{
	"ai_search_namespaces": [
		{
			"binding": "AI_SEARCH",
			"namespace": "default",
			"remote": true
		}
	]
}
[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "default"
remote = true

Use remote: true to query deployed AI Search instances during local development with wrangler dev.

AI Search

Create managed retrieval pipelines over websites, R2 buckets, and uploaded files.

Workers binding

Query AI Search directly from Workers code.

Create an AI Search instance

Create your first AI Search instance and run your first query.