AgenSights TypeScript SDK

TypeScript SDK for AgenSights - AI Agent Observability.

Track LLM calls, tool invocations, and multi-step agent executions with zero-friction auto-instrumentation or manual tracking.

Installation

npm install agensights

Quick Start — Auto-Instrumentation (Recommended)

Wrap your OpenAI client and every call is tracked automatically. Zero manual work.

import OpenAI from "openai";
import { instrumentOpenAI } from "agensights";

const openai = instrumentOpenAI(
  new OpenAI({ apiKey: "sk-xxx" }),
  {
    agensightsApiKey: "sk-prod-xxx",
    agentName: "support_bot",          // optional — tags all events
  }
);

// This call is now automatically tracked (model, tokens, latency, errors)
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

// Flush on shutdown
await (openai as any)._agensights.close();

Environment Variables

You can configure the SDK via environment variables instead of passing options:

export AGENSIGHTS_BASE_URL="https://api.agensights.dev/api/v1"

The SDK reads AGENSIGHTS_BASE_URL at startup. If set, it is used as the default base URL for all clients.

What Gets Captured Automatically

| Field | Source | |-------|--------| | model | Response model (falls back to request model) | | inputTokens | response.usage.prompt_tokens | | outputTokens | response.usage.completion_tokens | | latencyMs | Wall-clock time around the API call | | status | "success" or "error" | | errorCode | HTTP status code or error name on failure | | provider | "openai" | | agentName | From InstrumentOptions.agentName |

Using an Existing AgenSights Client

If you already have an AgenSights instance, pass it directly instead of an API key:

import { AgenSights, instrumentOpenAI } from "agensights";
import OpenAI from "openai";

const as = new AgenSights({ apiKey: "sk-prod-xxx" });
const openai = instrumentOpenAI(new OpenAI({ apiKey: "sk-xxx" }), {
  agensightsClient: as,
  agentName: "support_bot",
});

// ... use openai as normal ...

await as.close();

Manual Tracking

For non-OpenAI providers or when you need full control:

import { AgenSights } from "agensights";

const client = new AgenSights({ apiKey: "sk-prod-xxx" });

// Track a single LLM call
client.trackLLM({
  model: "gpt-4o",
  inputTokens: 100,
  outputTokens: 50,
  latencyMs: 300,
});

// Track a tool call
client.trackTool({
  toolName: "web_search",
  latencyMs: 150,
});

// Flush and close when done
await client.close();

Tracing

Group related LLM and tool calls under a single trace:

const trace = client.startTrace("support_agent", "workflow-123");

trace.llmCall({
  model: "gpt-4o",
  inputTokens: 100,
  outputTokens: 50,
  latencyMs: 300,
});

trace.toolCall({ toolName: "web_search", latencyMs: 150 });
trace.toolCall({ toolName: "db_lookup", latencyMs: 80 });

await trace.end();

All events within a trace share the same traceId, making it easy to view the full execution flow in the AgenSights dashboard.

Agent Hierarchy

Track multi-agent workflows with parent-child spans:

const trace = client.startTrace("pipeline", "wf-001");

const orchestrator = trace.agent("orchestrator");

// Sub-agents with automatic parent linking
const researcher = orchestrator.agent("researcher");
researcher.toolCall({ name: "web_search", latencyMs: 200 });
researcher.llmCall({ model: "gpt-4o", inputTokens: 100, outputTokens: 50, latencyMs: 300 });

const writer = orchestrator.agent("writer");
writer.llmCall({
  model: "claude-3-5-sonnet",
  inputTokens: 200,
  outputTokens: 100,
  latencyMs: 400,
  provider: "anthropic",
});

await trace.end();

This produces a full trace tree in the dashboard:

pipeline (trace)
  └── orchestrator (agent)
        ├── researcher (agent)
        │     ├── web_search (tool)
        │     └── gpt-4o (llm)
        └── writer (agent)
              └── claude-3-5-sonnet (llm)

Configuration

Environment Variables

| Variable | Description | |----------|-------------| | AGENSIGHTS_BASE_URL | Backend API base URL (default: https://api.agensights.com/api/v1) |

Client Options

const client = new AgenSights({
  apiKey: "sk-prod-xxx",                          // Required
  baseUrl: "https://api.agensights.dev/api/v1",   // Or set AGENSIGHTS_BASE_URL env var
  flushInterval: 5000,                             // Auto-flush every 5s (default)
  flushSize: 100,                                  // Auto-flush at 100 events (default)
});

API Reference

instrumentOpenAI(openaiClient, options)

Monkey-patches chat.completions.create to automatically track every call. Returns the same client object.

| Option | Type | Required | Description | |--------|------|----------|-------------| | agensightsApiKey | string | * | API key for AgenSights (creates a new client) | | agensightsClient | AgenSights | * | Existing AgenSights client instance | | agentName | string | no | Tag all events with this agent name | | baseUrl | string | no | Override AgenSights API base URL |

* Provide either agensightsApiKey or agensightsClient.

client.trackLLM(params)

Track an LLM call.

| Parameter | Type | Required | Default | |---------------|----------|----------|-------------| | model | string | yes | | | inputTokens | number | yes | | | outputTokens| number | yes | | | latencyMs | number | yes | | | status | string | no | "success" | | provider | string | no | null | | errorCode | string | no | null | | traceId | string | no | auto | | agentName | string | no | null |

client.trackTool(params)

Track a tool call.

| Parameter | Type | Required | Default | |-------------|----------|----------|-------------| | toolName | string | yes | | | latencyMs | number | yes | | | status | string | no | "success" | | traceId | string | no | auto | | agentName | string | no | null |

client.startTrace(agentName, workflowId?)

Returns a Trace instance. All calls made through the trace share the same traceId.

• trace.llmCall(params) — record an LLM call within the trace
• trace.toolCall(params) — record a tool call within the trace
• trace.agent(name) — create an AgentSpan for hierarchy tracking
• trace.end() — flush all trace events

AgentSpan

Created via trace.agent(name) or agent.agent(name) for nesting.

• agent.llmCall(params) — LLM call as child of this agent
• agent.toolCall(params) — tool call as child of this agent
• agent.agent(name) — create a sub-agent

client.flush()

Manually flush buffered events to the backend.

client.close()

Flush remaining events and stop the background flush timer.

License

MIT - see LICENSE for details.