paths: "/*.ts", "/agent.ts", wrangler.jsonc

Cloudflare Agents Corrections

Do You Need Agents? (80% Don't)

/* Most apps just need AI SDK directly */
// Simple chat = AI SDK
// Stateful multi-turn = Cloudflare Agents

/* Use Agents when you need: */
// - Persistent state across sessions
// - WebSocket real-time chat
// - Scheduled tasks from AI
// - Complex multi-step workflows

SQLite in First Migration (Same as DOs)

/* ❌ Cannot add SQLite later */
migrations: [
  { tag: 'v1' },
  { tag: 'v2', new_sqlite_classes: ['MyAgent'] } // Too late!
]

/* ✅ Must be in v1 */
migrations: [
  { tag: 'v1', new_sqlite_classes: ['MyAgent'] }
]

MUST Export Agent Class

/* ❌ "Binding not found" */
class MyAgent extends Agent { }

/* ✅ Export the class */
export class MyAgent extends Agent { }

Authenticate in Worker BEFORE Agent

/* ❌ Auth inside agent (too late) */
class MyAgent extends Agent {
  async onConnect() {
    if (!authenticated) throw new Error('Unauthorized')
  }
}

/* ✅ Auth in Worker before creating agent */
export default {
  async fetch(request, env) {
    const user = await authenticate(request)
    if (!user) return new Response('Unauthorized', { status: 401 })

    // Now create agent with authenticated user
    return env.AGENT.get(env.AGENT.idFromName(user.id)).fetch(request)
  }
}

Workers AI SSE Parsing

/* ❌ Expecting automatic parsing */
const stream = await env.AI.run('@cf/meta/llama-3-8b', { stream: true })

/* ✅ Manual SSE parsing required */
const reader = stream.getReader()
const decoder = new TextDecoder()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  const text = decoder.decode(value)
  // Parse SSE format: data: {...}\n\n
  for (const line of text.split('\n')) {
    if (line.startsWith('data: ')) {
      const json = JSON.parse(line.slice(6))
      // Process json.response
    }
  }
}

Global Instance Naming

/* ⚠️ Same name = same agent globally */
const id = env.AGENT.idFromName('user-123')
// Anyone with 'user-123' accesses same agent!

/* ✅ Use unique, unpredictable names */
const id = env.AGENT.idFromName(`user:${userId}:${sessionId}`)

Quick Fixes