DEV Community: Alexey Sazhin

Supercharge Your LLM Router with a Decision Model: Clef on Cloudflare Workers

Alexey Sazhin — Fri, 09 Oct 2026 22:51:33 +0000

In part 1 we built a classification router in about 50 lines on a Cloudflare Worker. It classifies each prompt and routes it through AI Gateway: coding questions to Claude Sonnet, everything else to a cheap Workers AI model. The classifier was a small LLM, Llama 4 Scout, with a one-line system prompt: "Reply with only that single word."

Since then, a new kind of model has appeared for exactly this job: decision models. TypeSafe introduced Jev, and on October 1 Cloudflare published Clef and Clef-flash on Workers AI. A decision model doesn't write an answer. It takes your content and a typed question and returns the choice directly, with no text to generate token by token. For a router that only needs one word, coding or simple, that looks like a perfect fit.

So in this post we'll bolt Clef and Clef-flash onto the existing router as drop-in classifiers, then test them against Llama on the same labelled prompts: which one routes each prompt to the right model?

Disclosure: I work at Cloudflare. This is a personal side project; opinions and measurements are my own.

Make the classifier testable

Before changing the classifier, I wanted a way to score it. Two small additions made that possible.

1. A /classify endpoint. POST /classify runs only the classifier and returns its decision as JSON. It doesn't call Claude, so testing costs nothing beyond the classifier itself:

curl https://prompt.demolabs.fyi/classify \
  -H "x-classifier: clef-flash" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What is the capital of Portugal?"}]}'


{"task":"simple","raw":"simple","confidence":0.9117,
"fallback":false,"classifier":"clef-flash",
"model":"@cf/cloudflare/clef-flash","ms":734}

2. A benchmark script. scripts/bench.mjs sends 20 labelled prompts (10 coding, 10 general, a few of them long) through /classify N times and reports accuracy against the labels, listing every prompt it got wrong:

npm run bench -- \
  --url https://prompt-router.<your-subdomain>.workers.dev \
  --classifier llama-4-scout,clef --runs 10

The x-classifier request header picks the classifier per request, so one deployment can compare several models on identical prompts.

Example of the benchmark script's output:

 npm run bench -- --url https://prompt.demolabs.fyi --classifier llama-4-scout,clef,clef-flash --runs 10

Endpoint: https://prompt.demolabs.fyi/classify
Prompts: 20 × 10 runs, concurrency 1, warmup 2

=== llama-4-scout ===
  20/20 requests
  model: @cf/meta/llama-4-scout-17b-16e-instruct
  latency (ms)               n   min   p50   p90   p95   p99   max  mean
  server classify           20   111   129   267   801  4117  4117   372
  client round-trip         20   141   164   293   829  4142  4142   402
  accuracy: 75.0% (15/20)
  ✗ expected simple, got coding (raw: "coding") — Translate 'Good morning, how are you?' into German.
  ✗ expected simple, got coding (raw: "coding") — Summarize the plot of Hamlet in two sentences.
  ✗ expected simple, got coding (raw: "coding") — I have a job interview tomorrow for a solutions architect ro
  ✗ expected coding, got simple (raw: "**coding**\n\n## Explanation\n\nIn") — Explain the difference between useEffect and useLayoutEffect
  ✗ expected coding, got simple (raw: "To classify the user based on ") — Write a Dockerfile for a Node 20 Express app that runs as a
  saved → \Projects\prompt-router\bench-results\llama-4-scout-2026-10-08T21-56-12-168Z.json

=== clef ===
<...>

What the LLM classifier got wrong

The first run of Llama 4 Scout scored 75% accuracy: one prompt in four went to the wrong model. The failures came in two kinds.

It ignored "one word". For some coding prompts, Llama answered like a chatbot:

// "Explain useEffect vs useLayoutEffect"
raw: "**coding**\n\n## Explanation\n\nIn..."

// "Write a Dockerfile for a Node 20 app"
raw: "To classify the user based on ..."

My parser expected exactly coding, so both went to the cheap model: the two prompts that most needed Sonnet. It also means the router spent its time generating a paragraph nobody reads.

It was confidently wrong. Three general prompts came back as a clean coding:

"Translate 'Good morning, how are you?' into German."
"Summarize the plot of Hamlet in two sentences."
"I have a job interview tomorrow for a solutions architect role…"

Those aren't expensive mistakes (they just cost Sonnet prices), but they repeated on every run.

Patching it only goes so far

The obvious fix is a safer default: only an explicit simple goes to the cheap model, and anything else (rambling, empty, unexpected) goes to the strong one.

const isSimple = raw.trim().toLowerCase() === "simple";
const task: Task = isSimple ? "simple" : "coding";

That lifted Llama to 85%: the rambling answers now route correctly. But the three confident mistakes stayed, on every run. A safe default can catch a model that is unsure or off-format. It can't catch a model that is sure and wrong.

Decision models: answers, not text

A chat model is asked to write a classification and hopes it complies. Clef is a decision model: you give it the content and typed questions, and it returns typed answers. There is no generated text, so there is nothing to ramble and nothing to parse.

A request has two parts:

