1. Hello agent

Checkpoint 1 of 69 minutes

Hello agent

Turn the main-branch starter into a FieldTrip agent with a durable identity, local memory, and a live endpoint.

The concept

An agent is an exported, capitalized function whose file starts with 'use agent'. Flue re-runs that function before every model call. useModel is the one required hook, and the function name becomes infrastructure: FieldTrip generates FlueFieldTripAgent and the FLUE_FIELD_TRIP_AGENT binding. Each conversation ID selects a separate Durable Object with its own SQLite-backed history.

→ Why this matters

Adding an agent is a three-part change: define the agent, mount its route, and add its Durable Object migration. Missing any one leaves the agent incomplete.

1. Confirm the starter branch

git status --short
git branch --show-current

Start from main with no local changes. Keep your workshop account exported in the terminal where you will run npm run deploy.

2. Add the agent

Delete the placeholder and create the agent file:

rm src/agents/.gitkeep

src/agents/field-trip.ts+8−0

New file from main → cp/1-hello-agent

Changes

src/agents/field-trip.ts

===================================================================
--- /dev/null  main
+++ b/src/agents/field-trip.ts  cp/1-hello-agent
@@ -0,0 +1,8 @@
+'use agent';
+
+import { useModel } from '@flue/runtime';
+
+export function FieldTrip() {
+  useModel('cloudflare/@cf/google/gemma-4-26b-a4b-it');
+  return `You are FieldTrip, a helpful team-offsite planner. You help groups plan memorable offsites by understanding their destination, dates, headcount, budget, and interests.`;
+}

Complete file

src/agents/field-trip.ts

'use agent';

import { useModel } from '@flue/runtime';

export function FieldTrip() {
  useModel('cloudflare/@cf/google/gemma-4-26b-a4b-it');
  return `You are FieldTrip, a helpful team-offsite planner. You help groups plan memorable offsites by understanding their destination, dates, headcount, budget, and interests.`;
}

Update src/app.ts to import and mount the agent:

src/app.ts+3−0

Changes from main → cp/1-hello-agent

Changes

src/app.ts

===================================================================
--- a/src/app.ts  main
+++ b/src/app.ts  cp/1-hello-agent
@@ -1,4 +1,6 @@
 import { Hono } from 'hono';
+import { createAgentRouter } from '@flue/runtime/routing';
+import { FieldTrip } from './agents/field-trip.ts';
 import chatUi from './ui/index.html?raw';

 // src/app.ts is the Flue route map. Its default export owns every HTTP request
@@ -9,5 +11,6 @@
 // A small chat UI for trying the agent in a browser, locally and on workers.dev.
 app.get('/', (c) => c.html(chatUi));
 app.get('/api/ping', (c) => c.text('pong'));
+app.route('/agents/field-trip', createAgentRouter(FieldTrip));

 export default app;

Complete file

src/app.ts

import { Hono } from 'hono';
import { createAgentRouter } from '@flue/runtime/routing';
import { FieldTrip } from './agents/field-trip.ts';
import chatUi from './ui/index.html?raw';

// src/app.ts is the Flue route map. Its default export owns every HTTP request
// the Worker receives. Agents get mounted here with createAgentRouter(...)
// starting in checkpoint 1.
const app = new Hono();

// A small chat UI for trying the agent in a browser, locally and on workers.dev.
app.get('/', (c) => c.html(chatUi));
app.get('/api/ping', (c) => c.text('pong'));
app.route('/agents/field-trip', createAgentRouter(FieldTrip));

export default app;

Update wrangler.jsonc to add the agent’s first migration:

wrangler.jsonc+6−1

Changes from main → cp/1-hello-agent

Changes

wrangler.jsonc

===================================================================
--- a/wrangler.jsonc  main
+++ b/wrangler.jsonc  cp/1-hello-agent
@@ -16,5 +16,10 @@
   // Durable Object migrations. Flue generates one DO class per agent
   // (FieldTrip -> FlueFieldTripAgent), but YOU own the migration history.
   // Checkpoint 1 adds the first entry here. Append; never rewrite deployed entries.
-  "migrations": []
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["FlueFieldTripAgent"]
+    }
+  ]
 }

Complete file

wrangler.jsonc

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "field-trip-agent",

  // Flue requires nodejs_compat and a compatibility_date of 2026-04-01 or newer.
  "compatibility_date": "2026-09-01",
  "compatibility_flags": ["nodejs_compat"],

  // Workers AI binding: powers `cloudflare/@cf/...` models. No API keys needed.
  // AI always runs remotely (even in `vite dev`), so `remote: true` is explicit.
  "ai": {
    "binding": "AI",
    "remote": true
  },

  // Durable Object migrations. Flue generates one DO class per agent
  // (FieldTrip -> FlueFieldTripAgent), but YOU own the migration history.
  // Checkpoint 1 adds the first entry here. Append; never rewrite deployed entries.
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["FlueFieldTripAgent"]
    }
  ]
}

Account selection comes from CLOUDFLARE_ACCOUNT_ID, set in your terminal during Session setup. Keep the account ID out of wrangler.jsonc.

3. Verify

Live deploy

npm run deploy
sleep 5
npm run smoke -- https://field-trip-agent.<subdomain>.workers.dev cp1-live "Hi, who are you? Two sentences."
npm run smoke -- https://field-trip-agent.<subdomain>.workers.dev cp1-live "What was the first thing I asked you? One sentence."

Use the exact URL printed by the deploy command. The deployment should list the AI binding and FlueFieldTripAgent Durable Object. The first command should end with ✔ completed; the second should recall your introduction question.

Save your workers.dev subdomain to open this test ↗https://field-trip-agent.<subdomain>.workers.dev/?id=cp1-live

This opens the same conversation as the smoke test. If you repeat this checkpoint, use a fresh test IDbefore copying its commands.

Local dev

In Terminal A, start the dev server and leave it running:

npm run dev

Wait for VITE ... ready, then run in Terminal B:

npm run smoke -- http://localhost:5173 cp1-local "Hi, who are you?"
npm run smoke -- http://localhost:5173 cp1-local "What was the first thing I asked you? One sentence."

The first command should end with ✔ completed. The second should recall Hi, who are you? because it uses the same conversation ID.

Open local chat in your browser ↗http://localhost:5173/?id=cp1-local

This opens the same conversation as the smoke test. If you repeat this checkpoint, use a fresh test IDbefore copying its commands.

Verification gate

Prove it works

• The deployed smoke test exits successfully and introduces FieldTrip.
• A second message with cp1-live recalls the first.
• The browser-test link opens your deployed chat and the same conversation.

Optional mini quizCheck the agent foundation3 questions / instant feedback

1What turns an exported function into a Flue agent?

AThe 'use agent' directiveBThe Hono route aloneCThe AI binding alone

2What does the FieldTrip function name determine?

AOnly a display labelBThe generated Durable Object identityCThe model provider

3Why does the second smoke test remember the first question?

AIt shares the same conversation IDBThe prompt is hard-codedCAll users share one object

Check my answersStart over

Recovery lane

Get back on track in under a minute

If a dev server is running, stop it first. Uncommitted work is stashed and the current commit gets a backup branch before anything moves.

Option 01

Restart this exercise

Return to main, rebuild this exercise, then use its Live deploy verification tab. Stop any running dev server with Ctrl+C before switching.

TerminalCopy

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

Option 02

Catch up with the room

Jump to cp/1-hello-agent, then use this checkpoint's Live deploy verification tab. Stop any running dev server with Ctrl+C before switching.

TerminalCopy

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/1-hello-agent
npm ci

Next: Add persistent state →