AgentSea

Unite and orchestrate AI agents - A production-ready ADK for building agentic AI applications in Node.js.

AgentSea ADK unites AI agents and services to create powerful, intelligent applications and integrations.

✨ Features

🤖 Multi-Provider Support - Anthropic Claude, OpenAI GPT, Google Gemini
🎯 Per-Model Type Safety - Compile-time validation of model-specific options
🏠 Local & Open Source Models - Ollama, LM Studio, LocalAI, Text Generation WebUI, vLLM
💻 Agentic Coding - Interactive AI coding assistant with 13 built-in tools (file ops, git, shell, search)
🎙️ Voice Support (TTS/STT) - OpenAI Whisper, ElevenLabs, Piper TTS, Local Whisper
🔗 MCP Protocol - First-class Model Context Protocol integration
🛒 ACP Protocol - Agentic Commerce Protocol for e-commerce integration
🔄 Multi-Agent Crews - Role-based coordination with delegation strategies
💬 Conversation Schemas - Structured conversational experiences with validation
🧠 Advanced Memory - Episodic, semantic, and working memory with multi-agent sharing
🔧 Built-in Tools - 13 coding tools + 8 general tools + custom tool support
🛡️ Guardrails - Content safety, prompt injection detection, PII filtering, and validation
📊 LLM Evaluation - Metrics, LLM-as-Judge, human feedback, and continuous monitoring
🔴 Red Teaming - Adversarial testing, vulnerability scanning, and compliance checking
🌐 LLM Gateway - OpenAI-compatible API with intelligent routing, caching, and cost optimization
🔍 Embeddings - Multi-provider embeddings with caching and quality metrics
📝 Structured Output - TypeScript-native Zod schema enforcement for LLM responses
📥 Document Ingestion - Flexible pipeline with parsers, chunkers, and transformers
💾 Intelligent Caching - Exact match, semantic similarity, and streaming replay with multi-tier support
📋 Prompt Management - Version control, A/B testing, and environment promotion for prompts
🌐 Browser Automation - Web agents with Playwright, Puppeteer, and native backends
📈 Full Observability - Logging, metrics, distributed tracing, cost tracking, and conversation analytics
🎯 NestJS Integration - Decorators, modules, and dependency injection
🌐 REST API & Streaming - HTTP endpoints, SSE streaming, WebSocket support
🐛 Agent Debugger - Step-through execution, checkpoint replay, and what-if scenario testing
🚀 Production Ready - Rate limiting, caching, error handling, retries
📘 TypeScript - Fully typed with comprehensive definitions

🚀 Quick Start

Installation

# Core package (framework-agnostic)
pnpm add @lov3kaizen/agentsea-core

# NestJS integration
pnpm add @lov3kaizen/agentsea-nestjs

Basic Agent

import {
  Agent,
  AnthropicProvider,
  ToolRegistry,
  BufferMemory,
  calculatorTool,
} from '@lov3kaizen/agentsea-core';

// Create agent
const agent = new Agent(
  {
    name: 'assistant',
    model: 'claude-sonnet-4-20250514',
    provider: 'anthropic',
    systemPrompt: 'You are a helpful assistant.',
    tools: [calculatorTool],
  },
  new AnthropicProvider(process.env.ANTHROPIC_API_KEY),
  new ToolRegistry(),
  new BufferMemory(50),
);

// Execute
const response = await agent.execute('What is 42 * 58?', {
  conversationId: 'user-123',
  sessionData: {},
  history: [],
});

console.log(response.content);

Multi-Provider Support

import {
  Agent,
  GeminiProvider,
  OpenAIProvider,
  AnthropicProvider,
  OllamaProvider,
  LMStudioProvider,
  LocalAIProvider,
} from '@lov3kaizen/agentsea-core';

// Use Gemini
const geminiAgent = new Agent(
  { model: 'gemini-pro', provider: 'gemini' },
  new GeminiProvider(process.env.GEMINI_API_KEY),
  toolRegistry,
);

