> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellipsis1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Reference for installing, configuring and using the Ellipsis SDK in TypeScript and Node.js applications.

## Description

The Ellipsis SDK enables developers to collect and export telemetry from AI agents and LLM-powered applications to the E1 observability platform.

Use the SDK to monitor supported agent executions, LLM invocations, tool calls, traces, latency and token usage through framework instrumentation.

## Package

> [card] [@ellipsis1/sdk on npm](https://www.npmjs.com/package/@ellipsis1/sdk)
>
> View the published package, release information and installation instructions.

```bash theme={null}
npm install @ellipsis1/sdk
```

The published package listing identifies version `0.1.0` and Node.js `>=22`. Check npm for the latest release before upgrading or pinning a version.

## Runtime requirements

| Requirement | Supported version |
| - | - |
| Node.js | `>=22` |
| TypeScript | Supported |
| JavaScript | Supported |
| `@langchain/core` | `>=1.1.0` for LangChain/LangGraph instrumentation |

The package provides both ESM and CommonJS bundles.

## Supported integrations

### Framework compatibility

| Framework | Support | Instrumentation |
| - | - | - |
| LangChain | Supported | `ellipsis.langchain()` |
| LangGraph | Supported through LangChain callbacks | `ellipsis.langchain()` |

### LLM provider compatibility

The SDK captures telemetry emitted through the LangChain framework. It is not currently tied to a single LLM provider and can work with different models supported by LangChain, including OpenAI, Google Gemini, Anthropic, OpenRouter and other compatible providers.

> [!WARNING]
>
> Provider-specific instrumentation outside the LangChain framework is not
> currently supported.

## Initialization

Initialize the SDK once at the top level of your application, after loading the required configuration.

```typescript theme={null}
import { initEllipsis, type Config } from "@ellipsis1/sdk";

const config: Config = {
  ingestionUrl: process.env.ELLIPSIS_INGESTION_URL!,
  apiKey: process.env.ELLIPSIS_AGENT_API_KEY!,
};

const ellipsis = initEllipsis(config);
```

`initEllipsis()` accepts a configuration object and an optional logging level.

```typescript theme={null}
const ellipsis = initEllipsis(config, "info");
```

Supported logging levels:

* `debug`
* `info`
* `warn`
* `error`
* `silent`

The default logging level is `warn`.

## Configuration reference

The SDK accepts a `Config` object through `initEllipsis()`.

| Parameter | Required | Description |
| - | -: | - |
| `ingestionUrl` | Yes | E1 telemetry ingestion API endpoint. |
| `apiKey` | Yes | Agent API key generated in your E1 workspace. |
| `globalTags` | No | Tags applied globally to collected telemetry. |
| `globalMetadata` | No | Metadata describing your agent or Node.js project. |
| `globalMetadata.name` | No | Agent or project name; maximum 50 characters. |
| `globalMetadata.version` | No | Semantic version, for example `1.0.0`. |
| `globalMetadata.stage` | No | Execution environment. |

### Validation constraints

| Field | Constraint |
| - | - |
| `ingestionUrl` | Mandatory ingestion URL provided by E1 documentation. |
| `apiKey` | Mandatory agent API key generated in the E1 workspace. |
| `globalTags` | Array of strings; maximum 20 characters per tag. |
| `globalMetadata.name` | Maximum 50 characters. |
| `globalMetadata.version` | Semantic version format. |
| `globalMetadata.stage` | `DEV`, `INT`, `UAT` or `PROD`. |

The SDK logging `level` is passed as the optional second argument to `initEllipsis()`; it is not listed as a field in the `Config` object.

## Configuration example

### Using environment variables

Create a `.env` file:

```dotenv theme={null}
ELLIPSIS_INGESTION_URL=your_ingestion_url
ELLIPSIS_AGENT_API_KEY=your_agent_api_key
ELLIPSIS_AGENT_TAG_1=e1
ELLIPSIS_AGENT_TAG_2=first-try
ELLIPSIS_AGENT_NAME=My first project
ELLIPSIS_AGENT_VERSION=1.0.0
ELLIPSIS_AGENT_STAGE=DEV
```

Load the environment variables before initializing the SDK:

```typescript theme={null}
import "dotenv/config";
import { initEllipsis, type Config, type Stage } from "@ellipsis1/sdk";

const config: Config = {
  ingestionUrl: process.env.ELLIPSIS_INGESTION_URL!,
  apiKey: process.env.ELLIPSIS_AGENT_API_KEY!,
  globalTags: [
    process.env.ELLIPSIS_AGENT_TAG_1!,
    process.env.ELLIPSIS_AGENT_TAG_2!,
  ],
  globalMetadata: {
    name: process.env.ELLIPSIS_AGENT_NAME!,
    version: process.env.ELLIPSIS_AGENT_VERSION!,
    stage: process.env.ELLIPSIS_AGENT_STAGE! as Stage,
  },
};

const ellipsis = initEllipsis(config);
```

> [!WARNING]
>
> Do not commit `.env` files or expose your agent API key in public
> repositories. Use your deployment environment's secret-management facilities
> in production.

### Providing values directly

You can also provide configuration values directly:

```typescript theme={null}
import { initEllipsis, type Config } from "@ellipsis1/sdk";

const config: Config = {
  ingestionUrl: "YOUR_ELLIPSIS_INGESTION_URL",
  apiKey: "YOUR_AGENT_API_KEY",
  globalTags: ["e1", "first-try"],
  globalMetadata: {
    name: "My first project",
    version: "1.0.0",
    stage: "DEV",
  },
};

const ellipsis = initEllipsis(config);
```

Replace the placeholder values with your actual ingestion URL and agent API key. For production applications, environment variables or a secrets manager are preferable to hardcoded credentials.

## LangChain instrumentation

Create the LangChain handler from the initialized SDK instance:

```typescript theme={null}
const handler = ellipsis.langchain();
```

Pass it to the agent invocation using LangChain's callbacks option:

```typescript theme={null}
const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "Your question here" }],
  },
  {
    callbacks: [handler],
  }
);
```

The handler captures supported framework events, normalize them across different model providers and exports telemetry to E1.

## What the SDK collects

The SDK organizes captured execution events into traces and hierarchical spans. The E1 platform can present:

* Trace and span hierarchies.
* Agent and chain executions.
* LLM provider and model information.
* Token consumption.
* Prices per run.
* Execution duration and latency.
* Tool calls and associated operations.
* LLM reasoning behind each step.
* Errors and failed executions.

The SDK supports multi-agent and multi-model projects.

## How it works

The SDK acts as an instrumentation layer between your application and the E1 observability platform. Its architecture consists of four main components:

1. **Instrumentation adapters** connect to supported frameworks and capture execution events.
2. **Trace and span management** organizes events into traces with parent-child relationships.
3. **Telemetry processing** aggregates execution information, including duration, token usage and LLM metrics.
4. **Telemetry exporter** batches and transmits collected telemetry to E1.

The SDK is designed to minimize its impact on application execution. Telemetry is exported using batching and retry mechanisms for transient network failures.

## Module compatibility

The SDK supports both Node.js module systems:

* **ES Modules (ESM)**
* **CommonJS (CJS)**

The package provides dedicated ESM and CommonJS bundles.

## Related resources

* [Quickstart](https://docs.ellipsis1.com/quickstart.md)
* [API reference](https://docs.ellipsis1.com/api.md)
* [npm package](https://www.npmjs.com/package/@ellipsis1/sdk)
* [Weather Agent example](https://docs.ellipsis1.com/examples/weather-agent.md)
* [E1 workspace](https://app.ellipsis1.com)
* [Technical support](mailto:contact@ellipsis1st.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.