Zentis

Zentis is a high-performance Node.js framework for orchestrating Model Context Protocol (MCP) agents. It provides a robust, zero-identity reasoning layer with persistent multi-turn memory, multi-agent parallelization, and JIT tool discovery.

🚀 Key Features

• Multi-Server MCP Orchestration: Seamless connection to multiple MCP servers via SSE or HTTP.
• Dynamic Discovery (JIT Injection): Optimizes context window by hiding tool schemas until they are explicitly searched and "unlocked."
• Swarm Intelligence (Parallel Agents): Spawn concurrent agent instances and automatically aggregate their findings into a unified response.
• Context Slicing for "Huge Data": Automatically summarizes massive datasets for the LLM while passing the full raw data to your frontend.
• Process Mapping & Audit: Every internal turn (Planner, Tool, Aggregate) is tracked in an execution graph.
• Hybrid Storage: Support for SQLite and PostgreSQL with strict session isolation.

📦 Installation

npm install zentis

Peer Dependencies

npm install better-sqlite3 # for SQLite
npm install pg             # for PostgreSQL

🛠️ Usage Guide

1. Initialization

import { ZentisAgent } from 'zentis';

const agent = new ZentisAgent({
  llm: { apiKey: '...', model: 'gemini-3.5-flash' },
  mcp: [
    { name: 'Analytics', url: 'https://api.example.com/sse' },
    { name: 'Inventory', url: 'http://localhost:3001/mcp' }
  ],
  storage: { 
    type: 'sqlite', 
    userId: 'user_1', 
    sessionId: 'session_A' 
  },
  planner: true,   // Pre-plans tool sequences
  discovery: true  // Just-in-Time tool schema injection
});

await agent.waitReady();

2. Standard Querying

const response = await agent.query("Analyze sales data", {
  onStep: (step) => console.log(`[${step.type}] ${step.message}`),
  extraArgs: { auth_token: '...' } // Passed to tools, hidden from LLM
});

// Full Response Structure
console.log(response.text);           // Aggregated answer
console.log(response.results);        // ALL raw data results keyed by ID
console.log(response.interactions);   // Audit log of all calls
console.log(response.processes);      // Execution graph

3. Parallel Agents (Swarm Mode)

Wait for multiple agent processes to solve sub-tasks concurrently.

const res = await agent.parallel([
  "Get current price of BTC",
  "Summarize crypto news from today",
  "Calculate RSI for top 10 coins"
]);

// res.text contains the final synthesis of all three agents
// res.subResponses contains the raw results from each individual agent
console.log(res.subResponses[0].text); // "BTC is at $65,000..."

4. Handling Huge Datasets (Context Slicing)

When a tool returns >5 objects, Zentis hides the data from the LLM and provides a Result ID (e.g., res_1_list_all_employees).

• LLM sees: [DATA_REFERENCE:res_1_list_all_employees] (Metadata only)
• You see: response.results.res_1_list_all_employees contains the full raw data.
• UI Components: Zentis recursively scans UI props and automatically resolves IDs into full datasets.

5. UI Component Registry

Define which components your LLM can "trigger."

import { ZentisUI } from 'zentis';
const ui = new ZentisUI();

ui.register({
  name: 'Table',
  description: 'Dynamic data table.',
  props: {
    title: { type: 'string', description: 'Table title' },
    data: { type: 'data_reference', description: 'Link to a tool result ID' },
    fullWidth: { type: 'boolean', description: 'Enable wide mode' }
  }
});

const agent = new ZentisAgent({ ui, ... });

6. Process Tracking & Reliability

• Planner: A dedicated turn to lay out a tool plan, improving accuracy for complex multi-step tasks.
• Recursion Guard: Automatically blocks identical tool calls with same arguments to prevent infinite loops.
• Execution Graph: Every turn is recorded:

  response.processes.forEach(p => console.log(`${p.label} took ${p.duration}ms`));

🎨 Response Data Contract

interface AgentResponse {
  text: string;                 // Conversational text
  components: UIComponent[];    // Auto-resolved UI components
  results: Record<string, any>; // Keyed raw data (res_N_toolName)
  interactions: ToolInteraction[]; // Full audit trail
  processes: ProcessNode[];     // Execution graph
  subResponses?: AgentResponse[]; // (Optional) Individual agent results
}

🛡️ License

ISC