AgentMetrics

JavaScript SDK

Installation

Shell
npm install agentmetrics

Requires Node.js 18 or later. Works with TypeScript, ESM, and CommonJS.

Configuration

Call configure() once at startup, before any tracking calls.

JavaScript
import agentmetrics from "agentmetrics";

agentmetrics.configure({ apiKey: process.env.AGENTMETRICS_API_KEY });

Note

configure() must be called before any track() wrappers execute. Call it at module load time, not inside a function.

Tracking an agent

agentmetrics.track()

Wrap your agent function. Every call is tracked automatically.

JavaScript
const myAgent = agentmetrics.track("my-agent", async (task) => {
  const answer = await askLLM(task);
  return answer;
});

const result = await myAgent(task);

The wrapper records start time, end time, success/failure, and error messages. Errors are re-thrown after recording.

Signature

TypeScript
agentmetrics.track(
  agentId: string,
  fn: (...args: any[]) => Promise<any>,
  options?: TrackOptions
): (...args: any[]) => Promise<any>

Parameters

ParameterTypeRequiredDescription
agentIdstringYesIdentifier shown in the dashboard.
fnfunctionYesYour async agent function.
options.metadataobjectNoKey-value pairs attached to every run.

Tracking steps

agentmetrics.step()

Times a named phase within a tracked agent. Each step appears with its own latency in the dashboard.

JavaScript
const run = agentmetrics.track("pipeline", async (query) => {
  const docs = await agentmetrics.step("retrieve", () => vectorSearch(query));
  const answer = await agentmetrics.step("generate", () => callLlm(query, docs));
  return answer;
});

Tracking tools

agentmetrics.tool()

Times an individual tool call within a tracked agent.

JavaScript
const run = agentmetrics.track("research-agent", async (query) => {
  const results = await agentmetrics.tool("web_search", () => webSearch(query));
  const output = await agentmetrics.tool("code_interpreter", () => runCode(results));
  return summarize(output);
});

Eval scores

agentmetrics.score()

Attach named numeric scores to the current run. Call inside any tracked function. Scores appear in the dashboard alongside latency and token data.

JavaScript
const run = agentmetrics.track("rag-agent", async (query) => {
  const answer = await generateAnswer(query);
  agentmetrics.score("relevance", await evaluateRelevance(query, answer));
  agentmetrics.score("groundedness", await evaluateGroundedness(answer));
  return answer;
});

Note

score() must be called inside a track()-wrapped function. Calls outside a tracked run log a warning and are ignored.

Subagent tracking

When a track()-wrapped function calls another track()-wrapped function, the inner run is automatically linked to the outer run via parent_trace_id. No extra configuration is needed.

JavaScript
const subagent = agentmetrics.track("subagent", async (task) => {
  return await callLlm(task);
});

const orchestrator = agentmetrics.track("orchestrator", async (tasks) => {
  return await Promise.all(tasks.map(subagent));
});

Each subagent run appears as a child of the orchestrator run in the dashboard, with its own tokens, latency, and status.

Getting the trace ID

agentmetrics.traceId

Returns the active trace ID from inside a tracked function. Use it to correlate AgentMetrics runs with your own logs.

JavaScript
const run = agentmetrics.track("my-agent", async (task) => {
  console.log("trace_id:", agentmetrics.traceId);
  return await askLLM(task);
});

Returns undefined when accessed outside a tracked function.

Auto-capturing token usage

agentmetrics.instrument()

Call instrument() once after configure(). It patches the OpenAI and Anthropic Node.js SDKs to automatically capture token counts and model names on every LLM call within a tracked run.

JavaScript
agentmetrics.configure({ apiKey: process.env.AGENTMETRICS_API_KEY });
agentmetrics.instrument();

No changes to your existing openai.chat.completions.create() or anthropic.messages.create() calls are needed.

TypeScript

The SDK ships with full TypeScript types.

TypeScript
import agentmetrics, { type TrackOptions } from "agentmetrics";

const options: TrackOptions = { metadata: { env: "production" } };

const myAgent = agentmetrics.track(
  "my-agent",
  async (task: string): Promise<string> => {
    const answer = await askLLM(task);
    return answer;
  },
  options
);

CommonJS

JavaScript
const agentmetrics = require("agentmetrics");

agentmetrics.configure({ apiKey: process.env.AGENTMETRICS_API_KEY });
agentmetrics.instrument();

const myAgent = agentmetrics.track("my-agent", async (task) => {
  return await askLLM(task);
});

Error handling

Errors thrown inside a tracked function are re-thrown after AgentMetrics records them. No wrapping or try/catch needed.

JavaScript
const myAgent = agentmetrics.track("my-agent", async (task) => {
  throw new Error("something went wrong"); // tracked as failure, then re-thrown
});
NextOpenClaw plugin
GitHub