---
title: "Cloudflare Agents"
description: "Log native Cloudflare Agents lifecycle, RPC, tool, scheduling, workflow, MCP, recovery, and error events on Workers."
canonical_url: "https://www.blyp.dev/docs/ai/cloudflare"
markdown_url: "https://www.blyp.dev/docs/ai/cloudflare.md"
last_updated: "1970-01-01"
x_farming_labs_generated_preamble: true
---

# Cloudflare Agents
URL: /docs/ai/cloudflare
LLM index: /llms.txt
Description: Log native Cloudflare Agents lifecycle, RPC, tool, scheduling, workflow, MCP, recovery, and error events on Workers.
Related: /docs/ai/tracing, /docs/integrations/workers, /docs/ai/privacy-and-capture

# Cloudflare Agents

Use `@blyp/core/ai/cloudflare` to turn native Cloudflare Agents observability events into structured `ai_agent_event` records. Added in `@blyp/core@0.1.36`, the connector runs on Workers and implements the SDK's observability interface.

Each selected event produces its own record. The connector covers lifecycle, RPC, tools, schedules, workflows, MCP activity, chat recovery, and errors. It does not aggregate agent turns, capture model transcripts or token usage, or instrument direct `env.AI.run()` calls.

## Install

The connector targets Agents `~0.30.0`:

```bash
bun add @blyp/core@0.1.36 agents@~0.30.0
```

If your application does not already supply the pinned SDK's required Zod and MCP peers, add them:

```bash
bun add zod@^4 @modelcontextprotocol/client@2.3.1 @modelcontextprotocol/server@2.3.1 @modelcontextprotocol/sdk@1.32.1
```

Install any additional SDK peers your application's features require. Keep your normal Durable Object bindings, migrations, and Wrangler `nodejs_compat` configuration. Blyp requires no additional binding or storage.

## Quick start

Set the agent's `observability` property:

```ts
import { Agent } from "agents";
import { blypObservability } from "@blyp/core/ai/cloudflare";

export class SupportAgent extends Agent {
  override observability = blypObservability({
    metadata: { service: "support" },
  });
}
```

Run your agent through an operation that emits a native event, such as updating state or creating a schedule. Inspect Workers console output for a record with `type: "ai_agent_event"`, `ai.sdk: "cloudflare-agents-sdk"`, and the corresponding `ai.eventType`.

The default writer uses `console.info`, `console.warn`, or `console.error`. It does not load the Node logger, read project configuration, or use file or SQLite storage. Configure redaction on this adapter; `initWorkersLogger()` does not configure its default writer.

## Record fields

Each record has a unique group ID and an `ai` object:

| Field | Value |
| --- | --- |
| `sdk` | `"cloudflare-agents-sdk"` |
| `provider` | `"cloudflare"` |
| `operation` | `"cloudflare.agent.event"`, or your configured label |
| `eventType` | Original native event type, such as `rpc` or `tool:result` |
| `timestamp` | Source event timestamp as an ISO string; invalid timestamps use the current time |
| `agentName` / `instanceName` | Native agent class and instance names, when available |
| `attributes` | Allowlisted scalar technical IDs, names, counters, timings, flags, and statuses |
| `metadata` | Your sanitized custom metadata, when present |
| `payload` | Sanitized native payload, only with `capture.payload: true` |
| `hasError` | `true` for error-severity events |
| `truncated` | `true` when a byte limit omits optional data |

Detailed payloads, unknown attributes, error text, email payload addresses and subjects, and authorization URLs are omitted by default. Technical attribute values and custom metadata can still identify your application resources; choose their contents accordingly.

### Severity

| Native event condition | Record level |
| --- | --- |
| Type ends in `error`, `failed`, or `exhausted`; truthy payload `error`; or payload status is `error` or `failed` | `error` |
| Type ends in `retry`, `warning`, `stalled`, `interrupted`, `deadline`, `degraded`, or `conflict` | `warn` |
| Other events, including cancellations and approval rejections | `info` |

Error conditions take precedence over warning endings.

## Options

```ts
import {
  blypObservability,
  type BlypCloudflareAgentsLogger,
  type BlypCloudflareAgentsOptions,
} from "@blyp/core/ai/cloudflare";
```