state: the content to judge (here, the user's prompt).
questions: up to 64 named questions, each one of three types: noul (yes/no, returns a probability), choice (pick one option from a set), or score (place on an ordered scale).

For routing, one choice question is enough. The options are object keys, and each value describes when that option applies:

const CLEF_PROMPT = "Which model tier should handle this user request?";
const CLEF_CRITERIA = {
  coding:
    "Writing, debugging, reviewing or explaining code, " +
    "scripts, SQL, regex, configs or developer tooling",
  simple:
    "General knowledge, writing, translation, advice " +
    "and everything else",
};

The answer comes back as the chosen key, a probability per option and a confidence between 0 and 1. It can only be coding or simple, by construction. There is also Clef-flash, a smaller, faster variant with the same API.

The criteria descriptions do the work that my system prompt failed at. "Translation" and "writing" are listed under simple explicitly, which is exactly where Llama went wrong.

The swap

To compare models fairly, the classifier became a registry. Every entry takes the prompt and returns the same small shape, { raw, confidence? }, and parsing into a route happens in one place:

interface ClassifierOutput {
  raw: string;
  confidence?: number; // only classifiers that report one set it
}

interface Classifier {
  model: string;
  run(env: Env, prompt: string): Promise<ClassifierOutput>;
}

The Clef entry is about 15 lines:

"clef": {
  model: "@cf/cloudflare/clef",
  async run(env, prompt) {
    const out = (await env.AI.run(this.model, {
      model: "clef", // must match the model ID ("clef-flash" for Flash)
      state: prompt,
      questions: {
        classify: {
          type: "choice",
          instructions: CLEF_PROMPT,
          criteria: CLEF_CRITERIA,
        },
      },
    })) as ClefResult;

    return {
      raw: out.answers?.classify?.choice ?? "",
      confidence: out.answers?.classify?.confidence,
    };
  },
},

Two gotchas I hit. The text goes in state, not in a messages array; leave it out and Clef has nothing to judge. And the body's model field has to match the model ID: calling @cf/cloudflare/clef-flash with model: "clef" throws, which surfaces as a bare error code: 1101 unless you catch it.

When Clef isn't sure, pay for Sonnet

The two possible mistakes don't cost the same. A coding question sent to the cheap model gets a bad answer, which users notice. A simple question sent to Sonnet costs a little more and is still answered well. So low confidence routes to the strong model:

const CONFIDENCE_THRESHOLD = 0.7;

const lowConfidence =
  confidence !== undefined && confidence < CONFIDENCE_THRESHOLD;
const isSimple = raw.trim().toLowerCase() === "simple";

const task: Task = isSimple && !lowConfidence ? "simple" : "coding";

The result carries a fallback flag, so the logs show how often the safety net fires. If it's often, the threshold is too strict and you're paying Sonnet prices for easy prompts. Llama reports no confidence, so for it the rule reduces to the safe default from earlier.

The router picks the classifier from the x-classifier header, then the CLASSIFIER var, then a default in code. That's what made the side-by-side benchmark possible without redeploying.

Results

Both Clef models routed all 200 test requests correctly. The patched Llama still misrouted 3 of the 20 prompts, every time.

Classifier	Accuracy	Prompts misrouted (of 20)
Llama 4 Scout, strict parsing	75% (150/200)	5
Llama 4 Scout, safe default	85% (170/200)	3
Clef	100% (200/200)	0
Clef-flash	100% (200/200)	0

How I tested: 20 labelled prompts × 10 runs = 200 requests per classifier, sent through /classify:
npm run bench -- --url https://prompt.demolabs.fyi --classifier llama-4-scout,clef,clef-flash --runs 20
The mistakes were the same prompts on every run, so this is about which prompts each model gets wrong, not random noise.

A few things stand out:

The criteria descriptions matter. Llama's three remaining mistakes were translation, a summary and interview prep. All three are named under simple in Clef's criteria, and Clef got them right.
Clef vs Clef-flash was a tie for this task. Both scored 100%. For a two-way coding/simple split either works; a harder, multi-category task is where the bigger model should earn its keep.
20 prompts is a small test set. 100% here means "no mistakes on these 20, repeated 10 times", not "never wrong". The confidence fallback is there for the prompts I didn't think of.

Takeaways

Test the classifier, not just the router. Routing looked fine in manual tests. A labelled prompt set and a small bench script showed one prompt in four going to the wrong model.
Don't ask a text generator for a label. "Reply with one word" is a request, not a guarantee. A decision model can only return one of the options you defined.
Make "unsure" fail towards quality. Only an explicit simple goes cheap. Everything else, including low confidence, goes to the strong model.
To be fair to Llama: Clef also got a better prompt, with a description per option. A tighter Llama prompt would likely fix some of its confident mistakes, but not the off-format answers.

Try it

The code is on GitHub: palermo-777/prompt-router. The part 1 version is still at the part-1 tag.

git clone -b part-2 https://github.com/palermo-777/prompt-router.git
cd prompt-router && npm install

# copy the config, then fill in your gateway details
cp wrangler.example.jsonc wrangler.jsonc

npx wrangler secret put AI_GATEWAY_TOKEN
npm run deploy

npm run bench -- \
  --url https://prompt-router.<your-subdomain>.workers.dev \
  --classifier llama-4-scout,clef,clef-flash

The Worker doesn't authenticate its callers, so anyone who finds the URL can spend your Anthropic credits. Put Cloudflare Access or a bearer-token check in front of it before you share it.

What's next

More routes. Clef takes up to 64 questions per call, so reasoning, creative or needs-tools can be added as options or as separate questions, all answered in the same call.
A harder test set. Borderline prompts ("explain what an API is", "write a cover letter for a developer job") are where confidence and the threshold actually matter.

If you have prompts that trip up your classifier, share them in the comments. I'd like to grow the test set with real-world edge cases.

Building a German Speaking Partner with ElevenLabs Agents and Cloudflare Workers

Alexey Sazhin — Sun, 04 Oct 2026 00:52:27 +0000

Anyone who has learned a foreign language knows the gap between a passed exam and real fluency with native speakers. Closing it takes practice with someone at native level, and not everyone has a native-speaking partner or the budget and time for endless lessons.

So I asked myself: what if an AI voice agent could be that partner? Someone to have casual conversations with, like a buddy who speaks at native level, never loses patience, and points out your mistakes when they matter.

I built it with ElevenLabs agents and Cloudflare Workers.

What it does

Holds a casual conversation in German, like chatting with a friend.
Corrects real grammar and word-choice mistakes, then keeps the conversation going instead of stopping at every slip.
Saves mistakes and new vocabulary after each call to a review page, where learned items can be deleted.
Remembers earlier sessions, so you don't start from scratch every time.
Greets you by name and keeps the tone personal.

How it fits together

An ElevenLabs agent handles the voice, and a Cloudflare Worker (Hono) does everything else: it serves a small Vite + TypeScript page, stores data in D1, and exposes the endpoints the agent calls.

The browser requests the page. The Worker authenticates the user and rewrites the HTML before sending it.
The widget starts a call with a signed user ID as a dynamic variable.
During the call the agent calls two tools on my Worker: recall, which returns what happened in recent sessions, and store, which saves items from the conversation.

When the call ends, ElevenLabs sends a post-call webhook. The Worker verifies it and writes the mistakes and vocabulary to D1.
The review page reads those tables.

Decisions worth explaining

Memory. When I built this, ElevenLabs agents had no built-in memory across sessions, so I added it myself: the webhook stores each session, and the agent calls recall when a call starts. I load only the last two or three sessions. Pulling in more makes the agent sound robotic. Nobody remembers a hundred earlier conversations with a friend.

No secrets in the browser. The Worker puts the user's identity into the page before it reaches the browser, as an HMAC-signed ID. The signing key only exists in the Worker.

const rewritten = new HTMLRewriter()
  .on('elevenlabs-convai', {
    element(el) {
      el.setAttribute(
        'dynamic-variables',
        JSON.stringify({ user_id: token, name: displayName }),
      );
    },
  })
  .transform(response);

rewritten.headers.set('Cache-Control', 'no-store');

The no-store header matters, because this page is personalized and must never be served from a shared cache.

The agent's endpoints are not public. The agent never decides whose data it touches. The widget passes the signed user ID to the agent as a dynamic variable, and every tool call sends it back. The tool routes verify the signature before reading or writing anything, so an invented or altered ID is rejected. The post-call webhook has its own check. Route wiring, simplified:

app.get('/tools/recall', recallHandler);   // verifies the signed user_id first
app.post('/tools/store', storeHandler);    // same check before any write
app.post('/api/webhook', saveSession);     // webhook signature check

The browser sees the signed ID but can't create a new one.

Routing. Static files come straight from the asset bundle. Only /, /api/* and /tools/* invoke the Worker.

What I'd do next

Replace plain webhook tools with MCP tools, for cleaner and more standard tool access.
Add a demo mode with a throwaway user, call-length limits and a daily spend cap, so it can be public without burning credits.
Show progress over time, like which error categories are shrinking.

If you're building voice agents and want to know more about my agent - drop a comment, I'm happy to share details.

Verifying ElevenLabs Webhook Signatures on Cloudflare Worker (Without Their SDK)

Alexey Sazhin — Fri, 18 Sep 2026 13:47:49 +0000

I wrote a while back about Building Voice Agent using ElevenLabs, that can look up orders and open refund cases but never approve one.
That post covered the agent calling out to my Cloudflare Worker via tools. What it didn't cover: ElevenLabs calling me — a post-call webhook, fired after every conversation ends, carrying the transcript, the analysis, the cost breakdown, all of it. Same Worker, one more endpoint.

What is Post-call Webhook?

After a call ends, ElevenLabs can POST the full record to a Webhook endpoint you configure - transcript, per-turn tool calls, sentiment analysis, and a full token-level cost breakdown. Useful for anything you want to do after the call: log it somewhere durable, trigger a CRM update, flag a bad sentiment score for a human to review.

Since I already had a Worker doing double duty as storefront and API tools, adding one more route felt like the obvious move: POST /webhook/:hookId, gated by an HMAC signature ElevenLabs attaches to every request.

Don't Reach for the Official SDK Just for This

ElevenLabs' JS SDK ships a webhooks.constructEvent() helper that does exactly this verification. Before wiring it in, I actually checked what I'd be pulling into a Worker:

@elevenlabs/elevenlabs-js: 24.06 MB unpacked, 22,263 files
dependencies: ws, node-fetch, command-exists

command-exists shells out to check for a binary on PATH — meaningless in a Workers isolate, which has no filesystem or child_process. My wrangler.jsonc doesn't even have nodejs_compat enabled. Maybe constructEvent tree-shakes cleanly away from all of that; fern-generated SDKs vary. I wasn't going to bet a few-MB deployment budget on it to avoid writing 25 lines of standard Web Crypto - especially in a project whose only other dependency is Hono.

Worth checking, if you're deciding the same thing: npm view @elevenlabs/elevenlabs-js dist.unpackedSize before you npm install it into an edge function.

The Actual Signature Scheme

Confirmed straight from ElevenLabs' docs, since I didn't want to guess:

Header: elevenlabs-signature, formatted as t=<timestamp>,v0=<hex-signature> — and it can carry more than one v0= value.
Signature = HMAC-SHA256 (hex) of "<timestamp>.<raw_body>", keyed with your webhook secret.
Reject anything where the timestamp is more than 30 minutes old or in the future — that's ElevenLabs' own replay-protection window.

The code

// src/webhookAuth.ts
import type { Context, Next } from 'hono';
import type { AppEnv } from './index';

const TOLERANCE_SECONDS = 30 * 60; // matches ElevenLabs' own replay window

function hexToBytes(hex: string): Uint8Array {
  const bytes = new Uint8Array(hex.length / 2);
  for (let i = 0; i < bytes.length; i++) {
    bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
  }
  return bytes;
}

function parseSignatureHeader(header: string): { timestamp: string; signatures: string[] } | null {
  const parts = header.split(',');
  const timestampPart = parts.find((p) => p.startsWith('t='));
  const signatures = parts.filter((p) => p.startsWith('v0=')).map((p) => p.slice(3));

  if (!timestampPart || signatures.length === 0) return null;
  return { timestamp: timestampPart.slice(2), signatures };
}

async function verifyHmac(secret: string, timestamp: string, rawBody: string, signatureHex: string): Promise<boolean> {
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['verify'],
  );
  const message = `${timestamp}.${rawBody}`;
  return crypto.subtle.verify('HMAC', key, hexToBytes(signatureHex), encoder.encode(message));
}

export function elevenLabsWebhookAuth() {
  return async (c: Context<AppEnv>, next: Next) => {
    const rawBody = await c.req.text();
    const header = c.req.header('elevenlabs-signature');

    if (!header) {
      return c.json({ error: 'missing_signature' }, 401);
    }

    const parsed = parseSignatureHeader(header);
    if (!parsed) {
      return c.json({ error: 'malformed_signature' }, 401);
    }

    const ageSeconds = Math.abs(Date.now() / 1000 - Number(parsed.timestamp));
    if (ageSeconds > TOLERANCE_SECONDS) {
      return c.json({ error: 'timestamp_out_of_range' }, 401);
    }

    for (const sig of parsed.signatures) {
      if (await verifyHmac(c.env.WEBHOOK_SECRET, parsed.timestamp, rawBody, sig)) {
        return next();
      }
    }

    return c.json({ error: 'invalid_signature' }, 401);
  };
}

Wired into the app like any other Hono middleware:

// src/index.ts
import { elevenLabsWebhookAuth } from './webhookAuth';

app.post('/webhook/:hookId', elevenLabsWebhookAuth(), async (c) => {

  const body = await c.req.json();
  // ... do something with payload.type / payload.data
  return c.json({ ok: true });
});

Two things worth calling out in that pairing:

The hookId path segment isn't real security — it's an unguessable URL, defense-in-depth at best. The HMAC check is what actually authenticates the caller.

c.req.json() in the handler works even though the middleware already called c.req.text(). I assumed at first this would break — a Request body can normally only be read once. But Hono's HonoRequest caches the body internally: once .text() has been called, a later .json() call reuses that cached text and parses it, instead of trying to re-read an already-drained stream. No need to manually thread the parsed payload through c.set()/c.get() — worth knowing before you build machinery you don't need.

Why read raw text at all, instead of just calling .json() in the middleware? Because the HMAC has to be computed over the exact bytes ElevenLabs sent. Parsing to an object and re-serializing it for hashing risks differing in key order or whitespace from the original — a correct signature would then fail to verify for reasons that have nothing to do with security.

How to handle Webhook Secret?
WEBHOOK_SECRET isn't thing you hardcode — same pattern as API_TOKEN in the original post. Locally, add it to .dev.vars (and a placeholder pair to .dev.vars.example, so the repo stays self-documenting for anyone else setting it up):

WEBHOOK_SECRET=wsec_your_signing_secret_here

For the deployed Worker, .dev.vars doesn't apply — set the real secret with:

wrangler secret put WEBHOOK_SECRET

which stores it as a Cloudflare Secret rather than a plain environment variable: set once, never shown again, never checked into the repo. The signing secret itself comes from ElevenLabs' side, wherever you configure the post-call webhook URL for your agent.

Secret Rotation: Why Loop Over Every `v0=` Value

During a secret rotation, ElevenLabs signs each webhook with both the old and new secret for a grace period, producing a header like t=...,v0=<sig-with-old-secret>,v0=<sig-with-new-secret>. Your Worker doesn't know in advance which one matches whatever secret you currently have configured — so the correct check is "does any provided signature match," not "does the first one match." Outside of a rotation, there's just one value and the loop runs once. Cheap insurance for a scenario you'll eventually hit.

Testing it from Windows:

1) Test without a signature

curl.exe -X POST "http://localhost:5173/webhook/1234"

Output:

{"error":"missing_signature"}

2) Test with a correct signature

curl doesn't build the signature for you — you compute it yourself and attach the header. On Windows, .NET already has HMAC-SHA256 built in, so no extra tools.
Write body to a file, and have curl read the exact bytes from there:

$secret = "your-webhook-secret"
$body = '{"type":"post_call_transcription","data":{"foo":"bar"}}'
$timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
$message = "$timestamp.$body"

$hmac = New-Object System.Security.Cryptography.HMACSHA256
$hmac.Key = [System.Text.Encoding]::UTF8.GetBytes($secret)
$hashBytes = $hmac.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($message))
$signatureHex = ($hashBytes | ForEach-Object { $_.ToString("x2") }) -join ""
$header = "t=$timestamp,v0=$signatureHex"

$bodyFile = Join-Path $env:TEMP "webhook-body.json"
$utf8NoBom = New-Object System.Text.UTF8Encoding $false
[System.IO.File]::WriteAllText($bodyFile, $body, $utf8NoBom)

curl.exe -X POST "http://localhost:5173/webhook/1234" `
  -H "Content-Type: application/json" `
  -H "elevenlabs-signature: $header" `
  --data-binary "@$bodyFile"

Output:

{"ok":true}

3) Test with an invalid signature
Output:

{"error":"invalid_signature"}

Confirmed Working in Production

Add Post-call Webhook to your ElevenLabs Agent. In ElevenLabs dashboard Configure > Settings > Security and choose Select Webhook

And choose Create Webhook, include your Cloudflare Worker's Webhook Endpoint:

Call you ElevenLabs Agent, to test the Post-call Webhook. Once the call is finished, navigate to Cloudflare Dashboard: Compute > Observability and choose your Worker to get its logs:

I trimmed down the payload here to the interesting parts (the full thing includes a complete transcript, per-turn latency metrics, and TLS/geo request metadata I'm not publishing):

{
  "type": "post_call_transcription",
  "event_timestamp": 1789733272,
  "data": {
    "agent_id": "agent_8001m1rz48w8ez2r9zqrck4214jf",
    "status": "done",
    "environment": "production",
    "metadata": {
      "call_duration_secs": 32,
      "charging": {
        "llm_price": 0.0305259,
        "tts_usage": { "total_characters": 569, "total_audio_output_seconds": 31.2 },
        "asr_usage": { "total_audio_input_seconds": 9.42 }
      }
    },
    "analysis": {
      "call_successful": "success",
      "call_summary_title": "Order Status Check",
      "sentiment_analysis": { "overall_label": "positive" }
    }
  }
}

That per-token cost breakdown under metadata.charging is genuinely handy if you're trying to estimate what a conversational agent actually costs to run per call.

Wrap-up

The HMAC verification itself is unremarkable once you have the right message format — 25 lines, zero dependencies beyond Hono, which was the whole point of not reaching for the SDK.

Code's in the same repo as the original post: github.com/palermo-777/elevenlabs-agent-cf.

Building a RAG Chatbot on Cloudflare Workers (Vectorize + D1 + Workflows)

Alexey Sazhin — Wed, 16 Sep 2026 10:50:41 +0000

I first saw RAG in 2024, at a hackathon. The moment that stuck with me was realizing an LLM could "search" through documents I'd just uploaded and answer questions about them - not from its training data, from my content. I was genuinely astonished; it felt like a different category of capability than just chatting with a model.

Today, that's not a novelty anymore - it's close to a baseline expectation for any chatbot that needs to answer questions about content it wasn't trained on. A chatbot only knows what it was trained on - ask it about your own docs, your own product, your own notes, and it either hallucinates an answer or tells you it doesn't know. Retrieval-Augmented Generation (RAG) is the standard fix: before the model answers, you go find the actual relevant text and hand it over as context. I wanted to build the smallest version of that pattern that still behaves honestly - retrieves the right thing, admits when it can't, and doesn't lose data halfway through ingesting a document.

This is a walkthrough of chatbot-with-rag, a minimal RAG chat demo running entirely on Cloudflare:

Workers AI for embeddings and generation.
Vectorize for similarity search.
D1 for storing the actual text.
Workflows for durable ingestion.

No LangChain agent framework, no vector DB to self-host, no separate backend - one Worker, four bindings.

The architecture

Two flows, running through the same Worker.

Adding a document:

Asking a question:

The two stores are linked by a shared id: D1's auto-increment id for a chunk is the exact same value used as that chunk's Vectorize vector id. A similarity search gives you back an id; a D1 lookup on that id gives you the actual text. No metadata duplication, no second index to keep in sync - just one id, two stores, one source of truth each for what they're good at (Vectorize for "what's similar," D1 for "what does it actually say").

Why ingestion runs through a Workflow, not a plain loop

The obvious version of ingestion is: split the doc, loop over the chunks, embed and insert each one, done. The problem is what happens when chunk 7 of 12 fails - a rate-limited embedding call, a transient D1 failure, doesn't matter. A plain loop either crashes the whole request (losing all 12 chunks) or needs you to implement retry logic.

Cloudflare Workflows solve this by making each step.do() call a durable checkpoint. If a step fails, only that step retries - everything before it is already saved and never redone:

export class RAGWorkflow extends WorkflowEntrypoint<Env, RagWorkflowParams> {
    async run(event: WorkflowEvent<RagWorkflowParams>, step: WorkflowStep) {
        const { data } = event.payload;

        const texts = await step.do('split text', async () => {
            // split `data` into chunks with RecursiveCharacterTextSplitter
        });

        for (const [i, text] of texts.entries()) {
            const record = await step.do(`store in D1 db: ${i}/${texts.length}`, async () => {
                // insert the chunk's text into D1, return its new row id
            });

            const vector = await step.do(`Generate Embeddings: ${i}/${texts.length}`, async () => {
                // embed the chunk's text via Workers AI (bge-base-en-v1.5)
            });

            await step.do(`Insert Vector: ${i}/${texts.length}`, async () => {
                // upsert { id: record, values: vector } into Vectorize
            });
        }
    }
}

One thing worth being explicit about, because it's an easy trap: the loop is around step.do(), not inside it. Put a loop of several inserts inside a single step.do() call and Workflows can only checkpoint the whole step as one unit - a failure on item 7 means the entire step retries, re-inserting items 1 through 6 all over again. Giving each chunk its own uniquely-named step (store in D1 db: 3/12, not a bare store in D1 db reused across iterations - step names are the cache key Workflows uses to track what's already done) is what actually buys you per-chunk retry instead of per-batch retry.
Notice too that record- the id step.do() returns from the D1 insert:

const record = await step.do(`store in D1 db: ${i}/${texts.length}`,
 async () => { /* ... */ });

