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

# TypeScript Conversation SDK

> Track any AI interaction with begin() / end()

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install agnostai
  ```

  ```bash pnpm theme={null}
  pnpm add agnostai
  ```

  ```bash yarn theme={null}
  yarn add agnostai
  ```
</CodeGroup>

## Integrate

```typescript theme={null}
import * as agnost from 'agnostai';

agnost.init('your-org-id');
```

Get your org ID from [app.agnost.ai](https://app.agnost.ai).

## Track interactions

```typescript theme={null}
const interaction = agnost.begin({ userId: 'u-123', agentName: 'my-agent', input: '...' });
// ... your AI call ...
interaction.end('...');
```

Latency is auto-calculated. For errors:

```typescript theme={null}
interaction.end('Error: timeout', false);
```

## Group into conversations

```typescript theme={null}
const conversationId = crypto.randomUUID();

const t1 = agnost.begin({ userId: 'u-123', agentName: 'my-agent', input: 'Hello', conversationId });
t1.end('Hi!');

const t2 = agnost.begin({ userId: 'u-123', agentName: 'my-agent', input: 'Follow-up', conversationId });
t2.end('Sure!');
```

## Identify users

```typescript theme={null}
agnost.identify('u-123', { name: 'Alice', email: 'alice@example.com', plan: 'pro' });
```

## Custom properties

```typescript theme={null}
const interaction = agnost.begin({ userId: 'u-123', agentName: 'my-agent', input: '...' });
interaction.setProperties({ model: 'gpt-4', tokens: '150' });
interaction.end('...');
```

## Retrieve an interaction by ID

Useful when you need to complete an interaction from a different function or callback:

```typescript theme={null}
agnost.begin({ userId: 'u-123', agentName: 'my-agent', input: '...', interactionId: 'req-1' });

// elsewhere...
const interaction = agnost.getInteraction('req-1');
interaction?.end('...');
```

## Configuration

```typescript theme={null}
agnost.init('your-org-id', { endpoint: 'https://api.agnost.ai', debug: true });
```

| Option     | Type      | Default                 | Description          |
| ---------- | --------- | ----------------------- | -------------------- |
| `endpoint` | `string`  | `https://api.agnost.ai` | API endpoint         |
| `debug`    | `boolean` | `false`                 | Enable debug logging |

## Cleanup

```typescript theme={null}
await agnost.shutdown(); // flushes and cleans up
```