Sentry for Pi Durable (Cloudflare)

Learn how to send Pi Durable agent runs, model requests, tool calls, and errors to Sentry from Cloudflare Durable Objects.

Pi Durable is Earendil's durable agent harness, built on the same foundations as the Pi coding agent. This guide sets up the Sentry SDK in a Worker that runs Pi Durable in a Durable Object, for example through the Agents SDK PiHarness, so agent runs, model requests, tool calls, and errors flow into Sentry Agent Tracing.

Before you begin, you need:

  • A Sentry account and project. The project's DSN tells the SDK where to send data.
  • A Worker using @earendil-works/pi-durable version 1.0.0 or later, built with Vite and @cloudflare/vite-plugin. To host Pi Durable with PiHarness, you need the Agents SDK (agents) version 0.26.0 or later.
  • @sentry/cloudflare version 11.6.0 or later.

Choose the features you want to configure, and this guide will show you how:

Install the Sentry Cloudflare SDK:

Copied
npm install @sentry/cloudflare@^11.6.0

Add the Sentry Vite plugin to your Vite config:

vite.config.mts
Copied
import { cloudflare } from "@cloudflare/vite-plugin";
import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [cloudflare(), sentryCloudflareVitePlugin()],
});

The plugin instruments Harness.open() at build time, so every Harness your Worker opens is traced. It also wraps your Worker entry, your Durable Object classes, and your Agents SDK classes with Sentry, so Sentry.init() runs in the Durable Object that hosts Pi Durable without any changes to your code.

Create an instrument.server.ts file next to your Worker entry (the file named in Wrangler's main). The plugin picks it up by convention and uses its default export as the Sentry options:

src/instrument.server.ts
Copied
import { defineCloudflareOptions } from "@sentry/cloudflare";

export default defineCloudflareOptions((env: Env) => ({
  dsn: "___PUBLIC_DSN___",
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of spans for tracing.
  // We recommend adjusting this value in production.
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
}));

Enable Node.js compatibility in your Wrangler config so the SDK can run on Workers:

wrangler.toml
Copied
main = "src/index.ts"
compatibility_flags = ["nodejs_compat"]

Your Pi Durable code doesn't change. For example, an Agents SDK class that hosts Pi Durable with PiHarness is traced as is:

src/assistant.ts
Copied
import { createModels } from "@earendil-works/pi-ai/models";
import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { Agent } from "agents";
import { PiHarness } from "agents/harness/pi";

export class Assistant extends Agent<Env> {
  registry = createRegistry();

  harness = new PiHarness({
    harness: ({ storage, context }) => {
      // pi-ai reads provider keys from `process.env` by default, so hand over the Worker's secret.
      const models = createModels({
        authContext: {
          env: async (name) =>
            name === "OPENAI_API_KEY"
              ? this.env.OPENAI_API_KEY
              : undefined,
          fileExists: async () => false,
        },
      });
      models.setProvider(openaiProvider());
      return Harness.open(
        storage,
        { models, registry: this.registry },
        context,
      );
    },
    defaults: { model: { provider: "openai", id: "gpt-6.1-sol" } },
  });

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.lifecycle.use(this.harness);
  }
}

With this setup, Sentry captures errors thrown by your tools and extensions, and AI spans for every run (agent runs, model requests, tool calls, token usage, and latency). Manual spans you start inside a tool nest under that tool's span. Prompts and model outputs are recorded on your AI spans by default.

To review what's captured and turn recording of prompts and responses off, see Control the Data You Send to Sentry below.

By default, the SDK sends the inputs and outputs of your model requests and tool calls, such as prompts, responses, and tool arguments. This will give you rich debugging context. Review the data your agent handles before you deploy to production.

The SDK always filters sensitive values whose keys match a built-in denylist, such as auth or password, and sends [Filtered] instead.

To send less data, turn off the categories you don't need in the dataCollection option:

src/instrument.server.ts
Copied
import { defineCloudflareOptions } from "@sentry/cloudflare";

export default defineCloudflareOptions((env: Env) => ({
  dsn: "___PUBLIC_DSN___",
dataCollection: { genAI: { inputs: false, outputs: false }, },
}));

For the full list of categories and their defaults, see the dataCollection options.

Sentry groups the runs of a Pi Durable conversation into a single Conversation automatically — there's no Sentry-specific setup. The SDK sets gen_ai.conversation.id on the agent, model, and tool spans of every run to <harness id>:<conversation id>.

Pi Durable numbers conversations per storage, starting from 1, so the SDK prefixes a random id for each opened Harness to keep root conversations from different storages apart. This id changes when the Harness reopens, for example after a process restart or after a Durable Object restarts. Runs from before and after a restart then show up as separate conversations in Sentry.

A subagent runs in a conversation of its own. Its first run nests under the tool call that created it, so the subagent shows up inside the parent's trace.

Submit a message to one of your conversations, ideally one that calls a tool. Then open Explore → Agents in Sentry. Select the conversation to open its detail. The timeline shows the agent run, model requests, tool calls, token usage, latency, and any errors your tools threw.

If no data appears, confirm that:

  • The dsn belongs to the Sentry project you're viewing.
  • tracesSampleRate is greater than 0.
  • Your app completed at least one run after you added the setup.

  • No AI spans at all. Confirm sentryCloudflareVitePlugin() is in your Vite config and that you build and run the Worker through Vite. A Worker you deploy with wrangler directly, without the plugin, doesn't get the build-time instrumentation of Harness.open().
  • Every restart of the Durable Object starts a new conversation in Sentry. This is expected for now. See Link Conversations.

What gets captured?

Sentry's Pi Durable integration maps Pi Durable's runtime operations to Sentry operations for the Agents dashboards:

Pi Durable OperationSentry Operation
Run of a conversationgen_ai.invoke_agent
Model request (pi.generation)gen_ai.chat
Tool call (pi.tool)gen_ai.execute_tool

Spans are tagged with sentry.origin: auto.ai.pi_durable and carry the model, token usage, and finish reasons for each request. Each run starts a trace of its own, separate from the request that submitted it, so concurrent runs never end up in each other's traces.

Crash recovery. When the process dies during a run, the spans that were open in that process are lost. Once a new process resumes the run, its spans arrive in a new trace that starts with the resumed step, such as the rerun of a tool call.

Tool results. A tool span records the result the model receives, including output streamed with api.output() and results an afterTool hook rewrote.

Errors. A tool that throws is captured as an error, and its span is marked failed. Pi Durable hands the throw back to the model as a tool result, so your app never sees it.

The built-in coding tools (bash, read, edit, write) are the exception: they throw to report expected failures, such as a command that exits with a non-zero code, so their span is marked failed but no error is captured.

Failures Pi Durable only passes to onReport, such as a hook or system prompt section that throws, are captured too. A failed model request isn't captured as an error; its chat span carries the error status.

Provider SDKs. Pi Durable sends model requests through @earendil-works/pi-ai, which calls the openai, @anthropic-ai/sdk, and @google/genai clients, or the Workers AI binding. From the first run on, the SDK turns off its OpenAI, Anthropic, Google Gen AI, and Workers AI integrations for the whole process, so these requests aren't counted twice. Calls your app makes with those clients outside Pi Durable aren't traced either. Amazon Bedrock requests are still reported a second time by the AWS integration.

Not captured yet. Tool calls that Pi Durable answers without running the tool, custom tasks you define with defineTask, agent names (Pi Durable has none), a link between a run and the request that submitted it, and a marker for compaction requests.

  • @sentry/cloudflare: >=11.6.0
  • @earendil-works/pi-durable: >=1.0.0 <2.0.0
  • agents: >=0.26.0, when you host Pi Durable with PiHarness
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").