Node.js SDK

The agent SDK turns Agent Action Records or OTel GenAI spans into signed, hash-chained batches and ships them to your organization's ingest endpoint. No dependencies, Node 20+.

Install

Published on npm as @provantix/agent-sdk, source at github.com/provantix-tech/agent-sdk:

npm install @provantix/agent-sdk
import { AgentEmitter, buildAAR, validateAAR, ACTION_TYPES } from '@provantix/agent-sdk';

Creating an emitter

const emitter = new AgentEmitter({
  emitterId: 'emi_01m…',            // from emitter registration
  tenantId: 'ten_org_01m…',         // your organization's tenant
  privateKeyPem: process.env.PRIVATE_KEY.replace(/\\n/g, '\n'),
  spoolDir: '/var/spool/provantix', // optional: persistent offline queue
});

Emitting events

Agent Action Records give you full control over the evidence content:

emitter.emitAAR(buildAAR({
  tenantId: 'ten_org_01m…',
  emitterId: 'emi_01m…',
  system: 'internal-tools',
  agent: { vendor: 'acme', vendorAgentId: 'support-copilot' },
  action: { type: 'call_tool', targetSystem: 'crm', toolName: 'customer.lookup' },
  data: { classes: ['customer'] },
}));

OTel GenAI spans map automatically (OpenTelemetry JS SDK SpanExporter-shaped objects):

emitter.emitOtelSpan(span, { agent: { vendor: 'otel', vendorAgentId: 'support-copilot' } });

Spans without gen_ai.* attributes return null, so you can route all spans through and only agent telemetry is captured; the rest belongs in your normal trace backend.

Flushing and offline behavior

await emitter.flushAndDrain('https://app.provantix.tech');
  • Events buffer in memory, are signed per batch, and POST to /v1/batches.
  • On network failure, batches are written to the spool directory and retried with backoff. Gaps are surfaced in the platform as explicit custody-gap findings, never hidden.
  • flushAndDrain resolves when the queue is empty; call it at shutdown so nothing is lost.

Sealed batches (0.2.0)

From 0.2.0 the emitter signs the hash of every record in each batch and adds it to the envelope (the seal). It lets an auditor check that your emitter itself vouched for each record, and it still verifies after a person's data is erased. Sealing is on by default; pass seal: false only to match a platform that does not know seals yet.

  • Upgrading: upgrade and redeploy. Sealed and unsealed batches are accepted side by side, so emitters can move one at a time. Batches queued before the upgrade are sealed when the new version sends them, with the same records and batch number.
  • The deadline: unsealed batches are accepted until the end of a notice period Provantix sends you (90 days from the notice). After that an unsealed emitter is refused with 426 seal_required and its telemetry pauses until it is upgraded. Pilot and trial sources are exempt.
  • Your key: the proof is independent of Provantix only if the public key an auditor checks against came from you. Register your emitter with your own key and keep a copy of the public key.
  • What else is in 0.2.0: it is the first release since 0.1.1, so besides sealing it includes work that was not published before: approvals mapped into the record's authorization block (provantix.approval.* attributes), the delegation chain rebuilt from span parentage, tool arguments, results, data classes and the external recipient on records, an OpenTelemetry SpanExporter, the stable target-system contract for run ids, and runnable examples. Read the SDK's CHANGELOG.md before upgrading an emitter that is in production.

See The emitter proof and Sealing deadline, paused telemetry and lost seals.

Location and queue size (0.3.0)

Published as @provantix/[email protected] (the location option arrived in 0.3.0); upgrade with npm install @provantix/agent-sdk@latest.

From 0.3.0 an emitter can say where it runs and what it acts on, as short codes, and Provantix shows it in Investigate:

const emitter = new AgentEmitter({
  emitterId, tenantId, privateKeyPem,
  location: { runtime: { provider: 'aws', region: 'eu-west-1' }, target: { region: 'us-east-1' } },
});

With no location, the emitter reads the cloud region it runs in (AWS_REGION, GOOGLE_CLOUD_REGION, FLY_REGION, VERCEL_REGION) when one is set, and says nothing otherwise. A single action can override it with buildAAR({ location }). The location is part of the sealed record, so it is covered by the seal and the batch signature, and it is shown as declared. Only a provider, region, zone and country are kept; a city or address is dropped before it is sealed, and the platform refuses a record that carries one. See the record schema.

Queue size

While Provantix is unreachable (or a licence is lapsed), batches queue in the spoolDir on disk and are sent in order when it returns. The queue has a 2 GiB safety default; beyond it the emitter refuses new records with a 'spool full' error instead of growing without end. For a self-hosted deployment, which has no volume restrictions, remove the limit:

const emitter = new AgentEmitter({ emitterId, tenantId, privateKeyPem, spoolDir: '/var/spool/provantix', spoolMaxBytes: null });

With null the disk is the only limit, so put the spool on a volume with room for your longest outage.

Configuration: the feature flag variant a step ran under (0.4.0)

Say which feature flags a step ran under and the variant each served, and Provantix shows them beside the step, keeps evaluation windows under different variants apart, and, after a rollback, checks that the same cohort is on the expected variant:

emitter.emitAAR(buildAAR({
  tenantId, emitterId, system: 'openai',
  agent: { vendor: 'acme', vendorAgentId: 'support-bot' },
  action: { type: 'call_model', targetSystem: 'llm' },
  correlation: { traceId, spanId },                       // the same traceId on every step of one run
  configuration: [{ flag: 'new-prompt', variant: 'v2', provider: 'launchdarkly' }],
}));

At most ten flags per step. A variant is a string, a number or a boolean, kept as text; anything else is refused when you call buildAAR, because a flag value can be large or sensitive. The OpenTelemetry exporter reads the same thing from feature_flag.key, feature_flag.result.variant and feature_flag.provider.name on a span, or on its feature_flag.evaluation events, the way the hosted intake does. Provantix records what you say the step ran under. It does not know whether the flag changed anything.

Give every step of one run the same traceId. Expected steps and recovery checks group a run by it.

Attribution wiring

Create the agent record once, with matching vendor and vendor_agent_id, and every event attributes at 0.95 confidence by explicit platform id:

curl -X POST https://app.provantix.tech/v1/agents \
  -H "authorization: Bearer <token>" -H "content-type: application/json" \
  -d '{"display_name":"Support Copilot","vendor":"acme","vendor_agent_id":"support-copilot"}'

Records with no matching agent are still stored and chained, as unknown, and appear under Candidates.

Validation and redaction

validateAAR(aar) returns a list of schema problems (empty when valid). The emitter also applies field redaction before signing: payload content you mark as sensitive is committed to as a salted hash rather than stored in clear, so the evidence chain survives without carrying raw secrets.

Full example

See examples/emit-demo.mjs in the SDK repo for an end-to-end run against a live organization: register, emit, flush, then verify the record in Investigate.