SDK Quickstart

Install and initialize the Asymptote TypeScript SDK

Setup Flow

Follow this path to install @asymptote/sdk, initialize tracing, create a first span, and flush it before the process exits.

1. Install

Install the SDK

npm install @asymptote/sdk

The package requires Node.js 20 or newer.

2. Configure Export

Choose Asymptote Managed hosted Observe or a customer-managed OTLP endpoint.

Hosted Observe

Hosted Observe requires an Asymptote Managed account. To get an ASYMPTOTE_API_KEY, reach out for a demo, then initialize Observe as early as possible in your application startup:

Set the Asymptote Managed API key

export ASYMPTOTE_API_KEY=...

Hosted Observe initialization

import { Observe } from "@asymptote/sdk";

Observe.initialize({
  apiKey: process.env.ASYMPTOTE_API_KEY,
});

Hosted export uses OTLP/HTTP traces.

Setting	Value
Default base URL	https://api.asymptotelabs.ai
Observe path	/v1/observe
API key env var	ASYMPTOTE_API_KEY
Base URL env var	ASYMPTOTE_BASE_URL
Auth header	authorization: Bearer <api key>

The SDK appends /v1/observe when the configured base URL or endpoint does not already include it.

Customer-Managed OTLP

Use an explicit OTLP endpoint when traces should go to a local or customer-managed collector instead of Asymptote Managed hosted Observe:

Set the OTLP endpoint

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

Customer-managed OTLP initialization

import { Observe } from "@asymptote/sdk";

Observe.initialize({
  otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
});

Explicit OTLP export does not require an Asymptote Managed API key.

3. Create A First Trace

Wrap application code with Observe.observe() to create a Beacon-compatible span.

Create a traced function

import { Observe } from "@asymptote/sdk";

Observe.initialize({
  apiKey: process.env.ASYMPTOTE_API_KEY,
});

const plan = Observe.observe(
  {
    name: "agent.plan",
    attributes: {
      "beacon.harness.name": "custom_agent",
      "beacon.event.action": "tool.invoked",
      "beacon.event.category": "tool",
      "beacon.tool.name": "planner",
    },
  },
  async (input: string) => {
    return `Plan for: ${input}`;
  },
);

await plan("Review this pull request");
await Observe.flush();

Export Precedence

Observe.initialize() resolves export configuration in this order:

Priority	Source
1	initialize({ otlpEndpoint })
2	OTEL_EXPORTER_OTLP_ENDPOINT
3	Asymptote Managed hosted baseUrl when apiKey or ASYMPTOTE_API_KEY is present

If neither hosted credentials nor an explicit OTLP endpoint is configured, use a custom exporter or disable the default exporter.

Initialize with a custom exporter

import { InMemorySpanExporter } from "@opentelemetry/sdk-trace-base";
import { Observe } from "@asymptote/sdk";

Observe.initialize({
  spanExporter: new InMemorySpanExporter(),
  disableDefaultExporter: true,
  disableBatch: true,
});

What To Read Next

Instrumentation

Configure SDK initialization, module patching, and existing OpenTelemetry providers.

Observe

Wrap custom agent functions and control span metadata.

SDK Lifecycle

Decide when to flush or shut down tracing.

Agent SDK Integrations

Add supported Anthropic, Claude Agent SDK, OpenAI, or Vercel AI SDK instrumentation.

Flush Before Exit

For short-lived scripts, CI jobs, and serverless handlers, flush spans before the process exits:

Flush spans before exit

await Observe.flush();

When the process owns the OpenTelemetry provider lifecycle, shut it down during graceful termination:

Shut down tracing on exit

await Observe.shutdown();