Cloudflare Agent

Cloudflare Agent Governance

Overview

This skill enables ControlKeel to govern Cloudflare Agents by providing policy gates, budget enforcement, audit logging, and secure execution capabilities.

When to Use

Use this skill when:

• Building Cloudflare Agents that need governance guardrails
• Enforcing budget/spend limits on Workers AI or external providers
• Auditing agent actions for compliance
• Running shell commands in sandboxed environments within CF Agents
• Integrating PII detection and security scanning

Prerequisites

• Cloudflare Workers project with Agents SDK installed
• ControlKeel MCP connected to the agent
• For shell tools: ExecutionSandbox adapter (local/docker/e2b)

Integration Pattern

1. Connect CK to Cloudflare Agent via MCP

The agent exposes governance tools via MCP:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export class GovernedAgent extends McpAgent {
  server = new McpServer({
    name: "controlkeel-governance",
    version: "1.0.0"
  });

  async init() {
    // Register CK governance tools
    this.server.tool(
      "ck_validate",
      "Validate an action against governance policies",
      { prompt: z.string(), context: z.record(z.string(), z.any()).optional() },
      async ({ prompt, context }) => {
        // Call CK governance endpoint
        return await this.callCKGovernance(prompt, context);
      }
    );

    this.server.tool(
      "ck_budget_check",
      "Check remaining budget for AI spend",
      { scope: z.enum(["task", "session", "daily"]).optional() },
      async ({ scope }) => {
        // Query CK budget state
        return await this.callCKBudget(scope || "task");
      }
    );
  }

  async callCKGovernance(prompt: string, context?: Record<string, any>) {
    const response = await this.env.CK_GOVERNANCE.fetch("/validate", {
      method: "POST",
      body: JSON.stringify({ prompt, context })
    });
    return response.json();
  }
}

2. Policy Gate Pattern

Validate before execution:

export class GovernedAgent extends Agent {
  @callable()
  async executeWithGovernance(command: string, args: string[]) {
    // Pre-execution policy check
    const validation = await this.validateWithCK({
      action: "execute_command",
      payload: { command, args }
    });

    if (validation.decision === "denied") {
      return { error: "Policy violation", reason: validation.reason };
    }

    // Execute if approved
    const result = await this.executeCommand(command, args);

    // Post-execution audit
    await this.auditWithCK({
      action: "command_executed",
      payload: { command, args, result },
      validation_id: validation.id
    });

    return result;
  }
}

3. Budget Enforcement

export class BudgetedAgent extends Agent {
  @callable()
  async callAIWithBudget(model: string, messages: any[]) {
    // Check budget before AI call
    const budget = await this.ckBudgetCheck("task");
    
    if (!budget.has_remaining) {
      return { error: "Budget exhausted", remaining: 0 };
    }

    // Make AI call
    const response = await this.callAI(model, messages);

    // Deduct from budget
    await this.ckBudgetDeduct({
      amount: response.usage_tokens,
      scope: "task"
    });

    return response;
  }
}

4. Shell Execution (via CK ExecutionSandbox)

For agents that need shell access:

export class ShellEnabledAgent extends Agent {
  @callable()
  async shell(command: string, cwd?: string) {
    // Validate shell command
    const validation = await this.validateWithCK({
      action: "shell_execution",
      payload: { command, cwd }
    });

    if (validation.decision === "denied") {
      throw new Error(`Shell denied: ${validation.reason}`);
    }

    // Execute via CK sandbox (local/docker/e2b)
    const result = await this.env.CK_SANDBOX.fetch("/execute", {
      method: "POST",
      body: JSON.stringify({
        command,
        cwd: cwd || this.state.cwd || "/workspace",
        sandbox: "local" // or docker, e2b
      })
    });

    return result.json();
  }
}

5. File System via R2

export class FileEnabledAgent extends Agent {
  @callable()
  async readFile(path: string) {
    const object = await this.env.AGENT_BUCKET.get(path);
    if (!object) throw new Error(`File not found: ${path}`);
    return await object.text();
  }

  @callable()
  async writeFile(path: string, content: string) {
    await this.env.AGENT_BUCKET.put(path, content);
    return { success: true, path };
  }