| Option | Behavior |
| --- | --- |
| `logger` | Compatible structured logger; defaults to Workers console output |
| `operation` | Custom operation label |
| `metadata` | Custom fields included under `ai.metadata` |
| `events` | Selected native event types; omitted means all, while `false` or `[]` disables Blyp records |
| `capture.payload` | Opt into detailed native payload capture; defaults to off |
| `exclude.payloadPaths` | Dot paths relative to the native payload; also removes matching safe attributes |
| `exclude.metadataPaths` | Dot paths relative to custom metadata |
| `exclude.toolNames` | Skip Blyp records for matching payload tool names |
| `redact` | Adapter-specific Blyp redaction settings |
| `limits.maxContentBytes` | Separate serialized UTF-8 byte budget for each attributes, payload, and metadata value; defaults to 16,384 |
| `forward` | Defaults to Cloudflare's `genericObservability`; use `false` to disable or an observer to replace it |

## Capture, exclusions, and redaction

Enable detailed payload capture only when the native events contain application content you intend to store:

```ts
import { blypObservability } from "@blyp/core/ai/cloudflare";

const observability = blypObservability({
  operation: "support.events",
  events: ["rpc", "rpc:error", "tool:result", "schedule:error"],
  metadata: { team: "support", internal: "omit" },
  capture: { payload: true },
  exclude: {
    payloadPaths: ["private", "result.internal"],
    metadataPaths: ["internal"],
    toolNames: ["private_lookup"],
  },
  redact: {
    keys: ["customerEmail"],
    paths: ["ai.payload.result.email"],
  },
  limits: { maxContentBytes: 16_384 },
});
```

Exclusion paths are relative to their payload or metadata object. `redact.paths` addresses the complete record, such as `ai.payload.result.email`.

Recognized credential fields and MCP authorization URLs are removed even when capture is enabled or configurable redaction is disabled. URL usernames, passwords, query strings, and fragments are stripped. The connector reads own data fields and ignores accessors, so capturing content does not invoke application getters.

Exclusions, redaction, and limits apply before data reaches a custom logger. If an optional attributes, payload, or metadata value exceeds its byte budget, that entire value is omitted and `ai.truncated` is set. Finite limits are floored and clamped to zero; zero omits optional data, and invalid limits fall back to 16,384 bytes.

## Use a Workers request logger

Pass a logger implementing `BlypCloudflareAgentsLogger`. Only `createStructuredLog` is required. For example, inside a request handler with an existing `Request`:

```ts
import { createWorkersLogger } from "@blyp/core/workers";
import { blypObservability } from "@blyp/core/ai/cloudflare";

const log = createWorkersLogger(request);
const requestObserver = blypObservability({ logger: log });
```

This creates an observer using that logger; attach it where your application owns the relevant event scope. A long-lived agent can also emit background events outside an HTTP request. Use the default class-level observer for those events rather than assuming they belong to a particular request.

## Native forwarding and delivery

The original native event is forwarded to Cloudflare's `genericObservability` by default, preserving diagnostics-channel and Tail Worker behavior. No global subscription is installed.

Blyp filters, exclusions, capture controls, redaction, and byte limits affect Blyp records only. Native diagnostics receive the original event, including when `events: false` disables Blyp output. Use `forward: false` to disable that forwarding path, or supply another observability implementation.

Emission is synchronous and best effort. Forwarding and logger failures are isolated and produce at most one generic warning per adapter instance. Rejected promises from observers or custom logger emission are caught, but the adapter does not extend the Worker invocation's lifetime to await them.

## Troubleshooting

- **No Blyp records:** check the agent's `observability` property, event selection, excluded tool names, and Workers console visibility.
- **Payload or error text is missing:** detailed capture is off by default. Opt into `capture.payload` if appropriate, then check exclusions, redaction, and byte limits.
- **Native diagnostics still show an excluded event:** filters apply to Blyp records. Configure `forward` separately.
- **Workers logger settings do not affect the output:** pass the intended logger explicitly or configure the default adapter's `redact` option.
- **No token usage or turn summary appears:** this connector records native events. Model tracing and turn aggregation belong to other adapters with separate runtime requirements.

Read the [announcement](/docs/changelog/2026-10-23) or explore the [connector implementation](https://github.com/Blyphq/blyp/tree/main/src/ai/cloudflare).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).