Skip to content

Cloudflare Agents Integration

This document outlines the approach for integrating Cloudflare Agents into the Meta Agent Platform as API-based agents. It covers the implementation strategy, benefits, considerations, and provides code examples.

Overview

Cloudflare Agents is a serverless platform for building and deploying AI-powered agents that can autonomously perform tasks, communicate with clients in real-time, call AI models, persist state, and more. By integrating Cloudflare Agents into our Meta Agent Platform, we can offer users an additional deployment option that leverages Cloudflare's global edge network.

Key Features of Cloudflare Agents

  • Built-in State Management: Each agent has its own durable state and SQL database
  • Real-time Communication: WebSocket support for streaming updates
  • Long-running Operations: Agents can run for seconds, minutes, hours, or longer
  • Global Edge Deployment: Run close to users or data sources
  • Tool Integration: Built-in support for calling external APIs and services
  • Human-in-the-Loop Workflows: Native support for HITL interactions
  • AI Model Access: Seamless integration with various LLM providers

Implementation Strategy

We'll implement Cloudflare Agents as API-based agents in our platform, leveraging our existing agent abstraction layer. This approach requires minimal changes to our core architecture while providing users with the benefits of Cloudflare's infrastructure.

1. Cloudflare Agent Type

Add a new agent type for Cloudflare Agents in our agent data model:

// In agent-store.ts
export interface Agent {
  // Existing fields...
  type: string; // Add 'cloudflare' as a possible value
  // Other fields...
}

2. Cloudflare Agent Adapter

Create an adapter class that handles communication with Cloudflare Agents:

// cloudflare-agent-adapter.ts
export class CloudflareAgentAdapter {
  private apiKey: string;
  private accountId: string;

  constructor(config: { apiKey: string; accountId: string }) {
    this.apiKey = config.apiKey;
    this.accountId = config.accountId;
  }

  async execute(agentConfig: any, inputData: any): Promise<any> {
    const { workerId, endpoint } = agentConfig;

    // Construct the Cloudflare Workers URL
    const url = `https://${workerId}.${this.accountId}.workers.dev${endpoint || ''}`;

    // Make the API request
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify(inputData)
    });

    if (!response.ok) {
      throw new Error(`Cloudflare Agent execution failed: ${response.statusText}`);
    }

    return await response.json();
  }
}

3. Agent Creation UI

Update the agent creation UI to include Cloudflare as an option:

<!-- In demo/src/routes/agents/create/+page.svelte -->
<!-- Add to the methods array -->
{
  id: 'cloudflare',
  name: 'Cloudflare Agent',
  description: 'Deploy and run agents on Cloudflare Workers',
  icon: Cloud, // Import Cloud icon from lucide-svelte
  examples: 'Stateful agents with WebSockets, edge deployment'
}

Add a form for Cloudflare agent configuration:

<!-- Add this to your agent creation form -->
{#if $agentMethod === 'cloudflare'}
  <div class="space-y-4">
    <p>Configure a Cloudflare Agent:</p>
    <form class="space-y-4">
      <div class="grid gap-4">
        <div>
          <label for="cloudflare-worker-id" class="text-sm font-medium mb-1 block">Worker ID</label>
          <input id="cloudflare-worker-id" type="text" class="w-full p-2 border rounded" placeholder="e.g., my-agent" />
        </div>
        <div>
          <label for="cloudflare-account-id" class="text-sm font-medium mb-1 block">Account ID</label>
          <input id="cloudflare-account-id" type="text" class="w-full p-2 border rounded" placeholder="Your Cloudflare account ID" />
        </div>
        <div>
          <label for="cloudflare-api-key" class="text-sm font-medium mb-1 block">API Key</label>
          <input id="cloudflare-api-key" type="password" class="w-full p-2 border rounded" placeholder="Your Cloudflare API key" />
        </div>
        <div>
          <label for="cloudflare-endpoint" class="text-sm font-medium mb-1 block">Endpoint (optional)</label>
          <input id="cloudflare-endpoint" type="text" class="w-full p-2 border rounded" placeholder="e.g., /api/run" />
        </div>
      </div>
    </form>
  </div>
{/if}

4. Agent Configuration Schema

Example Cloudflare agent configuration:

{
  "name": "Text Summarizer",
  "description": "Summarizes text using Cloudflare Workers",
  "type": "cloudflare",
  "status": "active",
  "version": "1.0.0",
  "configuration": {
    "workerId": "text-summarizer",
    "accountId": "your-account-id",
    "apiKey": "your-api-key",
    "endpoint": "/api/summarize",
    "model": "claude-3-sonnet",
    "temperature": 0.7
  },
  "capabilities": [
    "text_summarization",
    "edge_deployment",
    "stateful_processing"
  ],
  "input_schema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "Text to summarize"
      },
      "max_length": {
        "type": "number",
        "description": "Maximum length of summary"
      }
    },
    "required": ["text"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "summary": {
        "type": "string",
        "description": "Summarized text"
      }
    },
    "required": ["summary"]
  }
}

5. Agent Execution Logic

Update the workflow execution engine to handle Cloudflare agents:

// In your workflow execution code
async function executeAgent(node, input) {
  const agent = getAgentById(node.data.agent_id);

  if (!agent) {
    throw new Error(`Agent not found: ${node.data.agent_id}`);
  }

  // Handle different agent types
  switch (agent.type) {
    case 'cloudflare':
      const cloudflareAdapter = new CloudflareAgentAdapter({
        apiKey: agent.configuration.apiKey,
        accountId: agent.configuration.accountId
      });

      return await cloudflareAdapter.execute(agent.configuration, {
        ...input,
        ...node.data.parameters
      });

    case 'docker':
      // Existing Docker agent execution logic
      break;

    case 'api':
      // Existing API agent execution logic
      break;

    // Other agent types...
  }
}

Creating a Cloudflare Agent

1. Agent Implementation

Example of a text summarization agent using the Cloudflare Agents SDK:

// worker.js
import { Agent } from "agents";

class TextSummarizer extends Agent {
  // Initial state
  initialState = {
    summaries: [],
    totalProcessed: 0
  };

  // Handle HTTP requests
  async onRequest(request) {
    if (request.method === "POST") {
      const data = await request.json();
      const result = await this.summarizeText(data);

      return new Response(JSON.stringify(result), {
        headers: { "Content-Type": "application/json" }
      });
    }

    return new Response("Method not allowed", { status: 405 });
  }

  // Text summarization method
  async summarizeText(data) {
    const { text, max_length = 200 } = data;

    // Call an AI model to summarize the text
    const response = await fetch("https://api.anthropic.com/v1/messages", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": this.env.ANTHROPIC_API_KEY
      },
      body: JSON.stringify({
        model: "claude-3-sonnet-20240229",
        max_tokens: max_length,
        messages: [
          {
            role: "user",
            content: `Summarize the following text in about ${max_length} words: ${text}`
          }
        ]
      })
    });

    const result = await response.json();
    const summary = result.content[0].text;

    // Update state
    this.setState({
      summaries: [...this.state.summaries, { text, summary, timestamp: new Date().toISOString() }].slice(-10),
      totalProcessed: this.state.totalProcessed + 1
    });

    return { summary };
  }
}

export default TextSummarizer;

2. Deployment

Deploy the agent using Wrangler:

# Install Wrangler
npm install -g wrangler

# Create a new project
npx wrangler init text-summarizer

# Add the Agents SDK
npm install agents

# Deploy the agent
npx wrangler deploy

3. Configuration

Example wrangler.toml configuration:

name = "text-summarizer"
main = "src/worker.js"
compatibility_date = "2023-10-30"

[durable_objects]
bindings = [
  { name = "TEXT_SUMMARIZER", class_name = "TextSummarizer" }
]

[[migrations]]
tag = "v1"
new_classes = ["TextSummarizer"]

[vars]
ENVIRONMENT = "production"

# Secret variables (set using wrangler secret put)
# ANTHROPIC_API_KEY

Benefits

  1. Global Edge Deployment: Run agents close to users for low latency
  2. Stateful Agents: Built-in state management without additional databases
  3. Scalability: Cloudflare's infrastructure handles scaling automatically
  4. Real-time Communication: WebSocket support for interactive agents
  5. Cost-Efficiency: Pay-per-use pricing model
  6. Simplified Operations: No infrastructure to manage

Considerations

Security

  • Store Cloudflare API keys securely in your platform's secret management system
  • Implement proper authentication between your platform and Cloudflare agents
  • Consider using Cloudflare Access for additional security

Performance

  • Monitor agent execution times and resource usage
  • Implement caching strategies for frequently accessed data
  • Use Cloudflare's built-in analytics to track performance

Cost Management

  • Monitor usage to avoid unexpected costs
  • Implement rate limiting for high-volume workflows
  • Consider using Cloudflare's tiered pricing for predictable costs

Error Handling

  • Implement robust error handling for API calls
  • Add retry logic for transient failures
  • Provide clear error messages to users

Integration with Other Platform Components

Workflow Builder

Cloudflare agents can be integrated into the visual workflow builder as standard agent nodes. The workflow engine will handle the execution of these agents through the Cloudflare adapter.

Monitoring Dashboard

Extend the monitoring dashboard to display Cloudflare-specific metrics:

  • Agent execution times
  • Resource usage
  • Error rates
  • State size

Agent Registry

Update the agent registry to include Cloudflare-specific metadata:

  • Worker ID
  • Account ID
  • Endpoint
  • Capabilities

Future Enhancements

  1. WebSocket Support: Add support for real-time communication with Cloudflare agents
  2. Model Context Protocol (MCP): Integrate with Cloudflare's MCP implementation
  3. Edge Deployment Optimization: Provide tools for optimizing agents for edge deployment
  4. Human-in-the-Loop Integration: Leverage Cloudflare's HITL capabilities

Conclusion

Integrating Cloudflare Agents as API-based agents in the Meta Agent Platform provides users with a powerful option for deploying stateful, globally distributed agents without managing infrastructure. This approach leverages our existing architecture while adding significant new capabilities.

Last updated: 2023-05-20