Documentation / @agentick/devtools

@agentick/devtools

Real-time debugging and observability for Agentick applications. Provides a server that captures execution events and a browser UI for inspection.

Installation

pnpm add @agentick/devtools

Quick Start

import { startDevToolsServer } from "@agentick/devtools";
import { createApp } from "@agentick/core";

// Start DevTools server
const devtools = startDevToolsServer({ port: 3001 });

// Enable DevTools in your app
const app = createApp(MyApp, {
  model: myModel,
  devTools: true, // Enables event emission
});

// Navigate to http://localhost:3001 to view DevTools UI

API

startDevToolsServer(config?)

Convenience function to create and start a DevTools server:

const devtools = startDevToolsServer({
  port: 3001, // Default: 3001
  host: "127.0.0.1", // Default: 127.0.0.1
  debug: false, // Enable debug logging
  heartbeatInterval: 30000, // SSE heartbeat interval (ms)
});

// Get server URL
console.log(devtools.getUrl()); // "http://127.0.0.1:3001"

// Stop when done
devtools.stop();

DevToolsServer Class

For more control, use the class directly:

import { DevToolsServer } from "@agentick/devtools";

const server = new DevToolsServer({ port: 3001 });
await server.start();

// Later...
await server.stop();

HTTP Endpoints

Endpoint	Method	Description
/	GET	DevTools UI
/events	GET	SSE stream of execution events
/api/history	GET	All buffered events as JSON
/api/clear	GET	Clear event history

Event Types

The DevTools server captures these events from @agentick/core:

Event	Description
execution_start	Execution began
execution_end	Execution completed
tick_start	Model API call started
tick_end	Model API call completed
compiled	JSX compiled to messages/tools
model_request	Request sent to provider
provider_response	Raw provider response
model_response	Normalized response
tool_call	Tool invocation
tool_result	Tool execution result
fiber_snapshot	Component tree state
content_delta	Streaming text chunk

UI Features

Execution List

View all executions with status, duration, and token usage.

Tick Navigator

Scrub through individual ticks within an execution to see:

• Compiled context (system, messages, tools)
• Provider input/output
• Model response
• Tool calls

Fiber Tree

Inspect the component hierarchy with:

• Props for each component
• Hook states
• Token estimates

Context Info

Monitor context utilization:

• Input/output tokens per tick
• Context window usage percentage
• Cumulative usage across ticks

Integration

With Express

import express from "express";
import { createExpressAdapter } from "@agentick/express";
import { startDevToolsServer } from "@agentick/devtools";

const app = express();

// Start DevTools on separate port
startDevToolsServer({ port: 3001 });

// Your Agentick app with DevTools enabled
const agentick = createExpressAdapter(MyApp, {
  model: myModel,
  devTools: true,
});

app.use("/api", agentick);
app.listen(3000);

With Gateway

import { createGateway } from "@agentick/gateway";
import { startDevToolsServer } from "@agentick/devtools";

startDevToolsServer({ port: 3001 });

const gateway = createGateway({
  agents: { assistant: myApp },
  devTools: true,
});

Architecture

┌─────────────────────────┐
│  Agentick App/Session  │
│   (devTools: true)      │
└────────────┬────────────┘
             │ devToolsEmitter.emit()
             ↓
┌─────────────────────────┐
│   DevToolsServer        │
│   - Buffers events      │
│   - Broadcasts via SSE  │
│   - Serves UI           │
└────────────┬────────────┘
             │ HTTP /events (SSE)
             ↓
┌─────────────────────────┐
│   Browser UI (React)    │
│   - Real-time updates   │
│   - Execution inspection│
│   - Fiber tree viewer   │
└─────────────────────────┘

Configuration

Environment Variables

TENTICKLE_DEVTOOLS_PORT=3001
TENTICKLE_DEVTOOLS_HOST=127.0.0.1

Programmatic

const devtools = startDevToolsServer({
  port: process.env.DEVTOOLS_PORT || 3001,
  host: process.env.DEVTOOLS_HOST || "127.0.0.1",
  debug: process.env.NODE_ENV === "development",
});

License

MIT

Classes

• DevToolsServer

Interfaces

• DevToolsServerConfig

Functions

• startDevToolsServer