# @lov3kaizen/agentsea-crews

A TypeScript-native multi-agent orchestration framework for building AI agent teams. Inspired by CrewAI and AutoGen, this package provides role-based agent coordination, task delegation strategies, workflow building capabilities, and pre-built crew templates.

## Features

- **Role-Based Agents**: Define agents with specific roles, capabilities, and goals
- **Multiple 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 & Debug**: Real-time dashboard and step-through debugging
- **Pre-built Templates**: Research, writing, code review, and customer support crews
- **NestJS Integration**: Decorators and dynamic modules for NestJS apps

## Installation

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

## Quick Start

### Basic Crew

```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-6',
      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.** By default, crew agents execute against real LLMs via
> `@lov3kaizen/agentsea-core` providers (a required peer dependency), so make
> sure the relevant API key is set (e.g. `ANTHROPIC_API_KEY`). Supported
> providers out of the box: `anthropic`, `openai`, `gemini`, `ollama`.
>
> - To plug in a different integration, pass an `execute` function on the crew
>   config (or to `createCrewAgent`).
> - For offline scaffolding and tests, set `mock: true` on the crew config to
>   get deterministic mock responses without any network calls.
>
> ```typescript
> // Offline / test mode
> const crew = createCrew({ ...config, mock: true });
>
> // Custom execution backend
> const crew2 = createCrew({
>   ...config,
>   execute: async (input, systemPrompt) => ({
>     output: await myLlm(systemPrompt, input),
>     tokensUsed: 0,
>     latencyMs: 0,
>     iterations: 1,
>   }),
> });
> ```

### Using Templates

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

// Create a research crew with pre-configured agents
const crew = createResearchCrew({
  depth: 'deep',
  includeWriter: true,
});

// Add tasks using templates
crew.addTask(ResearchTasks.research('electric vehicles', 'deep'));
crew.addTask(ResearchTasks.writeReport('EV Market Analysis', 'executive'));

const result = await crew.kickoff();
```

### Workflow Builder

```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);
```

## Core Concepts

### Roles & Capabilities

Roles define what an agent is and what it can do:

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

### 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({
  delegationStrategy: 'consensus',
  // ...
});
```

### Concurrency

By default a crew runs ready tasks **sequentially**, which keeps event ordering
deterministic. For independent tasks you can opt into a bounded worker pool so
they execute in parallel — set it on the crew config or per `kickoff()` call:

```typescript
// Crew-wide default
const crew = new Crew({
  name: 'Research Crew',
  agents: [...],
  delegationStrategy: 'best-match',
  maxConcurrentTasks: 4, // up to 4 ready tasks run at once
});

// Or override per run (takes precedence over the config value)
const result = await crew.kickoff({ maxConcurrentTasks: 4 });
```

Notes:

- The default is `1` (fully sequential) — behavior is unchanged unless you opt in.
- Only tasks that are _ready_ in the same scheduling iteration run together, so
  dependency ordering is still respected.
- With concurrency `> 1`, `task:assigned` / `task:completed` events from
  different tasks interleave as workers settle (each task still emits its own
  events in order). If a task fails after exhausting retries, no further tasks
  are launched, in-flight tasks are allowed to settle, and the crew ends with the
  same fatal `crew:error` as the sequential path.

### 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

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();
```

## Pre-built Templates

### Research Crew

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

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

### Writing Crew

```typescript
import { createWritingCrew, WritingTasks } from '@lov3kaizen/agentsea-crews';

const crew = createWritingCrew({
  contentType: 'blog', // 'blog' | 'technical' | 'marketing'
});
```

### 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,
  CustomerSupportTasks,
} from '@lov3kaizen/agentsea-crews';

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

## NestJS Integration

```typescript
import { Module } 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

### Agents

- `CrewAgent` - Enhanced agent with crew capabilities
- `AgentCapabilities` - Capability matching utilities
- `AgentRegistry` - Agent discovery and management

### 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

### Memory

- `SharedMemory` - Crew-wide shared state
- `ConversationHistory` - Multi-agent conversation tracking
- `KnowledgeBase` - Persistent knowledge store

### Monitoring

- `CrewDashboard` - Real-time monitoring
- `DebugMode` - Step-through debugging

## License

MIT