reappears two steps later in the Vectorize upsert:

env.VECTORIZE.upsert([{ id: record.toString(), values: vector }]);

That's not incidental: whatever a step.do() callback returns is exactly what Workflows durably persists as that step's result, so a later step can reuse it for free instead of recomputing or re-fetching it. It's the same relationship the architecture diagram's dashed chunk id arrow is pointing at - a value produced by one step, consumed by a later one, with nothing in between needing to know where it came from.

Setting up the bindings

Four bindings in wrangler.jsonc - Workers AI, Vectorize, D1, and the Workflow itself:

{
    "ai": { "binding": "AI" },
    "vectorize": [{ "binding": "VECTORIZE", "index_name": "vector-index" }],
    "d1_databases": [{ "binding": "database", "database_name": "database", "database_id": "..." }],
    "workflows": [{ "name": "rag", "binding": "RAG_WORKFLOW", "class_name": "RAGWorkflow" }],
    "assets": { "directory": "./public/", "binding": "ASSETS" }
}

Vectorize needs to exist before anything can be upserted into it:

npx wrangler vectorize create vector-index --dimensions=768 --metric=cosine

768 dimensions because that's what @cf/baai/bge-base-en-v1.5 - the embedding model - outputs. If you swap embedding models later, the dimension has to match, or upserts fail outright.