  @callable()
  async listFiles(prefix: string) {
    const objects = await this.env.AGENT_BUCKET.list({ prefix });
    return objects.objects.map(o => o.key);
  }
}

6. SQLite via D1

export class DBEnabledAgent extends Agent {
  @callable()
  async query(sql: string, params?: any[]) {
    const stmt = await this.env.DB.prepare(sql);
    return params ? stmt.bind(...params).all() : stmt.all();
  }

  @callable()
  async initSchema() {
    await this.env.DB.exec(`
      CREATE TABLE IF NOT EXISTS agent_state (
        key TEXT PRIMARY KEY,
        value TEXT,
        updated_at INTEGER
      );
    `);
  }
}

Tools Reference

Note: The tool names below are the Cloudflare agent's local abstractions, not direct CK MCP dispatch tool names. The agent maps these to CK MCP calls internally (e.g., ck_budget_check wraps ck_budget, ck_validate maps directly). Do not call these names against the CK MCP server directly.

MCP Tools (serve to agents)

CK to Agent Tools (agent-local, not CK MCP dispatch)

Environment Variables

# CK Governance endpoint (Durable Object or external)
CK_GOVERNANCE=do://agent-governance

# CK Sandbox endpoint
CK_SANDBOX=do://agent-sandbox

# Agent bucket (R2)
AGENT_BUCKET=agent-workspace

# Agent database (D1)
DB=agent-db

Example: Complete Governed Agent

import { Agent, callable } from "agents";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

type Env = {
  CK_GOVERNANCE: DurableObjectNamespace;
  AGENT_BUCKET: R2Bucket;
  DB: D1Database;
  AI: Ai;
};

export class GovernedCFAgent extends Agent<Env, { cwd: string }> {
  initialState = { cwd: "/workspace" };

  async onStart() {
    await this.initDB();
  }

  async initDB() {
    await this.env.DB.exec(`
      CREATE TABLE IF NOT EXISTS logs (
        id INTEGER PRIMARY KEY,
        action TEXT,
        payload TEXT,
        timestamp INTEGER
      );
    `);
  }

  @callable()
  async executeCommand(cmd: string, args: string[]) {
    // 1. Validate
    const validation = await this.validateAction("execute", { cmd, args });
    if (validation.denied) {
      await this.log("validation_denied", { cmd, reason: validation.reason });
      return { error: validation.reason };
    }

    // 2. Execute
    const result = await this.runCommand(cmd, args);

    // 3. Audit
    await this.log("executed", { cmd, args, exitCode: result.exitCode });

    return result;
  }

  @callable()
  async readFile(path: string) {
    const fullPath = `${this.state.cwd}/${path}`;
    const obj = await this.env.AGENT_BUCKET.get(fullPath);
    return obj?.text() || null;
  }

  @callable()
  async writeFile(path: string, content: string) {
    const fullPath = `${this.state.cwd}/${path}`;
    await this.env.AGENT_BUCKET.put(fullPath, content);
    await this.log("file_written", { path: fullPath });
    return { success: true };
  }

  private async validateAction(action: string, payload: any) {
    const governanceObject = this.env.CK_GOVERNANCE.get(this.env.CK_GOVERNANCE.idFromName("default"));
    return await governanceObject.validate({ action, payload, context: this.state });
  }

  private async log(action: string, payload: any) {
    await this.env.DB.prepare(
      "INSERT INTO logs (action, payload, timestamp) VALUES (?, ?, ?)"
    ).bind(action, JSON.stringify(payload), Date.now()).run();
  }

  private async runCommand(cmd: string, args: string[]): Promise<{ output: string; exitCode: number }> {
    // Execute via CK sandbox or direct
    const fullCommand = [cmd, ...args].join(" ");
    return { output: `Executed: ${fullCommand}`, exitCode: 0 };
  }
}

Security Considerations

1. Shell commands - Always validate via CK policy gates before execution
2. File access - Restrict to workspace directory, validate paths
3. AI budget - Set per-task and daily limits
4. Audit logging - Log all governance decisions and actions
5. PII scanning - Use CK PIIDetector on prompts/responses

Deployment

# Deploy to Cloudflare Workers
wrangler deploy

# Bind required resources
# - D1 database for agent state
# - R2 bucket for file workspace
# - Durable Object for governance
# - Workers AI or external provider