SDK

JavaScript / TypeScript SDK

Full reference for @agentlog/sdk. TypeScript-first, ESM + CJS compatible.

Install: npm install @agentlog/sdk · Requires Node.js 18+ or any modern browser runtime.

Installation

terminal
npm install @agentlog/sdk

Initialization

typescript
import { AgentLog } from '@agentlog/sdk';

const log = new AgentLog({
  apiKey:   'al_live_...',   // required
  orgId:    'org_...',        // optional, read from API key if omitted
  endpoint: 'https://...',   // optional, override ingest endpoint
  debug:    false,            // optional, log to console
});

log.track(event)

Logs a single agent event. Returns a Promise that resolves when the event is accepted.

typescript — AgentEvent type
{
  agentId:      string;     // unique agent identifier
  platform:     string;     'zapier' | 'n8n' | 'make' | 'claude' | 'openai' | string
  actionType:   string;     'bulk_update' | 'data_export' | 'send_email' | string
  dataCategory?: string;    'crm_contacts' | 'pii' | 'financial' | string
  recordCount?:  number;    // number of records affected
  outcome:      'success' | 'failed' | 'blocked';
  metadata?:    Record<string, unknown>;  // custom fields, NOT logged as PII
  timestamp?:   Date;        // defaults to now
}

log.batch(events[])

Log multiple events in a single request. Useful for high-throughput agents.

typescript
await log.batch([
  { agentId: 'agent-1', platform: 'n8n', actionType: 'record_read', outcome: 'success' },
  { agentId: 'agent-1', platform: 'n8n', actionType: 'send_email', outcome: 'success' },
]);

log.wrap(fn, eventTemplate)

Wrap any async function so AgentLog automatically tracks success and failure.

typescript
const result = await log.wrap(
  () => hubspot.updateContacts(contacts),
  {
    agentId:    'crm-sync',
    platform:   'hubspot',
    actionType: 'bulk_update',
    dataCategory: 'crm_contacts',
    recordCount: contacts.length,
  }
);

Error handling

The SDK never throws on network errors — failed tracking calls are silently dropped so your agent is never blocked. Set debug: true to see errors in the console.

Environment variables

VariableDescription
AGENTLOG_API_KEYYour API key. Read automatically if set.
AGENTLOG_ORG_IDOverride org ID. Optional.
AGENTLOG_DEBUGSet to 1 to enable debug logging.
On this page
InstallationInitializationlog.track()log.batch()log.wrap()Error handlingEnvironment variables