ClevAgent Node.js/TypeScript SDK

Runtime monitoring for AI agents. Heartbeat watchdog, loop detection, cost tracking, auto-restart — in 2 lines of code.

Installation

npm install clevagent

Quick Start

import clevagent from "clevagent";

// Initialize at agent startup — starts background heartbeats
clevagent.init({
  apiKey: "cv_your_api_key",  // from ClevAgent dashboard
  agent: "my-agent",          // unique name in your project
});

// Your agent runs normally...
// Heartbeats are sent automatically every 60 seconds.
// If the process crashes or hangs, alerts fire automatically.

API

clevagent.init(options)

Initialize monitoring. Call once at startup.

clevagent.init({
  apiKey: "cv_xxx",           // required
  agent: "my-agent",          // required
  interval: 60,               // heartbeat interval in seconds (default: 60)
  endpoint: "https://clevagent.io",  // override for self-hosted
  onLoop: "stop",             // "stop" | "alert_only" | () => void  (default: "stop")
  onCostExceeded: "alert_only",      // "stop" | "alert_only" | () => void  (default: "alert_only")
});

clevagent.ping(options?)

Send a manual heartbeat with status/metrics.

clevagent.ping({
  status: "ok",              // "ok" | "warning" | "error"
  message: "Processed 100 items",
  tokensUsed: 1500,
  costUsd: 0.023,
  iterationCount: 42,
});

clevagent.logPrompt(text)

Record a prompt for semantic loop detection. Hashes the text (SHA-256, 16 hex chars) and stores it in a rolling window of 5. The server detects 3/4+ identical hashes as a suspected stuck loop.

const userMsg = "Summarize the Q3 earnings report";
clevagent.logPrompt(userMsg);
const response = await openai.chat.completions.create({
  messages: [{ role: "user", content: userMsg }],
});

clevagent.logToolCall(name, argsSummary?)

Record a tool call for semantic drift analysis (Pro+ feature).

The last 20 tool calls are included in each heartbeat. The ClevAgent semantic detector compares them against the agent's task_description and fires an intent_drift alert if the agent's behavior diverges from its stated goal.

// Record manually:
clevagent.logToolCall("db_query", "SELECT * FROM orders WHERE status='pending'");
clevagent.logToolCall("send_email", "[email protected] subject=Report");

clevagent.logCost(tokens, costUsd)

Manually record cost data (use when you need precise accounting).

const response = await anthropic.messages.create({ ... });
clevagent.logCost(
  response.usage.input_tokens + response.usage.output_tokens,
  0.0045
);

clevagent.logIteration(count)

Update the current loop iteration count.

for (let i = 0; i < MAX_ITER; i++) {
  clevagent.logIteration(i);
  // ... agent work
}

clevagent.shutdown()

Stop monitoring gracefully. Sends a final "shutdown" heartbeat. Auto-called on SIGTERM / SIGINT.

await clevagent.shutdown();

Example: LangChain Agent

import clevagent from "clevagent";

clevagent.init({ apiKey: process.env.CLEVAGENT_API_KEY!, agent: "langchain-agent" });

async function runAgent() {
  for (let i = 0; i < 100; i++) {
    clevagent.logIteration(i);

    const result = await chain.call({ input: userQuery });

    // Log tool calls manually for semantic analysis
    for (const step of result.intermediateSteps) {
      clevagent.logToolCall(step.action.tool, step.action.toolInput?.toString() ?? "");
    }

    clevagent.ping({ status: "ok", message: `Completed iteration ${i}` });
  }
}

runAgent().finally(() => clevagent.shutdown());

Example: OpenAI Function Calling

import OpenAI from "openai";
import clevagent from "clevagent";

clevagent.init({ apiKey: process.env.CLEVAGENT_API_KEY!, agent: "openai-agent" });

const openai = new OpenAI();

async function callWithTools() {
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "What's the weather?" }],
    tools: [weatherTool],
  });

  // Log token usage and tool calls
  clevagent.logCost(response.usage?.total_tokens ?? 0, 0);
  for (const choice of response.choices) {
    for (const tc of choice.message.tool_calls ?? []) {
      clevagent.logToolCall(tc.function.name, tc.function.arguments);
    }
  }
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Project API key (cv_xxx) | | agent | string | required | Agent name | | interval | number | 60 | Heartbeat interval (seconds) | | endpoint | string | "https://clevagent.io" | API base URL | | onLoop | string \| () => void | "stop" | Action on loop detection | | onCostExceeded | string \| () => void | "alert_only" | Action on cost threshold |

Requirements

• Node.js >= 16
• No runtime dependencies (uses built-in https and crypto modules)

Links

• Dashboard: clevagent.io
• Docs: clevagent.io/docs
• Python SDK: pypi.org/project/clevagent
• npm: npmjs.com/package/clevagent
• Issues: GitHub Issues

License

MIT — see LICENSE.