Cloudflare Agents

Setup

Install Braintrust alongside the agents package, then set your API keys. Requires agents v0.17.0 or later.

Install packages

pnpm add braintrust agents

npm install braintrust agents

Set environment variables

.env

BRAINTRUST_API_KEY=<your-braintrust-api-key>

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url>

Manual instrumentation

Manual instrumentation is the recommended approach for Cloudflare Workers. Call wrapCloudflareAgent() on the base Agent class at module scope so all subclasses inherit Braintrust tracing without any changes to your class definitions. Initialize the logger inside fetch with your env bindings, then pass logger.flush() to ctx.waitUntil() so buffered traces ship after the response returns.

cloudflare-agent-manual.ts

import { initLogger, wrapCloudflareAgent } from "braintrust";
import { Agent, routeAgentRequest } from "agents";

interface Env {
  BRAINTRUST_API_KEY: string;
}

// Wrap the base class so all subclasses are instrumented
wrapCloudflareAgent(Agent);

export class MyAgent extends Agent {
  async onRequest(request: Request) {
    return new Response("Hello from agent");
  }
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const logger = initLogger({
      projectName: "cloudflare-agents-example", // Replace with your project name
      apiKey: env.BRAINTRUST_API_KEY,
    });

    try {
      return (
        (await routeAgentRequest(request, env)) ||
        new Response("Not found", { status: 404 })
      );
    } finally {
      ctx.waitUntil(logger.flush());
    }
  },
};

wrapCloudflareAgent() returns the same class it receives after patching its prototype. Calling it on the base Agent class instruments all subclasses without modifying your class definitions.Deploying to Cloudflare Workers requires the nodejs_compat compatibility flag and storing BRAINTRUST_API_KEY as a Wrangler secret. See the Cloudflare setup guide for the full deployment configuration.

Auto-instrumentation

Auto-instrumentation patches the SDK at runtime without modifying your application code, but the --import hook only runs under Node (local development or tests), not in the Cloudflare Workers runtime. For a deployed Worker, use manual instrumentation above.

Initialize Braintrust and define your agent

import { initLogger } from "braintrust";
import { Agent, routeAgentRequest } from "agents";

initLogger({
  projectName: "cloudflare-agents-example", // Replace with your project name
  apiKey: process.env.BRAINTRUST_API_KEY,
});

export class MyAgent extends Agent {
  async onRequest(request) {
    return new Response("Hello from agent");
  }
}

export default {
  async fetch(request, env) {
    return (
      (await routeAgentRequest(request, env)) ||
      new Response("Not found", { status: 404 })
    );
  },
};

Run with the import hook

node --import braintrust/hook.mjs cloudflare-agent-auto.js

The --import hook only patches the SDK when your code runs under Node, such as local development or tests. It does not run in the Cloudflare Workers runtime (workerd), so a Worker deployed with Wrangler stays uninstrumented. To trace a deployed Worker, use manual instrumentation with wrapCloudflareAgent().

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

What Braintrust traces

Braintrust captures:

Tool spans for each runAgentTool call, named after the agent class (for example, MyAgent).
Tool input passed to the agent tool call.
Tool output returned by the agent, or an error if the call fails.

AI providers

SDKs

Developer tools

Setup

Manual instrumentation

Auto-instrumentation

What Braintrust traces

Resources

​Setup

​Manual instrumentation

​Auto-instrumentation

​What Braintrust traces

​Resources

Setup

Manual instrumentation

Auto-instrumentation

What Braintrust traces

Resources