SDK Quickstart

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 Beacon Cloud hosted Observe or a customer-managed OTLP endpoint.

Hosted Observe

Hosted Observe requires a Beacon Cloud 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 Beacon Cloud 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. The base URL must use https://. Plain http:// is accepted only for loopback (localhost, 127.0.0.1, [::1]), so a local stub keeps working; any other http:// base URL with an API key makes Observe.initialize() throw instead of sending the key in cleartext.

Customer-managed OTLP

Use an explicit OTLP endpoint when traces should go to a local or customer-managed collector instead of Beacon Cloud 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 a Beacon Cloud API key, and does not send one. When ASYMPTOTE_API_KEY is also set, the SDK attaches it only if the OTLP endpoint has the same origin (scheme, host and port) as the Beacon Cloud base URL; a third-party or customer collector never receives it. Headers you pass in initialize({ headers }), including your own authorization, are sent unchanged.

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	Beacon Cloud 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,
});

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();

Beacon Observe SDK

SDK Quickstart

Setup flow

1. Install

2. Configure export

Hosted Observe

Customer-managed OTLP

3. Create a first trace

Export precedence

What to read next

Instrumentation

Observe

SDK Lifecycle

Agent SDK Integrations

Flush before exit

​Setup flow

​1. Install

​2. Configure export

​Hosted Observe

​Customer-managed OTLP

​3. Create a first trace

​Export precedence

​What to read next

Instrumentation

Observe

SDK Lifecycle

Agent SDK Integrations

​Flush before exit

Setup flow

1. Install

2. Configure export

Hosted Observe

Customer-managed OTLP

3. Create a first trace

Export precedence

What to read next

Flush before exit