Skip to main content

Hierarchical Sessions

Create session hierarchies for complex multi-Agent workflows. Child sessions inherit context from parents, enabling scoped conversations and forking.

Create Session Hierarchy

import { HierarchicalSession, createHierarchicalSession } from 'praisonai';

// Create parent session
const parentSession = createHierarchicalSession({
  id: 'main-workflow'
});

// Add context to parent
parentSession.setContext('goal', 'Build an AI application');
parentSession.setContext('language', 'TypeScript');

// Create child session (inherits parent context)
const childSession = parentSession.fork({
  id: 'research-phase'
});

// Child can access parent context
console.log(childSession.getContext('goal')); // 'Build an AI application'

// Child can add its own context
childSession.setContext('phase', 'research');

Multi-Level Hierarchy

import { HierarchicalSession } from 'praisonai';

// Root session
const root = new HierarchicalSession({ id: 'project' });
root.setContext('project', 'AI Agent Framework');

// Level 1: Phase sessions
const planning = root.fork({ id: 'planning' });
const development = root.fork({ id: 'development' });

// Level 2: Task sessions
const research = planning.fork({ id: 'research' });
const design = planning.fork({ id: 'design' });

// Each level inherits from parents
console.log(research.getContext('project')); // 'AI Agent Framework'

Context Inheritance & Scoping

import { HierarchicalSession } from 'praisonai';

const parent = new HierarchicalSession({ id: 'parent' });
parent.setContext('shared', 'visible-to-all');

const child = parent.fork({ 
  id: 'child',
  isolateContext: false  // Inherit parent context (default)
});

// Child sees parent context
console.log(child.getContext('shared')); // 'visible-to-all'

// Child modifications don't affect parent
child.setContext('local', 'child-only');
console.log(parent.getContext('local')); // undefined

Session Forking

Create branches for parallel exploration:
import { HierarchicalSession } from 'praisonai';

const main = new HierarchicalSession({ id: 'main' });
main.addMessage({ role: 'user', content: 'Help me design an API' });

// Fork for different approaches
const restApproach = main.fork({ id: 'rest-design' });
const graphqlApproach = main.fork({ id: 'graphql-design' });

// Each fork starts with same history but diverges
await restApproach.chat('Design REST endpoints');
await graphqlApproach.chat('Design GraphQL schema');

// Choose the best approach
const winner = restApproach; // Based on evaluation
main.merge(winner);  // Merge winning branch back

Use with Agents

import { Agent, HierarchicalSession } from 'praisonai';

const projectSession = new HierarchicalSession({ id: 'project' });
projectSession.setContext('requirements', 'Build a chatbot');

// Research Agent with scoped session
const researchSession = projectSession.fork({ id: 'research' });
const researcher = new Agent({
  name: 'Researcher',
  instructions: 'Research best practices for the given requirements.',
  session: researchSession
});

// Implementation Agent with different scope
const implSession = projectSession.fork({ id: 'implementation' });
const implementer = new Agent({
  name: 'Implementer',
  instructions: 'Implement based on research findings.',
  session: implSession
});

// Each Agent works in its own scope but shares project context
await researcher.chat('Research chatbot frameworks');
await implementer.chat('Implement the chatbot');

Session Tree Visualization

import { HierarchicalSession } from 'praisonai';

const root = new HierarchicalSession({ id: 'root' });
root.fork({ id: 'child-1' }).fork({ id: 'grandchild-1' });
root.fork({ id: 'child-2' });

// Get tree structure
const tree = root.getTree();
console.log(tree);
/*
root
├── child-1
│   └── grandchild-1
└── child-2
*/