The query side: retrieval with a floor, not just a top match

This is the part that actually determines whether the chatbot is trustworthy or just confidently wrong. Two decisions matter here: how many chunks to retrieve, and what to do when none of them are actually relevant.

const RELEVANCE_THRESHOLD: number = 0.58;
const TOP_K: number = 3;

export function filterRelevant(matches: VectorizeMatch[], threshold = RELEVANCE_THRESHOLD) {
    return matches.filter((match) => match.score > threshold);
}

async function QueryVector(question: string, c: Context<AppEnv>) {
    const modelResp = await c.env.AI.run('@cf/baai/bge-base-en-v1.5', { text: question });
    const vector = modelResp.data[0]; // (async/queued-response guard omitted for brevity)

    let { matches } = await c.env.VECTORIZE.query(vector, { topK: TOP_K });
    matches = filterRelevant(matches);

    const notes: string[] = [];
    const citeIds: number[] = [];
    for (const match of matches) {
        // look up match.id's text in D1, push it (and its id) onto notes / citeIds
    }

    const contextMessage = notes.length ? `Context:\n${notes.map((note) => `- ${note}`).join('\n')}` : '';
    return { contextMessage, citeIds };
}

topK: 3 retrieves up to three candidates - but filterRelevant can still drop all of them if none clear the threshold, which is the point: Vectorize will always hand back something close to your query vector, even if "closest" still means "not actually related." Force-using the nearest match regardless of score is how you get a chatbot that answers every question with unwarranted confidence.

That empty-context case gets handled explicitly on the generation side, not silently:

async function LlmWithRag(c: Context<AppEnv>, question: string, contextMessage: string) {
    const systemPrompt = contextMessage.length > 0
        ? `You are a helpful assistant. Answer using the context provided.\n\n${contextMessage}`
        : 'You are a helpful assistant. No relevant notes were found for this question - say so plainly rather than guessing.';

    const modelResp = await c.env.AI.run('@cf/qwen/qwen3.8-27b', {
        messages: [
            { role: 'system', content: systemPrompt },
            { role: 'user', content: question },
        ],
    });

    return modelResp.choices[0]?.message?.content; // (empty-response handling omitted for brevity)
}

