> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Agents

> Trace Cloudflare Agents tool calls in Braintrust to debug agent behavior, inspect tool inputs and outputs, and monitor errors

[Cloudflare Agents](https://developers.cloudflare.com/agents/) are Durable Object–backed workers built with the `agents` npm package. Braintrust traces every `runAgentTool` call, capturing the agent class name, tool inputs, tool outputs, and errors.

> [!NOTE]
>
> For Cloudflare Workers deployments, use [manual instrumentation](#manual-instrumentation-typescript) with `wrapCloudflareAgent()`. The `--import` auto-instrumentation hook only runs under Node, not in the Cloudflare Workers runtime (`workerd`). See the [Cloudflare setup guide](https://docs.braintrust.dev/sdks/typescript/install-and-instrument.md#cloudflare) for enabling `nodejs_compat` and flushing traces with `ctx.waitUntil()`.

**TypeScript**

## Setup

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

**1. Install packages**

```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pnpm add braintrust agents
```

```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
npm install braintrust agents
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```typescript title="cloudflare-agent-manual.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://docs.braintrust.dev/sdks/typescript/install-and-instrument.md#cloudflare) 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.

**1. Initialize Braintrust and define your agent**

```javascript title="cloudflare-agent-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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 })
    );
  },
};
```

**2. Run with the import hook**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
node --import braintrust/hook.mjs cloudflare-agent-auto.js
```

> [!WARNING]
>
> 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](#manual-instrumentation-typescript) 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 and run the compiled file with the import hook, or [run TypeScript directly](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) with a TypeScript loader.

> [!NOTE]
>
> If you're using a bundler, see [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) 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.

## Resources

* [Cloudflare Agents documentation](https://developers.cloudflare.com/agents/)
* [`agents` on npm](https://www.npmjs.com/package/agents)
* [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.