How the workshop works

How the workshop works

Each checkpoint follows the same four-part loop. The repetition is deliberate: it turns an unfamiliar agent framework into a predictable engineering workflow.

flowchart TD
  accTitle: Four-part workshop checkpoint loop
  accDescr: Each checkpoint moves from understanding to building, proving the result, and recovering if time expires.
  understand["01 · Understand<br/>Know the behavior and why"] --> build["02 · Build<br/>Review and apply the diff"]
  build --> prove["03 · Prove<br/>Deploy and test the live agent"]
  prove --> recover["04 · Recover<br/>Jump to the tested branch if needed"]

Review each checkpoint’s changes

Every file update opens on Changes, showing a diff from the previous checkpoint. + lines are additions; − lines are removals. Unchanged lines provide context, and @@ headers locate each change. A new file shows every line as an addition.

Review the changes, then apply them to the named file. For a ready-to-paste version, choose Complete file and use its copy button. Copy that file’s content into your editor, then run the lab’s verification commands. Keep each update within the current checkpoint.

Deploy and test each checkpoint

Every verification section opens on Live deploy. Run npm run deploy after applying that checkpoint’s file changes, wait for deployment to finish, then run the smoke tests against the exact workers.dev URL printed by the command. Keep your own CLOUDFLARE_ACCOUNT_ID exported in the deployment terminal.

Save your workers.dev subdomain once so the guide fills every live command and browser-test link. Open live chat in your browser takes you to the same conversation as the smoke test; you can inspect its history and try the prompts interactively. Select New conversation for a clean browser test. After redeploying, reload an already-open chat page to use the latest checkpoint.

The second tab, Local dev, keeps the local workflow available. Start npm run dev in Terminal A and run its http://localhost:5173 smoke tests in Terminal B. Local and deployed conversations have separate storage, even when their IDs match. The dev server uses a strict port; if 5173 is occupied, restart with npm run dev -- --port 5180 and use http://localhost:5180 for the local commands and browser instead.

→ Understand the change, then prove it

The workshop pins Flue and its dependencies to exact versions. Each complete change is compared with the guide’s previous checkpoint, so you can see exactly which imports, hooks, configuration, and instructions are added. The complete file remains available to copy when you want to apply the update quickly.

The recovery promise

Every lab includes two recovery branches:

• Restart this exercise switches to the previous known-good branch.
• Catch up with the room switches to the completed checkpoint branch.

Both flows stash tracked and untracked changes first. Your experiment remains in git stash list, and a backup branch preserves the current commit. If a dev server is running, stop it with Ctrl+C before switching. After npm ci, return to the selected checkpoint’s Live deploy tab to deploy and verify it. For Local dev, restart the server so its code, bindings, and container configuration match the branch.

git stash push --include-untracked -m "workshop recovery"
git fetch origin
git branch -f workshop-backup HEAD
git switch --no-track -C workshop origin/cp/3-api-tools
npm ci

Knowledge check: Why run npm ci after switching checkpoints?

A later checkpoint may add or change a dependency. Re-installing reconciles node_modules with the lockfile on the branch you just selected.

Generate safe forecast dates once

Open-Meteo only forecasts the near future. The guide automatically fills trip dates five and six days ahead in every smoke-test command and its copy button. Copy and paste the commands as shown — no date editing is needed.

Your dates are:

START="<START>"
END="<END>"

The guide saves this pair in your browser and reuses it across checkpoints. On a later visit, it generates a new pair if the saved dates are outside the forecast window. Do not reuse dates shown in screenshots; those become stale.

Timeboxes protect the finish line

Complete the code change and the first verification sequence inside each checkpoint’s timebox. Checks labelled Optional depth check are useful after the room moves on, but they repeat slower model, subagent, or container work and are not required to continue.

Checkpoint	Branch	Topic	Time
1	cp/1-hello-agent	First agent and deploy	9 min
2	cp/2-hooks-state	Persistent state	6 min
3	cp/3-api-tools	Open-Meteo API tools	9 min
4	cp/4-subagent	Venue-scout subagent	8 min
5	cp/5-sandbox	Cloudflare Sandbox	8 min
6	cp/6-iterate-observe	Agent tracing	7 min

When a checkpoint’s timer ends, move forward. A working reference point teaches more than spending the rest of the session debugging an early typo.

Next: Create and deploy your first agent →