Two different system prompts, chosen by whether retrieval actually found anything - not one prompt with a vague "use context if relevant" hedge and a hope the model interprets "no context" correctly on its own.

The /api/query route ties it together, and returns which notes the answer is grounded in, not just the answer text:

app.get('/api/query', async (c) => {
    const question = c.req.query('text');
    if (!question) return c.text('specify text in ?text query', 400);

    const { contextMessage, citeIds } = await QueryVector(question, c);
    const answer = await LlmWithRag(c, question, contextMessage);

    return c.json({ llmAnswer: answer, citedNoteIds: citeIds }, 200);
});

That's a small thing, but it's what makes the admin panel's delete button actually useful - if an answer traces back to a bad or stale note, you know exactly which row to remove.

Testing the endpoints directly (local environment)

A few things need to be in place first: the D1 migration applied, and a real ADMIN_TOKENset (the admin endpoints below won't authenticate without one).

npx wrangler d1 migrations apply database --local
cp .dev.vars.example .dev.vars   # then set a real ADMIN_TOKEN
npm run dev

With that running:

# Ask a question
curl -G "http://127.0.0.1:8787/api/query" --data-urlencode "text=How long is a Personal Access Token valid for?"
# → {"llmAnswer":"...", "citedNoteIds":[3]}

# Upload a document (raw markdown as the body - no JSON wrapping needed for a single field)
curl -X POST http://127.0.0.1:8787/admin/ingest \
  -H "Content-Type: text/markdown" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  --data-binary @my-notes.md
# → {"message":"Ingestion started"}

# List everything currently ingested
curl -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8787/admin/notes

# Delete a chunk from both D1 and Vectorize
curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8787/admin/notes/3

Worth noting on that upload: the body is raw markdown text, not JSON - since a browser File object can be handed straight to fetch() as the body, and /admin/ingest just reads it with c.req.text(). No JSON escaping of arbitrary file content, no encoding surprises to debug - the fewer places multi-line text has to survive being stringified and parsed back out, the fewer ways it can get mangled in transit.

The chat UI

Everything above is the same /api/query call you just made with curl - the actual chat widget is a plain HTML form wrapping it, no framework:

formEl.addEventListener('submit', async (e) => {
    e.preventDefault();
    const question = inputEl.value.trim();
    if (!question) return;
    inputEl.value = '';
    addMessage('user', question);

    submitBtn.disabled = true;
    try {
        const response = await fetch('/api/query?' + new URLSearchParams({ text: question }));
        if (!response.ok) {
            addMessage('assistant error', `Request failed (${response.status})`);
            return;
        }
        const { llmAnswer, citedNoteIds } = await response.json();
        addMessage('assistant', `${llmAnswer}\n\n (from note #${citedNoteIds.join(', ')})`);
    } finally {
        submitBtn.disabled = false;
    }
});

citedNoteIds — the same array QueryVector builds up earlier — is what turns into that (from note #62, 74, 63) line under the answer. It's a small thing, but it's the difference between a chatbot that just asserts something and one that shows its work.

The admin panel

A collapsible panel gated behind ADMIN_TOKEN, stored in sessionStorage (cleared on tab close - short-lived by design, since it's an admin credential typed into a page anyone with the URL can load). Once unlocked: a file picker for .md uploads, and a live table of every ingested chunk with a delete button per row.

Worth being precise about what that lock actually protects, since it's easy to overstate: the client-side gate is a convenience wrapper, not the real security boundary. The actual enforcement is bearerAuth on the server - anyone who has the token can hit /admin/ingest or DELETE /admin/notes/:id directly with curl, regardless of what the UI shows. The lock exists so you don't have to remember curl syntax to manage your own content, not to keep out someone who already has the token.

Wrap

Retrieval needs a floor. topK alone isn't a quality control - a similarity search always returns something; a relevance threshold is what lets the system say "nothing here is actually relevant" instead of forcing an answer out of the nearest available match.
Step granularity is the unit of retry. A Workflow only buys you resilience at the boundary you draw with step.do() - loop around it, not inside it, or a single failure forces a full batch to redo.
One shared id beats duplicated metadata. Keying Vectorize and D1 by the same value turns "which store has the truth" into a non-question - Vectorize finds it, D1 says what it is.

Full code: github.com/palermo-777/chatbot-with-rag. Happy to hear what you'd tune differently on the threshold or the chunking strategy - drop a comment.

Building a Voice Support Agent using ElevenLabs and Cloudflare

Alexey Sazhin — Mon, 07 Sep 2026 21:51:33 +0000

Artifacts

GitHub Repository with Cloudflare Workers code.
JSON config of ElevenLabs Agent in GitHub Repository

Intro

I've been using Claude by voice more and more lately — it's just faster than typing when I'm thinking out loud. Last week it hit me: every agent I've actually built myself only takes text. No voice, nothing. So I went looking and found ElevenLabs. Their voice models are top-notch, and on top of that, they let you build full conversational agents, not just turn speech into text.

That was enough to make me want to actually build something instead of just reading the docs.
I paired it with Cloudflare, because I believe it's the fastest and easiest way to test a backend.

There's one problem that shows up in almost every voice-agent demo: you give the agent a tool that's actually useful, and now it's also a tool that can hurt you.
"Look up my order" is safe. "Refund my order" sounds almost the same but is a completely different kind of risk — if you wire both the same way because they feel similar, you've built a bot that can move money on a hallucination.

I like to surf, so I wanted this demo to be as meaningful as possible.
So here's what I built: a voice concierge for a fake surf shop.
It can check order status, answer questions about products, and open a refund case — but it can't actually finish a refund itself.
The stack is ElevenLabs Conversational AI + Cloudflare Workers.

Quick disclaimer: this uses real public product names from a real German surfboard brand, WAU Eco Surfboards, purely for demo realism. It is not affiliated with, endorsed by, or operated by them.

The architecture

Two pieces:

The storefront + backend API — one Cloudflare Worker (Vite + TypeScript static assets, plus a D1 database) serving the storefront and embedded widget, and exposing the actual order-lookup and refund-case endpoints Surfie's tools call.
The agent — an ElevenLabs Conversational AI agent ("Surfie") with a system prompt, a knowledge base, and two webhook tools.

   visitor (browser load)                   caller (voice)
             |                                    |
             |                                    v
             |                        +-------------------------+
             |                        |    ElevenLabs Agent     |
             |                        |        "Surfie"         |
             |                        | prompt + workflow graph |
             |                        |    + knowledge base     |
             |                        +-------------------------+
             |                                     |
             |                              tool calls over HTTPS
             |                        +-------------+--------------+
             |                        |                            |
             |                        v                            v
             |               GET /orders/{id}            POST /initiate-refund
             |                 (no auth)                   (Bearer token)
             |                        |                            |
             |                        +-------------+--------------+
             |                                      |
             v                                      v
   +------------------------------------------------------------------------+
   |                 Cloudflare Worker (site.demolabs.fyi)                  |
   |                                                                        |
   |  +------------------------+      +----------------------------+      |
   |  |       index.html       |      |          index.ts          |      |
   |  |  (storefront, embeds   |      |         (Hono API)         |      |
   |  |      the widget)       |      |                            |      |
   |  +------------------------+      +----------------------------+      |
   +------------------------------------------------------------------------+
                                                     |
                                                     v
                                        +-------------------------+
                                        |     D1: wau-refunds     |
                                        |     (refund cases)      |
                                        +-------------------------+

Setting up Cloudflare

I did all of this on Cloudflare's Free plan — Workers, D1, and a custom domain all fit inside the free tier, which makes it a genuinely cheap way to test out an architecture like this before committing to anything.

Onboard your domain. If your domain isn't already on Cloudflare, you need to add it as a zone first — see Cloudflare's Onboard a domain guide. I bought mine directly through Cloudflare, so it was already set up as a zone in my account with nothing extra to configure.
Create the Worker. I set mine up by hand the first time, before I had a repo to point at. Since then I've published the code, so you don't have to: Cloudflare's Deploy to Cloudflare button below clones the repo into your own GitHub account, provisions whatever Cloudflare resources it needs (the D1 database, in this case), and wires up CI/CD so every push after that auto-builds and deploys — no manual Worker setup required.

→ Deploy to Cloudflare

Point it at your domain. Once it's deployed, go to the Worker's Settings → Domains & Routes → Add → Custom Domain and enter your domain (or subdomain). Cloudflare creates the DNS record for you.

Add your secret. Under Settings → Variables and Secrets → Add, set the type to Secret, name it (I used API_TOKEN), and paste in a token you generate yourself. This is the same value you'll paste into ElevenLabs later as a workspace secret — more on that in Wiring the tools, below.

The app itself

The whole thing is one Worker, built with Vite + vanilla TypeScript — no framework. index.html is the frontend: a static single-page site with the board grid and the embedded ElevenLabs widget. index.ts is the backend: a small Hono app defining the two API endpoints Surfie's tools actually call.

This is the part I like most about building on Cloudflare: one Worker serves both the marketing site and the API behind it. No separate backend deployment, no CORS dance between two origins for your own frontend — just one deploy for the whole thing.

wrangler.jsonc is where the bindings live: the D1 database that stores initiated refunds, plus the secret initiate-refund checks against (the secret itself never appears here — that's the point of a Secret binding, it only exists in the dashboard or via wrangler secret put):

{
  "d1_databases": [
    {
      "binding": "DB_REFUNDS",
      "database_name": "wau-refunds",
      "database_id": "<your-d1-database-id>"
    }
  ]
}

And the two endpoints themselves:

app.get('/orders/:orderId', (c) => {
  const orderId = c.req.param('orderId').toUpperCase();
  const order = ORDERS[orderId]; // a hardcoded lookup table for the demo

  if (!order) {
    return c.json({ order_id: orderId, status: 'not_found' });
  }

  return c.json({ order_id: orderId, ...order });
});

app.post(
  '/initiate-refund',
  bearerAuth({
    verifyToken: (token, c) => token === c.env.API_TOKEN,
  }),
  async (c) => {
    const body = await c.req.json().catch(() => null);
    const orderId = body?.order_id;
    if (typeof orderId !== 'string' || !orderId) {
      return c.json({ error: 'order_id is required' }, 400);
    }
    const caseId = `REF-${crypto.randomUUID().slice(0, 8).toUpperCase()}`;
    await c.env.DB_REFUNDS.prepare(
      'INSERT INTO refunds (case_id, order_id, reason) VALUES (?, ?, ?)'
    ).bind(caseId, orderId, body?.reason ?? null).run();
    return c.json({ status: 'refund_initiated', case_id: caseId, order_id: orderId });
  },
);

Testing the endpoints directly

Before wiring either one into ElevenLabs, it's worth hitting them with curl. A real order comes back with shipping details:

curl https://site.demolabs.fyi/orders/WAU-77102

{
  "order_id": "WAU-77102",
  "status": "shipped",
  "carrier": "DPD",
  "tracking_number": "01778812340099887766",
  "estimated_delivery": "2026-09-09",
  "items": [
    "Riverboard 5'6\" (B-Ware, Bav Boards)"
  ]
}

An order ID that doesn't exist doesn't error out, it just says so:

curl https://site.demolabs.fyi/orders/WAU-123456

{
  "order_id": "WAU-123456",
  "status": "not_found"
}

And a refund, with the right bearer token, opens a real case in D1:

curl -X POST https://site.demolabs.fyi/initiate-refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"order_id":"WAU-77102"}'

{
  "status": "refund_initiated",
  "case_id": "REF-B18C8D7F",
  "order_id": "WAU-77102"
}

The storefront itself

No React, no Vue, nothing componentized — a widget embed and a couple of fetch() calls don't need a framework's state management. The board grid is generated from two arrays of real product names (river/wave-pool boards, ocean boards) mapped over a small color palette, since the point was authentic content without scraping real product photography:

const RIVER_BOARDS = ['GHOUL', 'THRIFTSHOP', 'THE C', 'WASP', 'TOMBSTONE', /* ... */];
const OCEAN_BOARDS = ['MAORI', 'LONGBOARD', 'PARTY FISH', 'SOUL GLIDER', /* ... */];

function renderBoardGrid(containerId: string, names: string[]) {
  const container = document.getElementById(containerId);
  if (!container) return;
  container.innerHTML = names
    .map((name, i) => `
      <article class="board-card">
        <div class="board-shape" style="--board-color: ${PALETTE[i % PALETTE.length]}"></div>
        <h4>${name}</h4>
      </article>`)
    .join('');
}

Building the agent

In the ElevenLabs dashboard, open Agents in the sidebar.

Click + next to Agents to start a new one. This opens a "New agent" dialog — don't pick one of the sample cards (Personal Assistant, Business Agent) or Blank Agent; click Browse Templates at the top instead.

Search for "Track" (or browse) and pick Order Status & Tracking — it handles order inquiries, tracking, delivery estimates, and basic returns out of the box, with two integrations already wired in.

Under Knowledge Base in the sidebar, upload one markdown file per topic — about us, shipping & returns, products & pricing, ding repair, shop locations, and the "Test Me Baby" board-testing program — via Add Files. This is what the non-tool capabilities (company story, ding repair, shop locations, board testing, products and pricing) actually answer from.

I started from that template and then rewrote the system prompt from scratch, because the template locks you out of editing it directly — you have to fork it into a blank agent first if you want real control.
System Prompt can be change in Agent > System Prompt:

I followed ElevenLabs' recommended shape for the prompt — Personality, Environment, Tone, Goal, Flow, Guardrails, and a dedicated section for when to end the call — instead of one long block of instructions. The Goal section keeps Surfie to two things: order status lookups via a tool, and shipping/returns/B-Ware questions answered from the knowledge base. The two guardrail-shaped sections do a lot of the actual work:

# Guardrails
- Never invent an order status, tracking number, delivery date, or stock availability. Only state what the tool or knowledge base actually gives you.
- Never promise a refund, exchange, or exception to the return policy — that needs a human.
- Don't give board-size or skill-level recommendations as if they were firm advice; general orientation only ("that's listed as a beginner/intermediate board"), and point anyone who wants a real fitting to a human.
- If a board arrived damaged, or there's any freight claim or dispute, hand off to a person immediately rather than trying to resolve it.
- Keep it phone-call length, every turn.

# When to end the call
ALWAYS call the end_call tool (don't just say goodbye verbally) when:
- The caller says goodbye in any form ('thanks bye', 'I'm good', 'all set', 'no that's it')
- The caller explicitly asks to end the call
- Their question has been fully answered and they confirm they don't need anything else

Briefly acknowledge AND then call end_call. Verbal goodbye alone leaves the call open.

That second bullet is the one that matters most. It's not enough to build the refund tool correctly on the backend — the model also has to talk about it correctly, or a technically-safe system can still make a customer think a human doesn't need to look at anything.

The conversation is a graph, not just a prompt

The base prompt above isn't the whole story — underneath it, Surfie is wired as a small workflow. In the agent's Workflow tab I laid out six nodes, each able to layer its own instructions on top of the base prompt for just that step.

Greeting — opens with the fixed first message, figures out whether this is an order question or a product question, and branches.
Assess — looks up the order (or answers a product question straight from the knowledge base) and branches again: order status, warranty claim, or done.
Process Return / Process Warranty — the two branches. Process Warranty is the one that can actually call initiate-refund, and only after re-confirming the order exists and was delivered.
Confirm — reads back what happened and any reference numbers, then moves to End.
End — hangs up.

Each node's additional_prompt adds to the base prompt rather than replacing it. Greeting's, for example, is just:

Open warmly: 'Hi, this is Surfie... I can help you check on an order status or consult about our Surfboards, what is your order number or do you have a question about our Surfboards?' Capture identification. Identify intent: order number, or a question about products. Branch.

A node isn't limited to telling the model how to talk, though — it can also tell it which tool to reach for. Process Return, for instance, wires in order_status directly:

Capture: order number (format WAU-XXXXX). Never guess one.

Call order_status with exactly that order number. Don't call it before you have a number.

IMPORTANT: If the customer signals they want to end the call, briefly acknowledge AND call end_call.

That's the part that makes this more than a flowchart drawn on top of one prompt — each step pulls in exactly the tool and instructions it needs, instead of the base prompt having to anticipate every tool call up front.

It's easy to assume a voice agent is "one prompt plus some tools." In practice, routing different parts of the conversation through different prompt slices means the warranty-specific caution (verify the order was actually delivered before offering a refund case) only shows up when it's relevant, instead of cluttering every turn of a plain order-status lookup. I ran every node on Gemini 3.5 Flash and it held up fine across all six — no need to reach for a bigger model just because the conversation now had more moving parts.

Wiring the tools: read vs. write get treated differently

Surfie has two webhook tools, and they are not configured the same way on purpose. To add either one, go to Tools in the sidebar and click Add tool:

order_status — GET /orders/{order_id}, no auth, open CORS. It's read-only and returns nothing sensitive beyond a shipping status, so there's no reason to gate it. Set Method to GET, the URL to https://site.demolabs.fyi/orders/{order_id}, and leave Authentication as None:

Because {order_id} is a path parameter, ElevenLabs asks how the LLM should fill it in. Set Value Type to LLM Prompt and describe the format in plain language — "this is order id in format WAU-XXXXX" — so the model extracts it from the conversation instead of guessing at the shape:

You can test the tool right from this screen before ever wiring it into the agent — see Setting up Cloudflare above for what a real and a not-found order actually return. This also matters for the prompt: its Flow section tells Surfie to handle a not_found status by asking the customer to double-check the number, not by panicking.

initiate-refund — POST /initiate-refund, requires Authorization: Bearer <token>. This is the one that opens a support case in a D1 table. Same Add tool flow, but Method is POST and, critically, Authentication is not None — it's set to a named auth connection (Token_API_WRITE) rather than a raw string, so the token itself never sits in a visible field on the tool config:

order_id here is a body parameter instead of a path parameter, but the same idea applies: mark it Required, set Value Type to LLM Prompt, and spell out the format so the model doesn't invent one:

A successful test creates a real case in D1 and hands back a case ID — see Setting up Cloudflare above for the exact response:

ElevenLabs lets you store that bearer token as a workspace secret and reference it by connection name in the tool config, so the raw value never sits in a visible field — the tool auth setting points at a named connection, not a string.

On the Worker side — shown in full back in Setting up Cloudflare — the check is Hono's bearerAuth middleware, gated on env.API_TOKEN. That's a Cloudflare Secret, not a plain variable — set once via the dashboard (or wrangler secret put), never checked into the repo, never shown again after you set it. The same string gets pasted into ElevenLabs' side as a workspace secret. Two independent places holding the same shared value, neither of which is source control.

A rejected call gets a 401 with a WWW-Authenticate header, which is a small thing but worth doing — it's the difference between a tool config that fails obviously during setup and one that fails silently in front of a customer.

The widget itself is two lines, dropped straight into the page body (change code in index.html of Cloudflare Worker to your agent-id):

<elevenlabs-convai id="surfie-widget" agent-id="<<insert-your-agent-id-here>>"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async></script>

Note on Security

One gotcha worth flagging if you're trying this yourself: the widget needs a secure context for microphone access, so a plain file:// preview won't let voice input work. Test it via wrangler dev (localhost counts) or a real deploy — not by double-clicking the HTML file.

That embed snippet also exposes the agent's agent-id in plain text — anyone who copies those two lines onto their own page gets a fully working Surfie conversation, on my ElevenLabs usage. The fix is in the agent's Security tab: an Allowlist of hosts permitted to connect, plus a Fail when Origin header is missing toggle so a request with no Origin header at all doesn't sneak through. I added site.demolabs.fyi and turned that toggle on:

That's not the full list of widget-security settings worth knowing — this MindStudio writeup covers the rest in more depth than I will here.

What I'd add next

The natural next step is an MCP tool instead of a plain webhook, so Surfie could reach a broader set of backend actions through one connection rather than a hand-registered tool per endpoint — with the tradeoff that MCP tools need to be internet-reachable and currently don't mix with zero-retention/HIPAA workspace modes, which matters more once this stops being a demo. After that: a Twilio number so Surfie takes real phone calls instead of only the web widget, and a GET /refund-status/{case_id} tool so a customer can check on a case they already opened instead of only creating new ones.

Try it

Live at site.demolabs.fyi, clearly marked as an unofficial demo. Test order IDs if you want to see Surfie in action: WAU-10234, WAU-88213, WAU-55501, WAU-77102.

I built this evaluating ElevenLabs' agent platform properly rather than just reading the docs — the interesting decisions showed up in the tool config, the auth boundary, and how the conversation gets routed, not in the system prompt copy itself.

Stop Paying Claude Prices for "Hi" — Route LLM Prompts to the Right Model in 50 Lines

Alexey Sazhin — Wed, 15 Jul 2026 13:13:37 +0000

Every AI app hits the same fork in the road: pick an expensive frontier model and burn budget on trivial prompts, or pick a cheap open model and ship mediocre answers on hard ones.

You shouldn't have to pick. Not every prompt deserves Claude Sonnet 4.6. "What's the capital of Portugal?" and "Refactor this 400-line React component to use Suspense" are not the same job — and they shouldn't cost the same.

In this tutorial we'll build a prompt classifier that routes each incoming request to the right model automatically:

Coding questions → Claude Sonnet 4.6 (best-in-class for code)
Everything else → a cheap, fast open model on Workers AI

The whole thing is ~50 lines of TypeScript running on Cloudflare Workers, and the routing logic lives in AI Gateway — no vendor lock-in, unified logs, one endpoint for your app.

The architecture

Three moving parts:

A Worker intercepts each OpenAI-compatible chat request
It uses Workers AI (Llama 4 Scout, free tier) to classify the prompt as coding or simple
It attaches that tag as a cf-aig-metadata header, then forwards to AI Gateway, which reads the tag and routes to the correct upstream model

Your client only ever sees one endpoint. AI Gateway gives you unified logs, caching, and rate-limiting across both providers.

Prerequisites

A Cloudflare account (free tier is fine)
An Anthropic API key (sign up here)
Node.js 20+ and Wrangler installed

Step 1: Create an AI Gateway

In the Cloudflare Dashboard → AI → AI Gateway → Create Gateway. Give it a name (e.g. smart-router).
Make sure Authenticated Gateway option is enabled;
AI Gateway created with Authenticated Gateway enabled;
Copy the API token shown on the next screen — Cloudflare won't show it again. You will need this token to set the secret AI_GATEWAY_TOKEN on a later step.
Then add your Anthropic API key:
Open your gateway → Provider Keys tab
Click Add → select Anthropic → paste your key

AI Gateway will now handle authentication to Anthropic on your behalf — you won't need to expose that key from your Worker.

Step 2: Configure the Dynamic Route

Still in your gateway, go to Dynamic Routes → Add Route → Start from scratch. Name it route1.

Build this logic in the visual editor:

If metadata.task == "coding" → route to Anthropic → claude-sonnet-4-6
Else → route to Workers AI → @cf/moonshotai/kimi-k2.7-code (or any other cheap Workers AI model)

Save the route. AI Gateway now knows how to fork traffic based on a metadata.task field.

Step 3: Build the classifier Worker

Scaffold a new Worker:

npm create cloudflare@latest -- prompt-router --type hello-world --ts
cd prompt-router

Navigate into the new prompt-router/src folder and replace src/index.ts with:

export interface Env {
  AI: Ai;
  GATEWAY_ACCOUNT_ID: string;
  GATEWAY_NAME: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const gatewayUrl = `https://gateway.ai.cloudflare.com/v1/${env.GATEWAY_ACCOUNT_ID}/${env.GATEWAY_NAME}/compat/chat/completions`;

    let body: Record<string, any> = {};
    try {
      body = await request.json();
    } catch {
      return new Response("prompt-router is running");
    }

    if (!body.messages?.length) {
      return new Response("prompt-router is running");
    }

    // Extract the latest user message
    const lastMessage = body.messages.at(-1);
    const prompt = typeof lastMessage?.content === "string"
      ? lastMessage.content
      : lastMessage?.content?.find((c: any) => c.type === "text")?.text ?? "";

    // Classify with a small, cheap model
    const classification = await env.AI.run(
      "@cf/meta/llama-4-scout-17b-16e-instruct",
      {
        messages: [
          {
            role: "system",
            content:
              "Classify the user prompt into exactly one word: 'coding' or 'simple'. Reply with only that single word, nothing else.",
          },
          { role: "user", content: prompt },
        ],
      }
    );

    const task = classification.response?.trim().toLowerCase() === "coding"
      ? "coding"
      : "simple";

    // Forward to AI Gateway with the classification as metadata
    const headers = new Headers(request.headers);
    headers.set("cf-aig-metadata", JSON.stringify({ task }));

    return fetch(gatewayUrl, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    });
  },
};

Update wrangler.jsonc.
1) Replace {GATEWAY_ACCOUNT_ID} by your Cloudflare Account ID:

In the Cloudflare dashboard, go to the Account list.
Select the menu button at the end of the account row.
Select Copy account ID.

2) Update {GATEWAY_NAME} with your values (find them in AI > AI Gateway > Settings).

{
  "name": "prompt-router",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat"],
  "ai": {
    "binding": "AI"
  },
  "vars": {
    "GATEWAY_ACCOUNT_ID": "your-account-id",
    "GATEWAY_NAME": "smart-router"
  }
}

Store the AI Gateway API token (saved on the creation of AI Gateway) as a Worker secret:

wrangler secret put AI_GATEWAY_TOKEN
# paste the token when prompted

Deploy the worker:

npm run deploy

Step 4: Test it

Fire two prompts at your Worker with curl:

# Simple prompt — should route to Workers AI
curl -X POST https://prompt-router.<your-subdomain>.workers.dev \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-ai-gateway-token>" \
  -d '{
    "model": "dynamic/route1",
    "messages": [{"role": "user", "content": "What is the capital of Portugal?"}]
  }'

