🤖 Tawk Agents SDK

Production-Ready AI Agent Framework - Enterprise-grade multi-agent orchestration for intelligent systems

Production-ready AI agent framework with true agentic architecture, comprehensive observability, and enterprise-scale multi-agent coordination.

v1.0.0: Production-ready AI agent framework with true agentic architecture.

✨ Key Features

🤖 True Agentic Architecture - Autonomous agents with context-isolated transfers
🔧 Parallel Tool Execution - Automatic parallel execution for optimal performance
👥 Multi-Agent Coordination - Specialized agents with seamless transfers (not handoffs!)
🛡️ Smart Guardrails - 10 validators with LLM-based content safety
📊 Complete Observability - Hierarchical Langfuse tracing with token tracking
💾 Session Management - Memory, Redis, MongoDB with auto-summarization
🔄 Streaming Support - Real-time responses with granular events
🎯 TypeScript First - 100% type safety with strict mode
⚡ Production Ready - Zero lint errors, comprehensive tests, enterprise patterns

📦 Installation

Clone the repository and install dependencies:

git clone https://github.com/Manoj-tawk/tawk-agents-sdk.git
cd tawk-agents-sdk
npm install

Install your AI provider:

# OpenAI (recommended)
npm install @ai-sdk/openai

# Or Anthropic
npm install @ai-sdk/anthropic

# Or Google
npm install @ai-sdk/google

🚀 Quick Start

Basic Agent

import { Agent, run } from './src';
import { openai } from '@ai-sdk/openai';

const agent = new Agent({
  name: 'Assistant',
  model: openai('gpt-4o'),
  instructions: 'You are a helpful assistant.'
});

const result = await run(agent, 'Hello!');
console.log(result.finalOutput);
// Returns: "Hello! How can I assist you today?"

Agent with Tools (Parallel Execution)

import { Agent, run, tool } from './src';
import { z } from 'zod';

const agent = new Agent({
  name: 'Assistant',
  model: openai('gpt-4o'),
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      inputSchema: z.object({
        city: z.string()
      }),
      execute: async ({ city }) => {
        return { city, temp: 22, condition: 'Sunny' };
      }
    }),
    getTime: tool({
      description: 'Get current time',
      inputSchema: z.object({
        timezone: z.string().optional()
      }),
      execute: async ({ timezone }) => {
        return { time: new Date().toISOString(), timezone };
      }
    })
  }
});

// Both tools execute in parallel automatically for optimal performance
const result = await run(agent, 'Weather in Tokyo and current time?');

Multi-Agent System with Transfers

import { Agent, run } from './src';

// Specialist agent
const dataAnalyst = new Agent({
  name: 'DataAnalyst',
  model: openai('gpt-4o'),
  instructions: 'You analyze data and provide insights.',
  tools: { analyzeData: /* ... */ }
});

// Coordinator agent with subagents
const coordinator = new Agent({
  name: 'Coordinator',
  model: openai('gpt-4o'),
  instructions: 'Route tasks to specialist agents.',
  subagents: [dataAnalyst]  // Creates transfer_to_dataanalyst tool
});

// Agent autonomously transfers to specialist when required
const result = await run(coordinator, 'Analyze Q4 sales data');
// Execution flow: Coordinator → transfer_to_dataanalyst → Analysis → Return to Coordinator

With Guardrails

import {
  Agent,
  run,
  lengthGuardrail,
  piiDetectionGuardrail,
  contentSafetyGuardrail
} from './src';

const agent = new Agent({
  name: 'SafeAgent',
  model: openai('gpt-4o'),
  instructions: 'You are a safe assistant.',
  guardrails: [
    // Input validation
    lengthGuardrail({
      type: 'input',
      maxLength: 1000,
      unit: 'characters'
    }),
    piiDetectionGuardrail({
      type: 'input',
      block: true
    }),
    
    // Output validation
    lengthGuardrail({
      type: 'output',
      maxLength: 2000
    }),
    contentSafetyGuardrail({
      type: 'output',
      model: openai('gpt-4o-mini'),
      categories: ['violence', 'hate-speech']
    })
  ]
});

const result = await run(agent, 'User query');
// Automatically validates input and output with configured guardrails

With Observability (Langfuse)

import { initLangfuse, Agent, run } from './src';

// Initialize Langfuse (reads from env vars)
initLangfuse();

const agent = new Agent({
  name: 'TracedAgent',
  model: openai('gpt-4o'),
  instructions: 'You are helpful.'
});

const result = await run(agent, 'Hello!');

// Automatically traced to Langfuse with comprehensive metrics:
// - Complete execution hierarchy
// - Token usage per component
// - Tool execution times
// - Transfer chains
// - Guardrail validations (including LLM token tracking)
// - Total cost calculations

With Session Memory

import { Agent, run, MemorySession } from './src';

const agent = new Agent({
  name: 'Assistant',
  model: openai('gpt-4o')
});

