AgentWatch TypeScript SDK

TypeScript/JavaScript SDK for AgentWatch — observability for multi-agent AI systems.

Zero runtime dependencies. Works with Node.js 18+ using native fetch.

Installation

npm install agentwatch-sdk
# or
pnpm add agentwatch-sdk
# or
yarn add agentwatch-sdk

Quick Start

import {
  init,
  recordTrace,
  shutdown,
  createInteractionTrace,
  createSpanRecord,
  createAgentNode,
  SpanKind,
} from "agentwatch-sdk";

// Initialize the SDK
init({
  publicKey: "aw_pub_...",
  secretKey: "aw_sec_...",
  endpoint: "http://localhost:8080",
});

// Record a trace
recordTrace(
  createInteractionTrace({
    framework: "custom",
    agents: [
      createAgentNode({ name: "planner", framework: "custom" }),
      createAgentNode({ name: "executor", framework: "custom" }),
    ],
    spans: [
      createSpanRecord({
        name: "agent.planner",
        kind: SpanKind.AGENT,
        inputData: "Plan a trip to Paris",
        outputData: "Here is the itinerary...",
      }),
      createSpanRecord({
        name: "llm.gpt-4o",
        kind: SpanKind.LLM,
        inputData: "System: You are a travel planner...",
        outputData: "I recommend visiting...",
      }),
    ],
  }),
);

// Flush and shut down before process exit
await shutdown();

Configuration

| Option | Env Variable | Default | Description | |--------|-------------|---------|-------------| | publicKey | AGENTWATCH_PUBLIC_KEY | "" | AgentWatch public key | | secretKey | AGENTWATCH_SECRET_KEY | "" | AgentWatch secret key | | endpoint | AGENTWATCH_ENDPOINT | http://localhost:8080 | Backend URL | | flushIntervalMs | — | 500 | Flush interval (ms) | | flushBatchSize | — | 100 | Max traces per flush | | redactionPatterns | — | [] | Regex patterns for PII redaction |

Payload Redaction

Redact sensitive data before it leaves your process:

import { init, REDACT_EMAIL, REDACT_SSN, REDACT_API_KEY } from "agentwatch-sdk";

init({
  redactionPatterns: [REDACT_EMAIL, REDACT_SSN, REDACT_API_KEY],
});

Matching text in span input/output is replaced with [REDACTED] before export.

API Reference

Top-level Functions

• init(options?) — Initialize the SDK and start the flush loop
• shutdown() — Async. Flush remaining data and stop the engine
• recordTrace(trace) — Enqueue a trace for export
• getEngine() — Get the active engine instance (or null)

Factory Functions

• createInteractionTrace(overrides?) — Create a trace with defaults
• createSpanRecord(overrides?) — Create a span with defaults
• createAgentNode({ name, framework, ...overrides }) — Create an agent node
• createAgentInteraction({ traceId, fromAgent, toAgent, interactionType, ...overrides }) — Create an interaction

Enums

• SpanKind — AGENT, LLM, TOOL, HANDOFF, GUARDRAIL
• InteractionType — HANDOFF, STATE_TRANSFER, DELEGATION

Helpers

• getAgentCount(trace) — Number of agents in a trace
• hasError(trace) — Whether any span has error status
• getDurationMs(trace) — Trace duration in ms (or null)
• truncatePayload(text) — Truncate to 10,000 chars with suffix

Classes

• AgentWatchEngine — Core engine (buffer + flush + retry)
• AgentWatchExporter — OTLP JSON builder + HTTP exporter
• RedactionConfig — Regex-based payload redaction

License

Apache-2.0