Skip to content
bits
Sign in
Ship an agent to the edge · Lesson 8 of 8 · 30 min

Checkpoint: Klippy in production

Desk: best at a computer, with a terminal
Desk: best at a computer, with a terminal

Verified agents 0.33.0@cloudflare/ai-chat 0.12.2ai 7.0.162wrangler 4.157.0remix 3.1.0

Start from f-07 on GitHub. Starting here, or behind? Get the code at that tag:

Shell
git clone https://github.com/ryanyogan/klippy
cd klippy
git checkout f-07
Tutor:

Klippy is ready for the internet. The agent has no public address, every model call is labelled and the check probe is cached by key, a per-user limit and a daily budget hold (every call is charged before it's made), each turn logs its shape, a test proves a fooled model can't write or send data out, and CI can deploy main and preview pull requests. Name the tag, take the tour, and then deploy it yourself: bits checks your live web app.

Tutor:

1. Name the tag

In apps/agent/src/check.ts (and test/check.spec.ts):

// The lesson tag this code is at. bits reads it to see how far your Klippy has come.
export const TAG = 'f-08';
TypeScriptUTF-8at f-08● lines 2–2: apps/agent/src/check.ts
Tutor:

Run pnpm typecheck && pnpm test: ours was 25 agent test files, 111 tests passed.

Tutor:

2. The tour

Locally, with pnpm dev:web (the Workers AI fallback answered, not Claude). The check, through the web app:

recorded output
curl -s 'localhost:8802/klippy/check?nonce=checkpoint-f08'
{"nonce":"checkpoint-f08","tag":"f-08","probe":{"answer":"Hi bits, it's Klippy here to help!","model":"@cf/zai-org/glm-4.7-flash","cache":"MISS"}}
Tutor:

Signed out, / sends you to /login. Signed in (a test cookie for GitHub id 1), a file goes in through the web app and search finds it:

recorded output
curl -s -b <cookie> 'localhost:8802/sources/search?q=Lisbon+flight'
{"hits":[{"chunkId":2,"sourceId":2,"title":"trip-f08.md","url":null,"kind":"file","context":"","text":"# Trip\n\nMy Lisbon flight leaves on Friday at 18:40 from Terminal 2."}, …]}
Tutor:

Then the chat, in a browser. "What time does my Lisbon flight leave? Check my notes." got this (the tool card, then the reply):

recorded output
the chat, as the page read it
Klippy: searchNotes Done Your Lisbon flight leaves at 18:40 (6:40 PM) from Terminal 2 on Friday. Used 2 sources [1] trip-f08.md [2] pip-f01.md
Tutor:

Then "Save a note: pack the passport for Lisbon". The tool card said saveNote Failed, and that's correct: the retrieval cut from course E locks every writing tool for the rest of a chat once saved content has been read, and this chat had searched. The fallback model told the user it couldn't save "due to a technical issue". It wasn't. The tool card is the truth, not the model's story about it. Start a new chat to save a note.

Tutor:

3. Deploy it yourself

We haven't deployed the reference Klippy, so there's no recorded live run. Our dry runs printed a total upload of 4081.04 KiB (783.59 KiB gzipped) for the agent and 991.10 KiB (197.85 KiB gzipped) for the web app. Here's the order for yours, once:

  1. Your id only. In apps/web/wrangler.jsonc, set ALLOWED_GITHUB_IDS to your own GitHub id (gh api user --jq .id) and APP_ORIGIN to your web app's address. Point your GitHub OAuth app's callback at <that address>/auth/github/callback.

  2. The Workers' secrets, as in lesson 6: KLIPPY_TOKEN on the agent, and the four on the web app. They go in before any deploy.

  3. The database. Apply the migrations to the live D1 before the code that needs them: cd apps/agent && pnpm exec wrangler d1 migrations apply DB --remote.

  4. The agent, then the web app. pnpm deploy, then pnpm deploy:web, from the repo root. Or add the two CLOUDFLARE_* repository secrets and push to main: CI does steps 3 and 4 in that order.

  5. Check the side door. curl -i https://klippy.<subdomain>.workers.dev/ should no longer reach your Worker. The web app should still work, signed in.

  6. Set the brakes: a spend limit on the gateway (lesson 2), and the two saved queries (lesson 4) once a few turns have run.

No Anthropic key on your gateway? Klippy still works on the Workers AI fallback, as in every recording here. Add the key (AI Gateway → default → provider keys) to get Claude.

Tutor:

4. Let bits check it

Paste your web app's address: klippy-web.<subdomain>.workers.dev, or your own domain. Not the agent's: it has none now. bits calls /klippy/check there, which reaches your agent over the service binding, and looks for this checkpoint's tag.

deploy check+60 neurons

Goal Your Klippy is in production: the web app's /klippy/check answers with bits' nonce and tag f-08 (or a later one)

Paste the https://klippy-web….workers.dev address (or your custom domain) of your deployed web app.

bits calls /klippy/check?nonce=bits-checkpoint-f08 on your Worker, from bits’ server

  • /klippy/check?nonce=bits-checkpoint-f08 answers 200 OK, not yet
  • Answers the check, not yet
  • Echoes bits' nonce, not yet
  • Is at f-08 or later, not yet

Sign in to check your deploy: the check is saved to your account, and a certificate can link it.

Tutor:

A pass proves a web app at that address reaches an agent that answers the way this lesson asks. It doesn't prove who wrote it.

quick check+20 neurons
Tutor:

In the tour, saveNote failed and the model said it was "a technical issue". What really happened?

    Pick one option

    Pick one, then Check.

    Down the rabbit hole