feat: add ai_search_namespaces and ai_search binding types by G4brym · Pull Request #13027 · cloudflare/workers-sdk

G4brym · 2026-03-23T17:48:29Z

Summary

Add two new AI Search binding types to Wrangler, Miniflare, and workers-utils:

ai_search_namespaces: namespace binding — namespace name is required, provisions automatically at deploy time (like R2 buckets) if it doesn't exist
ai_search: single instance binding — bound directly to a pre-existing instance in the default namespace

Both binding types are remote-only in local dev (Miniflare proxies to the remote API).

Changes

workers-utils:

Config schema, runtime types, metadata/binding unions, validation, defaults, reverse mapping
ai_search_namespaces.namespace is required (type + validator in sync)

wrangler:

Upload form with INHERIT_SYMBOL/dryRun handling
Provisioning handler for ai_search_namespaces — checks for HTTP 404 before provisioning (same pattern as R2)
AI Search namespace API helpers (getAISearchNamespace, createAISearchNamespace)
Print bindings, config diffs, dev utils, miniflare mapping

miniflare:

Schema-only plugin with remote proxy for local dev

Tests
- Tests included/updated
- Automated tests not possible - manual testing has been completed as follows:
- Additional testing not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: docs will only be added when we announce the new binding

A picture of a cute animal (not mandatory, but encouraged)

portuguese water dog, aka the obama family dog

changeset-bot · 2026-03-23T17:48:35Z

🦋 Changeset detected

Latest commit: b35c8f2

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-03-23T18:05:25Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@13027

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@13027

miniflare

npm i https://pkg.pr.new/miniflare@13027

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@13027

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@13027

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@13027

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@13027

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@13027

wrangler

npm i https://pkg.pr.new/wrangler@13027

commit: b35c8f2

workers-devprod · 2026-03-23T19:08:58Z

Codeowners approval required for this PR:

✅ @cloudflare/wrangler

Show detailed file reviewers

petebacondarwin

Hi @G4brym - nice work on this. I have added a load of comments (sorry) but also I would really like there to be an e2e test (perhaps in a remote binding test) that demonstrates that the deployment of the remote binding is functional in practice.

packages/workers-utils/src/config/environment.ts

packages/miniflare/src/plugins/ai-search/index.ts

packages/workers-utils/src/worker.ts

packages/workers-utils/src/config/validation.ts

packages/wrangler/src/deployment-bundle/create-worker-upload-form.ts

packages/workers-utils/src/worker.ts

packages/wrangler/src/dev/miniflare/index.ts

Add two new AI Search binding types to Wrangler, Miniflare, and workers-utils: - ai_search_namespaces: namespace binding with dynamic instance CRUD - ai_search: single instance binding bound to one instance in a namespace Both are remote-only in local dev. Namespace auto-creation during deploy follows the R2 bucket provisioning pattern — checks for HTTP 404 on the namespace API before deciding to provision. The namespace field on ai_search defaults to 'default' if omitted. Changes across 3 packages: - workers-utils: config schema, runtime types, metadata/binding unions, validation, defaults, reverse mapping - wrangler: upload form with INHERIT_SYMBOL/dryRun handling, provisioning handler, API helpers, print bindings, config diffs, dev utils, miniflare mapping - miniflare: schema-only plugin with remote proxy for local dev

…Binding>

petebacondarwin

Great! Let's land this.
I have run the remote binding tests locally using our Dev Prod Testing account (since this is on a fork and can't run here). Also @G4brym has run them locally too using his account.

workers-devprod added this to workers-sdk Mar 23, 2026

github-project-automation bot moved this to Untriaged in workers-sdk Mar 23, 2026

G4brym force-pushed the gmassadas/ai-search-binding-wrangler branch from 092ea72 to 4425684 Compare March 23, 2026 18:53

G4brym marked this pull request as ready for review March 23, 2026 19:08

G4brym requested a review from a team as a code owner March 23, 2026 19:08