Cloudflare Workers + Workers AI Integration Guide 2026

Overview

This guide shows you exactly how to run AI at the edge with Cloudflare using Cloudflare Workers and Workers AI. We cover setup, core integration, and production-ready patterns.

Prerequisites

Cloudflare Workers environment set up

Workers AI API key or access credentials

Basic understanding of Cloudflare Workers development

Installation

bash
Install required packages
npm install workers-ai cloudflare-workers-sdk
or
pip install workers_ai cloudflare_workers

Quick Setup

javascript
// Initialize Workers AI client
import { WorkersAIClient } from 'workers-ai';
const client = new WorkersAIClient({
  apiKey: process.env.WORKERS_AI_API_KEY,
  // Additional config based on your Cloudflare Workers setup
});

Core Integration Code

typescript
// Complete Cloudflare Workers + Workers AI integration
import { OpenAI } from 'openai';
import express from 'express';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const app = express();
app.use(express.json());
// AI endpoint
app.post('/api/ai', async (req, res) => {
  const { message, context } = req.body;
  
  try {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [
        { role: 'system', content: You are integrated with Cloudflare Workers. Help with run AI at the edge with Cloudflare. },
        { role: 'user', content: message }
      ],
      stream: false
    });
    
    res.json({
      response: response.choices[0].message.content,
      usage: response.usage
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});
app.listen(3000);

Cloudflare Workers-Specific Integration

javascript
// Cloudflare Workers specific patterns for Workers AI integration
// Pattern 1: Middleware integration
const aiMiddleware = async (req, res, next) => {
  if (req.path.startsWith('/ai/')) {
    // Add AI context to the request
    req.aiClient = client;
    req.aiConfig = {
      model: 'gpt-4o-mini',
      maxTokens: 1000
    };
  }
  next();
};
// Pattern 2: Service layer
class AIService {
  constructor(private readonly client: typeof openai) {}
  
  async process(input: string, systemPrompt: string = ''): Promise {
    const response = await this.client.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [
        ...(systemPrompt ? [{ role: 'system' as const, content: systemPrompt }] : []),
        { role: 'user' as const, content: input }
      ]
    });
    return response.choices[0].message.content || '';
  }
}
// Pattern 3: React hook (if applicable)
function useAI() {
  const [response, setResponse] = useState('');
  const [loading, setLoading] = useState(false);
  
  const query = async (message: string) => {
    setLoading(true);
    try {
      const res = await fetch('/api/ai', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message })
      });
      const data = await res.json();
      setResponse(data.response);
    } finally {
      setLoading(false);
    }
  };
  
  return { response, loading, query };
}

Streaming Support

typescript
// Add streaming for better UX
app.post('/api/ai/stream', async (req, res) => {
  const { message } = req.body;
  
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  
  const stream = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: message }],
    stream: true
  });
  
  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) {
      res.write(data: ${JSON.stringify({ content })}\n\n);
    }
  }
  
  res.write('data: [DONE]\n\n');
  res.end();
});

Testing the Integration

bash
Unit test
curl -X POST http://localhost:3000/api/ai \
  -H "Content-Type: application/json" \
  -d '{"message": "Test message for run AI at the edge with Cloudflare"}'
Expected:
{"response": "AI response...", "usage": {...}}
Load test
ab -n 100 -c 10 -p test-payload.json -T application/json http://localhost:3000/api/ai

Production Deployment

yaml
docker-compose.yml
services:
  app:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - NODE_ENV=production
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s

Common Issues

Issue: Rate limit errors Solution: Implement exponential backoff and request queuing

Issue: Slow response times Solution: Use streaming and show loading states to users

Issue: High API costs Solution: Cache common responses and use cheaper models for simple tasks

Conclusion

The Cloudflare Workers + Workers AI integration is powerful and relatively straightforward. This guide gives you the foundation to run AI at the edge with Cloudflare in production.

Key takeaways:

Use environment variables for API keys

Implement streaming for better UX

Add error handling and retry logic

Monitor costs from day one

---

*Cloudflare Workers + Workers AI integration guide | May 2026*