cloudflare-knowledge

name	cloudflare-knowledge
description	Cloudflare edge platform patterns for Workers, Agents SDK, MCP servers, Vectorize, and Workflows. Use when building on Cloudflare infrastructure.

Cloudflare Knowledge

Quick Reference

Task	Read File	Key Constraint
Building Agent class	agents-sdk.md	new_sqlite_classes in migrations
Agent design patterns	agent-patterns.md	Use AI SDK with Durable Objects
MCP server (stateless)	agents-mcp.md	Use createMcpHandler (recommended)
MCP server (stateful)	agents-mcp.md	Agent + WorkerTransport + createMcpHandler
OAuth / auth patterns	auth-deployment.md	OAUTH_KV binding required for workers-oauth-provider
Vector search	vectorize.md	topK ≤20 with metadata, ≤100 without
Durable execution	workflows.md	Always await step.do(), steps must be idempotent
R2, KV, D1 bindings	workers-platform.md	Use bindings (not REST APIs), D1 prepared statements
Logging & tracing	observability.md	observability: { enabled: true } in wrangler.jsonc
CI/CD & deployment	auth-deployment.md	Workers Builds, GitHub Actions, secrets management

Critical Standards (Always Apply)

// wrangler.jsonc - REQUIRED settings
{
  "compatibility_date": "2025-03-07",  // Minimum for Agents
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true }
}

Reranker: MUST Use Batch API

// ✅ CORRECT
await env.AI.run("@cf/baai/bge-reranker-base", {
  query: "search query",
  contexts: [{ text: "passage1" }, { text: "passage2" }],
  top_k: 10
});

// ❌ WRONG - deprecated per-document format
await env.AI.run("@cf/baai/bge-reranker-base", {
  text: ["query", "passage"]
});

D1: MUST Use Prepared Statements

// ✅ CORRECT
env.DB.prepare("SELECT * FROM users WHERE id = ?").bind(userId)

// ❌ WRONG - SQL injection risk
env.DB.prepare(`SELECT * FROM users WHERE id = '${userId}'`)

KV: Eventually Consistent

// ✅ CORRECT - return what you wrote
await env.MY_KV.put("key", newValue);
return Response.json({ value: newValue });

// ❌ WRONG - may return stale data
await env.MY_KV.put("key", newValue);
const readBack = await env.MY_KV.get("key"); // May be stale!

When to Read Detail Files

Read agents-sdk.md when:

• Creating a new Agent class
• Implementing state management (this.setState, this.sql)
• Adding scheduling (this.schedule)
• Handling WebSocket connections
• Client APIs (AgentClient, useAgent hook)

Read agent-patterns.md when:

• Designing multi-step AI workflows
• Implementing routing/classification
• Building orchestrator-worker systems
• Need evaluator-optimizer loops

Read agents-mcp.md when:

• Building an MCP server (use createMcpHandler)
• Registering tools with schemas
• Adding OAuth authentication to MCP
• Connecting to external MCP servers as a client

Read auth-deployment.md when:

• Adding authentication (workers-oauth-provider, OAuth 2.1)
• Setting up CI/CD (Workers Builds, GitHub Actions, GitLab CI)
• Managing secrets (wrangler secret, .dev.vars)
• Creating deploy buttons

Read vectorize.md when:

• Creating/querying vector indexes
• Implementing semantic search or RAG
• Building two-stage retrieval (vector + rerank)
• Setting up metadata filters

Read workflows.md when:

• Building durable/long-running tasks
• Need automatic retries with backoff
• Implementing human-in-the-loop (waitForEvent)
• Scheduling delayed execution

Read workers-platform.md when:

• Using R2 (object storage), KV (key-value), or D1 (SQL)
• Configuring wrangler.jsonc bindings
• Need binding types reference
• Working with multipart uploads, presigned URLs

Read observability.md when:

• Setting up logging (Workers Logs, wrangler tail)
• Implementing distributed tracing
• Adding custom analytics (Analytics Engine)
• Configuring Logpush or Tail Workers

File Locations

All detail files are in the references/ subdirectory of this skill. Read the relevant file before implementing.