# Coding prompt — should route to Claude
curl -X POST https://prompt-router.<your-subdomain>.workers.dev \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-ai-gateway-token>" \
  -d '{
    "model": "dynamic/route1",
    "messages": [{"role": "user", "content": "Write a Python function that reverses a linked list in place."}]
  }'

Go to Cloudflare Dashboard > Compute > Workers & Pages prompt-router.
Check the Observability / Logs tab. You should see it successfully extract the prompt and log: Task: coding.
Go to AI > AI Gateway > Gateways > Your Gateway.
Click the Logs tab and make sure that claude-sonnet-4-6 model (slower, expensive, higher quality) is used for coding tasks and Kimi-K2 (fast, cheap) for the rest. Cost delta is visible in the logs.

Step 5: Point your existing app at it
Anything that speaks the OpenAI Chat Completions API will work. For example, in Open WebUI or LibreChat:
Base URL: https://prompt-router..workers.dev
Model: dynamic/route1
API Key: your AI Gateway token

In Continue.dev or Cursor, use the same base URL and model name. From the client's perspective it's a single OpenAI-compatible model — the routing is invisible.

Does this actually save money?

Very rough back-of-envelope, based on current public prices:

Model	Input $/1M tokens	Output $/1M token
Claude Sonnet 4.6	$3.0	$15.00
Workers AI (Kimi-K2)	$0.95	$4.00

If 70% of a typical chat app's prompts are "simple" (conversation, factual questions, summaries) and 30% are "coding" or complex reasoning, routing them separately cuts total LLM cost by roughly 60-70% versus sending everything to Claude — while keeping Claude on the workloads where it earns its price.

Your mileage will vary. Instrument the classifier's output and measure your own traffic mix before quoting numbers.

Where to go from here

A few natural extensions:

More categories. Add reasoning, creative, summarization, translation — each routed to a specialist model.
Confidence-based fallback. Ask the classifier for a confidence score, and only route to the cheap model if confidence is high; otherwise default to the strong one.
Per-user or per-tier routing. Free-tier users always hit the cheap model; paid users get the frontier one. Read a header or JWT claim and inject it into cf-aig-metadata alongside task.
Evals-based routing. Score responses from both models offline, then bias the router toward whichever one wins for a given category.

Wrap

The interesting bit isn't the classifier — it's the pattern. Once you have a Worker sitting between your app and AI Gateway, injecting metadata, you can express any routing policy you want in the Gateway's visual editor without touching code again.
Prompt-based routing is the simplest useful policy. Once you've shipped it, cost-aware, latency-aware, and quality-aware routing are all one Dynamic Route edit away.

Full code and setup notes: GitHub Repo

If you build something with this, drop a comment — especially if you find a smarter classifier prompt than mine.

