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

# TypeScript SDK

> Reference for the Adrian TypeScript SDK and its OpenAI integration: install, wrapping your client, configuration, and what it captures.

The Adrian TypeScript SDK (`@secureagentics/adrian`) attaches to your agent's LLM calls, captures activity and reasoning, and streams them to the Adrian backend over WebSocket. The core package owns the event pipeline - event pairing, PII redaction, JSONL logging, WebSocket streaming, and policy verdicts. Provider packages build on it; the [OpenAI integration](#openai-integration) wraps your OpenAI client so every call is captured with no change to your call sites.

## Install

```sh theme={null}
npm install @secureagentics/adrian
```

Requires Node.js 18 or later.

## OpenAI integration

`@secureagentics/adrian-openai` instruments the official `openai` client (Chat Completions). `init`, `adrian.openai(client)`, and `shutdown` bracket your normal OpenAI code - call sites stay unchanged.

```sh theme={null}
npm install @secureagentics/adrian-openai openai
```

```ts theme={null}
import OpenAI from "openai";
import { adrian } from "@secureagentics/adrian-openai";

async function main() {
  await adrian.init({ apiKey: "adr_live_..." });

  // Wrap your existing OpenAI client; every call is captured.
  const client = adrian.openai(new OpenAI());

  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [
      { role: "user", content: "Find the most underpriced recent IPOs and build an investment strategy" },
    ],
  });
  console.log(response.choices[0]?.message?.content);

  await adrian.shutdown();
}

main();
```

Requires the `openai` package as a peer dependency (`>=4.0.0`). Events appear in your [dashboard](https://app.adrian.secureagentics.ai) within seconds, classified by severity.

<Note>
  The SDK defaults to `ws://localhost:8080/ws`. For Adrian Cloud, pass `wsUrl: "wss://adrian.secureagentics.ai/ws"` to `init` (or set `ADRIAN_WS_URL`).
</Note>

## Configuration

Explicit `init()` options take precedence over environment variables.

| Variable                      | Default                  | Purpose                                                                           |
| ----------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| `ADRIAN_API_KEY`              | *(required)*             | API key for WebSocket authentication. `adr_live_...` for Adrian Cloud.            |
| `ADRIAN_WS_URL`               | `ws://localhost:8080/ws` | Backend WebSocket endpoint. `wss://adrian.secureagentics.ai/ws` for Adrian Cloud. |
| `ADRIAN_LOG_FILE`             | `events.jsonl`           | Local JSONL log path.                                                             |
| `ADRIAN_SESSION_ID`           | *(optional)*             | Session identifier for grouping events.                                           |
| `ADRIAN_BLOCK_TIMEOUT`        | `30`                     | Seconds to wait for a BLOCK-mode verdict before failing open.                     |
| `ADRIAN_REPLAY_BUFFER_FRAMES` | `1000`                   | WebSocket replay buffer for resending frames after a transient outage.            |

## Policy and BLOCK mode

When the dashboard policy is in **BLOCK** or **HITL** mode, the SDK waits for backend verdicts on the tool calls an LLM turn proposes. In **BLOCK** mode, if no verdict arrives within `blockTimeout` seconds, the SDK fails open and allows execution (matching the [Python SDK](/reference/sdk)). See [Severity codes](/reference/severity-codes) for the M-codes and [How it works](/how-it-works) for the operating modes.

## What's captured

* **Activity events.** LLM calls and tool executions, paired (start + end) and streamed to the backend.
* **Reasoning traces.** Captured where the model exposes them.

PII is redacted in your process before any data leaves it. See [Security and Privacy](/security-and-privacy).

## Manual instrumentation

For a framework without a provider package, attach the handler from `adrian.getHandler()` and pair each LLM or tool start and end by a shared `runId` (`handleChatModelStart` / `handleLLMEnd`, `handleToolStart` / `handleToolEnd`). Shared capture helpers are exposed at `@secureagentics/adrian/capture`.

## Known limitations

* **Fail-open on timeout.** In BLOCK mode a verdict timeout allows execution; a dashboard-configurable failure policy is planned.
* **OpenAI surface.** The OpenAI package instruments the `openai` client's Chat Completions calls.