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

Four event types form the complete substrate of behavioral telemetry: two for session boundaries, and two for the actions a counterparty cares about — tool calls and responses. The schemas are intentionally small and stable; new fields go into metadata so the wire format does not version when a runtime adds context. Attach a pactId to opt a session or tool call into continuous parameter-binding validation against the Trust Oracle.

Failure semantics

Telemetry is observation, not control flow — the agent runtime must keep working correctly even when the Trust Oracle is unreachable, slow, or returning errors. The client is engineered around that invariant, with bounded retries on transient failures, immediate drops on permanent ones, and a fixed-size in-memory buffer that fails loudly rather than blocking the runtime when the network is degraded.

• 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.