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

🧠 Supported Models

AgentSea ships a typed model registry (60+ models with capabilities and live pricing). Latest highlights per provider — pass any of these as model:

Provider	Latest models	Notes
Anthropic Claude	`claude-opus-4-8` (default), `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-fable-5`	Adaptive thinking on Opus 4.6+, Sonnet 4.6, Fable 5
OpenAI	`gpt-5.5`, `gpt-5.4-mini`, `gpt-5.2` (+ `pro` / `codex`), `gpt-5.1`, `o3`, `o1`	Reasoning-effort aware, per-model capability typing
Google Gemini	`gemini-3.5-flash`, `gemini-3.1-pro-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`
Local / OSS	Ollama, LM Studio, LocalAI, vLLM, Text Generation WebUI, any OpenAI-compatible endpoint	Run fully on your own hardware

Older generations (Claude 3.x / Sonnet 4.5, GPT-4o, Gemini 1.5/2.0, …) remain supported. See @lov3kaizen/agentsea-types for the full registry and costs for the pricing table.

🚀 Quick Start

Requirements

Node.js >= 20.0.0 (Node 18 is no longer supported as of v1.0.1)
TypeScript 5.0+ (recommended)

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-opus-4-8',
    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-2.5-pro', provider: 'gemini' },
  new GeminiProvider(process.env.GEMINI_API_KEY),
  toolRegistry,
);

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

// Use Anthropic
const claudeAgent = new Agent(
  { model: 'claude-opus-4-8', 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 Opus 4.8 supports tools and system prompts. Thinking is
// adaptive on 4.6+ models, so budget_tokens-style config is intentionally
// not part of the type.
const claudeConfig = anthropic('claude-opus-4-8', {
  tools: [myTool],
  systemPrompt: 'You are a helpful assistant',
});

// ✅ Valid: Claude Sonnet 4.5 still exposes explicit extended thinking
const sonnetConfig = anthropic('claude-sonnet-4-5-20250929', {
  tools: [myTool],
  systemPrompt: 'You are a helpful assistant',
  thinking: { type: 'enabled', budgetTokens: 10000 },
});

// ✅ 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
});

// 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-opus-4-8',
    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-opus-4-8',
    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-opus-4-8

# 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-opus-4-8',
        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

Concept	What it is
Agents	Autonomous entities that reason, call tools, and keep conversation context
Crews	Multi-agent teams with roles, delegation, and sequential/concurrent task execution
Tools	Functions agents call (built-in coding/general tools, MCP tools, or your own)
Memory	Episodic, semantic, and working memory with multi-agent sharing and access control
Guardrails	Input validation, output filtering, prompt-injection/PII safety checks
Gateway	OpenAI-compatible gateway with routing, load balancing, caching, and fallbacks
MCP	Model Context Protocol for plug-in tools and resources
Conversation Schemas	Structured, validated conversation flows with dynamic routing
Evaluation / Red Team	LLM-as-Judge, human feedback, monitoring + adversarial attack generation and jailbreak detection
Prompts / Debugger	Git-like prompt versioning & A/B testing; step-through execution with checkpoints and what-if replay
Analytics	Intent classification, sentiment, 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

🚧 Work 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
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 133 Commits
.changeset		.changeset
.github/workflows		.github/workflows
.husky		.husky
docs		docs
examples		examples
packages		packages
scripts		scripts
.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
RELEASING.md		RELEASING.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

🧠 Supported Models

🚀 Quick Start

Requirements

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

📚 Documentation

Getting Started

Core Concepts

Package Documentation

Integrations

Operations

🛠️ Development

🚧 Work in Progress

🤝 Contributing

📄 License

🙏 Credits

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages