Skip to content
Cloudflare Docs
DirectoryAPISDKsChangelog

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:

  • Search product docs, support content, user files, or internal knowledge bases.
  • Retrieve relevant chunks before calling a model.
  • Use managed indexing instead of building retrieval infrastructure yourself.
  • Query content from an R2 bucket, website, or uploaded files.

Basic pattern

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

JavaScript
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;
  }
}

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

JavaScript
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.

JSONC
{
  "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.