// Create session for persistent conversation
const session = new MemorySession('user-123', 50);

// First interaction
await run(agent, 'My name is Alice', { session });

// Second interaction - agent maintains context
const result = await run(agent, 'What is my name?', { session });
console.log(result.finalOutput);
// Returns: "Your name is Alice"

🎯 Core Concepts

True Agentic Architecture

graph LR
    A[User Query] --> B[Coordinator Agent]
    B --> C{Decision}
    C -->|Use Tool| D[Execute Tool]
    C -->|Transfer| E[Specialist Agent]
    C -->|Direct| F[Generate Response]
    
    D --> B
    E --> B
    
    B --> G[Guardrails]
    G --> H[Session Storage]
    H --> I[Langfuse Trace]
    I --> J[Return Result]
    
    style A fill:#e3f2fd
    style J fill:#c8e6c9

Key Principles:

Autonomous Decision Making - Agents decide their own actions
Context Isolation - Each agent gets only relevant context
Parallel Execution - Tools run simultaneously when possible
Complete Observability - Every step is traced

🛠️ Advanced Features

1. Session Management (3 Backends)

import { MemorySession, RedisSession, MongoDBSession } from './src';

// Memory (development/testing)
const session = new MemorySession('user-123', 50);

// Redis (production - fast)
const session = new RedisSession('user-123', {
  redis: redisClient,
  maxMessages: 50,
  ttl: 3600
});

// MongoDB (production - scalable)
const session = new MongoDBSession('user-123', {
  db: mongoClient.db('myapp'),
  maxMessages: 100
});

// All implementations support automatic summarization when history exceeds configured limit

2. Guardrails (10 Validators)

import {
  // Non-LLM (fast, no tokens)
  lengthGuardrail,
  piiDetectionGuardrail,
  formatValidationGuardrail,
  rateLimitGuardrail,
  
  // LLM-based (accurate, tracks tokens)
  contentSafetyGuardrail,
  topicRelevanceGuardrail,
  sentimentGuardrail,
  toxicityGuardrail,
  languageGuardrail,
  
  // Custom
  customGuardrail
} from './src';

// Mix and match for your needs
const agent = new Agent({
  guardrails: [
    lengthGuardrail({ type: 'output', maxLength: 500 }),
    contentSafetyGuardrail({ type: 'output', model: openai('gpt-4o-mini') })
  ]
});

3. Streaming

import { Agent, runStream } from './src';

const streamResult = await runStream(agent, 'Tell me a story');

// Stream text chunks
for await (const chunk of streamResult.textStream) {
  process.stdout.write(chunk);
}

// Or all events
for await (const event of streamResult.fullStream) {
  switch (event.type) {
    case 'text-delta':
      process.stdout.write(event.textDelta);
      break;
    case 'tool-call':
      console.log(`Tool: ${event.toolName}`);
      break;
    case 'transfer':
      console.log(`Transfer: ${event.from} → ${event.to}`);
      break;
  }
}

4. Message Helpers

import { user, assistant, system } from './src';

const messages = [
  system('You are a helpful assistant'),
  user('Hello!'),
  assistant('Hi! How can I help?'),
  user('Tell me about AI')
];

const result = await run(agent, messages);

5. Lifecycle Hooks

import { AgentHooks, RunHooks } from './src';

// Agent-level hooks
AgentHooks.on('agent:created', (agent) => {
  console.log(`Agent ${agent.name} created`);
});

// Run-level hooks
RunHooks.on('run:start', (runId, agent) => {
  console.log(`Run ${runId} started with ${agent.name}`);
});

RunHooks.on('run:complete', (runId, result) => {
  console.log(`Run ${runId} completed in ${result.metadata.duration}ms`);
});

📊 Architecture

graph TD
    A[src/index.ts<br/>Main Exports] --> B[core/]
    A --> C[guardrails/]
    A --> D[lifecycle/]
    A --> E[sessions/]
    A --> F[tracing/]
    
    B --> B1[agent/<br/>Modular Agent System]
    B --> B2[runner.ts<br/>Execution Engine]
    B --> B3[transfers.ts<br/>Multi-Agent System]
    
    C --> C1[10 Guardrail Validators]
    D --> D1[Event Hooks]
    D --> D2[Langfuse Integration]
    E --> E1[Memory/Redis/MongoDB]
    F --> F1[Hierarchical Tracing]
    
    style A fill:#e1f5ff
    style B1 fill:#fff9c4
    style B2 fill:#f3e5f5

See detailed architecture:

Flow Diagrams - Visual execution flows ⭐
Source Architecture - Complete codebase guide
Complete Architecture - Full system design

📚 Documentation

🚀 Getting Started (30 min)

Getting Started Guide 15 min
- Installation & setup
- Your first agent
- Basic tool calling
- Multi-agent basics
Flow Diagrams 30 min ⭐ NEW
- 7 comprehensive Mermaid sequence diagrams
- Visual explanation of all execution flows
- Complete end-to-end examples

