# @lov3kaizen/agentsea-core

> AgentSea - Unite and orchestrate AI agents. A production-ready ADK for building agentic AI applications with multi-provider support.

Latest version **1.2.1** (published 2026-07-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install @lov3kaizen/agentsea-core
pnpm add @lov3kaizen/agentsea-core
yarn add @lov3kaizen/agentsea-core
bun add @lov3kaizen/agentsea-core
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.1 |
| Published | 2026-07-02 |
| First published | 2025-12-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 10 |
| Unpacked size | 511 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | lovekaizen |
| Maintainers | lov3kaizen |
| Keywords | agentsea, ai, agents, agentic, llm, anthropic, claude, openai, gpt, gemini, google-ai, ollama, local-ai, local-models, mcp, model-context-protocol, multi-agent, multi-provider, workflows, orchestration, tools, memory, observability, conversation, chatbot, voice, tts, stt, text-to-speech, speech-to-text, whisper, elevenlabs, voice-assistant, typescript, nodejs |

## Links

- npm: https://www.npmjs.com/package/@lov3kaizen/agentsea-core
- Repository: https://github.com/lovekaizen/agentsea
- Homepage: https://agentsea.dev
- Issues: https://github.com/lovekaizen/agentsea/issues
- npm.io page: https://npm.io/package/@lov3kaizen/agentsea-core

## Dependencies (10)

- [zod](https://npm.io/package/zod.md) ^3.25.76
- [marked](https://npm.io/package/marked.md) ^12.0.2
- [openai](https://npm.io/package/openai.md) ^6.42.0
- [ioredis](https://npm.io/package/ioredis.md) ^5.11.1
- [winston](https://npm.io/package/winston.md) ^3.19.0
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.3.3
- [@anthropic-ai/sdk](https://npm.io/package/@anthropic-ai/sdk.md) ^0.104.1
- [zod-to-json-schema](https://npm.io/package/zod-to-json-schema.md) ^3.24.6
- [@google/generative-ai](https://npm.io/package/@google/generative-ai.md) ^0.24.1
- [@lov3kaizen/agentsea-types](https://npm.io/package/@lov3kaizen/agentsea-types.md) 1.2.1

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.2.1 (latest) — 2026-07-02
- 1.2.0 — 2026-06-30
- 1.1.1 — 2026-06-30
- 1.1.0 — 2026-06-25
- 1.0.1 — 2026-06-16
- 1.0.0 — 2026-06-16
- 0.8.0 — 2026-06-16
- 0.6.0 — 2026-02-09
- 0.5.2 — 2026-01-04
- 0.5.1 — 2026-01-04
- 0.5.0 — 2026-01-03
- 0.4.0 — 2025-12-08
- 0.3.1 — 2025-12-07
- 0.3.0 — 2025-12-04
- 0.2.0 — 2025-12-04
- … 2 more at https://npm.io/package/@lov3kaizen/agentsea-core/versions

## README

# @lov3kaizen/agentsea-core

**Unite and orchestrate AI agents** - Framework-agnostic core library for building agentic AI applications in Node.js.

[![npm version](https://img.shields.io/npm/v/@lov3kaizen/agentsea-core.svg)](https://www.npmjs.com/package/@lov3kaizen/agentsea-core)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

## 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
- **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 (14 operations)
- **Multi-Agent Workflows** - Sequential, parallel, and supervisor orchestration
- **Conversation Schemas** - Structured conversational experiences with validation
- **Advanced Memory** - Buffer, Redis, summary, and tenant-based memory stores
- **Built-in Tools** - 13 coding tools + 8 general tools + custom tool support
- **Isomorphic Tool Definitions** - Server, client, and hybrid tool types
- **Multi-Tenancy** - Built-in tenant isolation for SaaS applications
- **Full Observability** - Logging, metrics, and distributed tracing

## Installation

```bash
npm install @lov3kaizen/agentsea-core
# or
pnpm add @lov3kaizen/agentsea-core
# or
yarn add @lov3kaizen/agentsea-core
```

## Quick Start

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

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

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

console.log(response.content);
```

## Providers

### Cloud Providers

```typescript
import {
  AnthropicProvider,
  OpenAIProvider,
  GeminiProvider,
} from '@lov3kaizen/agentsea-core';

// Anthropic Claude (Opus 4.6, Sonnet 4.5, Haiku 4.5, and earlier)
const claude = new AnthropicProvider(process.env.ANTHROPIC_API_KEY);

// OpenAI (GPT-5, GPT-4.1, o3, o4-mini, GPT-4o, and more)
const openai = new OpenAIProvider(process.env.OPENAI_API_KEY);

// Google Gemini
const gemini = new GeminiProvider(process.env.GEMINI_API_KEY);
```

### Local Providers

```typescript
import {
  OllamaProvider,
  LMStudioProvider,
  LocalAIProvider,
  TextGenerationWebUIProvider,
  VLLMProvider,
  OpenAICompatibleProvider,
} from '@lov3kaizen/agentsea-core';

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

// LM Studio
const lmstudio = new LMStudioProvider({ baseUrl: 'http://localhost:1234/v1' });

// LocalAI
const localai = new LocalAIProvider({ baseUrl: 'http://localhost:8080/v1' });

// Any OpenAI-compatible endpoint
const custom = new OpenAICompatibleProvider({
  baseUrl: 'http://your-server/v1',
  apiKey: 'optional-key',
});
```

### Per-Model Type Safety

Get compile-time validation for model-specific options:

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

// Claude supports tools, system prompts, and extended thinking
const claudeConfig = anthropic('claude-sonnet-4-6', {
  tools: [myTool],
  systemPrompt: 'You are a helpful assistant',
  thinking: { type: 'enabled', budgetTokens: 10000 },
});

// o3 supports tools and reasoning effort
const o3Config = openai('o3', {
  tools: [myTool],
  reasoningEffort: 'high',
});

// Create type-safe provider from config
const provider = createProvider(claudeConfig);
```

## Tools

### Built-in Tools

```typescript
import {
  // General tools
  calculatorTool,
  // Coding tools
  fileReadTool,
  fileWriteTool,
  fileListTool,
  shellExecuteTool,
  codeEditTool,
  globTool,
  grepTool,
  gitStatusTool,
  gitDiffTool,
  gitAddTool,
  gitCommitTool,
  gitLogTool,
  gitBranchTool,
} from '@lov3kaizen/agentsea-core';
```

### Custom Tools

```typescript
import { z } from 'zod';

const weatherTool = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  parameters: z.object({
    location: z.string().describe('City name'),
  }),
  execute: async (params) => {
    return `Weather in ${params.location}: Sunny, 72°F`;
  },
};

toolRegistry.register(weatherTool);
```

### Isomorphic Tool Definitions

Define tools that work on server, client, or both:

```typescript
import { serverTool, clientTool, hybridTool } from '@lov3kaizen/agentsea-core';
import { z } from 'zod';

// Server-only tool
const dbQuery = serverTool({
  name: 'db_query',
  description: 'Query the database',
  parameters: z.object({ sql: z.string() }),
  execute: async (params) => {
    /* server-side only */
  },
});

// Client-only tool (runs in browser)
const showModal = clientTool({
  name: 'show_modal',
  description: 'Show a modal dialog',
  parameters: z.object({ message: z.string() }),
  execute: async (params) => {
    /* client-side only */
  },
});

// Hybrid tool (runs on both)
const logger = hybridTool({
  name: 'log',
  description: 'Log a message',
  parameters: z.object({ message: z.string() }),
  executeServer: async (params) => {
    /* server impl */
  },
  executeClient: async (params) => {
    /* client impl */
  },
});
```

## Memory

```typescript
import {
  BufferMemory,
  RedisMemory,
  SummaryMemory,
  TenantBufferMemory,
} from '@lov3kaizen/agentsea-core';

// Simple buffer (keep last N messages)
const buffer = new BufferMemory(50);

// Redis-backed for persistence
const redis = new RedisMemory({ url: 'redis://localhost:6379' });

// Summary-based (compresses old conversations)
const summary = new SummaryMemory(provider);

// Multi-tenant (isolates memory per tenant)
const tenant = new TenantBufferMemory(100);
```

## Workflows

Orchestrate multiple agents in different patterns:

```typescript
import {
  SequentialWorkflow,
  ParallelWorkflow,
  SupervisorWorkflow,
} from '@lov3kaizen/agentsea-core';

// Sequential: agents run one after another
const sequential = new SequentialWorkflow({
  name: 'research-pipeline',
  agents: [researchAgent, analyzeAgent, summaryAgent],
});

// Parallel: agents run simultaneously
const parallel = new ParallelWorkflow({
  name: 'multi-analysis',
  agents: [sentimentAgent, topicAgent, entityAgent],
});

// Supervisor: one agent delegates to others
const supervised = new SupervisorWorkflow({
  name: 'managed-team',
  supervisor: managerAgent,
  workers: [codeAgent, testAgent, reviewAgent],
});

const result = await sequential.execute('Research AI trends', context);
```

## MCP Integration

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

const mcpRegistry = new MCPRegistry();

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

const mcpTools = mcpRegistry.getTools();
const agent = new Agent({ tools: mcpTools }, provider, toolRegistry);
```

## ACP (Agentic Commerce Protocol)

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

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

// 14 commerce operations: search, cart, checkout, payments, orders
const acpTools = createACPTools(acpClient);
```

## Voice

```typescript
import {
  VoiceAgent,
  OpenAIWhisperProvider,
  OpenAITTSProvider,
} from '@lov3kaizen/agentsea-core';

const voiceAgent = new VoiceAgent(agent, {
  sttProvider: new OpenAIWhisperProvider(process.env.OPENAI_API_KEY),
  ttsProvider: new OpenAITTSProvider(process.env.OPENAI_API_KEY),
  ttsConfig: { voice: 'nova' },
});

const result = await voiceAgent.processVoice(audioBuffer, context);
```

**Supported Providers:**

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

## Conversation Schemas

```typescript
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',
    },
  ],
});
```

## Observability

```typescript
import {
  Logger,
  defaultLogger,
  MetricsCollector,
  globalMetrics,
  Tracer,
  globalTracer,
} from '@lov3kaizen/agentsea-core';

// Structured logging
const logger = new Logger({ level: 'info', pretty: true });
logger.info('Agent started', { agent: 'assistant' });

// Metrics collection
globalMetrics.increment('agent.requests');
globalMetrics.histogram('agent.latency', 150);

// Distributed tracing
const span = globalTracer.startSpan('agent.execute');
span.end();
```

## Utilities

```typescript
import {
  RateLimiter,
  LRUCache,
  ContentFormatter,
} from '@lov3kaizen/agentsea-core';

// Rate limiting
const limiter = new RateLimiter({ maxRequests: 100, windowMs: 60000 });

// LRU caching
const cache = new LRUCache<string>({ maxSize: 1000 });

// Content formatting
const formatted = ContentFormatter.format(response);
```

## API Reference

### Agent

| Method                             | Description                                  |
| ---------------------------------- | -------------------------------------------- |
| `execute(input, context)`          | Execute agent with input and return response |
| `executeStream(input, context)`    | Stream agent response chunks                 |
| `registerProvider(name, provider)` | Register a provider                          |

### ToolRegistry

| Method                           | Description               |
| -------------------------------- | ------------------------- |
| `register(tool)`                 | Register a tool           |
| `get(name)`                      | Get a tool by name        |
| `list()`                         | List all registered tools |
| `execute(name, params, context)` | Execute a tool            |

## Related Packages

| Package                                          | Description                                |
| ------------------------------------------------ | ------------------------------------------ |
| [@lov3kaizen/agentsea-cli](../cli)               | Command-line interface with agentic coding |
| [@lov3kaizen/agentsea-nestjs](../nestjs)         | NestJS integration                         |
| [@lov3kaizen/agentsea-crews](../crews)           | Multi-agent orchestration                  |
| [@lov3kaizen/agentsea-memory](../memory)         | Advanced memory systems                    |
| [@lov3kaizen/agentsea-cache](../cache)           | Intelligent LLM caching                    |
| [@lov3kaizen/agentsea-guardrails](../guardrails) | Safety & validation                        |
| [@lov3kaizen/agentsea-evaluate](../evaluate)     | LLM evaluation                             |
| [@lov3kaizen/agentsea-redteam](../redteam)       | Red teaming & security                     |
| [@lov3kaizen/agentsea-analytics](../analytics)   | Conversation analytics                     |
| [@lov3kaizen/agentsea-react](../react)           | React components                           |

## License

MIT License - see [LICENSE](../../LICENSE) for details

---
_Source: https://npm.io/package/@lov3kaizen/agentsea-core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._