Continuous behavioral telemetry for AI agents.

Install

pnpm add @armalo/telemetry
# or
npm i @armalo/telemetry

Quickstart

One client per agent runtime. Issue events; the client batches and flushes them automatically.

import { Telemetry } from '@armalo/telemetry';

const tel = new Telemetry({
  apiKey: process.env.ARMALO_API_KEY!,
});

const sessionId = crypto.randomUUID();
const agentId = 'YOUR_AGENT_UUID';

tel.sessionStart({
  sessionId,
  agentId,
  startedAt: new Date().toISOString(),
  pactId: 'YOUR_PACT_UUID', // enables continuous param-binding validation
});

tel.toolCall({
  sessionId,
  agentId,
  tool: 'transfer_funds',
  params: { destination: '0xAB...', amount: 250 },
  outcome: 'success',
  latencyMs: 142,
  attemptedAt: new Date().toISOString(),
});

tel.sessionEnd({
  sessionId,
  agentId,
  endedAt: new Date().toISOString(),
  outcome: 'success',
});

await tel.close(); // flush before process exit

One-liner: instrument any tool

Wrap any function and every invocation streams a tool_call event. Pass-through on return values and errors — telemetry never breaks the runtime.

const safeTransfer = tel.instrumentTool({
  sessionId,
  agentId,
  tool: 'transfer_funds',
  pactId: 'YOUR_PACT_UUID',
  fn: async (params) => yourTransferImpl(params),
});

// Every invocation emits a tool_call event automatically.
// Errors are captured + re-thrown — telemetry never breaks your runtime.
await safeTransfer({ destination: '0xAB...', amount: 250 });

Event shapes

Failure semantics

• Network errors and 5xx responses retry with exponential backoff up to maxRetries (default 3).
• 4xx (other than 429) is permanent — the batch is dropped with one log line.
• Buffer overflow (>1000 events) drops the oldest event with a warning. The agent's correctness must not depend on telemetry succeeding.
• The client is non-blocking by default. For strong isolation, run telemetry in a separate process/sidecar with a dedicated API key.