The Edge-Native Architect: Deploying Stateful AI Agents on Cloudflare

cloudflare/agents

Traditionally, we’ve built APIs that wait for a request and send a response. With Cloudflare Agents (often paired with Workflows), we're moving toward autonomous, stateful entities that can think, plan, and execute tasks over long periods.

Here’s a breakdown of why this matters and how you can get started.

From a dev perspective, the "magic" here isn't just the AI—it's the infrastructure.

State Management
Agents can maintain state across multiple turns of a conversation or steps in a process without you having to manually manage a database for every single interaction.

Long-Running Tasks
By using Workflows, your agent isn't capped by the typical 30-second timeout of a standard Worker. It can "sleep" while waiting for an API response or a human approval.

Edge Compute
Everything runs on Cloudflare's edge, meaning your AI logic is physically close to your users, reducing latency significantly.

Tool Use (Function Calling)
You can give your agents "tools" (like fetching weather data, querying a DB, or sending an email) which they can decide to use autonomously.

To use Cloudflare Agents, you'll typically work within the Wrangler CLI environment and the cloudflare/agents library.

You’ll need a Cloudflare account and the latest version of Wrangler

npm install -g wrangler

An agent usually consists of

The Brain
A Large Language Model (like Llama 3 running on Workers AI).

The Memory
A way to store past interactions.

The Tools
Specialized functions the agent can call.

Here’s a conceptual example of how you might define an agent that uses a tool to "look up" information.

import { Agent } from "@cloudflare/agents";

export default {
  async fetch(request, env) {
    // 1. Initialize the Agent
    const agent = new Agent({
      model: "@cf/meta/llama-3.1-8b-instruct",
      instructions: "You are a helpful research assistant. Use tools when you don't know something.",
    });

    // 2. Define a Tool
    agent.addTool("getWeather", {
      description: "Get the current weather for a location",
      parameters: { city: "string" },
      execute: async ({ city }) => {
        // Imagine a fetch to a weather API here
        return `The weather in ${city} is 22°C and sunny.`;
      }
    });

    // 3. Run the Agent with a user prompt
    const response = await agent.say("What is the weather in Tokyo like today?");
    
    return new Response(response.text);
  },
};

This is where it gets powerful. If your agent needs to perform a task that takes 10 minutes (like generating a complex report), you wrap it in a Cloudflare Workflow.

Trigger
A user submits a request.

Workflow Step
The Agent plans the report.

Workflow Step
The Agent calls external APIs (retrying automatically if they fail).

Completion
The Agent emails the user the result.

Observability
Use wrangler tail to watch your agent's thought process in real-time.

Cost Control
Since agents can "loop" (calling the LLM multiple times), always implement a maximum iteration cap to avoid unexpected compute bills.

Security
Never give an agent a tool that has "delete" permissions on your primary database unless you have a human-in-the-loop verification step!