Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

4.8 KB
Raw Blame
---
title: "SDK Quickstart"
description: "Install and initialize the Beacon 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

```bash title="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](https://asymptotelabs.ai/contact), then initialize `Observe` as early as possible in your application startup:

```bash title="Set the Beacon Cloud API key"
export ASYMPTOTE_API_KEY=...
```

```typescript title="Hosted Observe initialization" lines
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:

```bash title="Set the OTLP endpoint"
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
```

```typescript title="Customer-managed OTLP initialization" lines
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.

```typescript title="Create a traced function" lines
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.

```typescript title="Initialize with a custom exporter" lines
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

<Columns cols={2}>
  <Card title="Instrumentation" icon="wand-magic-sparkles" href="/sdk/instrumentation">
    Configure SDK initialization, module patching, and existing OpenTelemetry providers.
  </Card>
  <Card title="Observe" icon="diagram-project" href="/sdk/observe">
    Wrap custom agent functions and control span metadata.
  </Card>
  <Card title="SDK Lifecycle" icon="rotate" href="/sdk/lifecycle">
    Decide when to flush or shut down tracing.
  </Card>
  <Card title="Agent SDK Integrations" icon="plug" href="/sdk/integrations">
    Add supported Anthropic, Claude Agent SDK, OpenAI, or Vercel AI SDK instrumentation.
  </Card>
</Columns>

## Flush before exit

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

```typescript title="Flush spans before exit" lines
await Observe.flush();
```

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

```typescript title="Shut down tracing on exit" lines
await Observe.shutdown();
```