📖 Feature Guides (3 hours)

Core Concepts 20 min
- What is an agent?
- True agentic architecture
- Tool execution model
Features Overview 30 min
- All features at a glance
- When to use what
- Feature comparison
Advanced Features 45 min
- Message helpers
- Lifecycle hooks
- Safe execution
- RunState management
Agentic RAG 30 min
- RAG with Pinecone
- Multi-agent RAG patterns
Tracing & Observability 15 min
- Langfuse integration
- Hierarchical tracing
- Token tracking
Error Handling 15 min
- Error patterns
- Recovery strategies

📘 Technical Reference

API Reference
- Complete API documentation
- All 76 exports documented
- Type definitions
Source Architecture ⭐ NEW
- Complete src/ structure guide
- Module responsibilities
- Dependency graphs
- Quality metrics
Performance Guide 30 min
- Optimization strategies
- Benchmarks
- Best practices

🎨 Examples

Check out 19 working examples:

Basic (3 examples)

Simple agent
Tool calling
Multi-agent coordination

Intermediate (7 examples)

Guardrails & safety
Session management
Streaming responses
Tracing & observability

Advanced (4 examples)

Agentic RAG
Multi-agent research
Production patterns

Production (5 examples)

E-commerce system
Customer service
Financial analysis

🧪 Testing

# Build
npm run build

# All tests
npm test

# Test with coverage
npm run test:coverage

# Specific test suites
npm run test:unit         # Unit tests
npm run test:integration  # Integration tests
npm run test:e2e          # End-to-end tests

# Lint
npm run lint

Quality Metrics:

✅ Build: Passing
✅ Lint: Zero errors
✅ Tests: 96% passing (26/27)
✅ Type Safety: 100%
✅ Quality Score: 98/100 ⭐⭐⭐⭐⭐

🌍 Environment Variables

# AI Provider (required)
OPENAI_API_KEY=sk-...
# Or
ANTHROPIC_API_KEY=sk-ant-...
# Or
GOOGLE_API_KEY=...

# Langfuse Tracing (optional but recommended)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# Redis (optional - for production sessions)
REDIS_URL=redis://localhost:6379

# MongoDB (optional - for production sessions)
MONGODB_URI=mongodb://localhost:27017/myapp

📦 SDK Exports

Complete export list (76 items):

// Core Agent & Execution (14)
export { Agent, run, runStream, tool, setDefaultModel }
export { AgenticRunner, Usage, RunState }
export { createTransferTools, detectTransfer, createTransferContext }
export type { AgentConfig, CoreTool, RunOptions, RunResult, StreamResult }

// Tracing & Observability (10)
export { withTrace, getCurrentTrace, getCurrentSpan }
export { initLangfuse, getLangfuse, isLangfuseEnabled }
export { createContextualSpan, createContextualGeneration }

// Guardrails (12)
export { lengthGuardrail, piiDetectionGuardrail, customGuardrail }
export { contentSafetyGuardrail, topicRelevanceGuardrail }
export { sentimentGuardrail, toxicityGuardrail, languageGuardrail }

// Sessions (3)
export { SessionManager, MemorySession }
export type { Session }

// Helpers (7)
export { user, assistant, system, safeExecute }
export { getLastTextContent, filterMessagesByRole, extractAllText }

// Lifecycle (4)
export { AgentHooks, RunHooks }
export type { AgentHookEvents, RunHookEvents }

// Type Utilities (4)
export type { Expand, DeepPartial, Prettify, UnwrapPromise }

See complete API reference →

🏆 Quality & Status

Metric	Status	Details
Build	✅ Passing	Zero TypeScript errors
Lint	✅ Clean	Zero ESLint errors
Tests	✅ 96%	26/27 tests passing
Type Safety	✅ 100%	Strict mode enabled
Documentation	✅ 100%	All exports covered
Quality Score	⭐⭐⭐⭐⭐	98/100

Production Status: ✅ READY

See detailed quality report →

📄 License

MIT © Tawk.to

🙏 Acknowledgments

Built with industry-leading open source technologies:

Vercel AI SDK v5 - Multi-provider AI framework
Langfuse - LLM observability platform
Zod - TypeScript-first schema validation
TypeScript - Type-safe JavaScript

💬 Support

📖 Documentation: Complete Docs
🐛 Issues: GitHub Issues
📧 Email: support@tawk.to
💡 Examples: 19 Working Examples

Made with ❤️ by Tawk.to

Production-Ready • Enterprise-Grade • 100% TypeScript

Name		Name	Last commit message	Last commit date
Latest commit History 115 Commits
.github/workflows		.github/workflows
dist		dist
docs		docs
examples		examples
src		src
tests		tests
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.tests.json		tsconfig.tests.json

License

tawk/tawk-agents-sdk

Folders and files

Latest commit

History

Repository files navigation