@xy/swarm-core

Core framework for building XY enterprise agents with support for capabilities, events, LLM context, and more.

Features

• Decorator-based API: Easily define capabilities and event handlers with @Capability and @OnEvent decorators
• MCP Integration: Register and invoke capabilities through the MCP service
• Event-driven Architecture: Built-in support for event-based communication using Redis Streams
• LLM Context Management: Organize, store, and retrieve context for LLM conversations
• Dynamic Manifest Generation: Generate manifests from code annotations
• Agent Factory: Create agents with sensible defaults and minimal configuration
• Pluggable Components: Extensible architecture for custom event buses, storage backends, and more

Installation

npm install @xy/swarm-core

Quick Start

Create a basic agent:

import { EnterpriseAgent, Capability, OnEvent } from '@xy/swarm-core';

class MyAgent extends EnterpriseAgent {
  @Capability({
    description: 'Greet a user',
    parameters: {
      type: 'object',
      properties: {
        name: { type: 'string' }
      }
    }
  })
  async greet({ name }) {
    return `Hello, ${name}!`;
  }
  
  @OnEvent('user.registered')
  async handleUserRegistered(event) {
    const greeting = await this.greet({ name: event.data.name });
    console.log(greeting);
  }
}

// Create and initialize the agent
const agent = new MyAgent({ agentId: 'my-agent' });
await agent.initialize();

Agent Types

The framework provides several agent types:

• EnterpriseAgent: Base agent with capability and event support
• ContextAwareAgent: Agent with LLM context management features
• EventAwareAgent: Specialized agent for event-driven workflows

Creating Agents

Using Decorators

import { EnterpriseAgent, Capability } from '@xy/swarm-core';

class NewsAnalyzerAgent extends EnterpriseAgent {
  @Capability({
    description: 'Analyze news content',
    parameters: {
      type: 'object',
      properties: {
        content: { type: 'string' }
      }
    }
  })
  async analyzeContent({ content }) {
    // Implementation
    return { sentiment: 'positive', topics: ['technology'] };
  }
}

Using the Agent Factory

import { createAgent } from '@xy/swarm-core';

const agent = await createAgent({
  name: 'news-analyzer',
  eventsEnabled: true,
  llmContextEnabled: true,
  redisUrl: 'redis://localhost:6379'
});

await agent.initialize();

Event Handling

Subscribe to events with the @OnEvent decorator:

import { EnterpriseAgent, OnEvent } from '@xy/swarm-core';

class NotificationAgent extends EnterpriseAgent {
  @OnEvent('news.analyzed')
  async handleNewsAnalyzed(event) {
    // Handle the event
    console.log(`News analyzed: ${event.data.title}`);
  }
}

Publish events:

await agent.publishEvent('news.created', {
  id: '12345',
  title: 'New Article',
  content: 'Article content...'
});

LLM Context Management

The ContextAwareAgent provides features for managing LLM context:

import { ContextAwareAgent } from '@xy/swarm-core';

class AssistantAgent extends ContextAwareAgent {
  async processQuery(query) {
    // Store context
    await this.createContext({
      type: 'conversation',
      content: query,
      metadata: { userId: '123' }
    });
    
    // Search for relevant context
    const relevantContext = await this.searchContext({
      query,
      type: 'knowledge_base',
      limit: 5
    });
    
    // Use the context in the LLM conversation
    return this.withLLMContext(relevantContext, async (llm) => {
      return llm.complete(query);
    });
  }
}

Generating Manifests

Generate a manifest from an agent class:

import { generateManifestFromClass, generateAndSaveManifest } from '@xy/swarm-core';

// Generate in memory
const manifest = generateManifestFromClass(MyAgent);

// Generate and save to file
await generateAndSaveManifest(MyAgent, './manifests/my-agent.json');

Advanced Features

News Workflow with Deduplication

The framework supports advanced news processing workflows including:

• Multi-layered LLM-based deduplication
• Semantic similarity detection
• Event-based article clustering

Event-driven Pipeline

Create complex event-driven pipelines with multiple agents:

• Publisher agents for creating events
• Analyzer agents for processing and enriching data
• Distributor agents for channel-based distribution

License

MIT © XY Retail