v1.1.0 release - Contributors, Sponsors and Enquiries are most welcome 😌

Multi-Agent Crews

Build powerful AI agent teams with role-based coordination, delegation strategies, and workflow orchestration. Inspired by CrewAI and AutoGen.

Crews enable multi-agent orchestration with role-based agents, delegation strategies, and pre-built templates for common use cases.

Installation

bash
pnpm add @lov3kaizen/agentsea-crews

Key Features

👥

Role-Based Agents

Define agents with specific roles, capabilities, and goals

🎯

Delegation Strategies

Round-robin, best-match, auction, hierarchical, and consensus

🔄

Workflow Builder

Fluent API for building complex workflows with DAG execution

🧠

Memory Systems

Shared memory, conversation history, and knowledge base

📊

Monitoring

Real-time dashboard and step-through debugging

📦

Pre-built Templates

Research, writing, code review, and customer support crews

Quick Start

Create a crew with role-based agents:

typescript
import { createCrew, type CrewConfig, type RoleConfig } from '@lov3kaizen/agentsea-crews';

// Define a role
const researcherRole: RoleConfig = {
  name: 'Researcher',
  description: 'Expert at finding and synthesizing information',
  capabilities: [
    { name: 'web-search', proficiency: 'expert' },
    { name: 'analysis', proficiency: 'advanced' },
  ],
  systemPrompt: 'You are a skilled researcher...',
  goals: ['Find accurate information'],
};

// Create crew configuration
const config: CrewConfig = {
  name: 'my-crew',
  agents: [
    {
      name: 'researcher',
      role: researcherRole,
      model: 'claude-sonnet-4-20250514',
      provider: 'anthropic',
    },
  ],
  delegationStrategy: 'best-match',
};

// Create and run the crew
const crew = createCrew(config);

crew.addTask({
  description: 'Research AI trends',
  expectedOutput: 'Summary of AI trends',
  priority: 'high',
});

const result = await crew.kickoff();
console.log(result.finalOutput);

Execution Model

As of v1.1.0, crew agents execute against a real LLM by default. Each agent runs through a core-backed executor (CoreExecutor) that calls the configured provider, so a crew produces genuine model output rather than placeholder text.

Real execution requires @lov3kaizen/agentsea-core (a peer dependency) and an API key for the chosen provider. Core is imported lazily on first execution, so orchestration scaffolding and mocked runs never need provider SDKs or keys. Supported providers for the default executor are anthropic, openai, gemini, and ollama.

Mock Execution (Offline / Tests)

Opt into deterministic mock output with mock: true. No provider SDK, network access, or API key is required, which makes it ideal for offline scaffolding and tests.

typescript
const crew = createCrew({
  name: 'my-crew',
  agents: [...],
  delegationStrategy: 'best-match',
  mock: true, // deterministic, offline — no LLM call
});

Provider Injection

Instead of having the executor lazily construct a provider by name, you can inject a pre-built core CoreLLMProvider via the provider option. This is useful for dependency injection, custom provider instances, and deterministic end-to-end tests with no network. (The provider option is ignored when execute or mock is set.)

typescript
import { createCrew, type CoreLLMProvider } from '@lov3kaizen/agentsea-crews';

// Any object matching CoreLLMProvider satisfies the seam — a concrete core
// provider (e.g. AnthropicProvider) or a deterministic test double.
const testProvider: CoreLLMProvider = {
  async generateResponse(messages, config) {
    return {
      content: 'deterministic response',
      usage: { inputTokens: 10, outputTokens: 5 },
    };
  },
};

const crew = createCrew({
  name: 'my-crew',
  agents: [...],
  delegationStrategy: 'best-match',
  provider: testProvider, // injected instead of loaded by name
});
For any provider not covered by the default executor, pass a custom execute function on the crew config. It receives the formatted task input and the agent's generated system prompt and takes precedence over the default core-backed executor.

Delegation Strategies

Choose how tasks are assigned to agents:

round-robin

Cycle through agents sequentially

best-match

Match tasks to agents by capabilities

auction

Agents bid on tasks based on confidence

hierarchical

Manager delegates to workers

consensus

Multi-agent voting for task assignment

typescript
const crew = createCrew({
  name: 'my-crew',
  agents: [...],
  delegationStrategy: 'consensus', // or 'round-robin', 'best-match', 'auction', 'hierarchical'
});

Roles & Capabilities

Roles define what an agent is and what it can do. Capabilities enable intelligent task matching.