DEV Community: Alexey Sazhin

Supercharge Your LLM Router with a Decision Model: Clef on Cloudflare Workers

Make the classifier testable

What the LLM classifier got wrong

Patching it only goes so far

Decision models: answers, not text

The swap

When Clef isn't sure, pay for Sonnet

Results

Takeaways

Try it

What's next

Building a German Speaking Partner with ElevenLabs Agents and Cloudflare Workers

What it does

How it fits together

Decisions worth explaining

What I'd do next

Verifying ElevenLabs Webhook Signatures on Cloudflare Worker (Without Their SDK)

What is Post-call Webhook?

Don't Reach for the Official SDK Just for This

The Actual Signature Scheme

The code

Secret Rotation: Why Loop Over Every v0= Value

Testing it from Windows:

Confirmed Working in Production

Wrap-up

Building a RAG Chatbot on Cloudflare Workers (Vectorize + D1 + Workflows)

The architecture

Why ingestion runs through a Workflow, not a plain loop

Setting up the bindings

The query side: retrieval with a floor, not just a top match

Testing the endpoints directly (local environment)

The chat UI

The admin panel

Wrap

Building a Voice Support Agent using ElevenLabs and Cloudflare

Artifacts

Intro

The architecture

Setting up Cloudflare

The app itself

Testing the endpoints directly

The storefront itself

Building the agent

The conversation is a graph, not just a prompt

Wiring the tools: read vs. write get treated differently

Note on Security

What I'd add next

Try it

Stop Paying Claude Prices for "Hi" — Route LLM Prompts to the Right Model in 50 Lines

The architecture

Prerequisites

Step 1: Create an AI Gateway

Step 2: Configure the Dynamic Route

Step 3: Build the classifier Worker

Does this actually save money?

Where to go from here

Wrap

Secret Rotation: Why Loop Over Every `v0=` Value