Workers binding (5)

Last updated Oct 1, 2026 provides a serverless execution environment that allows you to create new applications or augment existing ones. Use a Workers binding to search and chat with your AI Search instances from a Cloudflare Worker.

Configure the binding

To use AI Search with Workers, you must create an AI Search binding. You create bindings by updating your Wrangler configuration. AI Search provides two types of bindings:

• Namespace binding: ai_search_namespaces
• Instance binding: ai_search

Namespace binding

Access all instances within a namespace. You can get, create, list, and delete instances at runtime.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "my-namespace"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"

Instance binding

Bind directly to a single instance in the default namespace. Use this when you know which instance you need at deploy time.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search": [
    {
      "binding": "MY_SEARCH",
      "instance_name": "my-instance"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search]]
binding = "MY_SEARCH"
instance_name = "my-instance"

Instance methods

The following methods are available on both the ai_search_namespaces and ai_search bindings. With the namespace binding, call methods on the handle returned by get(). With the instance binding, call methods directly on the binding (for example, env.MY_SEARCH.search()).

The examples below use the namespace binding.

search()

Search for relevant content chunks from your indexed data source. Returns scored chunks with source references.

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

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

Parameters

The Workers binding accepts string values for messages[].content. To send image or file content parts, use the REST API or a public endpoint.

messages array required

An array of message objects representing the conversation. Each message has a role and content field.

• role string required
• The role of the message sender. Valid values: system, developer, user, assistant, tool.
• content string | array required
• The message content. Use a string for text, or an array containing text, image_url, and file parts.
• A text part contains text. An image_url part contains an https:// URL or a data:image/<subtype>;base64,... URI.
• A file part contains file_data as a data:<mime>;base64,... URI and a filename. The decoded file can be up to 10 MiB.

query string optional

A simple text query string. Alternative to messages. Provide either query or messages, not both.

ai_search_options object optional

Configuration options for the search operation.

• custom_metadata object optional
• Adds up to two string, number, or boolean entries to AI Gateway logs. The keys ai-search, task, origin, and keys beginning with cf. are reserved.
• retrieval object optional
• retrieval_type string optional
  • The type of retrieval to perform. Valid values: vector, keyword, hybrid. Defaults to hybrid.
• match_threshold number optional
  • The minimum match score required for a result to be considered a match. Must be between 0 and 1. Defaults to 0.4.
• max_num_results integer optional
  • The maximum number of results to return. Must be between 1 and 50. Defaults to 10.
• filters object optional
  • Filter search results based on metadata. Supports comparison filters ( eq, ne, gt, gte, lt, lte) and compound filters ( and, or). For more details, refer to Metadata filtering.
• context_expansion integer optional
  • The number of surrounding chunks to include for additional context. Must be between 0 and 3. Defaults to 0.
• fusion_method string optional
  • Controls how vector and keyword scores are combined when using hybrid retrieval. Valid values: rrf (Reciprocal Rank Fusion), max (takes the maximum score). Defaults to the instance-level setting.
• keyword_match_mode string optional
  • Controls how keyword (BM25) matching selects candidate documents. and requires all terms to match. or requires any term to match. Defaults to and.
• boost_by array optional
  • Boost results by metadata fields. Maximum 3 items. Each item has:
  • field string required - The metadata field name to boost by (for example, timestamp). Maximum 64 characters.
  • direction string optional - The boost direction. Valid values: asc, desc, exists, not_exists. Defaults to asc for numeric fields and exists for text fields.
• metadata_only boolean optional
  • Return only metadata for each chunk without the text content.
• return_on_failure boolean optional
  • Whether to return partial results if some processing steps fail. Defaults to true.
• query_rewrite object optional
• enabled boolean optional
  • Rewrites the query to improve retrieval accuracy. Defaults to false.
• model string optional
  • The model to use for query rewriting.
• rewrite_prompt string optional
  • A custom prompt to guide query rewriting.
• reranking object optional
• enabled boolean optional
  • Reorders retrieved results based on semantic relevance using a reranking model. Defaults to false.
• model string optional
  • The reranking model to use. Valid value: @cf/baai/bge-reranker-base.
• match_threshold number optional
  • The minimum score for reranked results. Must be between 0 and 1. Defaults to 0.4.
• cache object optional
• enabled boolean optional
  • Override the instance-level cache setting for this request.
• cache_threshold string optional
  • The similarity threshold for cache hits. Valid values: super_strict_match, close_enough, flexible_friend, anything_goes.

Response

The response contains the following fields:

chatCompletions()

Generate chat completions using your AI Search instance as context. This method retrieves relevant content and uses it to generate a response.

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

const response = await instance.chatCompletions({
    messages: [
        { role: "system", content: "You are a helpful documentation assistant." },
        { role: "user", content: "What is Cloudflare?" },
    ],
    model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    ai_search_options: {
        retrieval: {
            max_num_results: 5,
        },
        query_rewrite: {
            enabled: true,
        },
    },
});

Stream responses

Set stream: true to receive responses as Server-Sent Events (SSE) as they are generated:

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

const stream = await instance.chatCompletions({
    messages: [{ role: "user", content: "What is Cloudflare?" }],
    stream: true,
});

return new Response(stream, {
    headers: {
        "content-type": "text/event-stream",
        "cache-control": "no-cache",
    },
});

When stream is enabled, the method returns a ReadableStream of SSE events. Each event contains a JSON object with choices[0].delta.content for incremental text. The stream ends with a data: [DONE] event.

Parameters

messages array required

An array of message objects representing the conversation. Each message has a role and content field.

• role string required
• The role of the message sender. Valid values: system, developer, user, assistant, tool.
• content string | array required
• The message content. Use a string for text, or an array containing text, image_url, and file parts.
• A text part contains text. An image_url part contains an https:// URL or a data:image/<subtype>;base64,... URI.
• A file part contains file_data as a data:<mime>;base64,... URI and a filename. The decoded file can be up to 10 MiB.