Observability

Agent instances use the observability property to emit various internal events that can be used for logging and monitoring.

Default behavior

The default behavior is to console.log() the event value:

{
  "displayMessage": "State updated",
  "id": "EnOzrS_tEo_8dHy5oyl8q",
  "payload": {},
  "timestamp": 1758005142787,
  "type": "state:update"
}

Custom observability

You can configure observability by overriding the property with an implementation of the Observability interface. This interface has a single emit() method that takes an ObservabilityEvent.

JavaScript

JavaScript

import { Agent } from "agents";
import {} from "agents/observability";

const observability = {
  emit(event) {
    if (event.type === "connect") {
      console.log(event.timestamp, event.payload.connectionId);
    }
  },
};

class MyAgent extends Agent {
  observability = observability;
}

TypeScript

TypeScript

import { Agent } from "agents";
import { type Observability } from "agents/observability";

const observability: Observability = {
  emit(event) {
    if (event.type === "connect") {
      console.log(event.timestamp, event.payload.connectionId);
    }
  },
};

class MyAgent extends Agent {
  override observability = observability;
}

Disabling observability

Alternatively, you can set the property to undefined to ignore all events:

JavaScript

JavaScript

import { Agent } from "agents";

class MyAgent extends Agent {
  observability = undefined;
}

TypeScript

TypeScript

import { Agent } from "agents";

class MyAgent extends Agent {
  override observability = undefined;
}

Event types

The observability system emits events for various agent activities:

Event Type	Description
connect	WebSocket connection established
disconnect	WebSocket connection closed
state:update	Agent state was updated
message	Message received from client
error	Error occurred during processing
schedule:execute	Scheduled task executed
queue:process	Queue task processed

ObservabilityEvent structure

Each event has the following structure:

TypeScript

type ObservabilityEvent = {
  id: string; // Unique event identifier
  type: string; // Event type (e.g., "connect", "state:update")
  displayMessage: string; // Human-readable description
  timestamp: number; // Unix timestamp in milliseconds
  payload: Record<string, unknown>; // Event-specific data
};

Integration with external services

You can integrate observability with external logging and monitoring services:

JavaScript

JavaScript

import { Agent } from "agents";
import {} from "agents/observability";

const observability = {
  emit(event) {
    // Send to external logging service
    fetch("https://logging.example.com/ingest", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        service: "my-agent",
        level: event.type === "error" ? "error" : "info",
        message: event.displayMessage,
        metadata: {
          eventId: event.id,
          eventType: event.type,
          timestamp: event.timestamp,
          ...event.payload,
        },
      }),
    }).catch(console.error);
  },
};

class MyAgent extends Agent {
  observability = observability;
}

TypeScript

TypeScript

import { Agent } from "agents";
import {
  type Observability,
  type ObservabilityEvent,
} from "agents/observability";

const observability: Observability = {
  emit(event: ObservabilityEvent) {
    // Send to external logging service
    fetch("https://logging.example.com/ingest", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        service: "my-agent",
        level: event.type === "error" ? "error" : "info",
        message: event.displayMessage,
        metadata: {
          eventId: event.id,
          eventType: event.type,
          timestamp: event.timestamp,
          ...event.payload,
        },
      }),
    }).catch(console.error);
  },
};

class MyAgent extends Agent {
  override observability = observability;
}

Filtering events

You can filter which events to process:

JavaScript

JavaScript

const observability = {
  emit(event) {
    // Only log errors and state updates
    if (event.type === "error" || event.type === "state:update") {
      console.log(JSON.stringify(event));
    }
  },
};

TypeScript

TypeScript

const observability: Observability = {
  emit(event) {
    // Only log errors and state updates
    if (event.type === "error" || event.type === "state:update") {
      console.log(JSON.stringify(event));
    }
  },
};

Next steps

Configuration wrangler.jsonc setup and deployment.

Dashboard setup View logs in the Cloudflare dashboard.

Agents API Complete API reference for the Agents SDK.