---
title: "Cloudflare Agents SDK"
description: "Link Cloudflare Agents SDK chats to Sentry Conversations with a chat session ID."
url: https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/agents-sdk/
---

# Cloudflare Agents SDK | Sentry for Cloudflare

When you build agents with the [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/), set a conversation ID so multi-turn AI activity groups correctly in [Conversations](https://docs.sentry.io/product/agents/conversations.md).

Use **your chat session ID** (for example a UUID or `conv_...` value your app creates when the user starts a chat). Do not use a user ID, room name, or the Durable Object instance name unless that name is already one chat session.

Workers AI does **not** set this for you. Set the ID on the isolation scope that runs your AI work — for chat agents, that is typically at the start of `onChatMessage`, before any model or tool calls.

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/agents-sdk.md#prerequisites)

* [Tracing enabled](https://docs.sentry.io/platforms/javascript/guides/cloudflare/tracing.md)
* Durable Objects instrumented with `instrumentDurableObjectWithSentry` (see [Durable Objects](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/durableobject.md))

## [Link conversations](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/agents-sdk.md#link-conversations)

Set the conversation ID before any AI calls in the chat handler:

```typescript
import * as Sentry from "@sentry/cloudflare";
import { AIChatAgent } from "@cloudflare/ai-chat";

class MyChatAgentBase extends AIChatAgent<Env> {
  async onChatMessage() {
    // Your chat session ID (not user id / "default")
    Sentry.setConversationId("conv_abc123");

    // … run your model and tools …
  }
}

export const MyChatAgent = Sentry.instrumentDurableObjectWithSentry(
  (env: Env) => ({
    dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
    tracesSampleRate: 1.0,
  }),
  MyChatAgentBase,
);
```

Define the conversation ID however your app tracks chats (client param, storage, etc.). Re-set it at the start of each handler that performs AI work so it applies on that isolation scope.

If you already name each agent instance as one chat session (for example `useAgent({ name: chatSessionId })`), you can pass that value:

```typescript
Sentry.setConversationId(this.name);
```

Only do this when the instance name is **one conversation**, not per-user or a shared singleton like `"default"`.

To clear the ID: `Sentry.setConversationId(null)`.

## [Users](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/agents-sdk.md#users)

Populate the Conversations **User** column with `Sentry.setUser` on every request or handler that performs AI calls, before those calls run. See [Tracking Conversations](https://docs.sentry.io/platforms/javascript/guides/cloudflare/agent-tracing.md#tracking-conversations).

## [Related](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/agents-sdk.md#related)

* [Workers AI](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/workers-ai.md)
* [Durable Objects](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/durableobject.md)
* [Tracking Conversations](https://docs.sentry.io/platforms/javascript/guides/cloudflare/agent-tracing.md#tracking-conversations)
* [Conversations](https://docs.sentry.io/product/agents/conversations.md) product docs