# @aerograph/sdk

> Reference SDK for emitting AeroGraph trace events from AI applications.

Latest version **0.3.0** (published 2026-06-30) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @aerograph/sdk
pnpm add @aerograph/sdk
yarn add @aerograph/sdk
bun add @aerograph/sdk
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-06-30 |
| First published | 2026-05-24 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 40.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Maintainers | sgcpu |
| Keywords | ai, agent, sdk, trace, observability |

## Links

- npm: https://www.npmjs.com/package/@aerograph/sdk
- Repository: https://github.com/SGcpu/AeroGraph
- Homepage: https://github.com/SGcpu/AeroGraph#readme
- Issues: https://github.com/SGcpu/AeroGraph/issues
- npm.io page: https://npm.io/package/@aerograph/sdk

## Dependencies (2)

- [nanoid](https://npm.io/package/nanoid.md) ^5.0.7
- [@aerograph/contracts](https://npm.io/package/@aerograph/contracts.md) 0.3.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.3.0 (latest) — 2026-06-30
- 0.2.1 — 2026-06-10
- 0.2.0 — 2026-06-03
- 0.1.0 — 2026-05-24

## README

# @aerograph/sdk

The core Node.js Flight Recorder for emitting normalized trace events from any JavaScript/TypeScript codebase to the AeroGraph collector.

## Overview

AeroGraph is an open-source cognitive observability layer for AI agent workflows. It allows you to record, playback, and visually inspect the deterministic decision-making paths of your agents.

This SDK provides a `FlightRecorder` instance to seamlessly construct and emit strictly validated `TraceEvent` objects.

## Installation

```bash
npm install @aerograph/sdk
```

*(Requires Node.js >= 18.18.0)*

## Quick Start

```typescript
import { FlightRecorder } from "@aerograph/sdk";

// 1. Initialize the recorder
const recorder = new FlightRecorder({
  endpoint: "http://localhost:4317", // AeroGraph Collector URL
  actor: {
    id: "my-travel-agent",
    name: "Travel Planner",
  },
  projectId: "travel-app", // Optional (v1.1.0)
  environment: "production" // Optional (v1.1.0)
});

// 2. Emit events
const promptEvent = await recorder.prompt({
  text: "Plan a trip to Tokyo",
  // Optional v1.1.0 canonical telemetry
  model: { name: "gpt-4o", provider: "openai" },
  usage: { inputTokens: 10, totalTokens: 10 },
  durationMs: 50
});

const responseEvent = await recorder.response({
  parentSpanId: promptEvent.spanId,
  text: "Here is your 3-day itinerary...",
  usage: { inputTokens: 10, outputTokens: 50, totalTokens: 60 },
  durationMs: 2500
});
```

## Available Event Kinds

The `FlightRecorder` supports 10 canonical event kinds:
- `prompt`: Input sent to an LLM.
- `response`: Output from an LLM.
- `tool_call`: Invocation of a tool.
- `tool_result`: The tool's resulting output.
- `handoff`: Delegating execution from one agent to another.
- `error`: Any exception or system failure.
- `retriever`: RAG retrieval query and source documents.
- `state_snapshot`: A deterministic hash of a LangGraph node's state.
- `checkpoint`: A human-in-the-loop pause.
- `note`: Freeform structured annotations.

## Span Hierarchy

Every event acts as a "span" in the trace tree. To link a child event to a parent event, pass the parent's `spanId` via the `parentSpanId` parameter:

```typescript
const root = await recorder.prompt({ text: "root prompt" });
const child = await recorder.tool_call({ 
  parentSpanId: root.spanId, 
  toolId: "search", 
  input: { q: "query" } 
});
```

## License
Apache-2.0

---
_Source: https://npm.io/package/@aerograph/sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._