@fiberplane/agents

A toolkit for introspecting and debugging agents built with Cloudflare's Agents SDK.

Overview

@fiberplane/agents provides debugging and introspection capabilities for agents built with Cloudflare's Agents SDK. It allows you to monitor agent state, track messages, and view instance information in real-time.

Installation

npm install @fiberplane/agents
# or
yarn add @fiberplane/agents
# or
pnpm add @fiberplane/agents

Usage

1. Wrap your worker's fetch entrypoint

Use the fiberplane wrapper for your worker's fetch entrypoint:

import { fiberplane } from "@fiberplane/agents";

export default {
  fetch: fiberplane(
    async (request: Request, env: Env, ctx: ExecutionContext) => {
      // Your existing worker logic...
      return await routeAgentRequest(request, env) || 
        new Response("Not found", { status: 404 });
    }
  ),
};

2. Use the withInstrumentation

Add the withInstrumentation mixin to any agent class you want to introspect:

import { withInstrumentation } from "@fiberplane/agents";
import { Agent } from "agents";

class SpecialAgent extends Agent<MyEnv, MyState> {
  // Your agent implementation...
}

const MySpecialAgent = withInstrumentation(SpecialAgent)

2b. Bonus step: gain visibility into your LLM calls

When you use Cloudflare's AI Gateway you can gain visibility into the most recent calls by adding an CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to your .dev.vars file. The API token only needs AI Gateway:Read permissions. See the Cloudflare documentation around Create API Token

3. Access the Agents playground in your browser by appending /fp to your worker's URL

Features

• State Introspection: Monitor the internal state of your agents
• Message Tracking: View incoming and outgoing messages between agents
• Instance Monitoring: Track each instance of your agents
• Database Inspection: View the state of underlying SQLite database used by the agent
• AI Gateway Inspection: Gain visibility into the calls that go through Cloudflare's AI Gateway

Current Status

This package is in early development and is considered a work in progress. APIs may change in future releases. Also, please do not use this package in production yet.

Publishing a New Version

This package uses the changeset workflow for versioning:

1. Run pnpm build:agents from the root of the monorepo
2. Run pnpm changeset from the root of the monorepo
3. Select major/minor/patch version increment
4. Add a summary of changes
5. Run pnpm changeset version when happy with the change description
6. Commit changelog changes
7. Run pnpm -F @fiberplane/agents publish

License

MIT/Apache-2.0