typescript
const role: RoleConfig = {
  name: 'Security Analyst',
  description: 'Expert at identifying security vulnerabilities',
  capabilities: [
    { name: 'vulnerability-detection', proficiency: 'expert' },
    { name: 'secure-coding', proficiency: 'advanced' },
  ],
  systemPrompt: 'You are a security expert...',
  goals: ['Identify vulnerabilities', 'Ensure secure code'],
  constraints: ['Flag all security concerns'],
};

Pre-built Templates

Get started quickly with pre-configured crew templates for common use cases.

Research Crew

typescript
import { createResearchCrew, ResearchTasks } from '@lov3kaizen/agentsea-crews';

const crew = createResearchCrew({
  depth: 'deep', // 'shallow' | 'standard' | 'deep'
  includeWriter: true,
});

crew.addTask(ResearchTasks.research('electric vehicles', 'deep'));
crew.addTask(ResearchTasks.writeReport('EV Market Analysis', 'executive'));

const result = await crew.kickoff();

Code Review Crew

typescript
import { createCodeReviewCrew, CodeReviewTasks } from '@lov3kaizen/agentsea-crews';

const crew = createCodeReviewCrew({
  languages: ['typescript', 'python'],
  strictness: 'strict',
});

Customer Support Crew

typescript
import { createCustomerSupportCrew } from '@lov3kaizen/agentsea-crews';

const crew = createCustomerSupportCrew({
  productName: 'MyApp',
  supportStyle: 'friendly',
});

Workflow Builder

Build complex workflows with the fluent API for DAG (Directed Acyclic Graph) execution:

typescript
import { workflow, createDAGExecutor, createDAGFromSteps } from '@lov3kaizen/agentsea-crews';

const workflowDef = workflow('data-pipeline')
  .addStep('fetch', async (ctx) => {
    // Fetch data
    return { output: 'data', success: true };
  })
  .parallel(
    { name: 'validate', handler: validateFn },
    { name: 'transform', handler: transformFn }
  )
  .when((ctx) => ctx.getVariable('needsReview'))
    .then((b) => b.addStep('review', reviewFn))
    .otherwise((b) => b.addStep('auto-approve', approveFn))
  .endBranch()
  .build();

const dag = createDAGFromSteps(workflowDef.steps, workflowDef.handlers);
const executor = createDAGExecutor(dag, workflowDef.handlers);
const result = await executor.execute(context);

Memory Systems

Share state and knowledge across agents:

typescript
import { createSharedMemory, createKnowledgeBase } from '@lov3kaizen/agentsea-crews';

// Shared memory for crew-wide state
const memory = createSharedMemory();
memory.setShared('key', 'value');

// Knowledge base for persistent knowledge
const kb = createKnowledgeBase();
kb.addFact('title', 'content', ['tag1', 'tag2']);
const results = kb.search('query');

Monitoring & Debugging

Monitor crew execution in real-time:

typescript
import { createDashboard, createDebugMode } from '@lov3kaizen/agentsea-crews';

// Dashboard for monitoring
const dashboard = createDashboard(crew);
dashboard.subscribe((update) => {
  console.log('Progress:', dashboard.getProgress());
});

// Debug mode for step-through debugging
const debug = createDebugMode(crew);
debug.setBreakpoint('task:completed');
debug.enable();

const stepResult = await debug.step();

NestJS Integration

typescript
import { Module, Injectable } from '@nestjs/common';
import { CrewsModule, CrewsService, InjectCrew, OnCrewEvent } from '@lov3kaizen/agentsea-crews/nestjs';

@Module({
  imports: [
    CrewsModule.forRoot({
      crews: [myCrewConfig],
      enableMonitoring: true,
    }),
  ],
})
export class AppModule {}

@Injectable()
export class MyService {
  constructor(
    private readonly crewsService: CrewsService,
    @InjectCrew('my-crew') private readonly myCrew: Crew,
  ) {}

  @OnCrewEvent('task:completed')
  handleTaskCompleted(event: CrewEvent) {
    console.log('Task completed:', event);
  }
}

API Reference

Core Classes

  • Crew - Main orchestrator for multi-agent crews
  • Role - Agent role definitions
  • Task - Task lifecycle management
  • TaskQueue - Priority-based task queue
  • ExecutionContext - Shared execution context

Coordination

  • DelegationCoordinator - Manages delegation strategies
  • CollaborationManager - Agent-to-agent communication
  • ConflictResolver - Handles disagreements

Workflows

  • WorkflowBuilder - Fluent API for workflows
  • DAGExecutor - DAG execution engine
  • ParallelExecutor - Concurrent task execution
  • CheckpointManager - Workflow state persistence

Next Steps