Cloudflare Agents: Peeking Inside the AI Agent Black Box

If you hire a personal assistant to plan a trip, they don’t just instantly teleport you to your destination. They search for flights, check hotel availability, compare prices, write down draft itineraries, and maybe ask a coworker for help with local recommendations.

If they fail and say “Sorry, no rooms available,” you’d want to know why. Did they search the wrong dates? Did they check the wrong hotels? Or did they spend too much time on a loop checking the same flight?

Building AI agents is exactly like that. When an agent fails, it might still return a successful HTTP 200 status code. But under the hood, it might have chosen the wrong tool, passed stale data to a subagent, or gotten stuck in a costly infinite loop.

Until now, looking into an agent’s “mind” was incredibly difficult. Today, Cloudflare announced Cloudflare Agents, starting with Agent Tracing to solve this exact problem.

The AI Agent Black Box Problem#

Traditional application monitoring (APM) tools are great for normal web apps. They tell you when a database query is slow or when an API call fails. But AI agents are different. They don’t just run linear code; they make autonomous decisions in a loop:

graph TD
    User([User Request]) --> Agent[AI Agent Worker]
    subgraph "Cloudflare Agents Dashboard"
        Agent --> |"1. Thought (Reasoning)"| Thought["Thought / Messages Tab"]
        Agent --> |"2. Tool Call (Action)"| Tool["Tool Execution / Traces Tab"]
        Tool --> |"Reads State"| D1[(D1 Database)]
        Tool --> |"Fetches Data"| Fetch[External API]
        Agent --> |"3. Subagent Handoff"| Subagent[Subagent Worker]
    end
    Agent --> Response([Final Response])

If an agent makes a mistake, looking at raw database query spans won’t tell you why it decided to run that query in the first place. You need to see the agent’s thought process: the model calls, the tool arguments, the prompt history, and how much it actually cost in tokens.

Introducing Cloudflare Agents#

Cloudflare is already a powerhouse for running agents: it has the serverless runtime (Workers), stateful storage (Durable Objects, KV, D1), and LLM execution (Workers AI).

Now, Cloudflare Agents ties them all together into a unified observability platform. It introduces a dedicated Agents dashboard in Cloudflare with two powerful views:

1. The Messages Tab (The Conversation Replay)#

This view acts as a “flight recorder” for your agent’s turns. It visualizes:

• System instructions and user prompts.
• The LLM’s raw thoughts and reasoning process.
• The specific tools called, along with their parameters and outputs.
• Handoffs/delegations to subagents.

[!NOTE] Privacy is built-in. If you are handling sensitive data, frameworks like Think, Flue, and AI SDK let you toggle off payload storage using storeMessages and storeTools options.

2. The Traces Tab (The Execution Waterfall)#

This view shows a timeline of the request, combining high-level agent logic with underlying infrastructure performance. You can see:

• How long the LLM took to think.
• Which D1 database reads or KV lookups were triggered by which tools.
• Exactly how subagent calls nest under the parent agent.

How to Enable Agent Tracing#

Getting started is straightforward.

Step 1: Enable Tracing in wrangler.jsonc#

Add the observability configuration to your Worker’s config file:

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

Step 2: Instrument Your Code#

Depending on the framework you use, setup is minimal:

A. Think and Flue Frameworks#

These runtimes natively support agent telemetry. They will automatically emit agent, conversation, turn, model, and tool spans through their integrations.

B. Vercel AI SDK#

If you are using the Vercel AI SDK, wrap it with Cloudflare’s helper:

import { wrapAISDK } from '@cloudflare/ai-sdk-opentelemetry'; // [!code focus]
import { generateText } from 'ai';

// Wrap your SDK initialization
const ai = wrapAISDK(yourModelProvider); // [!code focus]

C. Custom Harness#

If you use a custom setup, you can manually trigger spans following OpenTelemetry Generative AI semantic conventions.

[!TIP] Cloudflare is working on native OpenTelemetry support inside Workers. Once shipped, any framework using standard OTel GenAI semantic conventions will work out-of-the-box without Cloudflare-specific adapters.

Pricing & Beta Timeline#

• During Beta: Agent tracing is completely free to use.
• From October 1, 2026: Pricing will be integrated directly into Workers Observability:
  • Workers Free: 200,000 trace events/day (3 days retention).
  • Workers Paid: 20 million trace events/month included, then $0.60 per million events (7 days retention).

Agent tracing is just the beginning. The long-term vision is a feedback loop where you can feed trace data back into your development lifecycle to build self-improving, autonomous agents.

References#

• Agents on Cloudflare - Cloudflare Blog ↗