// Use OpenAI
const openaiAgent = new Agent(
  { model: 'gpt-4-turbo-preview', provider: 'openai' },
  new OpenAIProvider(process.env.OPENAI_API_KEY),
  toolRegistry,
);

// Use Anthropic
const claudeAgent = new Agent(
  { model: 'claude-sonnet-4-20250514', provider: 'anthropic' },
  new AnthropicProvider(process.env.ANTHROPIC_API_KEY),
  toolRegistry,
);

// Use Ollama (local)
const ollamaAgent = new Agent(
  { model: 'llama2', provider: 'ollama' },
  new OllamaProvider(),
  toolRegistry,
);

// Use LM Studio (local)
const lmstudioAgent = new Agent(
  { model: 'local-model', provider: 'openai-compatible' },
  new LMStudioProvider(),
  toolRegistry,
);

// Use LocalAI (local)
const localaiAgent = new Agent(
  { model: 'gpt-3.5-turbo', provider: 'openai-compatible' },
  new LocalAIProvider(),
  toolRegistry,
);

Per-Model Type Safety

Get compile-time validation for model-specific options. Inspired by TanStack AI:

import { anthropic, openai, createProvider } from '@lov3kaizen/agentsea-core';

// ✅ Valid: Claude 3.5 Sonnet supports tools, system prompts, and extended thinking
const claudeConfig = anthropic('claude-3-5-sonnet-20241022', {
  tools: [myTool],
  systemPrompt: 'You are a helpful assistant',
  thinking: { type: 'enabled', budgetTokens: 10000 },
  temperature: 0.7,
});

// ✅ Valid: o1 supports tools but NOT system prompts
const o1Config = openai('o1', {
  tools: [myTool],
  reasoningEffort: 'high',
  // systemPrompt: '...' // ❌ TypeScript error - o1 doesn't support system prompts
});

// ❌ TypeScript error: o1-mini doesn't support tools
const o1MiniConfig = openai('o1-mini', {
  // tools: [myTool], // Error: 'tools' does not exist in type
  reasoningEffort: 'medium',
});

// Create type-safe providers
const provider = createProvider(claudeConfig);
console.log('Supports vision:', provider.supportsCapability('vision')); // true

Key Benefits:

Zero runtime overhead - All validation at compile time
IDE autocomplete - Only valid options appear per model
Model capability registry - Query what each model supports

See full per-model type safety documentation →

Local Models & Open Source

Run AI models on your own hardware with complete privacy:

import { Agent, OllamaProvider } from '@lov3kaizen/agentsea-core';

// Create Ollama provider
const provider = new OllamaProvider({
  baseUrl: 'http://localhost:11434',
});

// Pull a model (if not already available)
await provider.pullModel('llama2');

// List available models
const models = await provider.listModels();
console.log('Available models:', models);

// Create agent with local model
const agent = new Agent({
  name: 'local-assistant',
  description: 'AI assistant running locally',
  model: 'llama2',
  provider: 'ollama',
  systemPrompt: 'You are a helpful assistant.',
});

agent.registerProvider('ollama', provider);

// Use the agent
const response = await agent.execute('Hello!', {
  conversationId: 'conv-1',
  sessionData: {},
  history: [],
});

Supported local providers:

Ollama - Easy local LLM execution
LM Studio - User-friendly GUI for local models
LocalAI - OpenAI-compatible local API
Text Generation WebUI - Feature-rich web interface
vLLM - High-performance inference engine
Any OpenAI-compatible endpoint

See full local models documentation →

Voice Capabilities

Add voice interaction with Text-to-Speech and Speech-to-Text:

import {
  Agent,
  AnthropicProvider,
  ToolRegistry,
  VoiceAgent,
  OpenAIWhisperProvider,
  OpenAITTSProvider,
} from '@lov3kaizen/agentsea-core';

