cloudflare-knowledge

# 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)
```jsonc
// wrangler.jsonc - REQUIRED settings
{
  "compatibility_date": "2025-03-07",  // Minimum for Agents
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true }
}
```

### Reranker: MUST Use Batch API
```typescript
// ✅ 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
```typescript
// ✅ 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
```typescript
// ✅ CORRECT - return what you wrote
await env.MY_KV.put("key", newValue);
return Response.json({ value: newValue });

// ❌