Agnost Conversation SDK for TypeScript

TypeScript/JavaScript SDK for tracking AI conversations and events. Monitor your AI agent interactions, track user conversations, and gain insights into how your AI applications are performing.

Installation

npm install agnostai

Basic Usage

import * as agnost from 'agnostai';

// Initialize with your organization ID
agnost.init('your-org-id');

// Begin an AI interaction
const interaction = agnost.begin({
  userId: 'user_123',
  agentName: 'weather-agent',
  input: 'What is the weather?'
});

// ... do async work ...

// Complete the interaction (latency auto-calculated)
interaction.end('The weather is sunny.');

API Reference

init(writeKey, config?)

Initialize the SDK with your organization ID.

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

// With custom configuration
agnost.init('your-org-id', {
  endpoint: 'https://api.agnost.ai',
  debug: true
});

identify(userId, traits)

Associate user characteristics with a user ID.

agnost.identify('user_123', {
  name: 'John Doe',
  email: '[email protected]',
  age: 30,
  plan: 'paid'
});

begin(options)

Begin a partial interaction for deferred completion. Use this when the output is not immediately available.

Automatic latency tracking - Latency is automatically calculated from begin() to end()!

// Pass input directly (recommended)
const interaction = agnost.begin({
  userId: 'user_123',
  agentName: 'weather-agent',
  input: 'What is the weather?'
});

interaction.setProperty('temperature', '0.7');

// ... do async work ...

interaction.end('The weather is sunny.');
// Latency automatically calculated! (~duration from begin to end)

Alternative: Set input later:

const interaction = agnost.begin({
  userId: 'user_123',
  agentName: 'weather-agent'
});
interaction.setInput('What is the weather?');
interaction.end('The weather is sunny.');

Manual latency override (optional):

interaction.end(
  'The weather is sunny.',
  true,   // success
  1500    // Override auto-calculation if needed
);

BeginOptions:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | userId | string | Yes | User identifier | | agentName | string | Yes | Agent name | | input | string | No | Input text/prompt (can be set later) | | conversationId | string | No | Conversation ID for grouping (auto-generated if not provided) | | properties | object | No | Additional event properties | | event | string | No | Optional event name |

Interaction Methods:

| Method | Description | |--------|-------------| | setInput(text) | Set the input text (optional if passed to begin()) | | setProperties(obj) | Set multiple properties | | setProperty(key, value) | Set a single property | | end(output, success?, latency?) | Complete the interaction. When success=false, output is the error message. Latency is auto-calculated if not provided |

flush()

Manually flush all queued events.

await agnost.flush();

shutdown()

Shutdown the SDK and flush remaining events.

await agnost.shutdown();

setDebugLogs(enabled)

Enable or disable debug logging.

agnost.setDebugLogs(true);  // See queued events

Configuration

You can customize the SDK behavior using the configuration object:

import * as agnost from 'agnostai';
import { ConversationConfig } from 'agnostai';

// Create a custom configuration
const config: ConversationConfig = {
  endpoint: 'https://api.agnost.ai',
  debug: false
};

// Apply the configuration
agnost.init('your-org-id', config);

Configuration Options

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

Advanced Usage

Conversation Tracking

Group related events using conversationId:

import { v4 as uuidv4 } from 'uuid';

const conversationId = `conv_${uuidv4()}`;

// First message
const turn1 = agnost.begin({
  userId: 'user_123',
  agentName: 'support-bot',
  input: 'Hello!',
  conversationId
});
turn1.end('Hi there! How can I help?');

// Follow-up message
const turn2 = agnost.begin({
  userId: 'user_123',
  agentName: 'support-bot',
  input: "What's the weather?",
  conversationId
});
turn2.end('The weather is sunny.');

Direct Client Instantiation

For multiple clients or advanced use cases:

import { ConversationClient } from 'agnostai';

const client = new ConversationClient();
client.init('your-org-id');

const interaction = client.begin({
  userId: 'user_123',
  agentName: 'greeting-bot',
  input: 'Hello!'
});

interaction.end('Hello! How can I help you today?');

await client.shutdown();

Error Handling

When tracking errors, set success=false and pass the error message as the output:

// With begin() and end()
const interaction = agnost.begin({
  userId: 'user_123',
  agentName: 'image-agent',
  input: 'Generate an image'
});

try {
  const result = await generateImage();
  interaction.end(result);
} catch (error) {
  // Error message goes in output when success=false
  interaction.end(error.message, false);
}

Chainable Property Setting

const interaction = agnost.begin({
  userId: 'user_123',
  agentName: 'chat-agent',
  input: 'Tell me a story'
});

// Chain multiple property setters
interaction
  .setProperty('model', 'gpt-4')
  .setProperty('temperature', '0.9')
  .setProperty('max_tokens', '2000')
  .setProperties({
    genre: 'fantasy',
    length: 'short'
  });

// ... generate story ...

interaction.end('Once upon a time...');

Deferred Input Setting

Sometimes you might not know the input until after beginning the interaction:

const interaction = agnost.begin({
  userId: 'user_123',
  agentName: 'dynamic-agent'
});

// Collect user input later
const userInput = await getUserInput();
interaction.setInput(userInput);

// Process and complete
const response = await processInput(userInput);
interaction.end(response);

TypeScript Support

This SDK is written in TypeScript and provides full type definitions:

import * as agnost from 'agnostai';
import {
  ConversationClient,
  ConversationConfig,
  BeginOptions,
  Interaction,
  UserTraits,
  EventProperties
} from 'agnostai';

// All types are available for use
const options: BeginOptions = {
  userId: 'user_123',
  agentName: 'my-agent',
  input: 'Hello'
};

const traits: UserTraits = {
  name: 'John',
  email: '[email protected]'
};

const config: ConversationConfig = {
  endpoint: 'https://api.agnost.ai',
  debug: true
};

Browser Support

This SDK works in both Node.js and browser environments. It uses the native fetch API which is available in:

• Node.js 18+
• All modern browsers

For older Node.js versions, you may need to install a fetch polyfill.

Contact

For support or questions, contact the founders: [email protected]

License

MIT