feat(experimental): AI Search context provider with search_context tool

[mattzcarey]

Summary

Adds searchable context blocks backed by Cloudflare AI Search using the new ai_search_namespaces binding.

Draft — waiting for AI Search binding to stabilize before merging.

Deploy notes

Successfully deployed the example to agents-session-context-example.mattzcarey.workers.dev (Matt account) by manually patching the vite build output — the @cloudflare/vite-plugin does not yet pass through ai_search_namespaces to the deploy config, so it gets stripped during vite build. Workaround: after vite build, patch dist/agents_session_context_example/wrangler.json to re-add the ai_search_namespaces field, then wrangler deploy -c that config directly.

Was not able to save data quickly — needs further investigation.

Changes

SDK (packages/agents)

• ContextProvider gets optional search?(query: string): Promise<string>
• search_context tool auto-wired in ContextBlocks.tools() when any block has a search provider
• Searchable blocks render in system prompt even when empty, with [searchable — use search_context tool] tag
• AiSearchContextProvider — new provider using ai_search_namespaces wrangler binding:
  • Lazy instance creation on first use via binding.create()
  • set() uploads content via instance.items.upload()
  • search() queries AI Search, returns matching text chunks
  • Configurable: maxResults, hybridSearch, embeddingModel, etc.
• AiSearchBinding type exported for env.d.ts typing

Example (experimental/session-context)

Minimal chat app demonstrating:

• soul (readonly system prompt)
• memory (writable, AI saves facts via update_context)
• knowledge (searchable via AI Search, AI queries via search_context)
• Streaming chat with tool cards showing search queries and results

Wrangler config

{
  "ai_search_namespaces": [
    { "binding": "KNOWLEDGE", "namespace": "knowledge-base" }
  ]
}

Usage

import { AiSearchContextProvider } from "agents/experimental/memory/session";

Session.create(this)
  .withContext("knowledge", {
    description: "Product docs",
    provider: new AiSearchContextProvider(env.KNOWLEDGE)
  })

Test plan

• 39 existing session tests pass
• No search provider = no search_context tool (existing behavior unchanged)
• Search provider present = search_context tool appears with correct schema
• Tool execution calls provider.search() and returns tagged results
• Searchable blocks render in prompt when empty
• AI Search binding creates instance on first use
• set() uploads content for indexing

[changeset-bot]

⚠️ No Changeset found

Latest commit: 96cbf96

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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