// Create base agent
const provider = new AnthropicProvider(process.env.ANTHROPIC_API_KEY);
const toolRegistry = new ToolRegistry();

const agent = new Agent(
  {
    name: 'voice-assistant',
    model: 'claude-sonnet-4-20250514',
    provider: 'anthropic',
    systemPrompt: 'You are a helpful voice assistant.',
    description: 'Voice assistant',
  },
  provider,
  toolRegistry,
);

// Create voice agent with STT and TTS
const sttProvider = new OpenAIWhisperProvider(process.env.OPENAI_API_KEY);
const ttsProvider = new OpenAITTSProvider(process.env.OPENAI_API_KEY);

const voiceAgent = new VoiceAgent(agent, {
  sttProvider,
  ttsProvider,
  ttsConfig: { voice: 'nova' },
});

// Process voice input
const result = await voiceAgent.processVoice(audioBuffer, context);
console.log('User said:', result.text);
console.log('Assistant response:', result.response.content);

// Save audio response
fs.writeFileSync('./response.mp3', result.audio!);

Supported providers:

STT: OpenAI Whisper, Local Whisper
TTS: OpenAI TTS, ElevenLabs, Piper TTS

See full voice documentation →

MCP Integration

import { MCPRegistry } from '@lov3kaizen/agentsea-core';

// Connect to MCP servers
const mcpRegistry = new MCPRegistry();

await mcpRegistry.addServer({
  name: 'filesystem',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
  transport: 'stdio',
});

// Get MCP tools (automatically converted)
const mcpTools = mcpRegistry.getTools();

// Use with agent
const agent = new Agent({ tools: mcpTools }, provider, toolRegistry);

ACP Commerce Integration

Add e-commerce capabilities to your agents with the Agentic Commerce Protocol:

import { ACPClient, createACPTools, Agent } from '@lov3kaizen/agentsea-core';

// Setup ACP client
const acpClient = new ACPClient({
  baseUrl: 'https://api.yourcommerce.com/v1',
  apiKey: process.env.ACP_API_KEY,
  merchantId: process.env.ACP_MERCHANT_ID,
});

// Create commerce tools
const acpTools = createACPTools(acpClient);

// Create shopping agent
const shoppingAgent = new Agent(
  {
    name: 'shopping-assistant',
    model: 'claude-sonnet-4-20250514',
    provider: 'anthropic',
    systemPrompt: 'You are a helpful shopping assistant.',
    tools: acpTools, // Includes 14 commerce tools
  },
  provider,
  toolRegistry,
);

// Start shopping
const response = await shoppingAgent.execute(
  'I need wireless headphones under $100',
  context,
);

Available Commerce Operations:

Product search and discovery
Shopping cart management
Checkout and payment processing
Delegated payments (Stripe, PayPal, etc.)
Order tracking and management

See full ACP documentation →

Conversation Schemas

import { ConversationSchema } from '@lov3kaizen/agentsea-core';
import { z } from 'zod';

const schema = new ConversationSchema({
  name: 'booking',
  startStep: 'destination',
  steps: [
    {
      id: 'destination',
      prompt: 'Where would you like to go?',
      schema: z.object({ city: z.string() }),
      next: 'dates',
    },
    {
      id: 'dates',
      prompt: 'What dates?',
      schema: z.object({
        checkIn: z.string(),
        checkOut: z.string(),
      }),
      next: 'confirm',
    },
  ],
});

Agentic Coding

Launch an interactive AI coding session with 13 built-in tools:

# Start agentic coding session
sea code

# Use a specific provider/model
sea code --provider anthropic --model claude-sonnet-4-20250514

# Verbose mode with token usage and latency
sea code --verbose

# Limit tool iterations
sea code --maxIterations 50

The coding agent has access to:

File Operations - file_read, file_write, file_list
Code Editing - code_edit (precise search-and-replace)
Search - glob (pattern matching), grep (regex search)
Shell - shell_execute (with safety checks)
Git - git_status, git_diff, git_add, git_commit, git_log, git_branch

See CLI documentation →

With CLI

# Install CLI globally
npm install -g @lov3kaizen/agentsea-cli

# Initialize configuration
sea init

# Start chatting
sea chat

# Start an agentic coding session
sea code

# Run an agent
sea agent run default "What is the capital of France?"

# Manage models (Ollama)
sea model pull llama2
sea model list

See CLI documentation →

With NestJS

import { Module } from '@nestjs/common';
import { AgenticModule } from '@lov3kaizen/agentsea-nestjs';
import { AnthropicProvider } from '@lov3kaizen/agentsea-core';

@Module({
  imports: [
    AgenticModule.forRoot({
      provider: new AnthropicProvider(),
      defaultConfig: {
        model: 'claude-sonnet-4-20250514',
        provider: 'anthropic',
      },
      enableRestApi: true, // Enable REST API endpoints
      enableWebSocket: true, // Enable WebSocket gateway
    }),
  ],
})
export class AppModule {}

REST API Endpoints:

GET /agents - List all agents
GET /agents/:name - Get agent details
POST /agents/:name/execute - Execute agent
POST /agents/:name/stream - Stream agent response (SSE)

WebSocket Events:

execute - Execute an agent
stream - Real-time streaming events
listAgents - Get available agents
getAgent - Get agent info

See API documentation →

📦 Packages

Core Packages

@lov3kaizen/agentsea-core - Framework-agnostic core library
@lov3kaizen/agentsea-types - Shared TypeScript type definitions
@lov3kaizen/agentsea-nestjs - NestJS integration with decorators
@lov3kaizen/agentsea-cli - Command-line interface

Agent Orchestration

@lov3kaizen/agentsea-crews - Multi-agent orchestration with role-based coordination
@lov3kaizen/agentsea-gateway - High-performance LLM gateway with routing, caching, and cost optimization

Memory & Retrieval

@lov3kaizen/agentsea-memory - Advanced memory with semantic retrieval and multi-agent support
@lov3kaizen/agentsea-embeddings - Embedding providers with caching and quality metrics
@lov3kaizen/agentsea-cache - Intelligent caching with semantic similarity, streaming replay, and multi-tier support

Data Processing

@lov3kaizen/agentsea-structured - TypeScript-native structured output with Zod schema enforcement
@lov3kaizen/agentsea-ingest - Document ingestion pipeline with parsers and chunkers
@lov3kaizen/agentsea-prompts - Prompt management with version control, A/B testing, and environment promotion

Safety & Evaluation

@lov3kaizen/agentsea-guardrails - Content safety, prompt injection detection, and validation
@lov3kaizen/agentsea-evaluate - LLM evaluation, human feedback, and continuous monitoring
@lov3kaizen/agentsea-redteam - Red teaming and adversarial testing for AI systems

Observability & Operations

@lov3kaizen/agentsea-analytics - Conversation analytics with intent classification, sentiment tracking, flow analysis, and KPI monitoring
@lov3kaizen/agentsea-costs - Cost tracking with 60+ model pricing registry, budget enforcement, and Stripe billing integration
@lov3kaizen/agentsea-debugger - Agent debugger with step-through execution, checkpoint replay, and what-if scenario testing

Automation

@lov3kaizen/agentsea-surf - Computer-use agent for desktop automation with screen capture, mouse/keyboard control, and browser automation

UI

@lov3kaizen/agentsea-react - React components for agent interfaces
@lov3kaizen/agentsea-admin-ui - Admin dashboard for monitoring agents

Examples

examples - Example applications

🏗️ Architecture

AgentSea follows a clean, layered architecture:

┌─────────────────────────────────────────┐
│         Application Layer               │
│  (Your NestJS/Node.js Application)      │
└─────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────┐
│         AgentSea ADK Layer               │
│  ┌─────────────────────────────────┐    │
│  │  Multi-Agent Orchestration      │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │  Conversation Management        │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │  Agent Runtime & Tools          │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │  Multi-Provider Adapters        │    │
│  │  (Claude, GPT, Gemini, MCP)     │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │  Observability & Utils          │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────┐
│         Infrastructure Layer            │
│  (LLM APIs, Storage, Monitoring)        │
└─────────────────────────────────────────┘

🎯 Core Concepts

Agents

Autonomous AI entities that can reason, use tools, and maintain conversation context.

Crews

Multi-agent teams with defined roles, delegation strategies, and coordinated task execution.

Tools

Functions that agents can call to perform specific tasks (API calls, calculations, etc.).

Memory

Hierarchical memory system with episodic, semantic, and working memory structures. Supports multi-agent sharing with access control.

Guardrails

Input validation, output filtering, and safety checks to ensure responsible AI behavior.

Evaluation

LLM-as-Judge, human feedback collection, and continuous monitoring for quality assurance.

Gateway

OpenAI-compatible API gateway with intelligent routing, load balancing, and fallback handling.

MCP

Model Context Protocol integration for seamless tool and resource integration.

Conversation Schemas

Define structured conversation flows with validation and dynamic routing.

Agentic Coding

Interactive AI coding sessions with 13 built-in tools for file operations, code editing, search, shell execution, and git operations. Works with any provider.

Red Teaming

Proactive security testing with adversarial attack generation, vulnerability scanning, jailbreak detection, compliance checking, and audit logging.

Prompt Management

Git-like version control for prompts with environment promotion (dev/staging/prod), A/B testing, and team collaboration.

Debugger

Step-through agent execution with breakpoints, checkpoint replay, what-if scenario testing, and decision tree visualization.

Analytics

Conversation analytics with intent classification, sentiment analysis, topic clustering, anomaly detection, and KPI tracking.

📚 Documentation

Full documentation available at agentsea.dev

Getting Started

Core Concepts

Package Documentation

Integrations

Operations

🛠️ Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:cov

# Development mode (watch)
pnpm dev

# Lint
pnpm lint

# Type check
pnpm type-check

✅ Feature Status

✅ Completed

🚧 In Progress

Admin UI dashboard improvements
Additional MCP tools/servers
Enhanced computer-use agent capabilities

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

💬 Discussions - Ask questions and share ideas
🐛 Issues - Report bugs and request features
📖 Documentation - Read the full documentation

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built with ❤️ by lovekaizen

Special thanks to:

Anthropic for Claude
OpenAI for GPT
Google for Gemini
The open source community

Website • Documentation • Examples • API Reference

Made with TypeScript and AI 🤖

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.changeset		.changeset
.github/workflows		.github/workflows
.husky		.husky
docs		docs
examples		examples
packages		packages
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
RELEASE_NOTES_v0.6.0.md		RELEASE_NOTES_v0.6.0.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

AgentSea

✨ Features

🚀 Quick Start

Installation

Basic Agent

Multi-Provider Support

Per-Model Type Safety

Local Models & Open Source

Voice Capabilities

MCP Integration

ACP Commerce Integration

Conversation Schemas

Agentic Coding

With CLI

With NestJS

📦 Packages

Core Packages

Agent Orchestration

Memory & Retrieval

Data Processing

Safety & Evaluation

Observability & Operations

Automation

UI

Examples

🏗️ Architecture

🎯 Core Concepts

Agents

Crews

Tools

Memory

Guardrails

Evaluation

Gateway

MCP

Conversation Schemas

Agentic Coding

Red Teaming

Prompt Management

Debugger

Analytics

📚 Documentation

Getting Started

Core Concepts

Package Documentation

Integrations

Operations

🛠️ Development

✅ Feature Status

✅ Completed

🚧 In Progress

🤝 Contributing

📄 License

🙏 Credits

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages