Skip to main content
PraisonAI TypeScript provides comprehensive session management for tracking conversations, runs, and traces.

​
Core Concepts

ConceptDescription
SessionA conversation container with message history
RunA single execution within a session
TraceA span within a run (LLM call, tool call)

​
Installation

npm install praisonai

​
Basic Usage

import { Session, SessionManager, getSessionManager } from 'praisonai';

// Create a session
const session = new Session();
console.log('Session ID:', session.id);

// Add messages
session.addMessage({ role: 'user', content: 'Hello!' });
session.addMessage({ role: 'assistant', content: 'Hi there!' });

// Get messages for LLM
const messages = session.getMessagesForLLM();

​
Session with Custom ID

const session = new Session({ 
  id: 'my-session-123',
  metadata: { userId: 'user-456' }
});

​
Run Tracking

const session = new Session();

// Create and track a run
const run = session.createRun();
run.start();

// Do work...
await someAsyncWork();

// Complete the run
run.complete({ tokensUsed: 150 });

console.log('Run duration:', run.duration, 'ms');
console.log('Run status:', run.status); // 'completed'

​
Trace Tracking

const session = new Session();
const run = session.createRun().start();

// Create a trace for an LLM call
const llmTrace = run.createTrace({ name: 'llm_call' }).start();

// Simulate LLM call
await callLLM();

llmTrace.complete({ model: 'gpt-4o', tokens: 100 });

// Create a trace for a tool call
const toolTrace = run.createTrace({ name: 'tool:calculator' }).start();
await executeTool();
toolTrace.complete({ result: '42' });

run.complete();

​
Nested Traces

const run = session.createRun().start();

const parentTrace = run.createTrace({ name: 'agent_execution' }).start();

// Child traces
const childTrace1 = parentTrace.createChild({ name: 'step_1' }).start();
childTrace1.complete();

const childTrace2 = parentTrace.createChild({ name: 'step_2' }).start();
childTrace2.complete();

parentTrace.complete();

​
Session Manager

import { SessionManager, getSessionManager } from 'praisonai';

// Use global session manager
const manager = getSessionManager();

// Create sessions
const session1 = manager.create({ id: 'session-1' });
const session2 = manager.create({ id: 'session-2' });

// Retrieve session
const retrieved = manager.get('session-1');

// Get or create
const session = manager.getOrCreate('session-3');

// List all sessions
const allSessions = manager.list();

// Delete session
manager.delete('session-1');

​
Error Handling

const run = session.createRun().start();

try {
  await riskyOperation();
  run.complete();
} catch (error) {
  run.fail(error);
  console.log('Run failed:', run.error?.message);
}

​
Serialization

const session = new Session();
session.addMessage({ role: 'user', content: 'Hello' });

// Export to JSON
const json = session.toJSON();
console.log(JSON.stringify(json, null, 2));